Shared spec knowledge, plus extract interview into cmk:elicit

.claude-plugin/plugin.json

@@ -1,12 +1,12 @@
 {
   "name": "ai-devkit",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Documentation-first skills for AI-powered software development",
   "author": {
     "name": "CommandOSS Labs",
     "url": "https://github.com/CommandOSSLabs"
   },
   "repository": "https://github.com/CommandOSSLabs/ai-devkit",
   "license": "MIT",
-  "keywords": ["documentation", "requirements", "design", "adr", "rules", "knowledge", "devkit", "repo-setup", "local-dev", "cicd", "infra", "delivery", "tracker", "linear", "sui", "sync", "vendoring"]
+  "keywords": ["documentation", "capabilities", "traceability", "requirements", "design", "adr", "rules", "knowledge", "devkit", "repo-setup", "local-dev", "cicd", "infra", "delivery", "tracker", "linear", "sui", "sync", "vendoring"]
 }

.gitignore

@@ -61,3 +61,4 @@ docker-compose.override.yml
 **/evals-workspace/**/without_skill/
 **/evals-workspace/**/benchmark.json
 .skills/
+.worktrees/

README.md

@@ -47,7 +47,7 @@ Requirements ──▶ Design ──▶ Plan ──▶ Implement ──▶ Simpl
 
 Three principles keep the flow coherent:
 
-- **Guidance over forms.** The requirements and design skills follow shaping directives, not fixed templates — they interview when the input is still an idea and distill documents specific to your product rather than generic ones.
+- **Guidance over forms.** `cmk:elicit` interviews when the input is still an idea. The requirements and design skills follow shaping directives, not fixed templates, and distill documents specific to your product rather than generic ones.
 - **Coherence cascades.** Docs cross-reference each other, so changing one means checking what it links to and what links back. Skills detect conflicts — a design contradicting a locked decision, a term drifting from the glossary — and flag them for you to resolve instead of silently overriding.
 - **Progressive disclosure.** Every docs folder README is a concise navigation index; depth lives one level down. Agents and humans read only what the task at hand needs.
 
@@ -66,10 +66,13 @@ This devkit solves that by using structured documentation as the shared state. T
 | Skill | Purpose |
 |---|---|
 | `cmk:docs` | Bootstrap or update the `/docs` directory structure |
+| `cmk:capability-map` | Register capabilities and derive, at ask time, which specs already own a surface and what they declined |
+| `cmk:elicit` | Interview until a confirmed close package; does not write `docs/requirements/` |
 | `cmk:requirements` | Create or iterate product/feature requirements in docs/requirements/ |
 | `cmk:design` | Create or iterate distilled design in docs/design/ — system-wide or per-feature |
 | `cmk:adr` | Create or update decisions in docs/decisions/ |
 | `cmk:glossary` | Create or maintain the shared normative glossary of systems, components, and actors |
+| `cmk:trace-audit` | Mechanical docs check — requirement IDs, design citations, and capability registry integrity |
 | `cmk:codebase-docs` | Generate or update hierarchical, AI-navigable docs under `docs/ai/` |
 | `cmk:learn` | Extract and record non-obvious learnings and gotchas |
 | `cmk:rule` | Codify engineering standards into `docs/rules/` |
@@ -122,17 +125,26 @@ Set up the docs structure for this project
 Check if our docs structure is up to date with the latest devkit
 ```
 
-### 2. Requirements — `cmk:requirements`
+### 2. Elicit — `cmk:elicit`
 
-Define what to build and why — the upstream source of truth everything downstream references. Works from conversation, Notion/Google Docs links, or an interview when all you have is an idea.
+Interview when all you have is an idea. Stops at a confirmed close package; it does not write `docs/requirements/`.
+
+```
+Grill me on billing dashboards
+We're underspecified on the session store — walk the decisions
+```
+
+### 3. Requirements — `cmk:requirements`
+
+Define what to build and why — the upstream source of truth everything downstream references. Works from conversation, Notion/Google Docs links, or a confirmed close package from `cmk:elicit`.
 
 ```
 We just discussed the billing system requirements — save that as requirements
 Use this Notion doc to draft requirements for the new onboarding flow: [link]
 Update the requirements — we're cutting the SSO requirement from v1
 ```
 
-### 3. Design — `cmk:design`
+### 4. Design — `cmk:design`
 
 Design how to build it as an implementation-agnostic spec — system-wide or per-feature. Checks upstream requirements and decisions for conflicts; cascades accepted changes downstream.
 

docs/README.md

@@ -7,6 +7,7 @@ This directory is the source of truth for documentation in this repository.
 ```
 docs/
 ├── README.md        # this navigation map
+├── capabilities/    # capability registry → which spec owns what
 ├── decisions/       # Architecture Decision Records
 ├── requirements/    # product/project requirements
 ├── design/          # distilled system and feature design
@@ -23,6 +24,7 @@ docs/
 ## When to read what
 
 - **Any task:** [`ai/`](./ai/) — find the right source files for a topic.
+- **Before writing any spec:** [`capabilities/`](./capabilities/) — which capability already owns this surface, and what it already declined.
 - **New feature or scope change:** [`requirements/`](./requirements/) — what we're building and why.
 - **Architecture or implementation:** [`design/`](./design/) — how a subsystem works; check [`decisions/`](./decisions/) for constraints.
 - **Writing code:** [`rules/`](./rules/) — the standards for the area you're touching.
@@ -40,6 +42,10 @@ docs/
 - `reports/` entries are named `YYYY-MM-DD-<topic>.md` and are **immutable**
   facts about a moment — never revised to stay current. Durable conclusions
   get distilled into `design/` or `runbooks/`.
+- `capabilities/INDEX.md` is the one registry of capability codes. A code is the
+  requirements doc's `ID prefix`, unique repo-wide and permanent. Rows are
+  written only after explicit confirmation; nothing under `capabilities/` is
+  generated.
 - `decisions/` entries are named `NNNN-<slug>.md`; numbers are monotonic and
   never reused.
 - Every directory has exactly one `README.md`: a map of what lives there and

docs/ai/skills/README.md

@@ -1,19 +1,22 @@
 # Skills
 
-The `cmk:*` skill packages under [`skills/`](../../../skills/): eight docs-family skills, thirteen setup-family skills, nine delivery-family skills, two knowledge-family skills, and one session-discipline skill (`cmk:interpret`). Each is a directory with a `SKILL.md` (frontmatter `name`/`description`/`version` plus the body the agent reads), and most ship a `references/` folder of guidance, templates, and conventions the workflow loads on demand.
+The `cmk:*` skill packages under [`skills/`](../../../skills/): eleven docs-family skills, thirteen setup-family skills, nine delivery-family skills, two knowledge-family skills, and one session-discipline skill (`cmk:interpret`). Each is a directory with a `SKILL.md` (frontmatter `name`/`description`/`version` plus the body the agent reads), and most ship a `references/` folder of guidance, templates, and conventions the workflow loads on demand.
 
 Docs-family skills follow the same shape: a "Workflow: Create" / "Workflow: Iterate" pair, with placement rules, shaping guidance, and templates kept out of `SKILL.md` itself and cited via "Read `references/<file>.md`" lines. Setup-family skills instead follow a facet shape (modes and/or a single workflow, plus a report-only `## Verify` section). Delivery-family skills follow a tracker-neutral phase/gate shape and never carry a `## Verify` section — that contract is setup-family only. Knowledge-family skills are reference packs with no create/iterate or phase shape at all. See [conventions.md](./conventions.md) for the exceptions and the full breakdown.
 
 ## Docs family
 
 - [adr.md](./adr.md) — `cmk:adr`, architecture decision records into `docs/decisions/`.
+- [capability-map.md](./capability-map.md) — `cmk:capability-map`, the capability registry `docs/capabilities/INDEX.md` and ask-time neighbor derivation over it.
 - [codebase-docs.md](./codebase-docs.md) — `cmk:codebase-docs`, this very skill — `docs/ai/` navigation tree.
 - [design.md](./design.md) — `cmk:design`, system-wide and feature-level design docs.
 - [docs.md](./docs.md) — `cmk:docs`, scaffolds/maintains the `/docs` directory itself.
+- [elicit.md](./elicit.md) — `cmk:elicit`, interview protocol; confirmed close package; never writes `docs/requirements/`.
 - [glossary.md](./glossary.md) — `cmk:glossary`, the repository's shared normative vocabulary.
 - [learn.md](./learn.md) — `cmk:learn`, captures non-obvious knowledge into `docs/knowledge/`.
 - [requirements.md](./requirements.md) — `cmk:requirements`, product requirements documents.
 - [rule.md](./rule.md) — `cmk:rule`, codifies engineering standards into `docs/rules/`.
+- [trace-audit.md](./trace-audit.md) — `cmk:trace-audit`, mechanical referential-integrity check across requirements, design, and the registry.
 
 ## Setup family
 

docs/ai/skills/capability-map.md

@@ -0,0 +1,28 @@
+# cmk:capability-map
+
+## What
+
+The horizontal layer of the docs tree: which capabilities exist, which part of
+the codebase each one owns, and what each one deliberately declined. Owns
+`docs/capabilities/INDEX.md` — the one registry of capability codes — and the
+ask-time neighbor derivation read over it.
+
+## Approach
+
+An Iron Law forbids a derived graph file, a cache, and any row written without
+explicit confirmation; derivation never gates, not even when it returns empty.
+An absent registry is a supported state that no-ops, not a misconfiguration.
+Two workflows: **Neighbors** derives ranked neighbors, their declined items
+attributed by code, and `owns_coverage`, completing only when the difference
+between the new work and its neighbors can be said out loud with evidence;
+**Register** adds or amends a row. Callers point at
+`references/neighbor-derivation.md` as the one home for the passes rather than
+restating them.
+
+## Where
+
+- Skill body: `skills/capability-map/SKILL.md`
+- Row grammar, code rules, card header: `skills/capability-map/references/registry-conventions.md`
+- Passes, envelope, claim rules: `skills/capability-map/references/neighbor-derivation.md`
+- Pressure-test record: `skills/capability-map/TESTS.md`
+- The registry itself: `docs/capabilities/INDEX.md`

docs/ai/skills/conventions.md

@@ -8,14 +8,14 @@ Frontmatter declares three fields the host (Claude Code or OpenCode) reads to di
 
 - `name` — `cmk:<short-name>`, used as the slash command and skill ID.
 - `description` — opens in the second person (`Use when…` / `Use whenever…`) with trigger phrases plus an **outcome noun** (the deliverable), not a workflow step list. Used by the agent to auto-select the skill from user intent. A user-invoked skill (`disable-model-invocation: true`) writes one plain human-facing line naming the deliverable instead — the agent never routes on that line.
-- `version` — `0.6.x` on `cmk:design`; `0.5.x` on `cmk:delivery-pipeline`; `0.4.x` on `cmk:cicd` (security-scanning facet) and `cmk:requirements` (Standard elicitation: close package, scope band, guards); `0.3.x` on `cmk:delivery-workflow`, `cmk:agent-instructions`, `cmk:adr`, `cmk:docs`, and `cmk:local-stack`; `0.2.0` on two docs-family skills (`learn`, `rule`) and six setup-family skills (`agent-instructions`, `agent-vendors`, `infra`, `mcp-config`, `project-layout`, `toolchain`); `0.1.x` on the rest — `repo-setup` and `sync`, `test-resources`, `rust`, and `testcontainers` (new setup-family skills), the other delivery-family skills (incl. new `cmk:delivery-simplify` at `0.1.0`), both knowledge-family skills, the two remaining docs-family skills (`codebase-docs`, `glossary`), and `cmk:interpret`.
+- `version` — `0.8.x` on `cmk:design`; `0.6.x` on `cmk:requirements` (writer; interview is `cmk:elicit`); `0.5.x` on `cmk:delivery-pipeline`; `0.4.x` on `cmk:cicd` (security-scanning facet); `0.3.x` on `cmk:delivery-workflow`, `cmk:agent-instructions`, `cmk:adr`, `cmk:docs`, and `cmk:local-stack`; `0.2.0` on two docs-family skills (`learn`, `rule`) and six setup-family skills (`agent-instructions`, `agent-vendors`, `infra`, `mcp-config`, `project-layout`, `toolchain`); `0.1.x` on the rest — `repo-setup` and `sync`, `test-resources`, `rust`, and `testcontainers` (new setup-family skills), the other delivery-family skills (incl. new `cmk:delivery-simplify` at `0.1.0`), the remaining docs-family skills (`codebase-docs`, `glossary`), `cmk:elicit` (`0.2.x`), and `cmk:interpret`.
 - `disable-model-invocation: true` — optional, fourth field only. Present on `cmk:interpret`. The closer is still `---`.
 
 No skill file references outside its own package by relative path — the rule binds a package's own references, not content it emits into a target repo; a skill that needs a target-repo artifact names it repo-root-relative, and a skill that needs another skill cites it by `cmk:` name — see `cmk:agent-vendors`.
 
-Docs-family skills (`adr`, `codebase-docs`, `design`, `docs`, `glossary`, `learn`, `requirements`, `rule`) mostly expose two phases — `Workflow: Create` and `Workflow: Iterate` — and offload long-form guidance, templates, and placement rules into `references/*.md` so the SKILL body stays scannable (`cmk:glossary` is compact enough to carry its rules inline and ships no `references/` folder). The `references/` files are loaded on demand via "Read `references/<file>.md`" lines. `cmk:requirements` and `cmk:design` pair a conventions file (placement) with a guidance file (a shaping directive rather than a fixed form) — the former fixed-form templates were retired in favor of the guidance files plus the baseline scaffold templates under `docs/templates/`.
+Docs-family skills (`adr`, `capability-map`, `codebase-docs`, `design`, `docs`, `elicit`, `glossary`, `learn`, `requirements`, `rule`, `trace-audit`) mostly expose two phases — `Workflow: Create` and `Workflow: Iterate` — and offload long-form guidance, templates, and placement rules into `references/*.md` so the SKILL body stays scannable (`cmk:glossary` is compact enough to carry its rules inline and ships no `references/` folder). The `references/` files are loaded on demand via "Read `references/<file>.md`" lines. `cmk:requirements` and `cmk:design` pair a conventions file (placement) with a guidance file (a shaping directive rather than a fixed form) — the former fixed-form templates were retired in favor of the guidance files plus the baseline scaffold templates under `docs/templates/`.
 
-Three docs-family skills break the create/iterate pattern: `cmk:learn` uses `Workflow: Extract` / `Workflow: Review`, `cmk:codebase-docs` uses Bootstrap/Update entry points with workflows behind `references/`, and `cmk:docs` uses `Modes` (Init/Update/Verify) plus a single `Workflow`. `cmk:rule` adds Audit/Gate modes (bodies in `references/`) and Promote.
+Four docs-family skills break the create/iterate pattern: `cmk:elicit` is an interview protocol (close package; never writes `docs/requirements/`), `cmk:learn` uses `Workflow: Extract` / `Workflow: Review`, `cmk:codebase-docs` uses Bootstrap/Update entry points with workflows behind `references/`, and `cmk:docs` uses `Modes` (Init/Update/Verify) plus a single `Workflow`. `cmk:rule` adds Audit/Gate modes (bodies in `references/`) and Promote.
 
 Setup-family skills (`agent-instructions`, `agent-vendors`, `cicd`, `infra`, `local-stack`, `mcp-config`, `project-layout`, `repo-setup`, `rust`, `sync`, `test-resources`, `testcontainers`, `toolchain`) don't follow create/iterate at all — every one exposes a `## Modes` section (Init/Update/Verify, or the skill's equivalents such as sync's baseline/sync/contribute) for standing up or auditing its facet, and every one ends in a report-only `## Verify` section a caller (human or `cmk:repo-setup`) can run to assess whether a target repo satisfies the facet. Verify never mutates.
 
@@ -27,8 +27,8 @@ Knowledge-family skills (`sui-sdk`, `sui-devstack`) are domain reference packs s
 
 ## Where
 - Frontmatter, on every skill: open any `skills/<name>/SKILL.md` and read lines 1–5 (1–6 when `disable-model-invocation: true` is present).
-- Skills with `references/`: `skills/adr/`, `skills/agent-instructions/`, `skills/agent-vendors/`, `skills/cicd/`, `skills/codebase-docs/`, `skills/design/`, `skills/docs/`, `skills/infra/`, `skills/learn/`, `skills/local-stack/`, `skills/project-layout/`, `skills/repo-setup/`, `skills/requirements/`, `skills/rule/`, `skills/rust/`, `skills/sync/`, `skills/test-resources/`, `skills/toolchain/`, `skills/delivery-workflow/`, `skills/discover-efforts/`, `skills/delivery-intake/`, `skills/delivery-simplify/`, `skills/delivery-review/`, `skills/delivery-ship/`, `skills/delivery-pipeline/`, `skills/sui-devstack/`, `skills/interpret/`. Skills without one: `skills/glossary/`, `skills/mcp-config/`, `skills/delivery-spec-plan/`, `skills/delivery-handoff/`, `skills/sui-sdk/`, `skills/testcontainers/`.
-- Skills with `eval.json`: `skills/agent-instructions/eval.json`, `skills/codebase-docs/eval.json`, `skills/local-stack/eval.json`, `skills/repo-setup/eval.json`, `skills/sync/eval.json`, `skills/interpret/eval.json`. No delivery-family or knowledge-family skill ships one.
+- Skills with `references/`: `skills/adr/`, `skills/agent-instructions/`, `skills/agent-vendors/`, `skills/cicd/`, `skills/codebase-docs/`, `skills/design/`, `skills/docs/`, `skills/elicit/`, `skills/infra/`, `skills/learn/`, `skills/local-stack/`, `skills/project-layout/`, `skills/repo-setup/`, `skills/requirements/`, `skills/rule/`, `skills/rust/`, `skills/sync/`, `skills/test-resources/`, `skills/toolchain/`, `skills/delivery-workflow/`, `skills/discover-efforts/`, `skills/delivery-intake/`, `skills/delivery-simplify/`, `skills/delivery-review/`, `skills/delivery-ship/`, `skills/delivery-pipeline/`, `skills/sui-devstack/`, `skills/interpret/`, `skills/capability-map/`, `skills/trace-audit/`. Skills without one: `skills/glossary/`, `skills/mcp-config/`, `skills/delivery-spec-plan/`, `skills/delivery-handoff/`, `skills/sui-sdk/`, `skills/testcontainers/`.
+- Skills with `eval.json`: `skills/agent-instructions/eval.json`, `skills/codebase-docs/eval.json`, `skills/elicit/eval.json`, `skills/local-stack/eval.json`, `skills/repo-setup/eval.json`, `skills/sync/eval.json`, `skills/interpret/eval.json`. No delivery-family or knowledge-family skill ships one.
 - The shared docs-family workflow shape: grep for `^## Workflow: Create` and `^## Workflow: Iterate` across `skills/*/SKILL.md`.
 - The shared setup-family Verify contract: grep for the exact heading `^## Verify$` across `skills/*/SKILL.md` — every hit is a setup-family skill. `skills/delivery-review/SKILL.md` has a similarly named but distinct `## Verify before acting` section (adversarial verification of review findings, not a report-only facet check) — match on the exact heading, not the prefix, to tell them apart.
 - The delivery-family tracker binding: grep for `references/linear.md` across `skills/delivery-*/SKILL.md` and `skills/discover-efforts/SKILL.md`, then confirm each hit is the sole conditional pointer line, not body prose.