speckiwi

v4.0.0

Published

16 days ago

SpecKiwi manages Git-tracked Markdown SRS requirements through a local CLI and stdio MCP server.

0High
0Medium
0Low

snoworca

srs mcp cli

SpecKiwi

SpecKiwi keeps your requirements as Markdown SRS (Software Requirements Specification) documents inside your Git repository, and gives people and coding agents the same view of them through a CLI and a stdio MCP server.

Kiwi skills are coding-agent skills built on SpecKiwi. They carry a request from requirement to commit: write the requirement, check that it is feasible, write a short design, implement it test-first, review the code, confirm the tests cover every acceptance criterion, and commit.

Requirements live in docs/spec/**/*.srs.md (GitHub-Flavored Markdown). There is no YAML, no database and no requirements server.
The CLI and the MCP server share one parser, validator, query engine and mutation engine.
Everything is a normal Git-tracked file, so requirements are reviewed and versioned like code.

Start with §1 and §2. They are all you need to begin; everything after them is reference.

1. Quick start

You need Node.js 22 or newer, Git, and a coding agent (Claude Code, Codex, OpenCode or Hermes). For a new project, run these at the top level of your Git repository. A project that already uses SpecKiwi only needs an update.

npm install -g speckiwi@latest
speckiwi init --target v0.1.0 --scope "App:APP"
speckiwi set-active-target v0.1.0
speckiwi doctor

init creates the SRS workspace under docs/spec/, registers the MCP server in .mcp.json, and installs the Kiwi skills for Claude and Codex. init --target only adds the target to the Target Map, so set-active-target makes it the target new work goes to. doctor confirms the result; in a new project it warns that no requirements exist yet, which is expected. Then reload or restart your coding agent so it starts the MCP server.

Codex does not read .mcp.json. Register the server once with codex mcp add speckiwi -- npx -y speckiwi mcp.
OpenCode or Hermes: init installs no skills for them. Run speckiwi skills install opencode all, or speckiwi skills install hermes all --global (a Hermes project install needs --dest <dir>; see Install skills for other agents). Then register npx -y speckiwi mcp as an MCP server in that agent.

Your first run

With the MCP server connected, ask for work in plain language. The Kiwi skills trigger on intent, or you can call one by name, such as /kiwi-pipeline:

Use kiwi-pipeline: a user can reset their password by email.

kiwi-pipeline runs the whole chain for that request, asking you before each step; add --auto to let it run to the end unattended. kiwi-srs allocates a Requirement ID and writes the requirement into a scope document such as docs/spec/01.app.srs.md; kiwi-srs-feasibility (when needed), kiwi-sds, kiwi-pm and kiwi-review-fix-loop then carry it to reviewed, verified code. §8 explains each step.

To write only the requirement and stop there, ask for kiwi-srs instead:

Use kiwi-srs to capture a requirement: a user can reset their password by email.

Update an existing project

If the project already uses SpecKiwi, update the package first, then refresh the project:

npm install -g speckiwi@latest
speckiwi upgrade --dry-run   # optional: read the plan first; nothing is written
speckiwi upgrade
speckiwi doctor

With a project-local install, update it with npm install speckiwi@latest and run the same commands through npx.

upgrade refreshes what the tool owns (the rules documents, the agent workflow block in AGENTS.md and CLAUDE.md, and the Kiwi skills). It fixes references to rules documents this release no longer ships in AGENTS.md and CLAUDE.md, and only reports them elsewhere. It never edits your requirements under docs/spec/. If you installed the skills globally (init -g), add --global so the global Claude and Codex copies are updated too; otherwise your agents keep loading the old global copies. On a machine without global copies, --global installs them. upgrade covers only the Claude and Codex skills; for OpenCode or Hermes, run the same speckiwi skills install command you installed them with again. Reload or restart your coding agent afterwards so it picks up the new MCP server and skills.

Coming from 3.x, also read Upgrading from 3.x to 4.0: a global kiwi-planner skill, one per agent that has it, has to be deleted by hand. §10 covers every upgrade option.

2. What to ask your agent

Find your situation, then ask your agent in plain language or call the skill by name.

| Your situation | Ask for | What happens | | --- | --- | --- | | A feature or change you can describe in a sentence or two | kiwi-pipeline: "Use kiwi-pipeline: users can export reports as CSV." | Runs the whole chain: requirement, design, test-first implementation, code review and test-sufficiency check. It asks before each step; add --auto to run it unattended. | | Work that may split into several parts, or that you cannot size | kiwi-orchestrator: "Use kiwi-orchestrator: add SSO login." | Sizes the work and picks the path itself: a single step (kiwi-tdd) for small work, parallel waves for large work. Resumable. | | An epic, a roadmap, or long research | kiwi-wave-master | Splits the work into ordered waves with a target each, and runs the waves whose dependencies are done in parallel. Resumable. | | Record a requirement only | kiwi-srs | Writes the requirement and its acceptance criteria into the SRS, then stops. | | An existing codebase with no SRS | kiwi-srs-from-code | Drafts SRS documents from the code, one per scope. | | You already changed the code | kiwi-srs-sync | Reads git diff and brings the SRS up to date. | | An urgent bug | kiwi-hot-fix | Fixes it test-first, runs regression, then syncs the SRS. | | Review local changes or PR comments | kiwi-review-fix-loop | Reviews, fixes, and reviews again. | | Commit and push, or open a PR | kiwi-commit-auto-push or kiwi-commit-auto-pr | Commits and pushes, then records the commit as evidence on the matching requirements; kiwi-commit-auto-pr also creates or updates the PR. | | "What should I do next?" | kiwi-pipeline --none-cycle | Recommends the next step without running anything. |

Not sure which one? Start with kiwi-orchestrator; it picks the path itself.

Every requirement-driven path ends with a code review, then a check that each acceptance criterion has a test citing it.

Options you may want

| Option | Effect | | --- | --- | | --serial | Runs the parallel steps of kiwi-orchestrator and kiwi-wave-master one at a time. Saying "one at a time" works too. | | --auto | Decides the user gates for you. Critical gates, such as a failure or a question only you can answer, still stop. | | --max | Verifies more strictly: more independent evaluators and a stricter pass gate. | | --mini / --loops N | Caps each verify-and-fix loop at 3 rounds, or at N rounds. |

Key terms

Target: a release that groups requirements, such as v0.1.0. The Active Target is the one new work defaults to; set it with speckiwi set-active-target.
Scope: a functional area with an ID prefix. App:APP produces IDs such as FR-APP-001.
Status: implementation and verification progress (planned, in_progress, blocked, implemented, verified, discarded).
Stability: change-control maturity (draft → evolving → stable → frozen, plus deprecated). Status and Stability are independent of each other.
SDS (Software Design Specification): a short design document an agent writes right before coding. The lite SDS at docs/sds/<sds-id>.sds.md is written for agents, not people, and is deleted once the requirements it covers are verified. Orchestrated runs commit it before that, so git history keeps it; in a kiwi-pipeline run it survives only if you committed it yourself. In the tdd work mode, a step SDS lives at docs/spec/steps/<name>/design.md instead.

3. Requirements

Node.js 22 or newer (engines.node is >=22). Nothing enforces this floor, so hold to it yourself: npm only warns with EBADENGINE unless engine-strict=true is set, and speckiwi doctor fails only below Node 18, so Node 20 passes it clean.
npm
Git. SpecKiwi finds the project root by searching upward for a Git repository. Keep docs/spec/ at the git top level: three things follow the git top level rather than the resolved root, namely the pre-commit hook init installs, the kiwi/ pipeline journal the skills pin, and the .claude / .codex skill folders. speckiwi doctor checks this as project root is the git top level.
A supported coding agent: codex, claude, opencode or hermes.

4. Install SpecKiwi

Install SpecKiwi globally to put speckiwi on your PATH:

npm install -g speckiwi@latest
speckiwi --version
speckiwi --help

Or install it into the project and run it through npx:

npm install speckiwi@latest
npx speckiwi --version

The examples in this document use the short speckiwi form. With a project-local install, put npx in front of each command.

On Windows, read Passing a value a command line cannot carry before your first mutation. Anything routed through cmd.exe (the npm .cmd shim, cmd /c, npm run, a shell: true spawn) silently cuts an argument at its first newline, and every flag written after that point is lost with the rest of the value.

Global options available on every command:

| Option | Description | | --- | --- | | --root <path> | Project root to operate on, for every command except mcp (see §6). Default: search upward from the current directory. | | --json | Write machine-readable JSON to stdout. | | --no-color | Disable ANSI color. | | --quiet | Suppress non-essential human output. | | -V, --version | Print the version. | | -h, --help | Print help for the command. |

5. Initialize a project

Run init once at the Git project root. It creates (or tops up) the SRS workspace and onboards your coding agents in one step:

speckiwi init --target v0.1.0 --scope "App:APP"

What `init` does

The whole run holds the SRS mutation lock and is idempotent. A file that already exists is reported as skipped and never overwritten unless you pass --force. The one exception is the agent-instruction block: whenever its content differs from the shipped text, it is replaced in place, whatever version it declares.

| # | Step | Result | | --- | --- | --- | | 1 | SRS scaffold | docs/spec/00.index.md (Target Map, Scope Map, Completed Work Log) and docs/spec/90.appendix.md. When the project has no scope document yet, it also creates an empty one from --scope, such as docs/spec/01.app.srs.md. The number comes from the allocator, not from --scope: it is the lowest number no .md file in docs/spec/ already uses. A project that already has scope documents gets no new one; its documents are registered under their own scope names. | | 2 | Step state | docs/spec/steps/state.md, with a Mode: wait metadata block and an empty step-state table. | | 3 | Authoring rules | docs/rule/SRS-MD-Rules-v2.5.0.md and docs/rule/SDS-MD-Rules-v2.6.0.md, the bundled SRS and SDS authoring rules. The SDS rules are at 2.6.0 because of the lite SDS profile. | | 4 | Agent instructions | Inserts or updates the SpecKiwi SRS workflow block in AGENTS.md and CLAUDE.md. A block whose content differs from the shipped text is replaced in place; a block that already matches is left untouched. | | 5 | Hooks | docs/.kiwi/hooks/{pre-commit.mjs,trace.mjs} and docs/.kiwi/trace/; a .git/hooks/pre-commit gate that delegates to the runner; .claude/settings.json (PostToolUse trace hook); .codex/hooks.json (apply_patch trace hook). An existing .git/hooks/pre-commit is never overwritten: it is reported as skipped if it already delegates to the runner, and otherwise left as it is with a warning that tells you how to connect it. The two agent hook files are reported as skipped when they exist, and --force overwrites them like every other scaffolded file. | | 6 | MCP registration | Registers the SpecKiwi stdio MCP server in .mcp.json (skipped if already there). Turn off with --no-mcp. | | 7 | Skills | Installs the bundled Kiwi skills for Claude (.claude/skills) and Codex (.agents/skills), then prunes orphaned kiwi-* skill directories that SpecKiwi installed earlier and nobody edited. Turn off with --no-skills. |

The result is reported in five arrays: created / updated / skipped / removed / warnings. Add --json for the machine-readable form.

A typical layout after the first run:

AGENTS.md                     # SpecKiwi SRS workflow block
CLAUDE.md                     # SpecKiwi SRS workflow block
.mcp.json                     # speckiwi MCP server registration
.claude/skills/kiwi-*         # Claude Kiwi skills
.claude/skills/_shared/kiwi/  # contracts the skills share
.agents/skills/kiwi-*         # Codex Kiwi skills
.agents/skills/_shared/kiwi/  # the same, for Codex
.claude/settings.json         # PostToolUse trace hook
.codex/hooks.json             # apply_patch trace hook
.git/hooks/pre-commit         # delegates to docs/.kiwi/hooks/pre-commit.mjs
docs/
├─ .kiwi/hooks/               # bundled hook runners
├─ .kiwi/trace/               # trace output written by trace.mjs
├─ rule/
│  ├─ SRS-MD-Rules-v2.5.0.md
│  └─ SDS-MD-Rules-v2.6.0.md
└─ spec/
   ├─ 00.index.md             # targets, scopes, completed work log
   ├─ 01.app.srs.md           # your first scope document
   ├─ 90.appendix.md
   └─ steps/state.md

docs/spec/00.index.md is the hub for targets, scopes and the completed work log. Requirement bodies live in docs/spec/**/*.srs.md, which is the canonical source of truth.

Two more directories appear once the skills run, and neither is edited by hand. kiwi/ holds skill-owned run state: pipeline.jsonl, waves.jsonl and the resume card. .kiwi/ at the project root holds per-run session state (locks, pm and coder state, worklog) under sessions/<run-id>/. Do not confuse either with docs/.kiwi/, which init creates for the hook runners.

`init` options

| Option | Description | | --- | --- | | --target <target> | When init creates the index, add this target (such as v0.1.0) to the Target Map as planned. It does not become the Active Target; run speckiwi set-active-target <target> for that. An existing index is left unchanged, so register a new target with speckiwi set-active-target <target> --create. | | --scope "Name:PREFIX" | Initial scope, used only when the project has no scope document yet ("App:APP" → FR-APP-001). To add a scope later, use speckiwi scaffold-scope <Name>:<PREFIX> --apply, which allocates the next document number and registers both index rows. | | --no-mcp | Do not register the MCP server in .mcp.json. | | --no-skills | Do not install the bundled Kiwi skills, and do not prune orphans. | | -g, --global | Also install or update the bundled Kiwi skills in each agent's global skills directory (Claude ~/.claude/skills, Codex ${CODEX_HOME:-~/.codex}/skills), for every agent whose home directory exists; the others are skipped with a warning. The project install still runs. No orphan prune happens at global scope, because the shared home may hold skills other projects use. | | --dry-run | Preview every step, filling created and the other arrays, without writing anything. | | --force | Overwrite existing scaffolded files instead of skipping them. This rewrites files you own, and their content is lost; no backup is kept, and the run reports the overwritten files as updated: 00.index.md (Target Map, Scope Map and Completed Work Log), 90.appendix.md, docs/spec/steps/state.md (work mode and step state), and, most painfully, the agent hook files .claude/settings.json and .codex/hooks.json, which hold your own permissions, hooks and environment settings. It also restores the two bundled hook runners under docs/.kiwi/hooks/, so local edits to them are lost too. An existing scope document is never rewritten, with or without --force. The bundled rules documents are refreshed without it. | | --ignore-lock | Bypass a stale SRS mutation lock. | | --json | Write the result as JSON. |

Exit codes: 0 success · 2 usage error (such as an unknown flag) · 5 init failure (such as a held mutation lock).

MCP parity note. The MCP init_project tool only scaffolds the SRS files. It never registers the MCP server or installs skills; those two steps belong to the CLI. So running init through an agent's MCP connection can never install skills or edit .mcp.json on its own.

6. Connect the MCP server

The Kiwi skills expect a connected SpecKiwi MCP server. speckiwi init writes this registration into .mcp.json:

{
  "mcpServers": {
    "speckiwi": {
      "command": "npx",
      "args": ["-y", "speckiwi", "mcp"]
    }
  }
}

Inside a checkout of SpecKiwi itself, init registers the local bin/speckiwi instead, so the checkout tests its own build. After init writes .mcp.json, reload or restart your agent so it launches the server. Codex does not read .mcp.json, so init leaves ~/.codex/config.toml untouched and prints the matching codex mcp add speckiwi -- … command to run instead (codex mcp add speckiwi -- npx -y speckiwi mcp in an ordinary project).

The server is started with this command:

speckiwi mcp

Run it by hand only for debugging: it waits on stdio and can look as if it hangs.

The server does not accept --root. It resolves the project root by searching upward from its own working directory, so set the client's working directory (cwd) to the project root. Started with --root, the server exits with an error.
Git worktrees. The root is bound to the server process, so a running server does not follow a worktree switch in the middle of a session; restart the agent inside the worktree instead. A session rooted in a worktree must not allocate new Requirement IDs and cannot edit the host repository's docs/spec/. Do both from the host root.

MCP tools

The Kiwi skills use MCP tools for every read and every safe SRS mutation. The matching CLI commands are a fallback for diagnostics and manual work, not the normal mutation path.

| Category | Tools | | --- | --- | | Target & goal | get_active_target, set_active_target, set_target_goal, summarize_target | | Read | list_requirements, get_requirement, list_completed_work, search_requirements, get_next_work_order | | Status & stability | update_status, update_stability | | Evidence & trace | check_acceptance_criteria, add_verification_evidence, add_trace_link | | Authoring & editing | add_requirement, append_section_note, add_completed_work, edit_requirement_fields, edit_requirement_table_rows, replace_acceptance_criteria, supersede_requirement | | Work mode | get_work_mode, set_work_mode | | Steps & TDD First | claim_step, scaffold_step, validate_step, synthesize_step_srs, promote_step_requirement, update_step_state, set_sds_status, list_steps, check_vibe_gate | | Duplicate-ID repair | diagnose_requirement_id_collisions, plan_requirement_id_collision_repair, apply_requirement_id_collision_repair | | Workspace | validate_spec, sync_index, init_project, register_scopes, scaffold_scope, mcp_workspace_info | | SDS & test sufficiency | check_sds, check_test_sufficiency | | Compatibility | add_compatibility_check, refresh_compatibility_check, revoke_compatibility_check, list_compat_edges, list_dirty_edges | | Orchestrator run surface | 25 orchestrate_* tools: the run lock and journal, routing probe and freeze, the wave schedule, verification rounds, wave close, resume and replay, and the --auto gate decision. | | Workflow & pipeline | 15 workflow_* tools: pipeline emit/status/tail, worklog, artifacts (SDS files included), session status, and repair and reclassification records. |

88 tools ship in total. 4.0.0 removed the twelve plan tools along with kiwi-planner, and two orchestrate tools along with the handoff validator and the coupling check; it added check_sds and check_test_sufficiency. The table names every tool a skill calls directly; the last two rows are families whose members are documented in the skills that drive them. After an upgrade, trust the count speckiwi doctor reports, because that is what the server actually registered.

Per-call `workspaceRoot`

The MCP server resolves its root from the directory it was started in, and that root is the only place it writes SRS. A session whose server is fixed to the host checkout can still reach run state that lives in a linked worktree, and read that worktree's SRS, by passing an optional absolute workspaceRoot on each call.

| Family | workspaceRoot | | --- | --- | | workflow_* (all 15) | accepted | | orchestrate_* | accepted, except orchestrate_replay_apply (a deferred SRS mutation replays only at the host root) and orchestrate_preflight (it already takes --mcp-root and --git-root) | | The SRS query tools — list_requirements, search_requirements, get_requirement, validate_spec, summarize_target, get_active_target, list_completed_work, validate_step, get_work_mode, check_vibe_gate, list_dirty_edges, list_compat_edges, list_steps, check_sds, check_test_sufficiency | accepted; each reads the named checkout and writes nothing. Under a per-call root the test-sufficiency check refuses an SDS path under docs/spec (a step design.md), so check a step inside its worktree with speckiwi coverage --tests | | Every tool that writes under docs/spec or allocates a Requirement ID — add_requirement, update_status, supersede_requirement, sync_index, diagnose_requirement_id_collisions, plan_requirement_id_collision_repair and the rest | refused | | mcp_workspace_info and get_next_work_order | refused: the first reports which root answered, so it cannot take that root as an argument; the second assembles a work order rather than querying a checkout's SRS |

Refusal is the default. A tool accepts the argument only by declaring the workspace scope it admits: worktree-local for run state that lives in a worktree, srs-read-only for a query that reads a checkout's SRS and writes nothing. A tool that declares no scope, or misspells the one it declares, refuses the argument, so a newly added SRS tool is safe without being listed anywhere.

An accepted root must be an absolute path to an existing directory, a git top level rather than a subdirectory of one, and a worktree that shares the startup root's git common directory. Each failure is refused with its own workspace-root-* reason before the tool runs, so a path that does not exist is refused rather than created. An SRS query is also refused when the named checkout holds no docs/spec/00.index.md, and the refusal names the checkout it examined. A path argument that lands under docs/spec is refused even on a tool that accepts the root, unless the tool declares that it takes no caller-supplied path at all; that declaration is what lets an SRS query filter on a docs/spec reference.

Confirm workspace identity from the envelope before any target-scoped read or mutation. Every result carries mcpWorkspace, with workspaceRoot, rootSource, indexPath and packageVersion. rootSource is server-cwd-discovery, auto-init or per-call-workspace-root. It is per-call-workspace-root exactly when the call supplied a workspaceRoot that passed every gate, so every answer names the root it came from.

7. Kiwi skills

Writing requirements

| Skill | What it does | | --- | --- | | kiwi-srs | Analyzes a new request or a change request and registers or aligns the SRS requirements for it. | | kiwi-srs-from-code | Reverse-engineers an existing codebase into draft SRS documents, one per scope. | | kiwi-srs-feasibility | Evaluates Active Target requirements for feasibility, risk and stability. | | kiwi-srs-research | Researches ambiguous requirements, blockers, external constraints and risks. | | kiwi-srs-sync | After code-first work, reads git diff and brings the SRS up to date. | | kiwi-step | Writes step-local requirement drafts under docs/spec/steps/<name>/: claims a step, writes only inside it (never the body-scope SRS), and validates it locally. A lightweight counterpart of kiwi-srs. |

Designing and implementing

| Skill | What it does | | --- | --- | | kiwi-sds | Writes the lite SDS (docs/sds/<sds-id>.sds.md) for the requirements in scope: the files and symbols to touch, one contract per interpretation decision, and the test that proves each contract. speckiwi sds check gates it, and it is agreed without a user approval gate. --close later moves its decisions into the SRS and deletes the file. | | kiwi-pm | Runs one agreed SDS through kiwi-coder, then hands off to kiwi-review-fix-loop. When it runs on its own, it also closes the SDS around that review. | | kiwi-coder | Implements one agreed SDS: tests first (red), the smallest implementation (green), review, regression, and MCP evidence. kiwi-pm calls it; you rarely call it directly. | | kiwi-tdd | Drives one step through the tdd work mode's TDD First cycle: writes the step SDS (design.md), turns its EARS acceptance contracts into failing tests, implements to green, runs regression, then synthesizes and promotes the step requirement with evidence. | | kiwi-hot-fix | Fixes an urgent bug with TDD and regression checks, then syncs the SRS afterward. |

Reviewing and shipping

| Skill | What it does | | --- | --- | | kiwi-review-fix-loop | Reviews local changes or PR comments, fixes them and reviews again. With --close-reqs (self-review mode only) it also promotes the affected requirements to verified once regression passes with no open findings. | | kiwi-commit-auto-push | Links the Git changes to requirement evidence, then commits and pushes. | | kiwi-commit-auto-pr | Commits and pushes, then creates or updates a GitHub PR with evidence links. |

Running whole workflows

| Skill | What it does | | --- | --- | | kiwi-pipeline | Reads kiwi/pipeline.jsonl and runs the next steps. By default it runs the full cycle from kiwi-srs to kiwi-review-fix-loop; --none-cycle recommends a single next step instead. The cycle runs only when the call carries a work input, so a status question stays a status question. | | kiwi-orchestrator | Takes one work item from a single entry point, probes it, routes it to the rung it needs (step or orchestrated), and runs that rung to a recorded close. It owns the run journal (kiwi/waves.jsonl), the --auto gate table and resume. On the orchestrated rung each wave gets its own SDS and worker, and the waves run in parallel; --serial runs every parallel branch (workers, SDS authors, investigators, verifiers) one at a time (see parallel waves). Options: --auto, --max, --mini / --loops N, --work, --base-branch, --lanes N, --serial. | | kiwi-wave-master | Splits an epic, a roadmap or long research into ordered waves, registers a target per wave, and runs the waves under the same parallel contract as kiwi-orchestrator; --serial runs them one at a time instead of in parallel. Resumable through kiwi/waves.jsonl. Options: --auto, --max, --mini / --loops N, --serial, and --drive, which also opens the integration-test and cost gates that --auto alone stops at. |

The same skill set ships in three source trees, one per agent family: skills/claude (the Claude skill environment), skills/codex (Codex invocation and clarification-gate wording), and skills/etc (the Agent Skills format for OpenCode, Hermes and local LLMs, defaulting to a single evaluator/sub-agent profile).

Install skills for other agents

speckiwi init already installs the Claude and Codex project skills. Use skills install for another agent (OpenCode, Hermes), a global install, or a custom destination:

speckiwi skills install <agent> <skill|all>

speckiwi skills install codex all
speckiwi skills install claude all
speckiwi skills install opencode all
speckiwi skills install hermes all --global
speckiwi skills install codex all --dry-run --json   # preview the plan, copy nothing

| Agent | Package source | Project destination | Global destination | | --- | --- | --- | --- | | Codex | skills/codex | .agents/skills/<skill> | ${CODEX_HOME:-$HOME/.codex}/skills/<skill> | | Claude | skills/claude | .claude/skills/<skill> | $HOME/.claude/skills/<skill> | | OpenCode | skills/etc | .opencode/skills/<skill> | $HOME/.config/opencode/skills/<skill> | | Hermes | skills/etc | requires --dest <dir> | $HOME/.hermes/skills/<category>/<skill> |

| Option | Description | | --- | --- | | --global, -g | Install into the user-level skill directory. | | --dest <dir> | Install under a custom root; each skill lands in <dir>/<skill>. | | --category <name> | Category for a Hermes global install (default kiwi; Hermes global only). | | --dry-run | Print the install plan without copying files. | | --json | Write machine-readable JSON. |

--global and --dest cannot be combined. Each skill is reported as install / update / skip / conflict. A conflict (an unsafe path, or a destination that is not a valid skill) stops the run before anything is copied.

Two more skills subcommands matter only when you maintain the skill sources themselves:

speckiwi skills add <agent> <skill>    # alias of `skills install`
speckiwi skills mirror --check         # verify .agents/skills/** against skills/codex/**
speckiwi skills mirror --write         # regenerate it

.agents/skills/** is a generated copy of skills/codex/**; never edit it by hand.

8. How work flows

A new feature or change request goes through five skills: kiwi-srs → (kiwi-srs-feasibility) → kiwi-sds → kiwi-pm → kiwi-review-fix-loop --close-reqs. kiwi-pipeline runs this chain for you.

kiwi-srs writes or updates the requirement and its acceptance criteria (AC) in the SRS.
kiwi-srs-feasibility checks feasibility and stability. It runs only when a requirement is still draft or its implementability is unverified; otherwise the chain goes straight to kiwi-sds. A blocker or an ambiguity can send the work to kiwi-srs-research; since that leaves two possible next steps, the pipeline asks you which way to go.
kiwi-sds writes the lite SDS: which files to touch, which interpretation decisions to make, and which test proves each. speckiwi sds check validates it, with no user approval gate.
kiwi-pm runs the SDS through kiwi-coder, which works test-first: a failing test, the smallest change that passes it, then refactoring.
kiwi-review-fix-loop --close-reqs reviews the code, fixes what the review finds, and promotes the requirements to verified once regression passes with no open findings.

Every workflow ends the same way: a code review, then a test-sufficiency check. The check runs speckiwi coverage --tests (MCP check_test_sufficiency): every acceptance criterion in scope needs a test whose line cites <REQ-ID> AC-<n>. One subagent adds the missing tests once; a gap that remains stops the requirement from being written verified (test-sufficiency-gap). Around that check, kiwi-sds --close runs twice: before the promoting review it moves the SDS's decisions into the SRS, and after the check it deletes the SDS file.

flowchart TD
    A["User requirement or work idea"] --> B{"Choose starting point"}
    B -->|New requirement| C["kiwi-srs: Write/update SRS requirement"]
    B -->|Reverse from existing code| D["kiwi-srs-from-code: Generate SRS from code"]
    B -->|Code changed first| E["kiwi-srs-sync: Sync SRS from git diff"]
    B -->|Urgent bug| Q["kiwi-hot-fix: Urgent TDD fix"]

    C -->|draft or unverified| F["kiwi-srs-feasibility: Evaluate feasibility/stability"]
    C -->|otherwise| I
    D --> F
    E --> F
    Q --> M

    F --> G{"Blocker or ambiguity?"}
    G -->|Yes| H["kiwi-srs-research: Research risk/blocker"]
    H --> F
    G -->|No| I["kiwi-sds: Write the lite SDS (docs/sds)"]

    I --> J["kiwi-pm: Run the agreed SDS"]
    J --> K["kiwi-coder: TDD implementation of the SDS"]
    K --> X["kiwi-sds --close: Move the SDS decisions into the SRS"]
    X --> R["kiwi-review-fix-loop --close-reqs: Review/fix/re-review, promote"]
    R --> V["Test sufficiency: speckiwi coverage --tests"]
    V --> Y["kiwi-sds --close: Delete the SDS"]
    Y --> M["SpecKiwi MCP: Record evidence/status/completed-work"]
    M --> S{"PR needed?"}
    S -->|No| N["kiwi-commit-auto-push: Commit + push"]
    S -->|Yes| T["kiwi-commit-auto-pr: Commit + push + PR"]
    N --> O["Done"]
    T --> O

    P["kiwi-pipeline: Run the next step (full cycle by default)"] -.-> B
    P -.-> F
    P -.-> I
    P -.-> J
    P -.-> N

Inside kiwi-coder, the SDS runs as a TDD loop:

flowchart TD
    A["kiwi-sds output: an agreed lite SDS"] --> B["kiwi-coder reads its Interfaces, contracts and Test Plan"]
    B --> C["Read related REQ/AC: speckiwi MCP"]
    C --> D["Write failing test"]
    D --> E["Confirm red"]
    E --> F["Implement the smallest change"]
    F --> G["Confirm green"]
    G --> H["Review/formal validation/regression tests"]
    H --> I{"Issues?"}
    I -->|Yes| F
    I -->|No| J["Add MCP evidence"]
    J --> K["Check AC / update status"]
    K --> L["Update kiwi/ state and worklog"]

Step-scoped work takes a different path. In the tdd work mode, kiwi-tdd runs the TDD First cycle (step SDS → red → green → regression → promote_step_requirement) instead of going through kiwi-sds and kiwi-pm. See Work modes and steps in §9.

To choose between kiwi-pipeline, kiwi-orchestrator and kiwi-wave-master, see What to ask your agent.

Parallel waves and `--serial`

kiwi-orchestrator (on its orchestrated rung) and kiwi-wave-master split the work into waves and group the waves into stages:

Each wave gets its own SRS requirements, its own SDS and one worker in its own git worktree. The worker runs kiwi-pm for that SDS and reviews its own commits.
The waves of a stage, whose dependencies are done and whose SDS write sets do not overlap, run in parallel.
Only the host writes the SRS, one wave at a time. After the workers finish, the host merges, verifies and promotes each wave in turn, then moves on to the next stage.
--serial, or simply asking for it in words such as "one at a time", turns every parallel step into a serial one: workers, SDS authors, investigators and verifiers all run one after another, on the same code path.

Every boundary that records a pass owes a review. Both orchestrating skills must run kiwi-review-fix-loop over the commit window that each boundary judges, exactly once and with no rung exempt, and record the result on the journal line that closes the run. speckiwi orchestrate validate refuses a close that reports completion without that review, so the guarantee can be checked rather than merely claimed.

9. Command reference

This section covers the commands worth running by hand. The CLI declares 134 command specs in all; speckiwi commands --json lists every one with its arguments and options.

Validate the workspace

speckiwi validate                    # exit 0 = ok, 1 = validation failed
speckiwi validate --fail-on-warning  # treat warnings as failures
speckiwi validate --json
speckiwi explain SRS-E002            # explain a diagnostic code
speckiwi explain SRS-W073            # a requirement quotes a stale value of a shipped constant
speckiwi explain SRS-W074            # a trace link names a repository path that does not exist

SRS-W073 and SRS-W074 check the documents against the code they describe: the first fires when a requirement quotes a constant's value that the source no longer holds, the second when a trace link cites a path that is not in the tree. SDS- codes are not in this registry (explain SDS-E054 reports an unknown code); the SDS rules document describes them.

Read requirements and status

speckiwi active-target                        # resolve the Active Target
speckiwi targets                              # list registered targets
speckiwi summary --target v0.1.0              # status/stability/type rollups + blockers
speckiwi list --target v0.1.0                 # list requirements (JSON via --json)
speckiwi show FR-APP-001 --markdown           # a single requirement
speckiwi search "login timeout"               # full-text search
speckiwi scopes                               # registered scopes
speckiwi completed-work --target v0.1.0 --order latest
speckiwi doctor                               # 11 checks: spec parseability, agent block currency, rules drift and reference,
#            SDS rules install, skill mirror and install drift, git-top-level root,
#            Active Target, scope/target consistency, Node version
speckiwi doctor --json                        # the same 11 under `health`, plus 9 package/MCP
#            smoke checks under `checks`: version and lockfile agreement, the bin entrypoint,
#            packed skill entrypoints, MCP metadata and tool schemas, two reads through an
#            in-process MCP server, and one dry-run mutation through it
speckiwi doctor --fix                         # re-upsert the agent workflow blocks; writes files

--fix is the only doctor option that writes. It re-upserts the SpecKiwi SRS workflow block in AGENTS.md and CLAUDE.md when the block is missing or outdated, and touches nothing else: not the rules documents, not the skills, not docs/spec/. Use speckiwi upgrade when more than that block has drifted.

Check an SDS and test sufficiency

speckiwi sds check docs/sds/<sds-id>.sds.md                 # lite SDS diagnostics and parsed summary
speckiwi coverage --tests --target v0.1.0                    # which tests cite each acceptance criterion
speckiwi coverage --tests --ids FR-APP-001,FR-APP-002        # the same for named requirements
speckiwi coverage --tests --sds docs/sds/<sds-id>.sds.md --fail-on-gap   # also check the SDS contracts; exit non-zero on a gap

A test counts for an acceptance criterion when its line cites <REQ-ID> AC-<n>, such as it("FR-APP-001 AC-2: rejects an expired token", ...). With --sds, each SDS contract also needs a line citing SDS-AC-<n> in the test file its Test Plan row names; the requirements checked still default to the Active Target unless --ids or --target narrows them. --test-glob <glob> replaces the default test-file patterns. The MCP equivalents are check_sds and check_test_sufficiency.

Maintain the index

speckiwi sync-index            # recompute the §5/§6 rollup summaries in 00.index.md
speckiwi sync-index --dry-run

Resolve duplicate Requirement IDs after a merge

When two branches each add requirements, a merge can produce duplicate IDs (SRS-E002) and validate fails. Do not edit IDs by hand; use the guided repair workflow, which is also available as MCP tools. Choose the occurrence to keep and the one to rename explicitly, by file:line:blockHash:

speckiwi repair requirement-id-collisions diagnose --json
speckiwi repair requirement-id-collisions plan --duplicate-id <id> \
  --keep <file:line:blockHash> --rename <file:line:blockHash> --allocate-next \
  --write-plan .kiwi/id-repair.json --json
speckiwi repair requirement-id-collisions apply --plan .kiwi/id-repair.json --json

Track progress and traceability

speckiwi release-readiness --target v0.1.0   # release gate rollup
speckiwi coverage --target v0.1.0            # acceptance-criteria coverage
speckiwi rtm --target v0.1.0                 # requirements traceability matrix
speckiwi history FR-APP-001                  # change history of one requirement
speckiwi changed-since 2026-07-01            # requirements changed since a date
speckiwi stale                               # requirements with no recent activity
speckiwi attention                           # requirements needing attention
speckiwi links check                         # trace-link integrity (workflow gate)

Work modes and steps

The work mode is stored in docs/spec/steps/state.md; a new project starts in wait.

wait: the default. No Active Task; the SRS-first rules apply.
sdd: spec-driven body work. Write or adjust body-scope requirements first, then implement.
vibe: code-first. Write code against an Active Task, then synthesize the SRS afterward; vibe-gate blocks commits that were never synthesized.
tdd: the step-scoped TDD First cycle through kiwi-tdd. Write a step SDS (design.md) with EARS acceptance contracts, turn them into failing tests, implement to green, run regression, then synthesize and promote the step requirement.

speckiwi mode                                    # show the current work mode (sdd | vibe | wait | tdd)
speckiwi mode tdd                                # switch mode (sdd, vibe, wait, or tdd)
speckiwi step claim <name> --touches-scope APP   # claim a step before writing it
speckiwi step scaffold <name>                    # create design.md + intent.md stubs
speckiwi step validate <name>                    # validate a step-local draft under docs/spec/steps/<name>/
speckiwi step sds-status <name> agreed           # advance the step SDS (draft -> agreed -> superseded)
speckiwi step synthesize <name>                  # synthesize the step SRS from design.md
speckiwi step promote <id> --from-step <name> --to-scope APP   # promote into a body scope (evidence required in tdd)
speckiwi step update-state <name> --status merged              # move the step through the completion gate
speckiwi vibe-gate check                         # CI gate that blocks unsynthesized vibe/tdd commits

Mutations (MCP is the normal path; the CLI is for manual work and diagnostics)

--reason records a Change Notes row, and --dry-run previews the result without writing it.

speckiwi update-status FR-APP-001 implemented --reason "AC met, regression passed"
speckiwi update-stability FR-APP-001 stable --reason "interface finalized"
speckiwi check-ac FR-APP-001 AC-1 AC-2
speckiwi add-evidence FR-APP-001 --type command --reference "npm test" --covers all --notes "regression passed"
speckiwi add-trace FR-APP-001 --type code --reference "src/app.ts:42" --relation implements
speckiwi append-note FR-APP-001 --section rationale --text "record decision background"
speckiwi set-target-goal v0.1.0 --goal "first usable release"
speckiwi set-active-target v0.2.0
speckiwi set-target-status v0.1.0 completed   # planned|active|frozen|completed|released|archived
speckiwi add-completed-work --date 2026-07-13 --target v0.1.0 --scope APP --summary "..."

Most mutation commands accept --json, --dry-run and --ignore-lock. A failed mutation exits with 5. Discarding a protected requirement (Status verified, Stability stable or frozen, or implemented with verification evidence) is refused unless update-status also receives --confirm-discard-verified.

Status is checked on the way in. add_requirement (and speckiwi add-requirement) refuses a Status outside planned, in_progress, blocked, implemented, verified and discarded with a USAGE failure, and writes nothing. Older versions wrote the value and left validate to report SRS-E005 afterwards; the rule is the same, only the point of enforcement moved. The usual way to hit it is to run npm i -g speckiwi@latest without a following speckiwi upgrade --global: the package is current, but each agent still loads an older global skill that dictates the old value. Refresh the global skills and the calls pass again.

A bad value already written into docs/spec/ is not touched by this check, which reads only the call's input. Find it, then repair it one requirement at a time:

speckiwi validate --json          # SRS-E005 names the requirement holding it
speckiwi explain SRS-E005         # the same remediation, without parsing a workspace
speckiwi update-status FR-APP-001 planned --reason "SRS-E005 repair"

update-status validates only its own input, so it never blocks the move out of an invalid value. There is deliberately no bulk transition for this.

Passing a value a command line cannot carry

A value with a newline in it is not safe on the Windows command line. cmd.exe cuts the command line at the first newline, so the rest of the value, and every flag written after it, never reaches the process. Measured with the same arguments:

node bin/speckiwi ...  ["--statement","Line one.

Line two.","--dry-run"]
cmd /c node ...        ["--statement","Line one."]

Nothing reports this. The surviving line is a legitimate value on its own, so the command does exactly what it received; and because the --dry-run written after the newline never arrives, the write happens. The paths that go through cmd.exe are the npm .cmd shim, cmd /c, npm run, and a Node spawn with shell: true. Calling node bin/speckiwi directly, or speckiwi from PowerShell (which resolves the .ps1 shim), is not affected.

Length alone also breaks it, though more loudly. 8,191 characters still go through and 8,192 do not: cmd.exe refuses the line, the process never starts, and you get The command line is too long. (localized, so a Korean Windows says 명령줄이 너무 깁니다.). This repository's own requirements already contain a single line of 9,475 characters.

Every command registered as a mutation command accepts its whole argument object on stdin instead, which no shell rewrites:

speckiwi edit-requirement --input-json - < payload.json

PowerShell has no input redirection (< is a reserved operator there, and the line above is a parse error). Pipe the file instead, with -Raw so that the newlines survive Get-Content:

Get-Content payload.json -Raw | speckiwi edit-requirement --input-json -

payload.json holds the same arguments as a JSON object, with the newlines encoded inside JSON strings where nothing can split them:

{
  "id": "FR-APP-001",
  "statement": "The system SHALL do the first thing.\n\nAnd the second, on its own line.",
  "dryRun": true
}

The keys are the camelCase argument names, not the flag spellings. --dry-run is dryRun, --related-docs is relatedDocs, --verification-method is verificationMethod. This matters more than it looks: a key the command does not recognize is dropped without a word, so a payload saying "dry-run": true previews nothing and writes. speckiwi <command> --help --json prints the flag spellings, the wrong side of that pair; speckiwi commands --json prints each option's flag together with its payload key, so read that one when you are unsure. --input-json <json> also takes the object inline, for a value short enough to survive the command line.

The set of commands with this channel is derived from the commands actually registered as mutations, not from a list kept beside them; an earlier hand-kept list had fallen out of step twice, leaving ten commands without the channel (IR-CLI-101).

The channel is top-level only. A subcommand inside a group (anything written as workflow , step , orchestrate , repair , skills , links  or vibe-gate ) does not have it, including the ones that write: workflow worklog-emit, step promote, orchestrate journal append, repair rules-references apply, skills install. For those, keep every value on one line, or drive them through MCP, which never touches a command line. Passing --input-json to one of them is refused as unknown option rather than ignored, so this gap announces itself. speckiwi <command> --help --json tells you in advance for any single command: a JSON description means the channel is there, and commander's plain-text help means it is not.

Inspect an orchestrated run

kiwi-orchestrator and kiwi-wave-master keep their state in kiwi/waves.jsonl. These read-only commands check a run without driving it:

speckiwi orchestrate validate --run-id <id> --json          # refuse a journal that breaks a run invariant
speckiwi orchestrate validate --run-id <id> --strict        # also fail an unstamped or downgraded line
speckiwi orchestrate validate --run-id <id> \
  --engine kiwi-wave-master                                 # read the other producer's lines
speckiwi orchestrate resume --run-id <id> --json            # what a resume would pick up

--engine selects which producer's lines are read: the two engines share one file, and a reader sees only its own lines. An unrecognized value is refused rather than defaulted, because a silent fallback would validate a journal it never opened and report it clean.

The other orchestrate subcommands (route, schedule, wave, round, issue, replay, auto-gate and more) are driven by the skills, not by hand; speckiwi orchestrate --help lists them. speckiwi workflow works the same way: its subcommands (artifacts, pipeline-status, pipeline-tail, pipeline-emit, worklog-tail, session-status and more) keep kiwi/pipeline.jsonl and the run state consistent for the skills, and speckiwi workflow --help lists them.

Less common commands

speckiwi repair rules-references diagnose lists each requirement whose Related Docs row still names a rules document this release no longer ships, with the requirement ID, file, line and the replacement it would write. It changes nothing. speckiwi repair rules-references apply performs those rewrites and has no --dry-run, so read the diagnose output and commit before running it. This pair exists because upgrade does not do it: upgrade repairs references in AGENTS.md and CLAUDE.md but only reports the ones under docs/, since editing a requirement body is a governance mutation, not a migration (FR-NODE-092).
speckiwi workflow verification-ledger plan and speckiwi workflow verification-ledger record keep the heading-keyed ledger that limits a prose re-review to the sections that changed.
speckiwi workflow work-order next assembles the next work order from the Active Target.
speckiwi commands --json prints every command spec, including granular editors such as edit-requirement and edit-requirement-table-rows that the Kiwi skills drive through MCP:

speckiwi commands --json

10. Upgrade and remove

Bring an older project up to date

After updating the package, refresh the project and the global skills together:

npm install -g speckiwi@latest
speckiwi upgrade --global

speckiwi init refreshes everything the tool owns: the rules documents, the agent workflow block, the skills, and the index Rules row when there is one. By contract it never edits content you own, so in a project set up by an older version two things survive it:

a link or a sentence still naming a rules document this release no longer ships, and
an index whose metadata table has no Rules row at all (the refresh only replaces an existing row).

speckiwi upgrade closes both. It performs the migration through the init it delegates to; pass --dry-run to read the plan first:

speckiwi upgrade                  # perform it
speckiwi upgrade --dry-run        # print the plan; the workspace is untouched
speckiwi upgrade --json           # the standard mutation result envelope

Each repaired reference is reported as file:line, in both spellings: the path form (SRS-MD-Rules-v1.0.0.md) and the prose form (SRS-MD Authoring Rules v1.0.0).

What it deliberately does not do, and says so in its report: it never renumbers a scope document, never edits a requirement body under docs/spec/ (a governance mutation, not a migration), and never overwrites an existing hook. A dangling mention anywhere else under docs/ is reported, not rewritten, because a note recording which rules version a project used to follow is a record, not a defect. speckiwi doctor reports the same dangling references under Rules reference presence, so you find out even if you never run upgrade.

| Option | Description | | --- | --- | | --dry-run | Print the plan and write nothing. | | --apply | Perform the plan. This is the default; the flag is still accepted for scripts written before the default changed. Combined with --dry-run, it is refused rather than resolved by precedence. | | -g, --global | Also refresh the bundled skills in each present agent's global skills directory. | | --no-skills / --no-mcp | Skip the corresponding init step during the refresh. | | --ignore-lock | Bypass a stale SRS mutation lock. | | --json | Write the result as JSON. |

Reach for --global right after npm i -g speckiwi@latest: that is when the bundled skills are known to have changed, and without it upgrade refreshes only the project copies while each agent keeps loading the older global ones. It means the same as on init, in addition to the project and never instead of it. It never deletes: a global skill this release no longer ships is left alone, because the same home may serve another project still pinned to the version that ships it. speckiwi remove --global is what removes those.

Exit codes: 0 success · 5 failure (such as a held mutation lock, or --apply together with --dry-run; nothing is written).

upgrade is CLI-only. No MCP tool exposes it, because it rewrites files you own.

Upgrading from 3.x to 4.0

The planning step is gone. 4.0.0 removed kiwi-planner, its plan sidecar and the twelve plan tools that served it; kiwi-sds now sits where the planner was, and the lite SDS it writes is deleted once its requirements are verified.
speckiwi init and speckiwi upgrade remove a project copy of kiwi-planner that they installed and nobody edited, but init -g and upgrade -g never remove a globally installed kiwi-planner, so delete that global directory by hand (such as ~/.claude/skills/kiwi-planner or ${CODEX_HOME:-~/.codex}/skills/kiwi-planner).
Orchestrated runs split the work into waves, one SDS and one worker per wave, and run the waves of a stage in parallel (see parallel waves); --serial runs them one at a time instead.

Remove what init wired in

speckiwi remove undoes speckiwi init. It never removes your requirements: docs/spec/ is what you wrote with the tool, not what the tool wrote, and no flag opens it. docs/rule/ stays too, because the index Rules row cites it, and so does docs/.kiwi/trace/, which holds accumulated hook output with no second copy. The report names all three as deliberately kept, so you never have to guess whether they were missed.

speckiwi remove --dry-run           # read the plan; nothing is written
speckiwi remove --apply             # remove this project's wiring
speckiwi remove --global --apply    # remove the agents' GLOBAL kiwi skills instead

There is no default mode. A bare speckiwi remove is refused, because this command must never be reachable through a forgotten flag: what it deletes lives outside git or is untracked, so an unintended run cannot be recovered.

Here -g means instead of, not in addition to. This is the one place the flag reads differently from init -g, and it is deliberate: when a destructive flag is misread, the reading that removes less is the one to be wrong about. (The flag already has both meanings in this CLI: additive on init, selective on skills install.)

Nothing is deleted on the strength of its path alone. Each item is removed only against proof that speckiwi wrote it:

| What | Proof required | If the proof fails | | --- | --- | --- | | kiwi-* skill directories | install metadata naming this agent and skill, plus a checksum that still matches the install | kept: you edited it | | .mcp.json | the speckiwi key only; other servers and keys stay, and the file is never deleted | kept, reported | | .claude/settings.json, .codex/hooks.json | only the hook entry that invokes the trace runner; the file goes only if that leaves it empty | kept, reported | | .git/hooks/pre-commit, docs/.kiwi/hooks/*.mjs | byte-identical to what the installer renders | kept: you edited it | | AGENTS.md, CLAUDE.md | the managed block, bounded by both its heading and its end marker | kept: a legacy block's extent can only be guessed |

A run that kept anything exits non-zero and names what it kept. That is not a failure to fix so much as a fact you need: a removal that reports success while directories remain teaches you the tool is gone, and the next thing you do is uninstall the package that could have finished the job. For the same reason, a project-scope run tells you when managed skills are still installed globally.

speckiwi itself is installed by npm, and this command does not remove it; run npm uninstall -g speckiwi for that. The report says so.

| Option | Description | | --- | --- | | --dry-run | Print the plan and write nothing. Required unless --apply is given. | | --apply | Perform the removal. Required unless --dry-run is given. | | -g, --global | Remove the agents' global kiwi skills instead of this project's. | | --ignore-lock | Bypass a stale SRS mutation lock. | | --json | Write the result as JSON. |

Exit codes: 0 removed everything it found (including nothing to remove) · 2 no mode given, or a positional argument · 5 failure, or a run that kept something.

Like upgrade, this command is CLI-only. No MCP tool exposes it, because an agent should not drive an uninstall unattended.

11. SRS working principles

Before any change, read docs/spec/00.index.md, find the relevant Requirement ID, and cite it in your work summary. If no requirement matches, stop and ask whether to write one first.
docs/spec/**/*.srs.md is the only canonical requirements source. Never create another source of truth, and never edit generated JSON as if it were canonical.
Do not invent Requirement IDs by hand; allocate them with the SpecKiwi mutation tools.
Each requirement carries two independent lifecycle fields:
- Status tracks implementation and verification: planned, in_progress, blocked, implemented, verified, discarded.
- Stability tracks maturity and change control: draft → evolving → stable → frozen, plus deprecated. Do not implement a draft or deprecated requirement without explicit approval.
When Status is discarded or Stability is draft, the requirement heading is decorated with a [DISCARDED] or [DRAFT — pending decision] marker, which is removed when the requirement is revived.
Mark a requirement verified only after its acceptance criteria are checked and verification evidence is linked. Bulk mutations that flip many requirements to verified at once, or empty the Active Target, are blocked by the tools.
Follow TDD for behavior changes: write a failing test for the Requirement ID first, make the smallest change that passes it, then refactor.
The Kiwi skills never use raw Markdown edits as the normal mutation path; MCP tools come first.

12. Package development

From a source checkout:

npm ci
npm run build
node bin/speckiwi --help

Validation commands:

npm run typecheck
npm run typecheck:test    # test sources; narrower than the name suggests, see tsconfig.test.json
npm run lint
npm test                  # vitest, --no-file-parallelism
npm run test:coverage
npm run test:integration
npm run release:acceptance
npm run version:check
npm run release:check     # version:check, then the release gate for the Active Target
npm run perf:srs
npm run value-sites:diff

release:check reads the Active Target, so it reports on the target being worked on, not on the version in package.json. A target that still holds planned requirements is not release-ready, and the command says so.

Release baseline tag example:

git tag srs-v1.0.0-baseline

The npm package ships:

bin/
dist/
docs/rule/SRS-MD-Rules-v2.5.0.md
docs/rule/SDS-MD-Rules-v2.6.0.md
docs/.kiwi/hooks
skills/codex/
skills/claude/
skills/etc/

13. Related requirements

The behavior this document describes maps to these SpecKiwi requirements. The Target Map in docs/spec/00.index.md has the full list.

Workflow (4.0.0)

FR-FLOW-182 / FR-FLOW-183: kiwi-sds writes one lite SDS and checks it deterministically; the SDS is disposable, and close-out moves its lasting content into the SRS before deleting the file.
FR-FLOW-184 / FR-FLOW-185: the chain kiwi-srs → kiwi-srs-feasibility → kiwi-sds → kiwi-pm → kiwi-review-fix-loop, kiwi-planner removed from it, and kiwi-pm / kiwi-coder running one agreed SDS as a unit.
FR-FLOW-186: every workflow ends with a code review and a test-sufficiency check.
FR-FLOW-187 / FR-FLOW-188: one SDS per wave on the orchestrated rung, parallel waves by default, and --serial.
FR-FLOW-189: this README and the packaged documents describe 4.0.0.
FR-NODE-209 / FR-NODE-210 / IR-CLI-102 / FR-MCP-065 / FR-MCP-066: SDS lite-profile parsing, speckiwi sds check, speckiwi coverage --tests, and their MCP tools check_sds and check_test_sufficiency.
FR-NODE-211 / FR-NODE-212 / FR-NODE-213: the plan tools removed, a router with two rungs, and the wave schedule planning one lane per wave from SDS write sets.
IR-CLI-103: update-status --confirm-discard-verified.

Earlier workflow

FR-FLOW-012: the Kiwi skills require the SpecKiwi MCP for normal operation.
FR-FLOW-124 … FR-FLOW-130: the kiwi-pipeline default cycle and its single --none-cycle opt-out (2.9.0).
FR-FLOW-131 … FR-FLOW-135 / FR-NODE-188: the terminal review on every rung, and the terminal_review journal record without which the run-close validator refuses completion (2.10.0).
FR-PARSE-032 / FR-FLOW-036 / FR-FLOW-037 / FR-MCP-052: the tdd work mode, the step SDS (design.md), the kiwi-tdd skill, and get_work_mode / set_work_mode.
Targets 2.5.2-phase1-target-lifecycle, 2.6.0-phase2-parallel-lanes and the kiwi-orchestrator requirement set: the target status lifecycle, the worktree contract and the orchestrator run surface.
FR-NODE-207: the orchestrator run lock is held by lease expiry, not by the lifetime of the process that wrote it. REL-NODE-008 is its neighbor: a concurrency test that waits for the signal it needs rather than for a clock.

Install, onboarding and upgrade

FR-NODE-067 / FR-NODE-068 / FR-NODE-069 / FR-NODE-070 / IR-CLI-070: speckiwi init MCP registration, Claude/Codex skill installation, the orphan kiwi-* prune, and the shared dry-run/report envelope.
IR-CLI-027 / FR-NODE-016: speckiwi skills install <agent> <skill|all> and its core service.
MIG-FLOW-002: the skills/etc variant for OpenCode and Hermes.
IR-CLI-095 / IR-CLI-096: upgrade --global, and remove, which deletes only against proof that it installed what it deletes (2.13.0).
FR-NODE-179: docs/spec/ must sit at the git top level, and doctor says so (2