claude-sdd-planner CLAUDE.md

SDD Planner

A spec-driven development toolchain: structured project planning with lifecycle skills, intent-isolated review agents, and a deterministic Go validator (sdd). This repository is the single source for every supported harness:

• Repo root — the canonical, hand-edited Claude Code plugin (commands/, agents/, skills/, shared/, hooks/).
• .codex-plugin/ and .opencode-plugin/ — generated plugin trees for Codex and OpenCode, produced by sdd plugin sync. Never hand-edited; drift fails make test.

Directory Structure

claude-sdd-planner/               # Repository root = canonical Claude plugin root
├── .claude-plugin/
│   └── plugin.json               # Canonical manifest — single source of version + minSddVersion
├── commands/                     # Slash commands (auto-namespaced /sdd-planner:*); each is a dir with SKILL.md
│   └── <name>/SKILL.portable.md  #   optional hand-maintained portable variant (code-review, implement, setup)
├── skills/                       # Model-only reference skills (auto-loaded by description, not /-invocable)
│   ├── <lang>-specifications/    #   per-language structural verification (cpp, rust, go, python, typescript, java, swift)
│   ├── decision-log/             #   ad-hoc decision capture outside lifecycle skills
│   └── sdd-cli/                  #   how to drive the sdd binary — task→command map + write-path discipline
├── agents/                       # Subagent definitions — also the source for the portable role prompts
├── hooks/                        # Wrappers that locate the binary; hooks.json is NOT shipped —
│   ├── sdd-hook.sh               #   `sdd provision` generates it per-platform (see below)
│   └── sdd-hook.ps1
├── shared/                       # Conventions + templates, shipped to every harness
│   ├── frontmatter-schema.md     #   single source of truth for artifact metadata
│   ├── completion-evidence.md    #   evidence-gated completion — what `complete` requires, per level
│   ├── decision-log.md           #   decision ledger — entry schema, admission test, collision procedure
│   ├── decision-framework.md     #   universal decision discipline for all skills and agents
│   ├── path-resolution.md        #   planning-root / plugin-dir / target-repo resolution (marker-managed)
│   ├── orchestration.md          #   orchestration model + portable prompt catalog (marker-managed)
│   ├── vcs-detection.md          #   VCS detection algorithm + operations table (git / p4 / plain)
│   ├── autonomy.md               #   cross-skill autonomy table — what runs solo vs stops for the user
│   ├── review-lanes.md           #   project-supplied review-lane socket (+ .portable.md variant)
│   ├── review-artifacts.md       #   persisted review contract incl. the phase-completion gate
│   ├── language-verification.md  #   language-specific verification — what good looks like
│   ├── agent-runtime.md          #   portable runtime conventions (resolution, delegation, resource boundary)
│   └── templates/                #   document templates (+ agents-md-*, claude-md-*, custom-reviewer variants)
├── cmd/sdd/                      # The `sdd` binary — validation, artifact writes, hooks, plugin sync
├── internal/                     # Binary internals (rules, dlg, compile, hook, provision, schema, vcs, portable)
├── tools/                        # genfixtures + the frozen regression corpus (run by `go test ./...`)
├── .codex-plugin/                # GENERATED Codex plugin tree — never hand-edit
├── .opencode-plugin/             # GENERATED OpenCode plugin tree (same content) — never hand-edit
├── portable-overrides/           # Hand-maintained portable-only sources (the portable README)
├── .plans/                       # This repo's own planning artifacts (planning-config.json → ".plans")
│   └── Decisions/decisions.md    #   the decision ledger — D-NNNN entries are standing constraints
├── Makefile                      # build / test / plugins / bump-*
└── bump-version.py               # patch|minor|major bumps, `set X.Y.Z`, `set-floor X.Y.Z`