@agent-ix/quoin 0.3.7 → 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 +54 -3
- package/default-modules.yaml +2 -2
- package/dist/{cli-CNlT2O2s.js → cli-CQCkDA9J.js} +69 -59
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +1 -1
- package/dist/index.js +1 -1
- package/package.json +3 -3
- package/skills/gap-analysis/SKILL.md +97 -0
- package/skills/gap-analysis/references/step-1-target-selection.md +53 -0
- package/skills/gap-analysis/references/step-2-plan-completion.md +49 -0
- package/skills/gap-analysis/references/step-3-matrix-verification.md +54 -0
- package/skills/gap-analysis/references/step-4-underspecified-code.md +63 -0
- package/skills/gap-analysis/references/step-5-semantic-review.md +51 -0
- package/skills/gap-analysis/references/step-6-specreview-artifact.md +95 -0
- package/skills/spec-to-plan/SKILL.md +29 -8
- package/skills/spec-to-plan/references/step-0-plan-selection.md +121 -0
- package/skills/spec-to-plan/references/step-1-analysis.md +23 -3
- package/skills/spec-to-plan/references/step-2-test-plan.md +4 -2
- package/skills/spec-to-plan/references/step-3-execution-plan.md +52 -25
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/templates/implementation-plan/default.md +2 -1
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/workflows/to-plan/def.yaml +4 -1
|
@@ -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.
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
43
|
-
-
|
|
44
|
-
|
|
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
|
|
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 (
|
|
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
|
-
|
|
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
|
|
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 (
|
|
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
|
|
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
|
-
|
|
94
|
-
|
|
95
|
-
|
|
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
|
|
126
|
-
- Mark parallel-ready tasks
|
|
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
|
|
143
|
+
### 7. Write the bundle index and log
|
|
129
144
|
|
|
130
|
-
|
|
131
|
-
-
|
|
132
|
-
|
|
133
|
-
|
|
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
|
-
|
|
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
|
|
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
|