• The install is per project, into the working directory and not into ~. A new checkout needs download-skill run again.
• The archive endpoint (GET /api/v1/mcp/skills/archive) requires an authenticated browser session, so fetching it with curl will not work. Use download-skill, or download the archive from a logged-in browser.

Choosing a specs directory

We recommend keeping specs outside the codebase project, for example ../specs/. When multiple agents extract different domains in parallel, none of them can then read the output of the others. The examples in this guide use ../specs/.

Kiro users

Kiro restricts access to directories outside the project it is working in, which can cause repeated permission problems during a run. When using Kiro, use a sub-directory inside the project instead, such as ./specs/. Claude Code has no such restriction.

• What SDD-Extract-Specs Does
• Example Prompts
• What You Get
• Model Selection
• Before Moving On

What SDD-Extract-Specs Does

Sdd-extract-specs reverse-engineers the application’s business behavior into OpenSpec specifications, one artifact set per vFunction domain. The skill has three stages that all read from and write to the same specs root. It runs one stage per request: it stops after each stage, reports, and asks before continuing.

Stage 1 runs in one of three modes:

SDD-Extract-Specs Example Prompts

Extract the specs for this application into ../specs/
Reverse-engineer the spec for the Billing domain into ../specs/
Extract specs from the codebase alone into ../specs/ (there's no vFunction analysis for this app)
Consolidate the ubiquitous language in ../specs/
Extract and modernize the tech stack for ../specs/

SDD-Extract-Specs What You Get

../specs/
    ubiquitous-language.md              # after stage 2: the aggregated, cross-domain glossary
    technology-decisions.md             # after stage 3: the current stack
    technology-decisions-modern.md      # after stage 3: the recommended target stack
    <domain-slug>/
        overview.md                       # domain overview
        ubiquitous-language.md            # this domain's glossary
        domain-data-model.md
        external-contracts.md             # handoffs to and from other domains
        traceability.md                   # where each claim came from
        open-questions.md
        specs/<capability-slug>/spec.md   # one per business flow
        specs/quality-attributes/spec.md
        features/<capability-slug>.feature
        features/<capability-slug>.evidence.md
        changes/establish-baseline/       # the baseline scaffold, always emitted
        changes/proposed/                 # suggestions this analysis seeded, if any

SDD-Extract-Specs Model Selection

Domain spec extraction needs a large amount of code and information in a single context window. Use a model with a large context window (around 1M tokens), regardless of how strong its reasoning is. This matters even though each sub-agent is told where its domain is bounded. In customer deployments, smaller-context models have produced unreliable results on whole-codebase extraction.

SDD-Extract-Specs Before Moving On

• What SDD-Fix-Architecture Does
• Example Prompts
• What You Get
• Before Moving On

What SDD-Fix-Architecture Does

This step is optional but recommended.

Takes the architectural problems vFunction found and resolves each one in the specifications, not in the code. Every fix is written as a proposed delta under changes/pending/. No baseline spec file and no source file is ever modified. After a run, the specs still describe the architecture as it is, with the fixes alongside as proposals.

One sub-agent works each finding, in parallel by default. Four kinds of finding are covered:

SDD-Fix-Architecture Example prompts

Fix the architecture TODOs in ../specs/ (the codebase is at ./src)
Fix the circular flows in ../specs/, codebase at ./src
Remove the cross-domain dependencies in my specs at ../specs/ (source: ./src)
Fix the shared tables exclusivity issues in ../specs/

The codebase path is required. A fix cannot be judged without seeing the implementation that the specs deliberately omit.

SDD-Fix-Architecture What You Get

../specs/changes/pending/fix-NN-<scope>/           # change-level documents at the root
../specs/<domain>/changes/pending/fix-NN-<scope>/  # the per-domain delta

Each fix reports one of four outcomes, and they mean different things:

SDD-Fix-Architecture Before Moving On

Run this step before sdd-sanitize-specs, not after.

The fixers map each finding onto requirements through traceability.md and the *.evidence.md files, which are exactly the files sanitization deletes. Fixing a sanitized tree leaves the fixers working from the codebase alone, which is slower and weaker.

The same specs-directory guidance given in the Prerequisites applies here, including the Kiro recommendation to use a sub-directory such as ./specs/.

• What SDD-Sanitize-Specs Does
• Example Prompts
• What You Get
• Before Moving On

What SDD-Sanitize-Specs Does

SDD-Sanitize-Specs removes everything in the specs tree that would bias code generation toward the original implementation, so the regenerated code is written from the business requirements rather than from a description of the old code. It strips:

Along the way it settles ubiquitous-language conflicts and open questions wherever the evidence in the specs allows, and reports what it could not settle.

Have domain experts settle conflicts and open questions.

Resolving ubiquitous-language conflicts and open questions is best done by domain experts and product managers, not by AI agents. If items are left unanswered, the sanitization step will try to settle them itself, for better or worse.

It writes a sanitized copy; your original tree is never modified. It also writes a findings report. Once started, it runs to completion without asking anything, and unresolved items are collected and surfaced at the end.

Change directories are sorted rather than uniformly stripped:

SDD-Sanitize-Specs Example prompts

Sanitize the specs in ../specs into ../specs-sanitized
Get these specs ready for codegen: ../specs
Sanitize ../specs (the original codebase is at ./src if you need a tie-breaker)

As in the earlier steps, Kiro users should use a sub-directory inside the project for the specs and the sanitized output.

SDD-Sanitize-Specs What You Get

../specs-sanitized/                # the de-biased tree, ready for Skill 4: sdd-codegen
../specs-sanitized-report.md       # the findings report

SDD-Sanitize-Specs Before Moving On

Read the report, in particular:

• What SDD-Codegen Does
• Example Prompts
• What You Get
• If it refuses to run

What SDD-Codegen Does

SDD-Codegen generates the application’s code from the specifications alone. The agent does not read the original source; everything it needs was distilled into the specs. Two modes are available:

Generation is from the baseline only. Nothing under any changes/ directory is implemented, and none of it influences the dependency graph, the ordering, or a contract.

SDD-Codegen Example prompts

Generate the code from ./specs-sanitized/ into ./generated/
Generate the Billing domain from ./specs-sanitized/ into ./src/
Build the app from ./specs-sanitized/ using the modern tech stack

If both technology-decisions.md and technology-decisions-modern.md exist, you will be asked which governs the run. This is a run-wide decision made once, so answer deliberately: the current stack reproduces the application as it is, while the modern stack replatforms it.

SDD-Codegen What You Get

./generated/
  <the application's source code>
  orchestration/
    generation-order.md               # the order chosen, cycles found, forward references, rationale
    handbacks/<domain>.md             # each worker's report
    summary.md
  openspec/
    changes-applied.md                # which architectural fixes this code contains
    implementation-map/<domain>.md    # requirement -> the code implementing it

The openspec/ folder matters beyond this run. implementation-map/ is how a later change finds the code behind a given requirement instead of searching for it, and changes-applied.md is how you tell whether the code and the specs still agree.

SDD-Codegen If It Refuses To Run

sdd-codegen stops if the specs tree still carries extraction artifacts: a traceability.md, an *.evidence.md, an open-questions.md, or a source-basis tag such as [Observed] or [Derived]. This means Step 3 was skipped or did not complete successfully. Run sdd-sanitize-specs and point sdd-codegen at the sanitized copy, or complete the sanitization yourself.

• What SDD-Apply-Change Does
• Example Prompts
• What You Get

What SDD-Apply-Change Does

SDD-Apply-Change Applies one prepared change, a delta identified by its slug, to code that has already been generated. This is surgical editing of existing code, not regeneration. The specs are read-only; the run writes only inside the repository: the code, the ledger, and the implementation maps.

Run it once per change. Each run sees the previous run’s edits, which lets it notice a change arriving against code that an earlier one already moved.

SDD-Apply-Change Example prompts

Apply fix-01-orders-shipping to ./generated, specs at ./specs-sanitized
Implement the pending change fix-02-users-table in the generated repo
Bring ./generated up to date with fix-03-payment-retry from ./specs-sanitized

If you name the change loosely, you will be shown the candidates and asked to pick.

SDD-Apply-Change What You Get

The run stops to ask whenever what it finds is not what it expected:

Each of these has more than one plausible cause, so the decision is yours, not the agent’s.