Standards and conventions for spec-driven software development. This project defines how we run projects — the workflow, spec structure, principles, and quality rules that apply regardless of tech stack.

• constitution.md — Guiding principles, development pipeline, spec lifecycle, and quality standards
• sdd-context.md — What spec-driven development is, how it differs from other approaches, and repository structure patterns
• templates/ — Starter files for specs, plans, tasks, data models, and research
• commands/ — Slash command templates that operationalize the pipeline
• govern/ — Platform-specific adopt commands (Claude Code, Auggie)
• AGENTS.md — Agent rules template for AI-assisted development
• security-backend.md — Enforceable backend security rules (RFC 2119)
• security-frontend.md — Enforceable frontend security rules (RFC 2119)
• specs/ — Feature specs for governance itself (dogfooding the pipeline)

Governance uses its own spec-driven pipeline to develop itself.

For brownfield projects, install the govern command and run it — no clone required. Once adopted, use /capture to initialize skeleton specs for existing features and let them gain precision incrementally through bug fixes, enhancements, and clarification.

mkdir -p .claude/commands
curl -fsSL https://raw.githubusercontent.com/stonean/govern/main/govern/govern.md \
  > .claude/commands/govern.md

Then run /govern {project-name}.

mkdir -p .augment/commands
curl -fsSL https://raw.githubusercontent.com/stonean/govern/main/govern/govern-auggie.md \
  > .augment/commands/govern.md

Then run /govern {project-name}.

The command fetches governance files, scaffolds the spec directory, installs slash commands, and displays next steps. It is idempotent — safe to run again to pick up new governance files.

Adoption installs a full set of slash commands that operationalize the pipeline. All commands are session-aware — run /target first to set the working feature, then use pipeline commands in context.

The recommended path is /gov:init, which automates the steps below — including a guided tech stack questionnaire that populates the AGENTS.md Tech Stack table automatically. The manual steps are listed here for reference or for agents that don't support the init command.

mkdir my-project && cd my-project
git init

Copy these files from governance into your project root:

Open AGENTS.md and replace every placeholder section:

• Tech Stack — list your languages, frameworks, databases, and versions
• Commands — define dev, build, test, lint (or your equivalents)
• Project Structure — map out your directory layout
• Code Style — show idiomatic patterns with code examples
• Testing — define test types, file placement, and tooling conventions
• Gotchas — document framework quirks and non-obvious behavior
• Boundaries — define what agents must never do without asking

Create a CLAUDE.md (or equivalent for your agent) that imports the constitution and agent rules:

@import constitution.md
@import AGENTS.md

mkdir specs

Write specs/system.md describing your architecture — server lifecycle, request flow, shared infrastructure, and module pattern. Add specs/errors.md and specs/events.md if your project uses structured errors or event-driven communication.

Run /specify to create a numbered feature directory with a spec from template. The command asks qualifying questions to determine whether the feature uses the standard track (separate spec, plan, and tasks) or the lightweight track (combined spec-and-plan for small, single-module features).

Alternatively, create one manually:

mkdir specs/000-skeleton
cp /path/to/governance/templates/spec.md specs/000-skeleton/spec.md

Follow the pipeline defined in constitution.md:

1. Spec — resolve all open questions, update status to clarified
2. Plan — create plan.md with technical decisions, list affected files. If the feature involves persistence, add data-model.md
3. Tasks — create tasks.md, break the plan into ordered work items. Update spec status to planned
4. Readiness check — run /validate to verify all gates pass before writing code
5. Implement — follow the tasks list, update spec status to in-progress, then done

The governance framework includes enforceable security rules for backend and frontend code, distributed via adopt. Rules use RFC 2119 language: MUST/MUST NOT are blocking violations, SHOULD/SHOULD NOT are advisory warnings.

• security-backend.md — Authentication, authorization, input validation, data protection, API security, logging, dependency management, and error handling
• security-frontend.md — XSS prevention, CSRF protection, secure storage, authentication handling, content security, and dependency management

Projects can reference these rules in their AGENTS.md or validate command to enforce security standards during development.

Bugs are unwritten scenarios. The governance framework treats every bug as evidence that a spec is missing, ambiguous, or violated.

When a bug is reported, follow in order:

1. No spec exists — write the spec first, then fix the code
2. Spec is ambiguous — fix the spec, then fix the implementation
3. Spec is clear, implementation is wrong — add a scenario, then fix the code

A scenario is a spec at a lower level of abstraction. Scenarios live in specs/NNN-feature/scenarios/slug.md and capture edge cases, bug fixes, and detailed behavior. Each scenario gets a linked task in the parent spec's tasks.md. Scenarios can be targeted directly with /target feature/scenario-slug for focused work.

For brownfield projects, specs/inbox.md is a temporary inbox. Items are migrated to specs or scenarios as the project adopts governance. The goal is for the inbox to eventually be empty.

Projects that were bootstrapped with /gov:init or adopted governance manually can pull the latest governance files by running the govern command. It uses three strategies to decide how each file is handled:

The .gitignore uses a merge strategy — governance patterns are appended below a # Governance marker if the marker is not already present.

If your project has customized a file that governance normally overwrites (update strategy), you can pin it to prevent adopt from overwriting your changes. Create a .governance.toml file in your project root:

[pinned]
# Files listed here use 'skip' instead of 'update'.
# Use destination paths (after placeholder resolution).
files = [
  ".claude/commands/myapp/implement.md",
  "constitution.md",
]

Any file listed in pinned.files is treated as skip instead of update when adopt runs. Pinned files are reported in the post-scaffolding summary.

If you prefer not to use adopt, governance is a reference, not a dependency. Review the governance changelog or diff, decide which changes apply to your project, and update your copies at your own pace.

Governance currently distributes to two AI coding agents:

• Claude Code — .claude/ paths, /govern and /gov:* commands
• Auggie — .augment/ paths, /govern command variant

Adding support for a new agent requires only a new govern/govern-{agent}.md file with platform-appropriate paths and configuration.

All .md files must pass markdownlint-cli2 using the project config. See constitution.md for the full rule set.