sdg-agents installs a set of markdown instruction files into your project. AI agents (Claude Code, Cursor, Windsurf, Copilot, Codex, and others) read these files and follow the defined protocol for every task.

Note: If your agent does not pick up the rules automatically, reference .ai/skills/AGENTS.md at the start of the session.

The instruction set covers:

• Working protocol: a 5-phase cycle (SPEC → PLAN → CODE → TEST → END) that structures how the agent handles any task. Includes a unified Work Checklist (Intent recited at CODE entry; Form recited at CODE entry and verified at TEST) and a 3-strike Circuit Breaker (STOP) to prevent regression loops.
• Code style & quality gates: consolidated in code-style.md — a single WorkChecklist rule with two binary sections: Intent (Mental Reset, Target Files, Naming, Narrative, Comments, Tests planned, Security, Blockers) and Form (Pure entry point, Narrative Siblings, Explaining Returns, Revealing Module Pattern, Vertical Density, Boolean prefix, No framework abbreviations, No section banners) wired to narrative heuristics in governance.mjs.
• Skills, on-demand: code style, testing, security, API design, data access, observability, CI/CD, cloud, SQL style, UI/UX, code review, performance, domain modeling — each a self-contained skill unit loaded only when the current cycle needs it.
• Dynamic stack context: the land: cycle elicits the project's languages and versions from the developer, optionally enriches them via an allow-listed doc fetch, and persists the result in .ai/backlog/stack.md. Phase CODE reads that file as the single source of truth — no static idiom catalog, no version registry to maintain.
• Delivery contract: BFF response envelope (server-side) and UI contract execution (client-side) fused into one self-gated competencies/delivery.md, loaded when the task touches delivery logic.
• Architectural flavors: rules for your project's structural pattern (vertical slice, MVC, lite, legacy).
• Any-agent compatible: a single canonical .ai/skills/AGENTS.md that any AI agent (Claude Code, Cursor, Windsurf, Copilot, Codex, Gemini, Cline/Roo) can reference. CLAUDE.md is auto-generated at the repo root for Claude Code; other tools are wired up by a one-line pointer (see "Using with other IDEs" below).
• Harness Engineering (Memory): a .ai/backlog/ folder that persists context and task state across sessions.
• Impact Map: a volatile blast-radius file (.ai/backlog/impact-map.md) created at Phase PLAN and cleared at Phase END — tells the agent exactly which files to load for the current cycle, keeping context lean and focused.
• Inert tooling catalog: sdg-agents init copies a pre-made bundle into .ai/tooling/ — prune-backlog.mjs (trims backlog Done entries), bump-version.mjs (semver-only bump), and husky hook templates (pre-commit gate + commit-msg prefix check). Nothing is wired by default: no package.json edit, no .husky/ created, no devDep installed. Activate on demand with agent assistance or manually.

Quick Start

npx sdg-agents

The interactive wizard guides you through selecting an architectural flavor. Stack discovery (languages + versions) happens later via the land: cycle — kept out of install so the developer can declare it deliberately, once the project brief is clear. For non-interactive use:

# Zero-prompt install (lite flavor + placeholder stack.md)
npx sdg-agents init --quick

# Vertical Slice — any stack
npx sdg-agents init --flavor vertical-slice

# MVC — any stack
npx sdg-agents init --flavor mvc

After install, open the agent chat and run land: <vision> — the agent elicits the stack, writes .ai/backlog/stack.md, and seeds the backlog.

What Gets Installed

After running init, your project receives:

your-project/
├── .ai/                         ← Instruction set (committed)
│   ├── skills/                  ← Engineering skills (loaded on-demand per cycle phase)
│   │   ├── AGENTS.md            ← Main entry point + skill registry
│   │   ├── code-style.md        ← Code style + Work Checklist (Intent + Form) — Phase CODE core
│   │   ├── testing.md
│   │   ├── security.md
│   │   └── ... (api-design, data-access, observability, ci-cd, cloud, sql-style, ui-ux)
│   ├── instructions/            ← Flavors, fused delivery competency, templates
│   ├── commands/                ← Cycle commands (feat/fix/docs/audit/land/end)
│   ├── tooling/                 ← Inert tooling bundle (scripts + husky hooks — activate on demand)
│   └── backlog/                 ← Harness Engineering (Memory) — gitignored, local working state
│       └── ...                  ← (See docs/reference/PROJECT-STRUCTURE.md for details)

.ai/skills/AGENTS.md is a minimal router: it lists all available skills and loads them on demand. Only workflow.md (the 5-phase protocol) is always in context — everything else activates only when the current cycle needs it.

CLAUDE.md at the repo root is a thin pointer that @-imports .ai/skills/AGENTS.md, so Claude Code auto-loads the governance on every session. Other IDEs are wired up by pointing their native config file at the same canonical file — see "Using with other IDEs" below.

For a detailed breakdown of each file's role, see Project Structure.

How the Protocol Works

When you prefix a message to the agent, it enters the corresponding cycle:

| Trigger | Cycle | What happens | | :-------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------- | | land: <description> | Land | Agent turns a raw vision into a grounded backlog of sequenced feat: tasks — runs before any code is written | | feat: <description> | Feature | Agent runs SPEC → PLAN → CODE → TEST → END | | fix: <description> | Fix | Agent runs SPEC → PLAN → CODE → TEST → END with RCA focus | | docs: <description> | Docs | Agent updates changelogs, ADRs, or specs | | audit: <scope> | Audit | Agent verifies project alignment against rulesets (drift detection) | | end: | — | Close the active cycle — runs the END Phase checklist (changelog, backlog, commit). Also recovers a cycle if the agent loses track mid-conversation | | No prefix | — | Agent asks: "land, feat, fix, docs, or audit?" — then proceeds |

The agent stops and waits for your approval at SPEC and PLAN before writing any code.

SPEC  →  PLAN  →  CODE  →  TEST  →  END
  ↑           ↑                       ↑
  Wait        Wait                 "end:"

Type end: to close the active cycle. The agent runs the full END checklist — changelog, backlog sync, commit proposal. If the agent loses track mid-conversation, end: also recovers the cycle.

For a detailed walkthrough of each phase and its rules, see Spec-Driven Development Guide. For a visual breakdown of the internal decision gates and loops, see Agent Deep-Flow.

Architectural Flavors

Select the flavor that matches your project's structure:

| Flavor | Pattern | Use when | | :--------------- | :-------------------------------------- | :--------------------------- | | vertical-slice | Feature-driven vertical cuts | Monorepo or domain-heavy API | | mvc | Classic layered (Model-View-Controller) | Standard REST service | | lite | Minimal scaffold | Scripts, CLIs, utilities | | legacy | Refactor-safe bridge patterns | Migrating existing codebases |

For the data flow diagram of each flavor, see Architectural Pipelines.

Stack Declaration via land:

Stack is dynamic, not cataloged. After sdg-agents init, run the land: cycle to declare the project's languages, runtimes, and framework versions:

land: a Node.js + TypeScript API serving a React dashboard

The agent:

1. Asks you to list every language and version (free-form).
2. Classifies each entry by role (Backend / Frontend / Data / Scripts).
3. Offers optional enrichment via an allow-list of canonical doc sources (nodejs.org/api, react.dev, typescriptlang.org, tc39.es, docs.astro.build, docs.python.org, go.dev/doc, doc.rust-lang.org, kotlinlang.org/docs, dart.dev, learn.microsoft.com/dotnet, developer.apple.com/documentation/swift).
4. Writes .ai/backlog/stack.md — the single source of truth for stack-specific idioms. Edit it directly when versions change; no regen needed.

Phase CODE loads stack.md on every cycle. No static idiom catalog, no --idiom flag.

Using with other IDEs

sdg-agents generates a single canonical governance file at .ai/skills/AGENTS.md and a CLAUDE.md pointer at the repo root. Claude Code auto-loads it with no extra step. For other tools, add a one-line pointer in your IDE's native rules file:

| Agent | Native config file | How to wire it | | :--------------- | :--------------------------------- | :------------------------------------------------------------------------------- | | Claude Code | CLAUDE.md (root, auto-generated) | Auto-loaded. No action required. | | Cursor | .cursor/rules/sdg-agents.mdc | Create the file with a single line: Read .ai/skills/AGENTS.md before any task. | | Windsurf | .windsurfrules | Same pointer line. | | GitHub Copilot | .github/copilot-instructions.md | Same pointer line. | | Codex CLI | AGENTS.md (root) | Already at repo root via .ai/skills/AGENTS.md; or create a thin pointer file. | | Gemini CLI | GEMINI.md | Same pointer line. | | Cline / Roo Code | .clinerules | Same pointer line. |

Prefer a custom preset, voice, or skill? Paste the skill content into your agent as a prompt — the same way docs/reference/REFERENCES.md documents external influences. Custom skills do not require a CLI subcommand.

Maintenance

npx sdg-agents gate      # Run SDG gate review against staged diff (language-agnostic pre-commit)
npx sdg-agents review    # Detect drift between local rules and source
npx sdg-agents audit     # Run governance audit (law violations, drift)
npx sdg-agents clear     # Remove the .ai/ folder

Reference

• Quick Reference (CHEATSHEET) — all CLI flags and agent triggers
• Project Structure — detailed breakdown of every generated file
• Architectural Pipelines — data flow diagrams for each flavor
• Engineering Constitution — the philosophical principles behind the rules (reference only; runtime rules live in code-style.md)
• UI/UX System — design philosophy, hierarchy, surface tonal scale, presets, and external research references
• Roadmap — planned work
• Changelog — release history
• Token Optimization — cost model, compaction process, and routing efficiency
• Migration v2 → v3 — breaking changes and step-by-step migration guide
• Credits and Philosophies — project influences and research credits

Warning: This project is in early development. Review and adjust the installed rules to fit your team's standards before relying on them.

Balance is the key.

SDG is in constant evolution. There is no perfect solution, only continuous improvement. Feel free to contribute, fork, and share.