cc-sdd-adr

A dependency-free add-on for cc-sdd that keeps consequential decisions under human control and turns them into Architecture Decision Records.

What it does

cc-sdd-adr extends the cc-sdd skills that are already installed in your project. It never replaces them — it appends an Extension Section inside managed markers, and adds one skill of its own.

• During Requirements and Design generation, the agent must stop at consequential choices instead of deciding silently. It presents why a decision is needed, the meaningful options, and their trade-offs, then waits for a provisional decision with a reason from you. Local, easily reversible implementation details are out of scope and stay with the agent.
• Provisional decisions are recorded in .kiro/specs/{feature}/decisions.md as PD-{n} entries (phase / subject / options / trade-offs / chosen option / rationale). That file is owned by this extension; requirements.md, design.md, and tasks.md stay untouched by it.
• The kiro-adr skill converts them into formal ADRs. It is optional and runs any time after Design generation and before Tasks generation. It collects the provisional decisions, normalizes them to ADR granularity (merging, splitting, or dropping candidates), and presents each candidate for approval. Only an explicit agreement materializes an ADR under .kiro/adr/. Silence, "sounds good", the agent's own recommendation, and blanket -y / --auto approvals are not agreement. Skipping the skill never blocks Tasks generation.
• Tasks generation and implementation read the decisions back as constraints. Both scan .kiro/adr/ for ADRs with Status: Accepted and treat them as binding: settled questions are not reopened, and a conflict must be surfaced rather than silently overridden. When implementation is delegated to another agent, the Accepted ADRs must be carried into that agent's context in full — a path reference is not enough.

ADRs live at .kiro/adr/NNNN-kebab-case-title.md, identified as ADR-NNNN, numbered from 0001 upward across the whole project. Status is two-valued: Accepted or Superseded. A changed decision is recorded as a new ADR that supersedes the old one; history is never rewritten.

Run ADR Resolution as a skill, naming the spec it should collect from:

/kiro-adr <feature-name>

Running it is optional — you can go straight to tasks generation and leave the provisional decisions unconverted.

Language

The instruction text this tool installs is written in English, matching how cc-sdd ships its own skill definitions. ADRs and provisional decisions are written in whatever language the target spec configures via spec.json.language, so running cc-sdd with --lang ja still gives you Japanese ADRs.

The headings and the provisional-decision field names (Phase, Decision, Options, Trade-offs, Chosen, Rationale) stay in English regardless — /kiro-adr parses them.

Requirements

• Node.js >= 22
• A project where cc-sdd skills are already installed

Install

Run from the root of your cc-sdd project:

npx cc-sdd-adr@latest install

A subcommand is required — running npx cc-sdd-adr@latest with no arguments only prints help.

The installed cc-sdd targets are detected automatically. You can also select them explicitly:

npx cc-sdd-adr@latest install --claude-skills
npx cc-sdd-adr@latest install --codex-skills

Preview the changes without writing anything:

npx cc-sdd-adr@latest install --dry-run

Commands

| Command | What it does | | --- | --- | | install | Adds missing artifacts and brings outdated ones to the running version. Accepts --dry-run. | | update | Brings already installed artifacts to the running version. Creates nothing, so it never changes which environments or which host skills are installed into. If something is missing, it says so and points you at install. | | uninstall | Removes the Extension Sections and the kiro-adr skill directory. Keeps generated ADRs and decisions files. | | status | Reports the state of every artifact per environment. Read-only. No installation state makes it fail — not even broken; it exits non-zero only when no cc-sdd target can be resolved at all. |

Options:

• --claude-skills / --codex-skills — target one environment explicitly instead of auto-detecting. Selecting an environment that has no cc-sdd installation is an error.
• --dry-run — install only. Shows the changes that would happen without touching the filesystem. Passing it to another subcommand is rejected.
• --help — print help.

Each artifact is reported on its own line, for example:

cc-sdd-adr 0.2.0 status
  [claude] Requirements Extension: installed
  [claude] Design Extension: installed
  [claude] Tasks Extension: installed
  [claude] Implementation Extension: installed
  [claude] ADR Skill: installed

Reported states are installed, not_installed, outdated (with both the installed and the running version), and broken (the managed markers were damaged by hand). A broken artifact is never guessed at: it is reported and left untouched, while the other artifacts continue to be processed.

What it installs

Four Extension Sections, appended inside <!-- cc-sdd-adr:begin v… --> / <!-- cc-sdd-adr:end --> markers to existing cc-sdd skill definitions, plus the kiro-adr skill directory with its bundled ADR template.

For Claude Code (skill root .claude/skills/):

.claude/skills/kiro-spec-requirements/SKILL.md   (Extension Section appended)
.claude/skills/kiro-spec-design/SKILL.md         (Extension Section appended)
.claude/skills/kiro-spec-tasks/SKILL.md          (Extension Section appended)
.claude/skills/kiro-impl/SKILL.md                (Extension Section appended)
.claude/skills/kiro-adr/SKILL.md
.claude/skills/kiro-adr/adr-template.md

For Codex (skill root .agents/skills/):

.agents/skills/kiro-spec-requirements/SKILL.md   (Extension Section appended)
.agents/skills/kiro-spec-design/SKILL.md         (Extension Section appended)
.agents/skills/kiro-spec-tasks/SKILL.md          (Extension Section appended)
.agents/skills/kiro-impl/SKILL.md                (Extension Section appended)
.agents/skills/kiro-adr/SKILL.md
.agents/skills/kiro-adr/adr-template.md
.agents/skills/kiro-adr/agents/openai.yaml

Nothing is written outside those skill roots. In particular the installer never creates anything under .kiro/settings/, .kiro/adr/, or .kiro/specs/, and it does not add a managed block to CLAUDE.md or AGENTS.md.

Only the declared files are written. A file you add yourself under kiro-adr/ survives install and update; uninstall removes the whole directory and reports which undeclared files it took with it.

Uninstall

npx cc-sdd-adr@latest uninstall

The marked range — including the blank-line separator that was inserted with it — is stripped, so each host skill definition returns to its pre-install bytes. Generated ADRs under .kiro/adr/ and provisional decisions in .kiro/specs/{feature}/decisions.md are yours, not the installer's, and are left in place.

Scope

cc-sdd-adr intentionally does not provide a database, MCP server, CI check, Git hook, or documentation site. The repository is the source of truth:

.kiro/adr/NNNN-kebab-case-title.md

Development

The package has zero runtime and zero development dependencies; there is no node_modules to install before running the tests.

npm test        # node --test
npm run check   # syntax check of bin/ and lib/, then the test suite
npm pack --dry-run

Releases

Releases use Semantic Versioning while the project is pre-1.0:

• patch releases fix behavior without changing the installed contract;
• minor releases may add targets or revise the installation contract.

Every pull request and push to main runs npm run check and npm pack --dry-run on Node 22 and 24. Publishing a GitHub Release whose tag matches v<package.json version> runs the same checks again and publishes to npm through trusted publishing.

License

MIT