platform-template

Starter template for all Divinity Science repositories. Copy this repo when starting a new product, agent, or platform service.

Every DS repo should be traceable end-to-end: Notion spec -> Linear issue -> GitHub branch/PR -> CI checks -> deploy.

Repository naming

Prefix	Purpose
product-*	Deployable user-facing apps
agent-*	Agent harnesses, planners, evaluators, control services
platform-*	Shared infra, auth, internal SDKs, observability
security-*	Security tooling, threat models, eval pipelines

Branch and PR flow

1. Create a Linear issue for the work.
2. Branch from main using the format <type>/<linear-id>-short-description.
   • Example: feat/DS-42-add-eval-gate
3. Open a PR against main. The PR title must include the Linear issue ID so Linear auto-links and updates status.
4. All required checks must pass before merge.
5. Merge only via PR. Direct pushes to main are blocked.

Branch types

Type	Use
feat/	New feature or capability
fix/	Bug fix
chore/	Maintenance, deps, config
security/	Security fix or hardening
prompt/	Prompt or agent policy change
infra/	Infrastructure or IaC change

Required checks

• test - unit and integration tests
• lint - linting and type checking
• secret-scan - Gitleaks fast scan
• sast-lite - Semgrep lite scan

Security scanning schedule

Layer	Tool	When	Blocking
Local	Gitleaks pre-commit	Every commit	Yes
PR	Gitleaks	Every PR	Yes
PR	Semgrep lite	Every PR	Yes
Repo	Dependabot alerts	Continuous	No
Nightly	Semgrep full	Nightly	No
Weekly	TruffleHog deep	Weekly	No

Linear integration

• Connect the Linear GitHub integration at the org level.
• Branch names and PR titles must include the Linear issue ID (e.g. DS-42).
• Linear will auto-transition issue state as PRs move from draft -> open -> review -> merged.
• Do not create GitHub issues for work tracked in Linear. Use GitHub issues only for security findings and dependency alerts.

Notion links

Every repo should have a corresponding Notion page linked in the repo description or pinned in the repo's issue sidebar. That page should contain:

• Architecture decision records (ADRs)
• Threat model
• Runbooks
• Postmortem templates

Setup checklist for new repos

• Rename this repo following the naming convention
• Update repo description and link the Notion spec page
• Enable Dependabot alerts in repo settings
• Enable dependency graph in repo settings
• Configure branch protection on main (see .github/branch-protection.md)
• Replace placeholder Linear project ID in workflow files
• Set required secrets: none required by default workflows; add as needed
• Add CODEOWNERS entries for your team