@agent-ix/quoin 0.3.8 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -15,6 +15,57 @@ workflows agents need to write and validate specs directly as Markdown.
15
15
 
16
16
  `quoin` is built on the [Quire](https://github.com/agent-ix/quire-rs) document standard and validation engine by Agent-IX.
17
17
 
18
+ > **Why:** AI agents write code fast but drift from vague intent. Quoin makes the spec the source of truth — your agent authors a validated, traceable spec first, then plans and builds against it.
19
+
20
+ ## How
21
+
22
+ In Claude Code, Codex, or the coding agent of your choice:
23
+
24
+ #### 1. Ideate & Specify
25
+
26
+ Ideate, then pass your idea to `/specify`. A `specification` containing `user stories`, `functional requirements`,
27
+ `stakeholder requirements`, `non-functional requirements`, and other artifacts will be created.
28
+
29
+ ```
30
+ > /specify an electron app for tracking spice production
31
+ ```
32
+
33
+ #### 2. Spec Review
34
+
35
+ Use `/spec-review` for agent-assisted review. Multiple analysis tasks will run in parallel and output `Reviews`
36
+ with `Findings` and suggested fixes.
37
+
38
+ ```
39
+ > /spec-review review the specs for the spice production tracker.
40
+ ```
41
+
42
+ #### 3. Convert to plans
43
+
44
+ Build the test `traceability matrix` and `plan`. These skills will break the work down into a `plan`
45
+ with multiple `tasks`.
46
+
47
+ ```
48
+ > /spec-matrix /spec-to-plan prep the spice tracking app for coding
49
+ ```
50
+
51
+ #### 4. Implement!
52
+
53
+ Call `/implement-plan` to trigger your coding agent to begin work on the plan.
54
+
55
+ ```
56
+ > /implement-plan build the spice tracking app
57
+ ```
58
+
59
+ #### 5. Gap review
60
+
61
+ `/gap-analysis` validates that the `UserStory` and `Functional Requirements` are implemented and tested using the `traceability matrix`
62
+ as the guide. `/gap-analysis` will optionally perform a _semantic_ comparison of `spec`, `code`, and `tests` to ensure the
63
+ `plan` is faithfully implemented.
64
+
65
+ ```
66
+ > /gap-analysis
67
+ ```
68
+
18
69
  ## What's included
19
70
 
20
71
  The default module set defines the spec archetypes and domain-object vocabulary.
@@ -65,7 +116,7 @@ Multi-agent workflows that fan out, run lenses in parallel, and synthesize resul
65
116
  ## Install
66
117
 
67
118
  Installing quoin into Claude is **two steps**: the CLI (from public npm) and the plugin
68
- that adds the [skills](#skills) and [workflows](#workflows) to Claude Code. No Anthropic API
119
+ that adds the [skills](#agent-skills) and [workflows](#agent-workflows) to Claude Code. No Anthropic API
69
120
  key is required — your Claude subscription is used.
70
121
 
71
122
  **1. Install the CLIs** (`quoin` plus `ix-flow`, which runs the workflow lifecycle commands):
@@ -89,9 +140,9 @@ the agent.
89
140
  ### skills & workflows
90
141
 
91
142
  The primary way users author specs is by asking an agent, which invokes the bundled
92
- [skills](#skills) and [workflows](#workflows).
143
+ [skills](#agent-skills) and [workflows](#agent-workflows).
93
144
 
94
- ### ClI commands
145
+ ### CLI commands
95
146
 
96
147
  Inspect the spec vocabulary and manage installed modules:
97
148
 
@@ -28,13 +28,13 @@ entries:
28
28
  ref: v0.2.0
29
29
 
30
30
  - name: spec-artifacts-process
31
- version: "0.3.0"
31
+ version: "0.4.0"
32
32
  defaultEnabled: true
33
33
  source:
34
34
  type: git-subdir
35
35
  url: agent-ix/spec-artifacts-process
36
36
  path: spec_artifacts_process
37
- ref: v0.3.0
37
+ ref: v0.4.0
38
38
 
39
39
  - name: spec-objects-business
40
40
  version: "0.3.0"
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@agent-ix/quoin",
3
- "description": "Spec workflow and catalog CLI for Agent IX.",
4
- "version": "0.3.8",
3
+ "description": "Spec-driven development for Claude Code — author validated, ISO/IEC/IEEE 29148-aligned specs, then plan and build against them.",
4
+ "version": "0.4.0",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "files": [
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: gap-analysis
3
+ description: Verify a targeted plan is complete and validated — every task done, the Test
4
+ Matrix backed by real tracking tags in tests, and code fully traced to spec (flagging
5
+ underspecified code with no owning requirement). Optional semantic review checks that
6
+ intent↔test↔code actually agree. Emits a quire-validated SpecReview artifact to
7
+ reviews/YY-MM-DD-<slug>.md.
8
+ ---
9
+
10
+ # Gap Analysis
11
+
12
+ Use this skill as a **post-implementation verification gate** for one targeted plan.
13
+ It answers three questions and, on request, a fourth:
14
+
15
+ 1. **Is the plan done?** Every `Task` in the targeted plan bundle is `status: done`.
16
+ 2. **Is the Test Matrix real?** Every Test Case in the matrix is backed by an actual test
17
+ carrying a matching **tracking tag** (`TC-xxx`, `FR-xxx-AC-x`) in the test code.
18
+ 3. **Is anything unspecified?** Code/behavior exists with **no owning** StR/US/FR/NFR
19
+ (the reverse, code→spec gap).
20
+ 4. **(optional) Does intent match reality?** For each requirement↔test↔code triple — does
21
+ the test validate the requirement's *intent*, does the test actually exercise the code,
22
+ and does the code match the requirement's intent.
23
+
24
+ The result is a single **quire-validated `SpecReview`** document (`analysis: gap-analysis`)
25
+ written to `reviews/YY-MM-DD-<slug>.md`, with a **Verdict** (PASS / CONDITIONAL / FAIL)
26
+ and a validated **Findings** table.
27
+
28
+ ## When to use
29
+
30
+ - After `implement-plan` (or any implementation effort) to confirm a plan is genuinely
31
+ complete and verified before closing it.
32
+ - To audit drift between spec, tests, and code for an existing component.
33
+ - As a release/merge gate that produces a durable, traceable review artifact.
34
+
35
+ This skill is **read-only over the codebase** — it inspects and reports; it does not fix
36
+ code, edit the plan, or change the matrix. Its only write is the SpecReview artifact.
37
+
38
+ ## Inputs
39
+
40
+ - A target **plan bundle** `plan/<Plan-id>-<slug>/` (the user may name it; otherwise pick).
41
+ - The component **spec** (`spec/spec.md` for `org`/`name`) and **Test Matrix**
42
+ (`spec/matrix.md` or `spec/tests.md`).
43
+ - The **source** and **test** trees of the component.
44
+
45
+ ## Steps
46
+
47
+ 0. **[Target selection](references/step-1-target-selection.md)**: Resolve the plan bundle,
48
+ spec root, Test Matrix, and `org`/`component` for `ix://` URIs.
49
+ 1. **[Plan completion](references/step-2-plan-completion.md)**: Assert every `Task` is
50
+ `done`; report incomplete/blocked tasks and stale `plan.md` checkboxes.
51
+ 2. **[Matrix verification](references/step-3-matrix-verification.md)**: For every matrix
52
+ Test Case, confirm a backing test with a matching tracking tag exists; flag unbacked
53
+ rows, untracked tests, and inconsistent status markers.
54
+ 3. **[Underspecified code](references/step-4-underspecified-code.md)**: Find code/behavior
55
+ with no owning requirement (reverse gap), plus stubs masquerading as complete.
56
+ 4. **[Semantic review](references/step-5-semantic-review.md)** *(OPTIONAL — ask first)*:
57
+ Judge intent↔test↔code agreement per requirement. Skip unless the user opts in.
58
+ 5. **[SpecReview artifact](references/step-6-specreview-artifact.md)**: Write and validate
59
+ the `SpecReview` to `reviews/YY-MM-DD-<slug>.md`.
60
+
61
+ All steps required except Step 4, which is gated on user choice.
62
+
63
+ ## The optional semantic review
64
+
65
+ Steps 1–3 are mechanical and cheap. Step 4 is an expensive, judgment-heavy LLM pass.
66
+ **Before running it**, ask the user explicitly (e.g. with a yes/no choice):
67
+
68
+ > Run the optional semantic review (intent↔test↔code)? It's slower but verifies that tests
69
+ > actually validate requirement intent and exercise real code.
70
+
71
+ If yes, fan the work out (one subagent per FR or per area) for thoroughness. If no, note in
72
+ the SpecReview's Coverage section that semantic review was skipped.
73
+
74
+ ## Output
75
+
76
+ A `SpecReview` (`spec-artifacts-process` archetype) at `<project_root>/reviews/YY-MM-DD-<slug>.md`:
77
+
78
+ - Frontmatter `type: SpecReview`, `analysis: gap-analysis`, `id: SR-NNN`, `scope`,
79
+ `review_set: subset`, and `relationships:` (`reviews` → the plan, `references` → the matrix).
80
+ - Body: `## Summary`, `## Verdict` (PASS/CONDITIONAL/FAIL), `## Findings`
81
+ (validated table `ID | Severity | Summary | Refs`), `## Coverage` (rollup).
82
+
83
+ > **Note:** `reviews/` is at the **repo root** by deliberate choice for this skill, not
84
+ > `spec/reviews/`. quire validation is path-agnostic, so this is fine.
85
+
86
+ Validate before finishing:
87
+
88
+ ```
89
+ quire validate --scope <project_root> "reviews/**/*.md"
90
+ ```
91
+
92
+ ## Verdict rule
93
+
94
+ - **FAIL** — any incomplete/blocked task, any matrix Test Case with no backing tagged test,
95
+ or any `high`-severity finding.
96
+ - **CONDITIONAL** — only `medium`/`low` findings (e.g. untracked tests, minor drift).
97
+ - **PASS** — no gaps; record the single `FND-001 | low | No gaps found | -` row.
@@ -0,0 +1,53 @@
1
+ # Step 1: Target Selection
2
+
3
+ **Goal**: Resolve exactly what this run audits — one plan bundle, its spec, its Test
4
+ Matrix — and the `ix://` identity used in the output artifact.
5
+
6
+ ## Process
7
+
8
+ ### 1. Resolve the target plan
9
+
10
+ Mirror `spec-to-plan/references/step-0-plan-selection.md`:
11
+
12
+ 1. **Named in context?** If the user passed a plan id (`Plan-002`) or one was established
13
+ earlier this session, use it.
14
+ 2. **Otherwise discover.** Glob `plan/*/plan.md`, read each frontmatter `id`/`title`/`status`,
15
+ and present the list:
16
+
17
+ ```
18
+ Plans available to gap-analyze:
19
+ - Plan-001 electron-hello core app (active)
20
+ - Plan-002 packaging & distribution (active)
21
+ ```
22
+
23
+ Ask which one. One run targets **one** bundle.
24
+
25
+ ### 2. Locate the spec and Test Matrix
26
+
27
+ - **Spec root.** Single-repo: `spec/`. Multi-repo: `specs/<category>/<component>/spec/`.
28
+ - **`org` / `component`.** Read from `spec/spec.md` frontmatter (`org`, `name`). These build
29
+ the `ix://<org>/<component>/<id>` URIs used in the SpecReview `relationships:`.
30
+ - **Test Matrix.** Look for `spec/matrix.md` first, then `spec/tests.md` (both names are in
31
+ use across the ecosystem). Note its frontmatter `id` (e.g. `TestMatrix-001` / `TM-001`)
32
+ for the `references` edge.
33
+ - **Requirements.** Note the requirement files under `spec/functional/`,
34
+ `spec/non-functional/`, `spec/usecase/`, `spec/stakeholder/` — Steps 3 and 4 trace against
35
+ these ids.
36
+ - **Source / test trees.** Identify where implementation and tests live (e.g. `src/` +
37
+ `tests/`, or language-specific layout). Used in Steps 2–4.
38
+
39
+ ### 3. Hand off
40
+
41
+ State explicitly, so later steps and the artifact agree:
42
+
43
+ - target bundle path (e.g. `plan/Plan-002-packaging-distribution/`)
44
+ - spec root, matrix path + id
45
+ - `ix://<org>/<component>` prefix
46
+ - where source and tests live
47
+
48
+ ## Notes
49
+
50
+ - If there is **no** plan bundle, stop and tell the user — gap-analysis audits a plan; it
51
+ does not invent one (use `spec-to-plan` first).
52
+ - If there is **no** Test Matrix, Step 2 a/Plan checks still run, but record a `high`
53
+ finding that the matrix is missing and Step 3 cannot verify coverage.
@@ -0,0 +1,49 @@
1
+ # Step 2: Plan Completion
2
+
3
+ **Goal**: Confirm every unit of work in the targeted plan is actually finished.
4
+
5
+ ## The Task contract
6
+
7
+ Tasks in the bundle are frontmatter-typed (`type: Task`). The machine contract
8
+ (see `quoin/skills/spec-to-plan/SKILL.md`):
9
+
10
+ ```yaml
11
+ ---
12
+ id: Task-001
13
+ type: Task
14
+ status: not_started | in_progress | blocked | done
15
+ track: A | B | C | S | J | <gate-name>
16
+ priority: P0 | P1 | P2 | P3
17
+ relationships:
18
+ - { target: "ix://org/component/Task-000", type: depends_on }
19
+ - { target: "ix://org/component/FR-002", type: references } # requirement ownership
20
+ - { target: "ix://org/component/TC-004", type: verifies } # test-case trace
21
+ ---
22
+ ```
23
+
24
+ ## Process
25
+
26
+ 1. **Enumerate tasks.** Read every `plan/<Plan-id>-<slug>/tasks/Task-*.md`.
27
+ 2. **Assert completion.** For each task, check `status`:
28
+ - `done` → OK.
29
+ - `not_started` / `in_progress` / `blocked` → **finding**. Severity:
30
+ - `high` if `priority: P0`/`P1` or it is on the critical path (`track: A`/`S`).
31
+ - `medium` otherwise. `blocked` → note the blocker (its unmet `depends_on`).
32
+ 3. **Check dependency sanity.** Flag a `done` task whose `depends_on` target is **not**
33
+ `done` (out-of-order completion) as a `medium` finding.
34
+ 4. **Cross-check `plan.md` checkboxes.** `plan.md` mirrors requirements/tests as
35
+ `- [ ]` / `- [x]`. Flag (`low`) any checkbox state that contradicts task status
36
+ (e.g. an unchecked requirement whose owning task is `done`, or vice-versa) — the plan
37
+ doc is drifting from its tasks.
38
+ 5. **Record the rollup.** Count tasks `done` / total — feeds the SpecReview `## Coverage`.
39
+
40
+ ## Output of this step
41
+
42
+ A list of findings (incomplete tasks, out-of-order completion, checkbox drift) with their
43
+ `Refs` (the Task id, and the requirement/TC it owns) for the SpecReview Findings table, plus
44
+ the tasks-done/total count.
45
+
46
+ ## Notes
47
+
48
+ - Do not edit task files or `plan.md` — gap-analysis only reports. If the user wants the
49
+ plan reconciled, that's `spec-to-plan` (update flow) or `implement-plan`.
@@ -0,0 +1,54 @@
1
+ # Step 3: Test-Matrix Verification
2
+
3
+ **Goal**: Prove the Test Matrix is *real* — every Test Case it claims is backed by an actual
4
+ test in the suite, identified by a matching **tracking tag** in the test code. This is the
5
+ heart of gap-analysis: a matrix row marked ✅ means nothing unless a tagged test exists.
6
+
7
+ ## The matrix shape
8
+
9
+ Built by `spec-matrix` (`quoin/skills/spec-matrix/SKILL.md`). Key tables:
10
+
11
+ - **Test Case Summary** — `Test ID | Title | Type | Priority | Traces To | Status`, where
12
+ `Test ID` = `TC-xxx`, `Traces To` = `FR-XXX-AC-X` etc., `Status` ∈ `✅ ⚠️ ❌ 🚧`.
13
+ - **Per-requirement coverage** — StR/US/FR/NFR → AC → TC → Status tables.
14
+
15
+ ## Tracking-tag patterns in test code
16
+
17
+ Tests declare which requirement/test-case they cover via tags in the code. The ecosystem
18
+ uses these forms (grep for all of them, across `.py`/`.ts`/`.rs`):
19
+
20
+ | Form | Example |
21
+ | --- | --- |
22
+ | Docstring AC trace | `FR-007-AC-01` inside a test docstring `Description:` block |
23
+ | Docstring `Trace:` | `Trace: FR-001` |
24
+ | Module docstring | `"""Tests for FR-017: Context Management."""` |
25
+ | Test-case id comment / name | `# TC-041`, or a test whose name maps to `TC-041` |
26
+
27
+ ## Process
28
+
29
+ 1. **Parse the matrix.** Extract the set of declared Test Cases `{TC-xxx → (Traces To, Status)}`.
30
+ 2. **Index the suite.** Grep the test tree for every tracking tag form above; build
31
+ `{tag → [test file :: test name]}` for `TC-xxx`, `FR-xxx`, `FR-xxx-AC-x`.
32
+ 3. **Reconcile, producing findings:**
33
+ - **Unbacked matrix row** — a `TC-xxx` (or its `Traces To` requirement) with **no**
34
+ matching tag in any test → `high` finding (the matrix overclaims coverage).
35
+ - **Status lie** — a row marked `✅ Complete` but its test is missing, skipped
36
+ (`pytest.skip`), or its requirement has no tagged test → `high`.
37
+ - **Untracked test** — a real test that exercises behavior but carries **no** tracking
38
+ tag and is **absent** from the matrix → `medium` (coverage exists but isn't traced).
39
+ - **Marker drift** — matrix `Status` inconsistent with reality (e.g. `🚧` for a passing
40
+ tagged test, or `✅` for a `⚠️`-quality test) → `low`.
41
+ 4. **Optionally run the suite.** If the user wants execution evidence (not just static
42
+ tag-matching), run `make test` and note failures/skips against matrix rows. Don't block
43
+ on this if the environment can't run tests; say so.
44
+ 5. **Rollup.** Count matrix Test Cases backed-by-tagged-test / total — feeds `## Coverage`.
45
+
46
+ ## Output of this step
47
+
48
+ Findings (unbacked rows, status lies, untracked tests, marker drift) with `Refs` =
49
+ `TC-xxx` / `FR-xxx` / test path, plus the backed/total count.
50
+
51
+ ## Notes
52
+
53
+ - A tag match proves *traceability*, not *correctness* — whether the test is a good test is
54
+ Step 4 (underspecified/stub) and Step 5 (semantic). Keep this step about presence + trace.
@@ -0,0 +1,63 @@
1
+ # Step 4: Underspecified Code (reverse gap)
2
+
3
+ **Goal**: Find the *reverse* gap — code and behavior that exist with **no owning
4
+ requirement**, plus stubs that masquerade as complete. Steps 2–3 verify spec→code/test
5
+ coverage; this step verifies code→spec, catching scope that was implemented but never
6
+ specified.
7
+
8
+ Reuse the detection heuristics in
9
+ `~/dev/agent_skills/implementation-gap-analysis/SKILL.md` — don't reinvent them.
10
+
11
+ ## A. Untraced behavior (code with no requirement)
12
+
13
+ 1. **Inventory the surface.** List the component's real behaviors — public
14
+ functions/methods, CLI commands/flags, HTTP endpoints, events, config knobs.
15
+ 2. **Trace each to a requirement.** A behavior is *traced* if it maps to an StR/US/FR/NFR
16
+ (via the matrix `Traces To`, a requirement that describes it, or a Task `references`
17
+ edge that owns it).
18
+ 3. **Flag the untraced.** Behavior with no owning requirement → finding:
19
+ - `high` if it is user-visible or security/data-affecting (an endpoint, a CLI command, a
20
+ destructive operation) — unspecified surface area.
21
+ - `medium` for internal-but-meaningful logic with no requirement.
22
+ - `low` for trivial helpers/glue.
23
+ `Refs` = the code location (`path::symbol`).
24
+
25
+ ## B. Implied requirements from code patterns
26
+
27
+ Map suspicious patterns to the requirement that *should* exist (per the
28
+ implementation-gap-analysis table):
29
+
30
+ | Code pattern | Missing requirement type |
31
+ | --- | --- |
32
+ | Defensive code (try/catch, null guards) | Robustness (NFR) |
33
+ | Ambiguous identity/equality logic | Integrity (StR) |
34
+ | Side effects / IO in core logic | Determinism (StR) |
35
+ | Recursion / unbounded structures | Topology / limits (NFR) |
36
+ | Unmapped constraints | Traceability (FR/StR/NFR) |
37
+
38
+ Each unstated-but-implemented constraint → `medium` finding.
39
+
40
+ ## C. Stubs masquerading as complete
41
+
42
+ Scan **source** (not just tests) for hollow implementations the plan/matrix may report as
43
+ done:
44
+
45
+ | Stub | Detect | Severity |
46
+ | --- | --- | --- |
47
+ | Tiny file (≤5 lines, excl. `__init__`) | line count | high |
48
+ | `pass` / placeholder return (`{}`,`[]`,`None`,`"not implemented"`) body | grep/AST | high |
49
+ | Protocol/ABC-only with no concrete impl | structure | high |
50
+ | Re-export-only module | structure | medium (may be intentional) |
51
+ | Trivially-covered stub (≤5 lines @ 100% cov) | coverage + size | medium |
52
+
53
+ A stub behind a `done` task or a ✅ matrix row is a `high` finding (false completion).
54
+
55
+ ## Output of this step
56
+
57
+ Findings for untraced behavior, implied-but-missing requirements, and stubs, each with
58
+ `Refs` = code location, plus a count of untraced behaviors/stubs for `## Coverage`.
59
+
60
+ ## Notes
61
+
62
+ - This is the bridge to better specs: untraced behavior usually means a requirement should
63
+ be authored (`/specify`) — but gap-analysis only **reports** it; it does not author specs.
@@ -0,0 +1,51 @@
1
+ # Step 5: Semantic Review (OPTIONAL)
2
+
3
+ **Goal**: Go beyond presence and traceability to *meaning* — for each requirement↔test↔code
4
+ triple, judge whether they actually agree. This is the expensive, judgment-heavy pass.
5
+
6
+ ## Gate first
7
+
8
+ **Do not run this step unless the user opts in.** Ask explicitly:
9
+
10
+ > Run the optional semantic review (intent↔test↔code)? It's slower but verifies tests truly
11
+ > validate requirement intent and exercise real code, and that code matches intent.
12
+
13
+ If declined, skip and note "semantic review: skipped" in the SpecReview `## Coverage`.
14
+
15
+ ## What to judge (per requirement)
16
+
17
+ For each requirement (FR/US/StR) in scope, with its tagged test(s) (from Step 3) and the
18
+ code it governs (from Step 4), assess three axes:
19
+
20
+ 1. **(a) Test validates intent** — does the test actually check the *behavior the
21
+ requirement describes*, including its acceptance criteria, or only an incidental/trivial
22
+ aspect? A test tagged `FR-007-AC-1` that asserts something unrelated to AC-1 fails here.
23
+ 2. **(b) Test exercises the code** — does the test run the real implementation, or is it
24
+ hollow? Reuse the implementation-gap-analysis **test-stub / coverage-inflation**
25
+ heuristics: no assertions, weak-only assertions (`is not None`, `isinstance`),
26
+ mock-everything (no real code path), import-only, circular-mock-of-a-stub.
27
+ 3. **(c) Code matches intent** — does the implementation actually do what the requirement
28
+ says (semantics, edge cases, error behavior), or has it drifted?
29
+
30
+ Each failing axis → a finding:
31
+ - `high` — test does not validate intent **or** does not exercise code (false confidence),
32
+ or code contradicts the requirement.
33
+ - `medium` — partial validation, meaningful edge cases unchecked, minor drift.
34
+
35
+ `Refs` = `FR-xxx` + test path + `path::symbol`.
36
+
37
+ ## How to run it (thoroughness)
38
+
39
+ Fan out for breadth and independence — **one subagent per FR (or per cohesive area)**, each
40
+ returning a structured verdict per axis. Then aggregate the findings. This keeps each
41
+ judgment focused and lets many run concurrently. For a small scope, a single pass is fine.
42
+
43
+ ## Output of this step
44
+
45
+ Per-requirement semantic findings (axis a/b/c failures) with `Refs`, plus a note for
46
+ `## Coverage` that semantic review ran and over how many requirements.
47
+
48
+ ## Notes
49
+
50
+ - Keep verdicts evidence-based: quote the requirement clause, the assertion, and the code
51
+ line that justify the finding. Avoid speculative "looks wrong" calls.
@@ -0,0 +1,95 @@
1
+ # Step 6: SpecReview Artifact
2
+
3
+ **Goal**: Emit the findings from Steps 1–5 as a single **quire-validated `SpecReview`**
4
+ document with a Verdict, at `reviews/YY-MM-DD-<slug>.md`.
5
+
6
+ ## Fetch the template, then author (guardrail)
7
+
8
+ The `SpecReview` archetype lives in `spec-artifacts-process`. Fetch its skeleton first, then
9
+ author, then validate (the ecosystem direct-render-then-validate model):
10
+
11
+ ```
12
+ quoin write --types SpecReview
13
+ ```
14
+
15
+ If `quoin write` is unavailable in the working tree, read the skeleton directly from
16
+ `~/.ix/filament/modules/spec-artifacts-process/skeletons/SpecReview.md`.
17
+
18
+ ## Frontmatter
19
+
20
+ ```yaml
21
+ ---
22
+ id: SR-001 # ^[A-Z]{2,4}-[0-9]+$ — SR- default is fine; bump if SR-001 exists
23
+ title: "Gap analysis — <Plan-id> <slug>"
24
+ type: SpecReview
25
+ analysis: gap-analysis # the dedicated analysis value
26
+ scope: "plan/<Plan-id>-<slug>/, spec/matrix.md"
27
+ review_set: subset
28
+ relationships:
29
+ - { target: "ix://<org>/<component>/<Plan-id>", type: reviews }
30
+ - { target: "ix://<org>/<component>/<TestMatrix-id>", type: references }
31
+ ---
32
+ ```
33
+
34
+ `<org>`/`<component>` come from `spec/spec.md` (`org`, `name`); the `<Plan-id>` and
35
+ `<TestMatrix-id>` from Step 1.
36
+
37
+ ## Body
38
+
39
+ `## Summary` and `## Findings` are **required and validated** by `quire validate`; the others
40
+ are extra sections (allowed).
41
+
42
+ ```markdown
43
+ ## Summary
44
+
45
+ <1–2 sentences: what plan/matrix/code was audited and the headline result.>
46
+
47
+ ## Verdict
48
+
49
+ **PASS | CONDITIONAL | FAIL** — <one line justifying the gate, per the verdict rule>.
50
+
51
+ ## Findings
52
+
53
+ | ID | Severity | Summary | Refs |
54
+ | ------- | -------- | ------------------------------------------------ | ------------------ |
55
+ | FND-001 | high | Task-007 still in_progress (P0, critical path) | Task-007, FR-004 |
56
+ | FND-002 | high | Matrix TC-012 has no backing tagged test | TC-012, FR-006 |
57
+ | FND-003 | medium | `cli.ts::--force` flag has no owning requirement | cli.ts::--force |
58
+
59
+ ## Coverage
60
+
61
+ - Tasks done: X / Y
62
+ - Matrix Test Cases backed by tagged test: X / Y
63
+ - Untraced behaviors / stubs: N
64
+ - Semantic review: ran over N requirements | skipped
65
+ ```
66
+
67
+ ### Findings table contract (validated)
68
+
69
+ - Headers EXACTLY: `ID | Severity | Summary | Refs`.
70
+ - `ID` matches `^FND-\d+$`; ≥1 row.
71
+ - `Severity` ∈ `low | medium | high`.
72
+ - A clean audit still records one row: `FND-001 | low | No gaps found | -`.
73
+
74
+ ## Verdict rule
75
+
76
+ - **FAIL** — any incomplete/blocked task, any unbacked matrix Test Case, or any `high` finding.
77
+ - **CONDITIONAL** — only `medium`/`low` findings.
78
+ - **PASS** — no gaps (single `No gaps found` row).
79
+
80
+ ## Validate
81
+
82
+ ```
83
+ quire validate --scope <project_root> "reviews/**/*.md"
84
+ ```
85
+
86
+ Fix any validation error (frontmatter pattern, `analysis` enum, findings headers/ids/severity)
87
+ before reporting completion. Then tell the user the artifact path and the Verdict.
88
+
89
+ ## Notes
90
+
91
+ - File name: `reviews/<YYYY-MM-DD>-<short-slug>.md` (today's real date; slug from the plan,
92
+ e.g. `2026-06-22-plan-002-packaging`).
93
+ - `reviews/` is **repo root** for this skill (deliberate); validation is path-agnostic.
94
+ - One run → one SpecReview doc (the `analysis: gap-analysis` lens), matching the one-doc-per-
95
+ analysis model used by `quoin:spec-review`.
@@ -1,16 +1,24 @@
1
1
  ---
2
2
  name: spec-to-plan
3
- description: Convert ISO spec requirements (StR, FR, NFR) into a TDD-based project plan with dependency analysis, parallel execution tracks, quality gates, and task decomposition. Creates /plan/plan.md and /plan/tasks/.
3
+ description: Convert ISO spec requirements (StR, FR, NFR) into a TDD-based project plan with dependency analysis, parallel execution tracks, quality gates, and task decomposition. Selects or starts a plan and writes a frontmatter-typed plan bundle under plan/<Plan-id>-<slug>/ (Plan + Task + index + log).
4
4
  ---
5
5
 
6
6
  # Spec to Plan
7
7
 
8
8
  This skill provides a structured workflow for converting ISO/IEC/IEEE 29148 compliant specifications into an executable, dependency-aware project plan with parallel execution tracks and quality gates.
9
9
 
10
+ A project may hold **multiple plans** — each a named group of tasks (e.g. "core app",
11
+ "packaging", "a11y hardening"). Every plan is a self-describing **bundle** under
12
+ `plan/<Plan-id>-<slug>/` containing an `index.md`, a `log.md`, the `plan.md` itself,
13
+ and a `tasks/` directory. Plans, tasks, and the index/log files are
14
+ **frontmatter-typed** (`Plan`, `Task`, `index`, `log`) so the dependency graph and
15
+ all task metadata are machine-parseable and quire-validatable.
16
+
10
17
  ## Purpose
11
18
 
12
19
  Use this skill when:
13
- - You are starting a new implementation task based on an existing Spec.
20
+ - You are starting a new implementation effort based on an existing Spec.
21
+ - You want to add a *new* plan to a project that already has one or more.
14
22
  - You need to generate a Test Plan before writing code (TDD).
15
23
  - You want to ensure full traceability from Requirements (StR/FR/NFR) to Tests.
16
24
  - You need to identify what can be parallelized vs what must be serial.
@@ -32,13 +40,26 @@ Failure to meet these conditions WILL result in unstable tasking. If any conditi
32
40
  ## Steps
33
41
  All steps required!
34
42
 
35
- 1. **[Analysis](references/step-1-analysis.md)**: Analyze the spec structure and map dependencies.
43
+ 0. **[Plan Selection](references/step-0-plan-selection.md)**: Select an existing plan to continue, or start a new one. Skip only if the target plan is already fixed in this session's context. Scaffolds the bundle (`index.md`, `log.md`, `tasks/`).
44
+ 1. **[Analysis](references/step-1-analysis.md)**: Analyze the spec structure and map dependencies into the bundle's `plan.md`.
36
45
  2. **[Test Plan](references/step-2-test-plan.md)**: Generate the list of required tests.
37
- 3. **[Execution Plan](references/step-3-execution-plan.md)**: Derive dependency graph, critical path, parallel tracks, quality gates, and task decomposition.
46
+ 3. **[Execution Plan](references/step-3-execution-plan.md)**: Derive dependency graph, critical path, parallel tracks, quality gates, and task decomposition into frontmatter-typed `Task` files.
38
47
 
39
48
  ## Output
40
49
 
41
- This skill produces or updates:
42
- - `<project_root>/plan/plan.md`: The central living document containing requirements summary, dependency graph, execution tracks, quality gates, and test plan.
43
- - `<project_root>/plan/tasks/`: Individual task files for distribution and tracking, with status, dependencies, and subtask breakdowns.
44
- - `<project_root>/plan/tasks/README.md`: Task index showing completed work, active tracks, and coordination rules.
50
+ This skill produces or updates a **plan bundle** at `<project_root>/plan/<Plan-id>-<slug>/`:
51
+
52
+ - `plan.md` (`type: Plan`): The central living document — requirements summary,
53
+ dependency graph, execution tracks, quality gates, and test plan. Frontmatter
54
+ `relationships:` trace (`references`) the requirements the plan covers.
55
+ - `tasks/Task-NNN-<slug>.md` (`type: Task`): One file per task. Frontmatter carries
56
+ the machine contract — `status`, `track`, `priority`, and `relationships:` edges
57
+ (`depends_on` for the DAG, `references` for requirement ownership, `verifies` for
58
+ test traces). The body holds the human sections (Scope/Subtasks/Deliverables/Notes).
59
+ - `index.md` (`type: index`): `## Contents` link list to `plan.md` and every task —
60
+ the bundle's table of contents.
61
+ - `log.md` (`type: log`): `## History` of dated plan lifecycle events (plan created,
62
+ tasks added, status changes).
63
+
64
+ Validate the bundle with:
65
+ `quire validate --scope <project_root> "plan/**/*.md"`
@@ -0,0 +1,121 @@
1
+ # Step 0: Plan Selection
2
+
3
+ **Goal**: Decide which plan this run targets — continue an existing one or start a
4
+ new one — and scaffold the plan bundle so Steps 1–3 have a place to write.
5
+
6
+ A project holds **multiple plans** under `plan/`, each a bundle
7
+ `plan/<Plan-id>-<slug>/`. This step picks exactly one target bundle.
8
+
9
+ ## Process
10
+
11
+ ### 1. Resolve the target plan
12
+
13
+ 1. **Already in context?** If the user named a plan (an arg like `Plan-002`, or a
14
+ plan established earlier this session), use it and skip the prompt.
15
+ 2. **Discover existing plans.** Glob `plan/*/plan.md`. For each, read the frontmatter
16
+ `id`, `title`, and `status`. Present them:
17
+
18
+ ```
19
+ Existing plans:
20
+ - Plan-001 electron-hello core app (active)
21
+ - Plan-002 packaging & distribution (active)
22
+
23
+ Continue one of these, or start a new plan?
24
+ ```
25
+ 3. **Continue** (update an existing plan, e.g. after a spec change) → use the chosen
26
+ bundle and **update it in place** (see below). **New** → go to step 2 below.
27
+
28
+ #### Updating an existing plan
29
+
30
+ A common flow is: the spec changed (a requirement was added, edited, or removed),
31
+ now regenerate the plan. Continue the existing bundle — **never spawn a second plan
32
+ for the same effort**:
33
+
34
+ - **Diff coverage.** Re-read the current requirements and compare them to the plan's
35
+ `relationships: references` and existing `tasks/`. Identify requirements that are
36
+ new, changed, or removed.
37
+ - **Add only what's missing.** Create `Task` files for newly covered requirements,
38
+ continuing the existing `Task-NNN` numbering. Do **not** duplicate tasks that
39
+ already exist for unchanged requirements.
40
+ - **Reconcile changed/removed.** For a changed requirement, update its task's scope
41
+ and `verifies`/`references` edges. For a removed requirement, drop or mark its task
42
+ (don't silently leave an orphan).
43
+ - **Preserve progress.** Leave `status` on tasks already `in_progress`/`done` intact.
44
+ - **Update the plan doc + edges.** Extend `plan.md`'s `relationships: references` and
45
+ body (dependency graph, tracks) to include the new work.
46
+ - **Refresh index + log.** Update `index.md`'s `## Contents` for any added/removed
47
+ task files, and append a dated `log.md` `## History` entry describing the change
48
+ (e.g. "Regenerated after FR-008 added: +Task-013").
49
+
50
+ ### 2. Create a new plan bundle
51
+
52
+ 1. **Allocate the id.** Next `Plan-NNN` after the highest existing id (zero-padded
53
+ to 3 digits, e.g. `Plan-003`). If none exist, `Plan-001`.
54
+ 2. **Derive `slug` and `title`.** Slug is kebab-case, no id prefix (e.g.
55
+ `electron-hello-core`). Title is human-readable.
56
+ 3. **Scope the requirements.** Collect the requirement ids (StR/FR/NFR) this plan
57
+ covers — these become the plan's `relationships: references` edges.
58
+ 4. **Scaffold the bundle** at `plan/<Plan-id>-<slug>/`:
59
+
60
+ - `plan.md` — `type: Plan` frontmatter (Step 1 fills the body):
61
+
62
+ ```yaml
63
+ ---
64
+ id: Plan-003
65
+ title: "Packaging & distribution"
66
+ type: Plan
67
+ status: active
68
+ relationships:
69
+ - target: ix://<org>/<component>/FR-008
70
+ type: references
71
+ # …one per covered requirement
72
+ ---
73
+ ```
74
+ `<org>`/`<component>` come from the spec's `spec.md` frontmatter (`org`, `name`).
75
+
76
+ - `index.md` — `type: index`, body `## Contents` (link list; starts with `plan.md`,
77
+ grows as tasks are added in Step 3):
78
+
79
+ ```markdown
80
+ ---
81
+ type: index
82
+ title: "Plan-003 — Packaging & distribution"
83
+ description: "Contents of the Plan-003 bundle."
84
+ okf_version: "0.1"
85
+ ---
86
+ # Plan-003 — Packaging & distribution
87
+
88
+ ## Contents
89
+
90
+ * [Plan-003: Packaging & distribution](./plan.md) - Plan overview, DAG, tracks, gates.
91
+ ```
92
+
93
+ - `log.md` — `type: log`, body `## History` (dated entries; seed with creation):
94
+
95
+ ```markdown
96
+ ---
97
+ type: log
98
+ title: "Plan-003 — Update Log"
99
+ description: "Chronological log of changes to the Plan-003 bundle."
100
+ ---
101
+ # Plan-003 — Update Log
102
+
103
+ ## History
104
+
105
+ * **<YYYY-MM-DD>** — Plan created from spec; scoped to FR-008, FR-009, NFR-004.
106
+ ```
107
+
108
+ - `tasks/` — empty directory (Step 3 populates it).
109
+
110
+ ### 3. Hand off
111
+
112
+ State the resolved bundle path (e.g. `plan/Plan-003-packaging-distribution/`)
113
+ explicitly so Steps 1–3 — and any downstream skill — write to the right place.
114
+
115
+ ## Notes
116
+
117
+ - **Never write to a second plan's files** during this run. One run targets one bundle.
118
+ - Use **today's date** (real calendar date) in `log.md`; do not invent or reuse a
119
+ date from the skeleton.
120
+ - `index.md`/`log.md` follow the reserved OKF archetypes from `spec-artifacts-iso`
121
+ (`skeletons/index.md`, `skeletons/log.md`).
@@ -20,13 +20,33 @@
20
20
  - **Build a DAG**: Express dependencies as directed edges with reasons. This graph drives Step 3 execution planning.
21
21
 
22
22
  4. **Traceability Mapping**:
23
- - Create or update `/plan/plan.md` with a requirements checklist.
23
+ - Create or update the target bundle's `plan/<Plan-id>-<slug>/plan.md` (the
24
+ bundle resolved in Step 0) with a requirements checklist.
24
25
  - Include the full dependency graph with edge labels.
26
+ - Ensure the plan's frontmatter `relationships:` carries one `references` edge
27
+ per requirement the plan covers (see the frontmatter block below); this is
28
+ the machine-readable trace.
25
29
 
26
- ## Output Format (/plan/plan.md)
30
+ ## Output Format (plan/<Plan-id>-<slug>/plan.md)
31
+
32
+ The file is a `type: Plan` artifact. Frontmatter is the machine contract; the body
33
+ below is the human-facing plan. `<org>`/`<component>` come from `spec.md`
34
+ frontmatter (`org`, `name`).
27
35
 
28
36
  ```markdown
29
- # Implementation Plan: [Component Name]
37
+ ---
38
+ id: Plan-001
39
+ title: "[Component] — [plan title]"
40
+ type: Plan
41
+ status: active
42
+ relationships:
43
+ - target: ix://<org>/<component>/FR-001
44
+ type: references
45
+ - target: ix://<org>/<component>/NFR-001
46
+ type: references
47
+ # …one `references` edge per covered requirement
48
+ ---
49
+ # Implementation Plan: [Plan title]
30
50
 
31
51
  ## Requirements Summary
32
52
 
@@ -17,10 +17,12 @@
17
17
  - For each Non-Functional Requirement (NFR), define the **Verification Method** (e.g., Load Test script, Static Analysis check, Manual Inspection).
18
18
 
19
19
  4. **Structure the Plan**:
20
- - Append a "Test Plan" section to `/plan/plan.md`.
20
+ - Append a "Test Plan" section to the bundle's `plan/<Plan-id>-<slug>/plan.md`.
21
21
  - Group tests by the component/module they target.
22
+ - Note the TC ids here — Step 3 wires them onto each task as
23
+ `relationships: verifies` edges, so keep them stable.
22
24
 
23
- ## Output Format (/plan/plan.md)
25
+ ## Output Format (appended to plan/<Plan-id>-<slug>/plan.md)
24
26
 
25
27
  ```markdown
26
28
  ## Test Plan
@@ -87,12 +87,28 @@ For each track, state:
87
87
 
88
88
  ### 6. Create Task Files
89
89
 
90
- Break each track into task files under `plan/tasks/`. Each task file should contain:
90
+ Break each track into `type: Task` files under the bundle's
91
+ `plan/<Plan-id>-<slug>/tasks/`, named `Task-NNN-<slug>.md`. **Frontmatter is the
92
+ machine contract** — the DAG, ownership, and test traces live there, not in prose.
93
+ The body holds the human-facing detail.
91
94
 
92
95
  ```markdown
93
- # Task NN: [Title]
94
-
95
- Status: [not started | in progress | blocked on Task XX | complete]
96
+ ---
97
+ id: Task-002
98
+ title: "FR-002 — greeting + runtime versions"
99
+ type: Task
100
+ status: not_started # not_started | in_progress | blocked | done
101
+ track: A # parallel-track label (A/B/C/S/J/Gate…)
102
+ priority: P0 # P0 | P1 | P2 | P3
103
+ relationships:
104
+ - target: ix://<org>/<component>/Task-001
105
+ type: depends_on # DAG edge — one per upstream task
106
+ - target: ix://<org>/<component>/FR-002
107
+ type: references # requirement(s) this task owns
108
+ - target: ix://<org>/<component>/TC-004
109
+ type: verifies # test case(s) this task is verified by
110
+ ---
111
+ # Task-002: FR-002 — greeting + runtime versions
96
112
 
97
113
  ## Scope
98
114
  [What this task delivers]
@@ -100,39 +116,44 @@ Status: [not started | in progress | blocked on Task XX | complete]
100
116
  ## Subtasks
101
117
  - [ ] **[Subtask name].** [Description with key concerns.]
102
118
 
103
- ## Owns
104
- - [FR/NFR IDs]
105
-
106
- ## Dependencies
107
- - [Task IDs this depends on]
108
-
109
- ## Unblocks
110
- - [Task IDs or capabilities this enables]
111
-
112
119
  ## Deliverables
113
120
  - [Concrete outputs]
114
121
 
115
- ## Primary Tests
116
- - [TC/BC IDs from the test plan]
117
-
118
122
  ## Notes
119
123
  - [Implementation guidance, references, risk callouts]
124
+ - [Unblocks: which tasks/capabilities this enables — narrative; the authoritative
125
+ edges are the `depends_on` relationships on the downstream tasks.]
120
126
  ```
121
127
 
128
+ **Frontmatter rules:**
129
+ - `relationships.target` MUST be a full `ix://<org>/<component>/<id>` URI; `<org>`
130
+ and `<component>` come from `spec.md` frontmatter (`org`, `name`).
131
+ - Use only the registered `Task` edge verbs: `depends_on`, `verifies`, `references`.
132
+ - Encode the DAG as `depends_on` edges (not prose). One edge per direct upstream task.
133
+ - Every task carries ≥1 `references` (requirement) and ≥1 `verifies` (test) edge.
134
+ - `status`/`track`/`priority` are flat operational fields (allowed by the schema's
135
+ `additionalProperties`). Downstream tooling (and the GitHub-issue sync) reads these.
136
+
122
137
  **Task decomposition rules:**
123
138
  - Tasks should be scoped to 1-3 agent sessions of work
124
139
  - If a task bundles items with different dependencies, split it (e.g., don't bundle "build + scan" if build is done and scan is blocked)
125
- - Mark blocked tasks with what they're blocked on
126
- - Mark parallel-ready tasks explicitly so agents know they can start
140
+ - Mark blocked tasks with `status: blocked` and a `depends_on` edge to the blocker
141
+ - Mark parallel-ready tasks (`status: not_started`, no unmet `depends_on`) so agents know they can start
127
142
 
128
- ### 7. Write the Task README
143
+ ### 7. Write the bundle index and log
129
144
 
130
- Create `plan/tasks/README.md` as an index showing:
131
- - Completed tasks
132
- - Each track (critical path, parallel, post-gate)
133
- - Coordination rules (what to freeze, what not to start early, merge sequencing)
145
+ - **`index.md`** (`type: index`): update the `## Contents` link list so it points at
146
+ `plan.md` and every `Task-NNN-*.md` just created — one bullet per file with a short
147
+ description. This is the bundle's table of contents (replaces the old
148
+ `tasks/README.md`).
149
+ - **`log.md`** (`type: log`): append a dated `## History` entry recording this
150
+ planning pass (e.g. "Decomposed into 12 tasks across tracks A/B/C/S/J + 3 gates").
151
+ Use today's real calendar date.
134
152
 
135
- ## Output Format (appended to /plan/plan.md)
153
+ Coordination notes (what to freeze, what not to start early, merge sequencing) go in
154
+ the `plan.md` body — see the Output Format below.
155
+
156
+ ## Output Format (appended to plan/<Plan-id>-<slug>/plan.md)
136
157
 
137
158
  ```markdown
138
159
  ## Remaining Work
@@ -166,7 +187,13 @@ Create `plan/tasks/README.md` as an index showing:
166
187
  [ASCII timeline showing tracks running concurrently]
167
188
 
168
189
  ## Task File Mapping
169
- [Table mapping task files to track items and status]
190
+ [Table mapping Task-NNN files → track → owned requirements → status. The
191
+ authoritative status/deps live in each task's frontmatter; this table is a
192
+ human-readable mirror.]
193
+
194
+ ## Coordination Rules
195
+ [What to freeze, what not to start early, shared-file/shared-state single-writer
196
+ discipline, merge sequencing.]
170
197
  ```
171
198
 
172
199
  ## Common Mistakes to Avoid
@@ -1,7 +1,8 @@
1
1
  ---
2
- type: implementation-plan
2
+ type: Plan
3
3
  id: "{{items.plan_answers.plan.id}}"
4
4
  title: "{{items.plan_answers.plan.title}}"
5
+ status: active
5
6
  traces_to:
6
7
  - "{{items.plan_answers.plan.requirement_ids}}"
7
8
  ---
@@ -65,7 +65,10 @@ interviews:
65
65
  artifactTemplates:
66
66
  implementation_plan:
67
67
  source: templates/implementation-plan/default.md
68
- target: spec/plans/${items.plan_answers.plan.id}-${items.plan_answers.plan.slug}.md
68
+ # Plan bundle layout: plan/<Plan-id>-<slug>/plan.md (index.md, log.md and the
69
+ # tasks/ Task files are authored by the skill's Step 0 / Step 3, which read the
70
+ # same plan_answers). This template drafts the bundle's plan.md shell.
71
+ target: plan/${items.plan_answers.plan.id}-${items.plan_answers.plan.slug}/plan.md
69
72
  phase: plan_drafted
70
73
  frontmatterSchema: ImplementationPlanSchema
71
74
  recipes: