@agent-ix/quoin 0.1.3

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.
Files changed (215) hide show
  1. package/.agents/plugins/marketplace.json +14 -0
  2. package/.claude-plugin/marketplace.json +16 -0
  3. package/.claude-plugin/plugin.json +8 -0
  4. package/.codex-plugin/plugin.json +27 -0
  5. package/.github/plugin/marketplace.json +16 -0
  6. package/LICENSE +21 -0
  7. package/README.md +266 -0
  8. package/bin/quoin.js +14 -0
  9. package/default-modules.yaml +82 -0
  10. package/dist/base-DrUMkAh1.js +137 -0
  11. package/dist/base.d.ts +23 -0
  12. package/dist/base.d.ts.map +1 -0
  13. package/dist/catalog.d.ts +32 -0
  14. package/dist/catalog.d.ts.map +1 -0
  15. package/dist/cli.d.ts +18 -0
  16. package/dist/cli.d.ts.map +1 -0
  17. package/dist/cli.js +20 -0
  18. package/dist/commands/catalog/index.d.ts +2 -0
  19. package/dist/commands/catalog/index.d.ts.map +1 -0
  20. package/dist/commands/catalog/index.js +2 -0
  21. package/dist/commands/catalog/list.d.ts +11 -0
  22. package/dist/commands/catalog/list.d.ts.map +1 -0
  23. package/dist/commands/catalog/list.js +22 -0
  24. package/dist/commands/catalog/show.d.ts +13 -0
  25. package/dist/commands/catalog/show.d.ts.map +1 -0
  26. package/dist/commands/catalog/show.js +25 -0
  27. package/dist/commands/catalog/validate.d.ts +10 -0
  28. package/dist/commands/catalog/validate.d.ts.map +1 -0
  29. package/dist/commands/catalog/validate.js +27 -0
  30. package/dist/commands/config/doctor.d.ts +7 -0
  31. package/dist/commands/config/doctor.d.ts.map +1 -0
  32. package/dist/commands/config/doctor.js +15 -0
  33. package/dist/commands/config/edit.d.ts +7 -0
  34. package/dist/commands/config/edit.d.ts.map +1 -0
  35. package/dist/commands/config/edit.js +13 -0
  36. package/dist/commands/config/get.d.ts +11 -0
  37. package/dist/commands/config/get.d.ts.map +1 -0
  38. package/dist/commands/config/get.js +20 -0
  39. package/dist/commands/config/index.d.ts +2 -0
  40. package/dist/commands/config/index.d.ts.map +1 -0
  41. package/dist/commands/config/index.js +2 -0
  42. package/dist/commands/config/set.d.ts +12 -0
  43. package/dist/commands/config/set.d.ts.map +1 -0
  44. package/dist/commands/config/set.js +26 -0
  45. package/dist/commands/matrix.d.ts +14 -0
  46. package/dist/commands/matrix.d.ts.map +1 -0
  47. package/dist/commands/matrix.js +15 -0
  48. package/dist/commands/module/ensure-defaults.d.ts +8 -0
  49. package/dist/commands/module/ensure-defaults.d.ts.map +1 -0
  50. package/dist/commands/module/ensure-defaults.js +17 -0
  51. package/dist/commands/module/index.d.ts +2 -0
  52. package/dist/commands/module/index.d.ts.map +1 -0
  53. package/dist/commands/module/index.js +2 -0
  54. package/dist/commands/module/install.d.ts +11 -0
  55. package/dist/commands/module/install.d.ts.map +1 -0
  56. package/dist/commands/module/install.js +22 -0
  57. package/dist/commands/module/list.d.ts +8 -0
  58. package/dist/commands/module/list.d.ts.map +1 -0
  59. package/dist/commands/module/list.js +13 -0
  60. package/dist/commands/module/remove.d.ts +10 -0
  61. package/dist/commands/module/remove.d.ts.map +1 -0
  62. package/dist/commands/module/remove.js +16 -0
  63. package/dist/commands/plugin/deprecation.d.ts +10 -0
  64. package/dist/commands/plugin/deprecation.d.ts.map +1 -0
  65. package/dist/commands/plugin/ensure-defaults.d.ts +8 -0
  66. package/dist/commands/plugin/ensure-defaults.d.ts.map +1 -0
  67. package/dist/commands/plugin/ensure-defaults.js +12 -0
  68. package/dist/commands/plugin/index.d.ts +2 -0
  69. package/dist/commands/plugin/index.d.ts.map +1 -0
  70. package/dist/commands/plugin/index.js +2 -0
  71. package/dist/commands/plugin/install.d.ts +8 -0
  72. package/dist/commands/plugin/install.d.ts.map +1 -0
  73. package/dist/commands/plugin/install.js +12 -0
  74. package/dist/commands/plugin/list.d.ts +8 -0
  75. package/dist/commands/plugin/list.d.ts.map +1 -0
  76. package/dist/commands/plugin/list.js +12 -0
  77. package/dist/commands/plugin/remove.d.ts +8 -0
  78. package/dist/commands/plugin/remove.d.ts.map +1 -0
  79. package/dist/commands/plugin/remove.js +12 -0
  80. package/dist/commands/review.d.ts +14 -0
  81. package/dist/commands/review.d.ts.map +1 -0
  82. package/dist/commands/review.js +15 -0
  83. package/dist/commands/to-plan.d.ts +14 -0
  84. package/dist/commands/to-plan.d.ts.map +1 -0
  85. package/dist/commands/to-plan.js +15 -0
  86. package/dist/commands/update.d.ts +13 -0
  87. package/dist/commands/update.d.ts.map +1 -0
  88. package/dist/commands/update.js +34 -0
  89. package/dist/commands/write.d.ts +16 -0
  90. package/dist/commands/write.d.ts.map +1 -0
  91. package/dist/commands/write.js +33 -0
  92. package/dist/config-schema-Dp-vlxuR.js +13 -0
  93. package/dist/config-schema.d.ts +52 -0
  94. package/dist/config-schema.d.ts.map +1 -0
  95. package/dist/deprecation-fRxUHoxv.js +4 -0
  96. package/dist/flow-command-SMjCSOFg.js +88 -0
  97. package/dist/flow-command.d.ts +25 -0
  98. package/dist/flow-command.d.ts.map +1 -0
  99. package/dist/flows.d.ts +7 -0
  100. package/dist/flows.d.ts.map +1 -0
  101. package/dist/index.d.ts +11 -0
  102. package/dist/index.d.ts.map +1 -0
  103. package/dist/index.js +9 -0
  104. package/dist/modules-CW8pBK41.js +22 -0
  105. package/dist/modules.d.ts +10 -0
  106. package/dist/modules.d.ts.map +1 -0
  107. package/dist/org.d.ts +61 -0
  108. package/dist/org.d.ts.map +1 -0
  109. package/dist/plugins-GSxafyD3.js +77 -0
  110. package/dist/plugins.d.ts +13 -0
  111. package/dist/plugins.d.ts.map +1 -0
  112. package/dist/version-_1nY4KyJ.js +17 -0
  113. package/dist/version.d.ts +3 -0
  114. package/dist/version.d.ts.map +1 -0
  115. package/dist/write-CQAitcI5.js +156 -0
  116. package/dist/write.d.ts +28 -0
  117. package/dist/write.d.ts.map +1 -0
  118. package/package.json +119 -0
  119. package/skills/gap-analysis/SKILL.md +97 -0
  120. package/skills/gap-analysis/references/step-1-target-selection.md +53 -0
  121. package/skills/gap-analysis/references/step-2-plan-completion.md +49 -0
  122. package/skills/gap-analysis/references/step-3-matrix-verification.md +54 -0
  123. package/skills/gap-analysis/references/step-4-underspecified-code.md +63 -0
  124. package/skills/gap-analysis/references/step-5-semantic-review.md +51 -0
  125. package/skills/gap-analysis/references/step-6-specreview-artifact.md +95 -0
  126. package/skills/spec-app-review/SKILL.md +51 -0
  127. package/skills/spec-app-review/references/checklist.md +197 -0
  128. package/skills/spec-dependency-analysis/SKILL.md +75 -0
  129. package/skills/spec-ears-analysis/SKILL.md +89 -0
  130. package/skills/spec-evidence-analysis/SKILL.md +78 -0
  131. package/skills/spec-failure-domain-analysis/SKILL.md +44 -0
  132. package/skills/spec-ideation/SKILL.md +46 -0
  133. package/skills/spec-integrity-analysis/SKILL.md +47 -0
  134. package/skills/spec-matrix/SKILL.md +168 -0
  135. package/skills/spec-matrix/assets/test-cases/TC-001.md +35 -0
  136. package/skills/spec-matrix/assets/test-cases/TC-002.md +37 -0
  137. package/skills/spec-matrix/assets/test-cases/TC-006.md +50 -0
  138. package/skills/spec-matrix/assets/test-matrix-example.md +104 -0
  139. package/skills/spec-matrix/assets/test-matrix-template.md +123 -0
  140. package/skills/spec-matrix/workflow-assets/skills/matrix/SKILL.md +35 -0
  141. package/skills/spec-matrix/workflow-assets/skills/matrix/scripts/invariants.js +1 -0
  142. package/skills/spec-matrix/workflow-assets/skills/matrix/templates/report/default.md +30 -0
  143. package/skills/spec-matrix/workflow-assets/skills/matrix/workflows/matrix/def.yaml +82 -0
  144. package/skills/spec-object-review/SKILL.md +125 -0
  145. package/skills/spec-object-review/references/object-type-guide.md +118 -0
  146. package/skills/spec-review/SKILL.md +71 -0
  147. package/skills/spec-review/references/checklist.md +50 -0
  148. package/skills/spec-review/workflow-assets/skills/review/SKILL.md +96 -0
  149. package/skills/spec-review/workflow-assets/skills/review/scripts/invariants.js +60 -0
  150. package/skills/spec-review/workflow-assets/skills/review/workflows/review/def.yaml +68 -0
  151. package/skills/spec-risk-complexity-analysis/SKILL.md +77 -0
  152. package/skills/spec-scope-boundary-analysis/SKILL.md +86 -0
  153. package/skills/spec-security-analysis/SKILL.md +84 -0
  154. package/skills/spec-security-analysis/assets/security-analysis-example.md +89 -0
  155. package/skills/spec-security-analysis/assets/security-analysis-template.md +73 -0
  156. package/skills/spec-security-analysis/references/component-type-mapping.md +161 -0
  157. package/skills/spec-security-analysis/references/gdpr/ChII-Principles.md +58 -0
  158. package/skills/spec-security-analysis/references/gdpr/ChIII-DataSubjectRights.md +84 -0
  159. package/skills/spec-security-analysis/references/gdpr/ChIV-ControllerProcessor.md +83 -0
  160. package/skills/spec-security-analysis/references/gdpr/ChV-DataTransfers.md +62 -0
  161. package/skills/spec-security-analysis/references/gdpr/index.md +54 -0
  162. package/skills/spec-security-analysis/references/iso27001/A5-OrganizationalControls.md +64 -0
  163. package/skills/spec-security-analysis/references/iso27001/A6-PeopleControls.md +30 -0
  164. package/skills/spec-security-analysis/references/iso27001/A7-PhysicalControls.md +35 -0
  165. package/skills/spec-security-analysis/references/iso27001/A8-TechnologicalControls.md +66 -0
  166. package/skills/spec-security-analysis/references/iso27001/index.md +43 -0
  167. package/skills/spec-security-analysis/references/nist-800-53/AC-AccessControl.md +57 -0
  168. package/skills/spec-security-analysis/references/nist-800-53/AU-AuditAccountability.md +49 -0
  169. package/skills/spec-security-analysis/references/nist-800-53/CM-ConfigurationManagement.md +36 -0
  170. package/skills/spec-security-analysis/references/nist-800-53/IA-IdentificationAuthentication.md +44 -0
  171. package/skills/spec-security-analysis/references/nist-800-53/SA-SystemServicesAcquisition.md +50 -0
  172. package/skills/spec-security-analysis/references/nist-800-53/SC-SystemCommunications.md +53 -0
  173. package/skills/spec-security-analysis/references/nist-800-53/SI-SystemInformationIntegrity.md +52 -0
  174. package/skills/spec-security-analysis/references/nist-800-53/index.md +58 -0
  175. package/skills/spec-security-analysis/references/owasp-asvs/V1-Architecture.md +33 -0
  176. package/skills/spec-security-analysis/references/owasp-asvs/V10-MaliciousCode.md +33 -0
  177. package/skills/spec-security-analysis/references/owasp-asvs/V11-BusinessLogic.md +32 -0
  178. package/skills/spec-security-analysis/references/owasp-asvs/V12-Files.md +34 -0
  179. package/skills/spec-security-analysis/references/owasp-asvs/V13-API.md +34 -0
  180. package/skills/spec-security-analysis/references/owasp-asvs/V14-Configuration.md +35 -0
  181. package/skills/spec-security-analysis/references/owasp-asvs/V2-Authentication.md +36 -0
  182. package/skills/spec-security-analysis/references/owasp-asvs/V3-SessionManagement.md +35 -0
  183. package/skills/spec-security-analysis/references/owasp-asvs/V4-AccessControl.md +39 -0
  184. package/skills/spec-security-analysis/references/owasp-asvs/V5-Validation.md +37 -0
  185. package/skills/spec-security-analysis/references/owasp-asvs/V6-Cryptography.md +34 -0
  186. package/skills/spec-security-analysis/references/owasp-asvs/V7-ErrorLogging.md +37 -0
  187. package/skills/spec-security-analysis/references/owasp-asvs/V8-DataProtection.md +34 -0
  188. package/skills/spec-security-analysis/references/owasp-asvs/V9-Communication.md +32 -0
  189. package/skills/spec-security-analysis/references/owasp-asvs/index.md +59 -0
  190. package/skills/spec-security-analysis/references/soc2/CC1-ControlEnvironment.md +31 -0
  191. package/skills/spec-security-analysis/references/soc2/CC2-CommunicationInformation.md +27 -0
  192. package/skills/spec-security-analysis/references/soc2/CC3-RiskAssessment.md +29 -0
  193. package/skills/spec-security-analysis/references/soc2/CC4-MonitoringActivities.md +27 -0
  194. package/skills/spec-security-analysis/references/soc2/CC5-ControlActivities.md +28 -0
  195. package/skills/spec-security-analysis/references/soc2/CC6-LogicalPhysicalAccess.md +45 -0
  196. package/skills/spec-security-analysis/references/soc2/CC7-SystemOperations.md +42 -0
  197. package/skills/spec-security-analysis/references/soc2/CC8-ChangeManagement.md +32 -0
  198. package/skills/spec-security-analysis/references/soc2/CC9-RiskMitigation.md +34 -0
  199. package/skills/spec-security-analysis/references/soc2/index.md +46 -0
  200. package/skills/spec-security-analysis/references/standards-index.md +46 -0
  201. package/skills/spec-to-plan/SKILL.md +75 -0
  202. package/skills/spec-to-plan/references/step-0-plan-selection.md +121 -0
  203. package/skills/spec-to-plan/references/step-1-analysis.md +88 -0
  204. package/skills/spec-to-plan/references/step-2-test-plan.md +43 -0
  205. package/skills/spec-to-plan/references/step-3-execution-plan.md +218 -0
  206. package/skills/spec-to-plan/workflow-assets/skills/to-plan/SKILL.md +35 -0
  207. package/skills/spec-to-plan/workflow-assets/skills/to-plan/scripts/invariants.js +1 -0
  208. package/skills/spec-to-plan/workflow-assets/skills/to-plan/templates/implementation-plan/default.md +44 -0
  209. package/skills/spec-to-plan/workflow-assets/skills/to-plan/workflows/to-plan/def.yaml +85 -0
  210. package/skills/specify/SKILL.md +154 -0
  211. package/skills/specify/assets/app-spec-template.md +143 -0
  212. package/skills/specify/assets/spec-template.md +299 -0
  213. package/skills/specify/references/integration-tests.md +72 -0
  214. package/skills/specify/references/us-to-fr.md +40 -0
  215. package/skills/specify/references/writing-good-requirements.md +61 -0
@@ -0,0 +1,218 @@
1
+ # Step 3: Execution Plan
2
+
3
+ **Goal**: Derive an actionable execution plan with dependency-aware sequencing, parallel tracks, task decomposition, and quality gates from the requirements and test plan.
4
+
5
+ ## Why This Step Exists
6
+
7
+ A requirements checklist and test plan tell you *what* to build and *how to verify it*. They don't tell you *in what order*, *what can run in parallel*, or *where to stop and validate before proceeding*. Without execution planning:
8
+ - Serial work blocks unnecessarily when items could be parallelized
9
+ - Shared dependencies are discovered late, causing rework or duplication
10
+ - There are no gates to catch fundamental problems before downstream work is wasted
11
+ - Task tracking doesn't reflect actual progress
12
+
13
+ ## Process
14
+
15
+ ### 1. Build the Dependency Graph
16
+
17
+ For each incomplete FR and NFR, determine what it depends on and what it unblocks.
18
+
19
+ **Sources of dependency information:**
20
+ - `traces:` frontmatter in spec files (explicit upstream requirements)
21
+ - `relationships:` arrays (explicit component dependencies)
22
+ - Normative references in requirement text (e.g., "SHALL use GenericXLog" implies WAL dependency)
23
+ - Shared algorithms or data structures (e.g., two FRs that both need graph traversal)
24
+
25
+ **Key output:** A directed acyclic graph (DAG) of requirements, with edges labeled by the reason for the dependency. Write this as a text list of edges with reasons:
26
+
27
+ ```markdown
28
+ ## Dependency Graph
29
+ - `FR-007 -> FR-008, FR-009, FR-010, FR-016`
30
+ Reason: build/scan/vacuum/insert all depend on stable page and tuple layout.
31
+ - `FR-009 (graph traversal) -> FR-016 (insert), FR-010 (vacuum)`
32
+ Reason: insert and vacuum reuse the scan traversal algorithm for neighbor search.
33
+ ```
34
+
35
+ ### 2. Identify the Critical Path
36
+
37
+ The critical path is the longest serial chain through the dependency graph. Everything not on the critical path is a candidate for parallel execution.
38
+
39
+ **Method:**
40
+ 1. Topologically sort the dependency graph
41
+ 2. Identify the longest chain (by estimated effort, not just count)
42
+ 3. Mark items on this chain — these determine minimum completion time
43
+ 4. Everything else is parallelizable
44
+
45
+ **Key output:** The critical path as an ordered list, with effort estimates per step.
46
+
47
+ ### 3. Identify Shared Dependencies
48
+
49
+ Look for requirements or algorithms that appear as dependencies of multiple downstream items. These are high-value deliverables that should be extracted as explicit, testable units.
50
+
51
+ **Common patterns:**
52
+ - A traversal algorithm used by both scan and insert
53
+ - A serialization format used by both build and vacuum
54
+ - A scoring function used by both query path and maintenance path
55
+
56
+ **Key output:** List shared dependencies explicitly and mark them as discrete deliverables in the task breakdown.
57
+
58
+ ### 4. Define Quality Gates
59
+
60
+ A gate is a checkpoint where you validate a fundamental assumption before investing in downstream work. Gates prevent wasted effort.
61
+
62
+ **When to add a gate:**
63
+ - After implementing a core algorithm whose correctness determines whether the whole system works (e.g., recall measurement after implementing search)
64
+ - Before starting optimization work (confirm correctness first)
65
+ - Before starting dependent work that would need rework if the gate fails
66
+
67
+ **Gate format** (this is the thinking format; in `plan.md` the gate is rendered
68
+ **once**, as a one-liner inline in its track — see Output Format below):
69
+ ```markdown
70
+ #### Gate: [Name]
71
+ - **Measures:** [What you're validating]
72
+ - **Pass criteria:** [Specific threshold]
73
+ - **If fails:** [What to investigate before proceeding]
74
+ ```
75
+
76
+ ### 5. Decompose into Parallel Tracks
77
+
78
+ Group remaining work into tracks based on dependency relationships:
79
+
80
+ - **Track A (Critical Path):** Items that must be serial because each depends on the previous. This is the primary agent's work.
81
+ - **Track B (Parallel):** Items with no dependency on the critical path. These can start immediately on a separate agent.
82
+ - **Track C (Post-Gate):** Items that depend on a gate passing. These should not start until the gate is confirmed.
83
+
84
+ For each track, state:
85
+ - What items it contains
86
+ - What it depends on (if anything)
87
+ - Whether it can run on an independent agent
88
+
89
+ ### 6. Create Task Files
90
+
91
+ Break each track into `type: Task` files under the bundle's
92
+ `plan/<Plan-id>-<slug>/tasks/`, named `Task-NNN-<slug>.md`. **Frontmatter is the
93
+ machine contract** — the DAG, ownership, and test traces live there, not in prose.
94
+ The body holds the human-facing detail.
95
+
96
+ ```markdown
97
+ ---
98
+ id: Task-002
99
+ title: "FR-002 — greeting + runtime versions"
100
+ type: Task
101
+ status: not_started # not_started | in_progress | blocked | done
102
+ track: A # parallel-track label (A/B/C/S/J/Gate…)
103
+ priority: P0 # P0 | P1 | P2 | P3
104
+ relationships:
105
+ - target: ix://<org>/<component>/Task-001
106
+ type: depends_on # DAG edge — one per upstream task
107
+ - target: ix://<org>/<component>/FR-002
108
+ type: references # requirement(s) this task owns
109
+ - target: ix://<org>/<component>/TC-004
110
+ type: verifies # test case(s) this task is verified by
111
+ ---
112
+ # Task-002: FR-002 — greeting + runtime versions
113
+
114
+ ## Scope
115
+ [What this task delivers]
116
+
117
+ ## Subtasks
118
+ - [ ] **[Subtask name].** [Description with key concerns.]
119
+
120
+ ## Deliverables
121
+ - [Concrete outputs]
122
+
123
+ ## Notes
124
+ - [Implementation guidance, references, risk callouts]
125
+ - [Unblocks: which tasks/capabilities this enables — narrative; the authoritative
126
+ edges are the `depends_on` relationships on the downstream tasks.]
127
+ ```
128
+
129
+ **Frontmatter rules:**
130
+ - `relationships.target` MUST be a full `ix://<org>/<component>/<id>` URI; `<org>`
131
+ and `<component>` come from `spec.md` frontmatter (`org`, `name`).
132
+ - Use only the registered `Task` edge verbs: `depends_on`, `verifies`, `references`.
133
+ - Encode the DAG as `depends_on` edges (not prose). One edge per direct upstream task.
134
+ - Every task carries ≥1 `references` (requirement) and ≥1 `verifies` (test) edge.
135
+ - `status`/`track`/`priority` are flat operational fields (allowed by the schema's
136
+ `additionalProperties`). Downstream tooling (and the GitHub-issue sync) reads these.
137
+
138
+ **Task decomposition rules:**
139
+ - Tasks should be scoped to 1-3 agent sessions of work
140
+ - 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)
141
+ - Mark blocked tasks with `status: blocked` and a `depends_on` edge to the blocker
142
+ - Mark parallel-ready tasks (`status: not_started`, no unmet `depends_on`) so agents know they can start
143
+
144
+ ### 7. Write the bundle index and log
145
+
146
+ - **`index.md`** (`type: index`): update the `## Contents` link list so it points at
147
+ `plan.md` and every `Task-NNN-*.md` just created — one bullet per file with a short
148
+ description. This is the bundle's table of contents (replaces the old
149
+ `tasks/README.md`).
150
+ - **`log.md`** (`type: log`): append a dated `## History` entry recording this
151
+ planning pass (e.g. "Decomposed into 12 tasks across tracks A/B/C/S/J + 3 gates").
152
+ Use today's real calendar date.
153
+
154
+ Coordination notes (what to freeze, what not to start early, merge sequencing) go in
155
+ the `plan.md` body — see the Output Format below.
156
+
157
+ ## Output Format (appended to plan/<Plan-id>-<slug>/plan.md)
158
+
159
+ `plan.md` is an **orchestration overview, not a mirror of the bundle.** Ownership, the
160
+ DAG, and test traces are authoritative in **task frontmatter** (`references`,
161
+ `depends_on`, `verifies`). State each fact **once**: the requirement checklist in
162
+ Requirements Summary (Step 1), the dependency *reasons* in the Dependency Graph (Step 1),
163
+ the TC enumeration in the Test Plan (Step 2), and the per-task row in the Task File
164
+ Mapping below. Step 3 appends only the sections below — it does **not** re-emit the
165
+ dependency graph, add a separate "Execution Tracks" section, restate any task's
166
+ `## Scope`, or re-list TC ids per track.
167
+
168
+ ```markdown
169
+ ## Remaining Work
170
+
171
+ Describe the tracks **once**, here. One line per item: title, difficulty (optional
172
+ size estimate), and a *behavioral* exit criterion. The item's scope and subtasks live
173
+ in its task file — do not repeat them. Do not list TC ids here; they live in the Test
174
+ Plan and the Task File Mapping.
175
+
176
+ ### Track A: Critical Path (serial)
177
+ - **A1 = Task-NNN** [title] — [Easy|Medium|Hard], ~NNN lines; exit: [behavioral outcome, e.g. "converges with no acknowledged loss"].
178
+ - **A2 = Task-NNN** [title] — [difficulty]; exit: [behavioral outcome].
179
+ - **Gate = Task-NNN** [name] — measures [what]; pass: [threshold]. (State each gate once, here in its track — never also in a separate section.)
180
+
181
+ ### Track B: Parallel (independent agent, can start now)
182
+ - **B1 = Task-NNN** [title] — [difficulty]; exit: [behavioral outcome].
183
+
184
+ ### Track C: Post-Gate
185
+ - **C1 = Task-NNN** [title] — [difficulty]; exit: [behavioral outcome].
186
+
187
+ ## Parallel Execution Summary
188
+ [ASCII timeline showing the tracks running concurrently.]
189
+
190
+ ## Task File Mapping
191
+
192
+ The single per-task table — the only place that enumerates per-task ownership and
193
+ verification. It is a human-readable mirror of the task frontmatter, which stays
194
+ authoritative for status and edges.
195
+
196
+ | Task | Track | Owns (references) | Verified by (verifies) | Status |
197
+ | -------- | ----- | ----------------- | ---------------------- | ----------- |
198
+ | Task-NNN | A | FR-00X | TC-0XX…TC-0XX | not_started |
199
+
200
+ ## Coordination Rules
201
+ [What to freeze, what not to start early, shared-file/shared-state single-writer
202
+ discipline, merge sequencing.]
203
+ ```
204
+
205
+ ## Common Mistakes to Avoid
206
+
207
+ - **Mirroring frontmatter in prose.** `plan.md` is an orchestration overview; ownership,
208
+ the DAG, and test traces are authoritative in task frontmatter (`references`,
209
+ `depends_on`, `verifies`). State each fact once — requirement checklist (Requirements
210
+ Summary), dependency reasons (Dependency Graph), TC enumeration (Test Plan), per-task
211
+ row (Task File Mapping). Do not add a second "Execution Tracks" section, re-emit the
212
+ dependency graph, re-list TC ids in track exit-criteria, restate a task's `## Scope`,
213
+ or describe a gate twice.
214
+ - **Bundling done + remaining work in one task.** If build is done but scan isn't, they're separate tasks even if they were originally planned together.
215
+ - **Missing shared dependencies.** If two items need the same algorithm, extract it as a deliverable — don't let two parallel workers implement it independently.
216
+ - **No gates.** If the whole system's value depends on one unproven property (e.g., recall quality), measure it before building everything around it.
217
+ - **Stale plans.** The execution plan should be updated as work progresses. Completed phases should be collapsed, not left as active planning noise.
218
+ - **Optimistic parallelism.** Don't mark items as parallel if they share mutable state (same files, same data structures). Merge conflicts erase the time savings.
@@ -0,0 +1,35 @@
1
+ ---
2
+ name: spec-to-plan
3
+ description: Convert validated requirements into an implementation plan.
4
+ contributes:
5
+ workflows: ./workflows
6
+ ---
7
+
8
+ # /spec-to-plan
9
+
10
+ ## When To Use
11
+
12
+ Use this skill when accepted requirements should become ordered implementation work.
13
+
14
+ ## What It Does
15
+
16
+ Convert validated requirements into an implementation plan. The workflow definition is the source of truth for phases, gates, item schemas, recipes, and validation points.
17
+
18
+ ## Workflow Behavior
19
+
20
+ - Start from the workflow status and follow reported next actions.
21
+ - Record evidence items before advancing analysis, review, or validation phases.
22
+ - Use recipes for deterministic command chains, but preserve human gates for acceptance.
23
+ - Prefer templates for stable artifact creation and generic file editing for broad semantic rewrites.
24
+
25
+ ## Acceptance Criteria
26
+
27
+ - AC-1: Produces a plan that traces tasks back to requirement IDs.
28
+ - AC-2: Preserves dependencies, risks, and verification expectations in the plan.
29
+ - AC-3: Flags requirements that are not ready for planning instead of forcing tasks.
30
+
31
+ ## Boundaries
32
+
33
+ - Do not silently overwrite existing human-authored requirements artifacts.
34
+ - Do not invent missing facts, links, or evidence; record assumptions and gaps.
35
+ - Do not expand to adjacent spec operations unless the user request requires it or the workflow directs it.
@@ -0,0 +1 @@
1
+ export { specInvariants as invariants } from "../../../dist/index.js";
@@ -0,0 +1,44 @@
1
+ ---
2
+ type: Plan
3
+ id: "{{items.plan_answers.plan.id}}"
4
+ title: "{{items.plan_answers.plan.title}}"
5
+ status: active
6
+ traces_to:
7
+ - "{{items.plan_answers.plan.requirement_ids}}"
8
+ ---
9
+
10
+ # {{items.plan_answers.plan.id}}: {{items.plan_answers.plan.title}}
11
+
12
+ ## Scope
13
+
14
+ This plan covers accepted requirements:
15
+
16
+ {{items.plan_answers.plan.requirement_ids}}
17
+
18
+ ## Readiness Notes
19
+
20
+ {{items.plan_answers.plan.readiness_notes}}
21
+
22
+ ## Work Breakdown
23
+
24
+ | Task | Requirement Trace | Outcome | Verification |
25
+ | ---- | ------------------------------------------- | ------------------------------ | ---------------------------------------------------- |
26
+ | T-1 | {{items.plan_answers.plan.requirement_ids}} | Define implementation changes. | Tests or review evidence linked to each requirement. |
27
+ | T-2 | {{items.plan_answers.plan.requirement_ids}} | Implement scoped changes. | Passing automated checks. |
28
+ | T-3 | {{items.plan_answers.plan.requirement_ids}} | Update verification evidence. | Requirements matrix or review report updated. |
29
+
30
+ ## Dependencies
31
+
32
+ - Confirm every traced requirement is accepted and implementation-ready.
33
+ - Resolve readiness notes before scheduling blocked work.
34
+
35
+ ## Risks
36
+
37
+ - Requirements with weak acceptance criteria may produce vague tasks.
38
+ - Missing trace evidence may cause implementation work to drift from the spec.
39
+
40
+ ## Acceptance Criteria
41
+
42
+ - Every task traces to at least one requirement id.
43
+ - Every traced requirement has an implementation or verification task.
44
+ - Blockers are explicit and not hidden inside task descriptions.
@@ -0,0 +1,85 @@
1
+ name: to-plan
2
+ version: 0.1.0
3
+ description: Convert accepted requirements into a traced implementation plan.
4
+ initialPhase: intake
5
+ phases:
6
+ - { name: intake }
7
+ - { name: evidence_recorded }
8
+ - { name: plan_drafted }
9
+ - { name: validated }
10
+ - { name: accepted, terminal: true }
11
+ transitions:
12
+ - from: intake
13
+ to: evidence_recorded
14
+ invariants:
15
+ - "interview.complete:plan"
16
+ defaultGate: auto
17
+ - from: evidence_recorded
18
+ to: plan_drafted
19
+ invariants: []
20
+ defaultGate: auto
21
+ - from: plan_drafted
22
+ to: validated
23
+ invariants:
24
+ - "artifact.frontmatter_valid:implementation_plan"
25
+ defaultGate: auto
26
+ - from: validated
27
+ to: accepted
28
+ invariants: []
29
+ defaultGate: hitl
30
+ itemSchemas:
31
+ plan_answers: {}
32
+ ImplementationPlanSchema:
33
+ required: [type, id, title, traces_to]
34
+ properties:
35
+ type: { type: string }
36
+ id: { type: string }
37
+ title: { type: string }
38
+ traces_to: { type: array }
39
+ linkSchemas: {}
40
+ interviews:
41
+ plan:
42
+ itemType: plan_answers
43
+ completenessRule: all_required
44
+ questions:
45
+ - key: artifact_id
46
+ prompt: "Plan id, for example PLAN-001."
47
+ type: text
48
+ required: true
49
+ - key: slug
50
+ prompt: "Filename slug without the plan id."
51
+ type: text
52
+ required: true
53
+ - key: title
54
+ prompt: "Implementation plan title."
55
+ type: text
56
+ required: true
57
+ - key: requirement_ids
58
+ prompt: "Comma-separated accepted requirement ids this plan traces to."
59
+ type: text
60
+ required: true
61
+ - key: readiness_notes
62
+ prompt: "Known blockers, assumptions, or readiness notes."
63
+ type: text
64
+ required: true
65
+ artifactTemplates:
66
+ implementation_plan:
67
+ source: templates/implementation-plan/default.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
72
+ phase: plan_drafted
73
+ frontmatterSchema: ImplementationPlanSchema
74
+ recipes:
75
+ draft-and-validate:
76
+ description: Record planning inputs, draft the traced plan, validate it, then stop at acceptance.
77
+ steps:
78
+ - command: advance
79
+ to: evidence_recorded
80
+ - command: advance
81
+ to: plan_drafted
82
+ - command: advance
83
+ to: validated
84
+ - command: advance
85
+ to: accepted
@@ -0,0 +1,154 @@
1
+ ---
2
+ name: specify
3
+ description: Create or update spec artifacts from a design or change request. Orchestrates authoring each requested requirement type (StR/US/FR/NFR/IT) as a discrete file using quoin catalog templates and Quire validation.
4
+ ---
5
+
6
+ # Specify
7
+
8
+ Use this skill when turning an agreed design, feature, or change request into
9
+ spec artifacts. `specify` decides **which artifacts the request needs**, authors
10
+ each one **as its own file** using the catalog templates, and validates.
11
+
12
+ ## Scope to the request
13
+
14
+ Author **only the artifact types the request calls for** — nothing more.
15
+
16
+ - "Add a user story for X" → one US.
17
+ - "Add the FR that implements US-003" → one FR (traced to US-003).
18
+ - "Add a user story and the requirement that implements it" → one US **and** one FR.
19
+ - "Edit FR-002 to …" → edit that one FR file in place.
20
+ - "Start a spec for service X" / "backport a spec from this code" → the full
21
+ chain (`spec.md` + US + FR + NFR, and IT where there are external integrations).
22
+
23
+ When unsure which types a request implies, decide from the request and state what
24
+ you are creating. A backport or new feature almost always needs **FR artifacts**,
25
+ not just a summary.
26
+
27
+ ## Requirements are files, not table rows
28
+
29
+ Each requirement is a **discrete artifact file** with `type:` frontmatter. The
30
+ Requirements table inside `spec.md` (master-requirements) is an **index/summary**
31
+ — it never replaces the artifacts. Author every requested requirement as its own
32
+ file under the matching directory:
33
+
34
+ | Type | `type:` | Location |
35
+ | ---- | ------- | ------------------------------ |
36
+ | StR | `StR` | `spec/stakeholder/StR-XXX-*.md`|
37
+ | US | `US` | `spec/usecase/US-XXX-*.md` |
38
+ | FR | `FR` | `spec/functional/FR-XXX-*.md` |
39
+ | NFR | `NFR` | `spec/non-functional/NFR-XXX-*.md` |
40
+ | IT | `IT` | `spec/integration/IT-XXX-*.md` |
41
+
42
+ > If a request asks for functional requirements and you produced only table rows
43
+ > in `spec.md`, the request is **not done** — create the `FR-XXX.md` files.
44
+
45
+ ## Writing good requirements
46
+
47
+ The templates and Quire enforce *shape*; you supply the *judgment*. Author it well
48
+ here so `spec-review` has less to send back. Three principles — full guidance with
49
+ examples in [references/writing-good-requirements.md](references/writing-good-requirements.md):
50
+
51
+ - **Scope: tight beats broad.** Prefer a narrow spec that fully defines its slice over
52
+ a sprawling, vague one. Treat `spec.md` §2.2 Out of Scope as first-class — decide
53
+ your non-goals deliberately; an empty Out-of-Scope is a smell.
54
+ - **User stories: INVEST + no solution-prescribing.** Describe the user need with a
55
+ real "so that …"; let the FRs pick the mechanism.
56
+ - **Acceptance criteria: cover the unhappy paths, be concrete.** Author happy/error/edge
57
+ and negative cases up front, in measurable terms ("returns HTTP 422 within 200ms",
58
+ not "handles errors gracefully").
59
+
60
+ ## Process
61
+
62
+ Run only the steps the request needs; stop after IT.
63
+
64
+ 1. Identify the repository that owns the spec files, and which artifact types the
65
+ request implies (any subset of StR, US, FR, NFR, IT).
66
+ 2. Run `quoin write <repo_dir> --types <type[,type...]>` **once** for the full
67
+ set. Use the returned skeletons, schemas, module roots, and examples as the
68
+ authoring contract — the per-type rules live in the template, not your memory.
69
+ The pack also reports the repo's `Org:`; use that value for the `org:` field
70
+ and for the `ix://<org>/<repo>/…` targets you write. If it reports
71
+ `Org: unresolved`, ask the user which organization owns the repo — never
72
+ invent one, never leave a literal `<your-org>` in a file, and never copy the
73
+ org out of a skeleton's example values.
74
+ 3. Author each artifact as its own file (table above), in this logical order,
75
+ skipping any type not requested:
76
+ - `spec.md` — **REQUIRED when starting a new spec**: the
77
+ `type: master-requirements` root/index at `spec/spec.md`, authored from
78
+ `assets/spec-template.md` (or `assets/app-spec-template.md` for an
79
+ application); keep scope tight and fill Out of Scope deliberately
80
+ (see [references/writing-good-requirements.md](references/writing-good-requirements.md)).
81
+ Then → StR → US (INVEST, no solution-prescribing — same reference) →
82
+ **derive FR from US** (see [references/us-to-fr.md](references/us-to-fr.md))
83
+ → FR (cover unhappy paths, measurable ACs — same reference)
84
+ → NFR → IT (see [references/integration-tests.md](references/integration-tests.md)).
85
+ 4. Keep traceability in frontmatter `relationships:` (e.g. a US `traces_to` its
86
+ FRs; an FR/NFR/IT links back to the US/FR it serves).
87
+ 5. Run `quire validate <glob> [glob2 ...]` over the changed spec scope and fix
88
+ every error before continuing.
89
+ 6. **Open in the review cockpit.** After validation passes, run
90
+ `filament open <primary-artifact>` to open the authored artifact in the running
91
+ filament-ide cockpit (it fires the `filament-ide://` deep link and prints a
92
+ clickable link as a fallback). Use the main artifact you created — the
93
+ new/edited `FR-XXX.md`, or `spec/spec.md` when starting a spec. Skip silently if
94
+ the `filament` command is not installed.
95
+ 7. **Stop at IT.** Then ask the user whether to build the test matrix
96
+ (`spec-matrix`) and run review (`spec-review`) — unless they already requested
97
+ them. Only run those on confirmation.
98
+
99
+ ## Functional requirements
100
+
101
+ FRs are normative (`SHALL` / `SHALL NOT`), atomic, and independently verifiable,
102
+ each with an Acceptance Criteria table (the `fr.md` skeleton enforces the shape).
103
+
104
+ - Derive FRs from the driving user story — see
105
+ [references/us-to-fr.md](references/us-to-fr.md).
106
+ - Make the ACs count: cover happy/error/edge and negative cases in concrete,
107
+ measurable terms — see
108
+ [references/writing-good-requirements.md](references/writing-good-requirements.md).
109
+ - A behavioral FR has no `object:` field. A **domain-typed** FR carries
110
+ `object: <type>` (e.g. `entity`, `event`, `api_endpoint`, `process`,
111
+ `configuration`) and uses that type's structural template. Look up the
112
+ type→template map and relationship verbs in
113
+ `spec-object-review`'s `references/object-type-guide.md`, and inspect a type
114
+ with `quoin catalog show <type>`.
115
+
116
+ ## Application specs
117
+
118
+ When `component_type: application`, initialize `spec.md` from
119
+ `assets/app-spec-template.md`. Application specs own **only cross-service
120
+ concerns** — architecture rationale (ADRs), cross-service sequence diagrams,
121
+ system-level NFRs, the external consumer contract, scope boundaries, security
122
+ model. Per-service detail (endpoint contracts, DB schemas, per-service NFRs)
123
+ stays in the individual service specs. Otherwise use `assets/spec-template.md`.
124
+
125
+ ## Authoring rules
126
+
127
+ - Let frontmatter identify each file. The discriminator is `type` (e.g.
128
+ `type: FR`, `type: master-requirements`) — it names the archetype.
129
+ - Use catalog skeletons and schemas rather than memory.
130
+ - Keep workflow definitions out of artifact/object type vocabularies.
131
+ - Validate every created or edited artifact with Quire before finishing.
132
+
133
+ ## Reserved OKF Files
134
+
135
+ `spec-artifacts-iso` ships two reserved archetypes for the OKF folder structure;
136
+ author them like any other type:
137
+
138
+ - `index.md` — `type: index`, body is a `## Contents` link list pointing at the
139
+ artifacts in the folder.
140
+ - `log.md` — `type: log`, body is a `## History` of changes to the folder's specs.
141
+
142
+ ## Common Spec Layout
143
+
144
+ ```text
145
+ spec/
146
+ ├── spec.md
147
+ ├── stakeholder/ # StR-XXX
148
+ ├── usecase/ # US-XXX
149
+ ├── functional/ # FR-XXX
150
+ ├── non-functional/ # NFR-XXX
151
+ ├── integration/ # IT-XXX
152
+ ├── matrix/
153
+ └── analysis/
154
+ ```
@@ -0,0 +1,143 @@
1
+ ---
2
+ type: master-requirements
3
+ name: <app-name>
4
+ org: <your-org> # use the `Org:` quoin write reports
5
+ component_type: application
6
+ tags: []
7
+ implementation_language: null
8
+ depends_on:
9
+ # List all component repos this application owns
10
+ # - service-one
11
+ # - library-one
12
+ standards_alignment:
13
+ - iso-iec-ieee-29148
14
+ security_critical: false
15
+ ---
16
+ # Master Requirements Specification
17
+ ## <App Name>
18
+
19
+ ### 1. Purpose
20
+
21
+ <!-- 2-3 sentences: What problem does this application solve? Who does it serve?
22
+ Be specific — avoid restating the component names. -->
23
+
24
+ ### 2. Scope
25
+
26
+ This specification defines the **application-level** domain, encompassing end-to-end processes that span multiple component repositories. Individual component behavior is specified in each component's own `spec/` directory; this document defines how they compose into a complete system.
27
+
28
+ ### 3. System Overview
29
+
30
+ #### 3.1 Component Registry
31
+
32
+ <!-- One row per component repo. Distinguish services vs libraries. -->
33
+
34
+ | Component | Type | Repo | Role |
35
+ |-----------|------|------|------|
36
+ | <!-- name --> | <!-- fastapi-service / python-lib / react-lib / etc --> | `<!-- repo-name -->` | <!-- What it does in 1 sentence --> |
37
+
38
+ #### 3.2 Dependency Graph
39
+
40
+ <!-- Required: Show how components connect. Use color styles to distinguish
41
+ services (red), libraries (green), SDKs (orange), UI (purple). -->
42
+
43
+ ```mermaid
44
+ graph TD
45
+ A[ComponentA] --> B[ComponentB]
46
+
47
+ style A fill:#e74c3c,color:#fff
48
+ style B fill:#2ecc71,color:#fff
49
+ ```
50
+
51
+ ### 4. Architecture Rationale
52
+
53
+ <!-- Required: Explain WHY the architecture looks the way it does.
54
+ One ADR entry per major structural decision. -->
55
+
56
+ #### ADR-001: <!-- Decision Title -->
57
+
58
+ **Decision**: <!-- What was decided. One sentence. -->
59
+
60
+ **Rationale**: <!-- Why? What problem does this solve? -->
61
+
62
+ **Alternatives considered**: <!-- What else was evaluated and why it was rejected. -->
63
+
64
+ ### 5. Stakeholder Requirements
65
+
66
+ | ID | Title | Artifact |
67
+ |----|-------|----------|
68
+ | StR-001 | <!-- Title --> | [StR-001](stakeholder/StR-001-<slug>.md) |
69
+
70
+ ### 6. User Stories
71
+
72
+ | ID | Title | Role | Artifact |
73
+ |----|-------|------|----------|
74
+ | US-001 | <!-- Title --> | <!-- Role --> | [US-001](usecase/US-001-<slug>.md) |
75
+
76
+ ### 7. Functional Requirements
77
+
78
+ <!-- Application specs MUST include these object types:
79
+ - domain: Bounded context, ER diagram (FR-001)
80
+ - process: One per major cross-service workflow
81
+ - configuration: Shared config across services
82
+ - integration: Consumer contract (how to integrate with this app) -->
83
+
84
+ | ID | Title | Object Type | Artifact |
85
+ |----|-------|-------------|----------|
86
+ | FR-001 | <!-- App --> Domain | domain | [FR-001](functional/FR-001-<slug>-domain.md) |
87
+ | FR-002 | <!-- Primary Workflow --> Process | process | [FR-002](functional/FR-002-<slug>-process.md) |
88
+ | FR-XXX | <!-- App --> Configuration | configuration | [FR-XXX](functional/FR-XXX-configuration.md) |
89
+ | FR-XXX | Consumer Integration Contract | integration | [FR-XXX](functional/FR-XXX-consumer-integration.md) |
90
+
91
+ ### 8. Non-Functional Requirements
92
+
93
+ <!-- Application specs MUST include these three NFRs:
94
+ - Security Constraints (crypto, transport, error handling)
95
+ - System Reliability (SLA, p99 latency, scale limits, RTO/RPO)
96
+ - Deployment Topology (namespace, ingress, discovery, secrets) -->
97
+
98
+ | ID | Title | Artifact |
99
+ |----|-------|----------|
100
+ | NFR-001 | Security Constraints | [NFR-001](non-functional/NFR-001-security.md) |
101
+ | NFR-002 | System Reliability | [NFR-002](non-functional/NFR-002-reliability.md) |
102
+ | NFR-003 | Deployment Topology | [NFR-003](non-functional/NFR-003-deployment.md) |
103
+
104
+ ### 9. Domain Model
105
+
106
+ See [FR-001 <!-- App --> Domain](functional/FR-001-<slug>-domain.md) for the bounded context definition, entity relationships, and ER diagram.
107
+
108
+ ### 10. Scope Boundaries
109
+
110
+ <!-- Required: Explicitly list what this application does NOT do.
111
+ These are deliberate exclusions, not future work. -->
112
+
113
+ | Out of Scope | Rationale |
114
+ |---|---|
115
+ | <!-- Feature --> | <!-- Why deliberately excluded --> |
116
+
117
+ ### 11. Security Model
118
+
119
+ <!-- Required: Define the actor model and trust hierarchy.
120
+ What roles exist? What can each role do? -->
121
+
122
+ #### Actor Roles
123
+
124
+ | Role | Description | Assigned By |
125
+ |------|-------------|-------------|
126
+ | `anonymous` | Unauthenticated caller | Default |
127
+ | `user` | Authenticated user | Auth system |
128
+ | `admin` | Administrator | Operator |
129
+ | `operator` | Infrastructure operator | Out-of-band |
130
+
131
+ #### Trust Boundaries
132
+
133
+ <!-- List capabilities and which roles can exercise them. -->
134
+
135
+ | Capability | anonymous | user | admin | operator |
136
+ |---|---|---|---|---|
137
+ | <!-- action --> | — | ✅ | ✅ | ✅ |
138
+
139
+ ### 12. References
140
+
141
+ | Standard | Description |
142
+ |----------|-------------|
143
+ | ISO/IEC/IEEE 29148 | Requirements engineering standard |