@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.
- package/.agents/plugins/marketplace.json +14 -0
- package/.claude-plugin/marketplace.json +16 -0
- package/.claude-plugin/plugin.json +8 -0
- package/.codex-plugin/plugin.json +27 -0
- package/.github/plugin/marketplace.json +16 -0
- package/LICENSE +21 -0
- package/README.md +266 -0
- package/bin/quoin.js +14 -0
- package/default-modules.yaml +82 -0
- package/dist/base-DrUMkAh1.js +137 -0
- package/dist/base.d.ts +23 -0
- package/dist/base.d.ts.map +1 -0
- package/dist/catalog.d.ts +32 -0
- package/dist/catalog.d.ts.map +1 -0
- package/dist/cli.d.ts +18 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +20 -0
- package/dist/commands/catalog/index.d.ts +2 -0
- package/dist/commands/catalog/index.d.ts.map +1 -0
- package/dist/commands/catalog/index.js +2 -0
- package/dist/commands/catalog/list.d.ts +11 -0
- package/dist/commands/catalog/list.d.ts.map +1 -0
- package/dist/commands/catalog/list.js +22 -0
- package/dist/commands/catalog/show.d.ts +13 -0
- package/dist/commands/catalog/show.d.ts.map +1 -0
- package/dist/commands/catalog/show.js +25 -0
- package/dist/commands/catalog/validate.d.ts +10 -0
- package/dist/commands/catalog/validate.d.ts.map +1 -0
- package/dist/commands/catalog/validate.js +27 -0
- package/dist/commands/config/doctor.d.ts +7 -0
- package/dist/commands/config/doctor.d.ts.map +1 -0
- package/dist/commands/config/doctor.js +15 -0
- package/dist/commands/config/edit.d.ts +7 -0
- package/dist/commands/config/edit.d.ts.map +1 -0
- package/dist/commands/config/edit.js +13 -0
- package/dist/commands/config/get.d.ts +11 -0
- package/dist/commands/config/get.d.ts.map +1 -0
- package/dist/commands/config/get.js +20 -0
- package/dist/commands/config/index.d.ts +2 -0
- package/dist/commands/config/index.d.ts.map +1 -0
- package/dist/commands/config/index.js +2 -0
- package/dist/commands/config/set.d.ts +12 -0
- package/dist/commands/config/set.d.ts.map +1 -0
- package/dist/commands/config/set.js +26 -0
- package/dist/commands/matrix.d.ts +14 -0
- package/dist/commands/matrix.d.ts.map +1 -0
- package/dist/commands/matrix.js +15 -0
- package/dist/commands/module/ensure-defaults.d.ts +8 -0
- package/dist/commands/module/ensure-defaults.d.ts.map +1 -0
- package/dist/commands/module/ensure-defaults.js +17 -0
- package/dist/commands/module/index.d.ts +2 -0
- package/dist/commands/module/index.d.ts.map +1 -0
- package/dist/commands/module/index.js +2 -0
- package/dist/commands/module/install.d.ts +11 -0
- package/dist/commands/module/install.d.ts.map +1 -0
- package/dist/commands/module/install.js +22 -0
- package/dist/commands/module/list.d.ts +8 -0
- package/dist/commands/module/list.d.ts.map +1 -0
- package/dist/commands/module/list.js +13 -0
- package/dist/commands/module/remove.d.ts +10 -0
- package/dist/commands/module/remove.d.ts.map +1 -0
- package/dist/commands/module/remove.js +16 -0
- package/dist/commands/plugin/deprecation.d.ts +10 -0
- package/dist/commands/plugin/deprecation.d.ts.map +1 -0
- package/dist/commands/plugin/ensure-defaults.d.ts +8 -0
- package/dist/commands/plugin/ensure-defaults.d.ts.map +1 -0
- package/dist/commands/plugin/ensure-defaults.js +12 -0
- package/dist/commands/plugin/index.d.ts +2 -0
- package/dist/commands/plugin/index.d.ts.map +1 -0
- package/dist/commands/plugin/index.js +2 -0
- package/dist/commands/plugin/install.d.ts +8 -0
- package/dist/commands/plugin/install.d.ts.map +1 -0
- package/dist/commands/plugin/install.js +12 -0
- package/dist/commands/plugin/list.d.ts +8 -0
- package/dist/commands/plugin/list.d.ts.map +1 -0
- package/dist/commands/plugin/list.js +12 -0
- package/dist/commands/plugin/remove.d.ts +8 -0
- package/dist/commands/plugin/remove.d.ts.map +1 -0
- package/dist/commands/plugin/remove.js +12 -0
- package/dist/commands/review.d.ts +14 -0
- package/dist/commands/review.d.ts.map +1 -0
- package/dist/commands/review.js +15 -0
- package/dist/commands/to-plan.d.ts +14 -0
- package/dist/commands/to-plan.d.ts.map +1 -0
- package/dist/commands/to-plan.js +15 -0
- package/dist/commands/update.d.ts +13 -0
- package/dist/commands/update.d.ts.map +1 -0
- package/dist/commands/update.js +34 -0
- package/dist/commands/write.d.ts +16 -0
- package/dist/commands/write.d.ts.map +1 -0
- package/dist/commands/write.js +33 -0
- package/dist/config-schema-Dp-vlxuR.js +13 -0
- package/dist/config-schema.d.ts +52 -0
- package/dist/config-schema.d.ts.map +1 -0
- package/dist/deprecation-fRxUHoxv.js +4 -0
- package/dist/flow-command-SMjCSOFg.js +88 -0
- package/dist/flow-command.d.ts +25 -0
- package/dist/flow-command.d.ts.map +1 -0
- package/dist/flows.d.ts +7 -0
- package/dist/flows.d.ts.map +1 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +9 -0
- package/dist/modules-CW8pBK41.js +22 -0
- package/dist/modules.d.ts +10 -0
- package/dist/modules.d.ts.map +1 -0
- package/dist/org.d.ts +61 -0
- package/dist/org.d.ts.map +1 -0
- package/dist/plugins-GSxafyD3.js +77 -0
- package/dist/plugins.d.ts +13 -0
- package/dist/plugins.d.ts.map +1 -0
- package/dist/version-_1nY4KyJ.js +17 -0
- package/dist/version.d.ts +3 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/write-CQAitcI5.js +156 -0
- package/dist/write.d.ts +28 -0
- package/dist/write.d.ts.map +1 -0
- package/package.json +119 -0
- 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-app-review/SKILL.md +51 -0
- package/skills/spec-app-review/references/checklist.md +197 -0
- package/skills/spec-dependency-analysis/SKILL.md +75 -0
- package/skills/spec-ears-analysis/SKILL.md +89 -0
- package/skills/spec-evidence-analysis/SKILL.md +78 -0
- package/skills/spec-failure-domain-analysis/SKILL.md +44 -0
- package/skills/spec-ideation/SKILL.md +46 -0
- package/skills/spec-integrity-analysis/SKILL.md +47 -0
- package/skills/spec-matrix/SKILL.md +168 -0
- package/skills/spec-matrix/assets/test-cases/TC-001.md +35 -0
- package/skills/spec-matrix/assets/test-cases/TC-002.md +37 -0
- package/skills/spec-matrix/assets/test-cases/TC-006.md +50 -0
- package/skills/spec-matrix/assets/test-matrix-example.md +104 -0
- package/skills/spec-matrix/assets/test-matrix-template.md +123 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/SKILL.md +35 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/scripts/invariants.js +1 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/templates/report/default.md +30 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/workflows/matrix/def.yaml +82 -0
- package/skills/spec-object-review/SKILL.md +125 -0
- package/skills/spec-object-review/references/object-type-guide.md +118 -0
- package/skills/spec-review/SKILL.md +71 -0
- package/skills/spec-review/references/checklist.md +50 -0
- package/skills/spec-review/workflow-assets/skills/review/SKILL.md +96 -0
- package/skills/spec-review/workflow-assets/skills/review/scripts/invariants.js +60 -0
- package/skills/spec-review/workflow-assets/skills/review/workflows/review/def.yaml +68 -0
- package/skills/spec-risk-complexity-analysis/SKILL.md +77 -0
- package/skills/spec-scope-boundary-analysis/SKILL.md +86 -0
- package/skills/spec-security-analysis/SKILL.md +84 -0
- package/skills/spec-security-analysis/assets/security-analysis-example.md +89 -0
- package/skills/spec-security-analysis/assets/security-analysis-template.md +73 -0
- package/skills/spec-security-analysis/references/component-type-mapping.md +161 -0
- package/skills/spec-security-analysis/references/gdpr/ChII-Principles.md +58 -0
- package/skills/spec-security-analysis/references/gdpr/ChIII-DataSubjectRights.md +84 -0
- package/skills/spec-security-analysis/references/gdpr/ChIV-ControllerProcessor.md +83 -0
- package/skills/spec-security-analysis/references/gdpr/ChV-DataTransfers.md +62 -0
- package/skills/spec-security-analysis/references/gdpr/index.md +54 -0
- package/skills/spec-security-analysis/references/iso27001/A5-OrganizationalControls.md +64 -0
- package/skills/spec-security-analysis/references/iso27001/A6-PeopleControls.md +30 -0
- package/skills/spec-security-analysis/references/iso27001/A7-PhysicalControls.md +35 -0
- package/skills/spec-security-analysis/references/iso27001/A8-TechnologicalControls.md +66 -0
- package/skills/spec-security-analysis/references/iso27001/index.md +43 -0
- package/skills/spec-security-analysis/references/nist-800-53/AC-AccessControl.md +57 -0
- package/skills/spec-security-analysis/references/nist-800-53/AU-AuditAccountability.md +49 -0
- package/skills/spec-security-analysis/references/nist-800-53/CM-ConfigurationManagement.md +36 -0
- package/skills/spec-security-analysis/references/nist-800-53/IA-IdentificationAuthentication.md +44 -0
- package/skills/spec-security-analysis/references/nist-800-53/SA-SystemServicesAcquisition.md +50 -0
- package/skills/spec-security-analysis/references/nist-800-53/SC-SystemCommunications.md +53 -0
- package/skills/spec-security-analysis/references/nist-800-53/SI-SystemInformationIntegrity.md +52 -0
- package/skills/spec-security-analysis/references/nist-800-53/index.md +58 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V1-Architecture.md +33 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V10-MaliciousCode.md +33 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V11-BusinessLogic.md +32 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V12-Files.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V13-API.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V14-Configuration.md +35 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V2-Authentication.md +36 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V3-SessionManagement.md +35 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V4-AccessControl.md +39 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V5-Validation.md +37 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V6-Cryptography.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V7-ErrorLogging.md +37 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V8-DataProtection.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V9-Communication.md +32 -0
- package/skills/spec-security-analysis/references/owasp-asvs/index.md +59 -0
- package/skills/spec-security-analysis/references/soc2/CC1-ControlEnvironment.md +31 -0
- package/skills/spec-security-analysis/references/soc2/CC2-CommunicationInformation.md +27 -0
- package/skills/spec-security-analysis/references/soc2/CC3-RiskAssessment.md +29 -0
- package/skills/spec-security-analysis/references/soc2/CC4-MonitoringActivities.md +27 -0
- package/skills/spec-security-analysis/references/soc2/CC5-ControlActivities.md +28 -0
- package/skills/spec-security-analysis/references/soc2/CC6-LogicalPhysicalAccess.md +45 -0
- package/skills/spec-security-analysis/references/soc2/CC7-SystemOperations.md +42 -0
- package/skills/spec-security-analysis/references/soc2/CC8-ChangeManagement.md +32 -0
- package/skills/spec-security-analysis/references/soc2/CC9-RiskMitigation.md +34 -0
- package/skills/spec-security-analysis/references/soc2/index.md +46 -0
- package/skills/spec-security-analysis/references/standards-index.md +46 -0
- package/skills/spec-to-plan/SKILL.md +75 -0
- package/skills/spec-to-plan/references/step-0-plan-selection.md +121 -0
- package/skills/spec-to-plan/references/step-1-analysis.md +88 -0
- package/skills/spec-to-plan/references/step-2-test-plan.md +43 -0
- package/skills/spec-to-plan/references/step-3-execution-plan.md +218 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/SKILL.md +35 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/scripts/invariants.js +1 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/templates/implementation-plan/default.md +44 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/workflows/to-plan/def.yaml +85 -0
- package/skills/specify/SKILL.md +154 -0
- package/skills/specify/assets/app-spec-template.md +143 -0
- package/skills/specify/assets/spec-template.md +299 -0
- package/skills/specify/references/integration-tests.md +72 -0
- package/skills/specify/references/us-to-fr.md +40 -0
- 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";
|
package/skills/spec-to-plan/workflow-assets/skills/to-plan/templates/implementation-plan/default.md
ADDED
|
@@ -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 |
|