@curdx/flow 2.2.3 → 2.2.5

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 (126) hide show
  1. package/.claude-plugin/marketplace.json +3 -2
  2. package/.claude-plugin/plugin.json +2 -1
  3. package/CHANGELOG.md +4 -566
  4. package/README.md +47 -113
  5. package/agents/flow-adversary.md +1 -0
  6. package/agents/flow-architect.md +9 -36
  7. package/agents/flow-brownfield-analyst.md +7 -18
  8. package/agents/flow-debugger.md +1 -0
  9. package/agents/flow-edge-hunter.md +1 -0
  10. package/agents/flow-executor.md +1 -0
  11. package/agents/flow-planner.md +11 -37
  12. package/agents/flow-product-designer.md +9 -41
  13. package/agents/flow-qa-engineer.md +1 -0
  14. package/agents/flow-researcher.md +9 -45
  15. package/agents/flow-reviewer.md +1 -0
  16. package/agents/flow-security-auditor.md +1 -0
  17. package/agents/flow-triage-analyst.md +1 -0
  18. package/agents/flow-ui-researcher.md +1 -0
  19. package/agents/flow-ux-designer.md +1 -0
  20. package/agents/flow-verifier.md +1 -0
  21. package/cli/doctor-workflow.js +5 -914
  22. package/cli/install-companions.js +8 -8
  23. package/cli/lib/doctor-claude-settings.js +736 -0
  24. package/cli/lib/doctor-runtime-environment.js +196 -0
  25. package/cli/lib/semver.js +14 -0
  26. package/cli/uninstall-actions.js +323 -0
  27. package/cli/uninstall.js +9 -253
  28. package/gates/coverage-audit-gate.md +1 -3
  29. package/gates/tdd-gate.md +0 -6
  30. package/gates/verification-gate.md +1 -5
  31. package/knowledge/artifact-output-discipline.md +24 -0
  32. package/knowledge/artifact-summary-contracts.md +50 -0
  33. package/knowledge/execution-strategies.md +6 -4
  34. package/knowledge/poc-first-workflow.md +2 -6
  35. package/knowledge/spec-driven-development.md +0 -4
  36. package/knowledge/systematic-debugging.md +0 -6
  37. package/knowledge/two-stage-review.md +8 -6
  38. package/knowledge/wave-execution.md +2 -1
  39. package/package.json +2 -2
  40. package/schemas/agent-frontmatter.schema.json +4 -0
  41. package/skills/brownfield-index/SKILL.md +14 -20
  42. package/skills/brownfield-index/references/applicability.md +12 -0
  43. package/skills/brownfield-index/references/handoff.md +8 -0
  44. package/skills/brownfield-index/references/index-contract.md +10 -0
  45. package/skills/browser-qa/SKILL.md +15 -35
  46. package/skills/browser-qa/references/handoff.md +6 -0
  47. package/skills/browser-qa/references/prerequisites.md +10 -0
  48. package/skills/browser-qa/references/qa-contract.md +20 -0
  49. package/skills/cancel/SKILL.md +20 -61
  50. package/skills/cancel/references/destructive-mode.md +17 -0
  51. package/skills/cancel/references/reporting.md +18 -0
  52. package/skills/cancel/references/state-recovery.md +30 -0
  53. package/skills/cancel/references/target-resolution.md +7 -0
  54. package/skills/debug/SKILL.md +23 -87
  55. package/skills/debug/references/context-gathering.md +11 -0
  56. package/skills/debug/references/failure-guard.md +25 -0
  57. package/skills/debug/references/intake.md +12 -0
  58. package/skills/debug/references/phase-workflow.md +34 -0
  59. package/skills/debug/references/reporting.md +20 -0
  60. package/skills/epic/SKILL.md +18 -50
  61. package/skills/epic/references/epic-artifacts.md +20 -0
  62. package/skills/epic/references/epic-intake.md +9 -0
  63. package/skills/epic/references/slice-handoff.md +16 -0
  64. package/skills/fast/SKILL.md +34 -102
  65. package/skills/fast/references/applicability.md +25 -0
  66. package/skills/fast/references/clarification.md +20 -0
  67. package/skills/fast/references/execution-contract.md +56 -0
  68. package/skills/help/SKILL.md +26 -132
  69. package/skills/help/references/dispatch.md +20 -0
  70. package/skills/help/references/overview.md +39 -0
  71. package/skills/help/references/troubleshoot.md +47 -0
  72. package/skills/help/references/workflow.md +37 -0
  73. package/skills/implement/SKILL.md +61 -237
  74. package/skills/implement/references/error-recovery.md +36 -0
  75. package/skills/implement/references/linear-execution.md +32 -0
  76. package/skills/implement/references/preflight.md +43 -0
  77. package/skills/implement/references/progress-contract.md +32 -0
  78. package/skills/implement/references/state-init.md +33 -0
  79. package/skills/implement/references/stop-hook-execution.md +36 -0
  80. package/skills/implement/references/strategy-router.md +38 -0
  81. package/skills/implement/references/subagent-execution.md +43 -0
  82. package/skills/init/SKILL.md +26 -95
  83. package/skills/init/references/gitignore-and-health.md +26 -0
  84. package/skills/init/references/next-steps.md +22 -0
  85. package/skills/init/references/preflight.md +15 -0
  86. package/skills/init/references/scaffold-contract.md +27 -0
  87. package/skills/review/SKILL.md +45 -153
  88. package/skills/review/references/optional-passes.md +48 -0
  89. package/skills/review/references/preflight.md +38 -0
  90. package/skills/review/references/report-contract.md +49 -0
  91. package/skills/review/references/reporting.md +20 -0
  92. package/skills/review/references/stage-execution.md +32 -0
  93. package/skills/security-audit/SKILL.md +16 -34
  94. package/skills/security-audit/references/audit-contract.md +21 -0
  95. package/skills/security-audit/references/gate-handoff.md +8 -0
  96. package/skills/security-audit/references/scope-and-depth.md +9 -0
  97. package/skills/spec/SKILL.md +55 -182
  98. package/skills/spec/references/artifact-landing.md +31 -0
  99. package/skills/spec/references/phase-execution.md +50 -0
  100. package/skills/spec/references/planning-review.md +31 -0
  101. package/skills/spec/references/preflight-and-routing.md +46 -0
  102. package/skills/spec/references/reporting.md +21 -0
  103. package/skills/start/SKILL.md +40 -123
  104. package/skills/start/references/branch-routing.md +51 -0
  105. package/skills/start/references/mode-semantics.md +12 -0
  106. package/skills/start/references/preflight.md +13 -0
  107. package/skills/start/references/reporting.md +20 -0
  108. package/skills/start/references/state-seeding.md +44 -0
  109. package/skills/start/references/workflow-handoff.md +26 -0
  110. package/skills/status/SKILL.md +17 -61
  111. package/skills/status/references/gather-contract.md +27 -0
  112. package/skills/status/references/health-rules.md +27 -0
  113. package/skills/status/references/output-contract.md +24 -0
  114. package/skills/status/references/preflight.md +10 -0
  115. package/skills/status/references/recovery-hints.md +18 -0
  116. package/skills/ui-sketch/SKILL.md +15 -34
  117. package/skills/ui-sketch/references/brief-intake.md +10 -0
  118. package/skills/ui-sketch/references/iteration-handoff.md +5 -0
  119. package/skills/ui-sketch/references/variant-contract.md +15 -0
  120. package/skills/verify/SKILL.md +31 -86
  121. package/skills/verify/references/evidence-workflow.md +39 -0
  122. package/skills/verify/references/output-contract.md +23 -0
  123. package/skills/verify/references/preflight.md +11 -0
  124. package/skills/verify/references/report-handoff.md +35 -0
  125. package/skills/verify/references/strict-mode.md +12 -0
  126. package/README.zh.md +0 -160
@@ -21,45 +21,27 @@ paths:
21
21
 
22
22
  # Security Audit
23
23
 
24
- You are invoked when the user wants a systematic security review of the current spec or codebase.
24
+ This skill orchestrates scoped security review. Keep the entrypoint focused on
25
+ scope/depth selection, required audit outputs, and the blocking gate. Detailed
26
+ rules live in:
25
27
 
26
- ## Preconditions
28
+ - `references/scope-and-depth.md`
29
+ - `references/audit-contract.md`
30
+ - `references/gate-handoff.md`
27
31
 
28
- 1. The code or spec under review is reachable from the current working directory.
29
- 2. The user has identified the scope (current spec, specific module, or whole repo).
32
+ ## Scope and Depth
30
33
 
31
- ## Workflow
34
+ Use `references/scope-and-depth.md` to confirm:
32
35
 
33
- ### Step 1: Clarify audit scope
36
+ - scope
37
+ - audit depth
38
+ - risk tolerance
34
39
 
35
- Confirm:
36
- - **Scope** (current spec / specific paths / whole repo)
37
- - **Depth** (OWASP-only / OWASP + STRIDE / + dependency CVE scan)
38
- - **Risk tolerance** (block on any SR / only block on SR with POC / advisory only)
40
+ ## Audit Contract
39
41
 
40
- ### Step 2: Run via `flow-security-auditor`
42
+ `flow-security-auditor` should follow `references/audit-contract.md`.
41
43
 
42
- This skill executes in a forked context through `flow-security-auditor`. It will:
43
- 1. Scan for hardcoded secrets, weak crypto, unsanitized inputs
44
- 2. Apply OWASP Top 10 (A01 Broken Access Control → A10 SSRF)
45
- 3. Apply STRIDE threat modeling (Spoofing, Tampering, Repudiation, Information disclosure, DoS, Elevation)
46
- 4. Run dependency CVE scan (`npm audit` / equivalent)
47
- 5. Produce a findings report with severity labels (SR = Blocking Red line, SW = Warning, SM = Mandatory-to-address)
44
+ ## Gate and Handoff
48
45
 
49
- ### Step 3: Write security report
50
-
51
- Output `.flow/specs/<active>/security-audit.md` containing:
52
- - **SR (blocking)** — must fix before ship
53
- - **SW (warning)** — should fix, won't block
54
- - **SM (mandatory)** — baseline items that must be present
55
- - **CVE hits** — direct / transitive dependencies with known vulns
56
- - **Recommended fixes** — concrete patches, not generic advice
57
-
58
- ### Step 4: Enforce gate
59
-
60
- Apply the `security-gate` (`@${CLAUDE_PLUGIN_ROOT}/gates/security-gate.md`) — if any SR findings exist, block completion until remediated or explicitly waived with a D-NN decision in STATE.md.
61
-
62
- ## References
63
-
64
- - `flow-security-auditor` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-security-auditor.md`
65
- - security-gate: `@${CLAUDE_PLUGIN_ROOT}/gates/security-gate.md`
46
+ Blocking semantics and next-step routing live in
47
+ `references/gate-handoff.md`.
@@ -0,0 +1,21 @@
1
+ # Security Audit Contract — What the Auditor Must Produce
2
+
3
+ `flow-security-auditor` should:
4
+
5
+ 1. scan for secrets, weak crypto, and unsafe inputs
6
+ 2. apply OWASP Top 10
7
+ 3. apply STRIDE threat modeling when requested
8
+ 4. run dependency CVE scanning
9
+ 5. label findings by severity
10
+
11
+ ## Required Artifact
12
+
13
+ - `.flow/specs/<active>/security-audit.md`
14
+
15
+ The report should include:
16
+
17
+ - SR (blocking)
18
+ - SW (warning)
19
+ - SM (mandatory baseline)
20
+ - CVE hits
21
+ - concrete fixes
@@ -0,0 +1,8 @@
1
+ # Security Gate Handoff — Blocking Rules and Next Steps
2
+
3
+ Apply `@${CLAUDE_PLUGIN_ROOT}/gates/security-gate.md`.
4
+
5
+ - if any SR findings exist, block completion until remediated or explicitly
6
+ waived with a D-NN decision in `STATE.md`
7
+ - if findings are advisory only, hand off `security-audit.md` as evidence for
8
+ later implementation or review work
@@ -0,0 +1,9 @@
1
+ # Security Scope and Depth — Confirm the Audit Shape
2
+
3
+ Before dispatching, confirm:
4
+
5
+ - scope: current spec, specific path, or whole repo
6
+ - depth: `owasp`, `stride`, or `full`
7
+ - risk tolerance: blocking vs advisory
8
+
9
+ The positional first argument is the scope. Depth stays in `--depth=...`.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: spec
3
- description: Generate or refresh the active spec across research, requirements, design, and tasks. Flags target phases, regeneration, and planning review.
3
+ description: Generate or refresh research, requirements, design, and tasks for the active spec.
4
4
  when_to_use: Use when the user wants to generate, resume, regenerate, or review a feature spec across research, requirements, design, and task planning.
5
5
  argument-hint: "[--phase=<X[,Y,...]>] [--until=<X>] [--review[=<dim[,dim]>]] [--regenerate] [--resume]"
6
6
  disable-model-invocation: true
@@ -9,7 +9,17 @@ allowed-tools: [Read, Write, Bash, Agent, AskUserQuestion]
9
9
 
10
10
  # Generate or Refresh the Active Spec
11
11
 
12
- This command writes the four spec documents (`research.md`, `requirements.md`, `design.md`, `tasks.md`) inside `.flow/specs/<active-spec>/`. It replaces the v1 commands `/research`, `/requirements`, `/design`, `/tasks`, `/plan-ceo`, `/plan-eng`, `/plan-design`, `/plan-dx`, and `/autoplan` — all expressed here as flags.
12
+ This command writes `research.md`, `requirements.md`, `design.md`, and
13
+ `tasks.md` into `.flow/specs/<active-spec>/`.
14
+
15
+ Keep this entrypoint focused on phase selection and orchestration. Detailed
16
+ phase prompts and landing checks live in:
17
+
18
+ - `references/preflight-and-routing.md`
19
+ - `references/phase-execution.md`
20
+ - `references/artifact-landing.md`
21
+ - `references/planning-review.md`
22
+ - `references/reporting.md`
13
23
 
14
24
  ## Flags
15
25
 
@@ -23,205 +33,68 @@ This command writes the four spec documents (`research.md`, `requirements.md`, `
23
33
 
24
34
  ## Preflight
25
35
 
26
- ```bash
27
- # 1. A .flow project must exist
28
- [ ! -d ".flow" ] && {
29
- echo "✗ Not a CurdX-Flow project. Run /curdx-flow:init first.";
30
- exit 1;
31
- }
32
-
33
- # 2. An active spec must be set
34
- SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
35
- if [ -z "$SPEC_NAME" ]; then
36
- echo "✗ No active spec. Run /curdx-flow:start <name> \"<goal>\" first.";
37
- exit 1;
38
- fi
39
- SPEC_DIR=".flow/specs/$SPEC_NAME"
40
- STATE_FILE="$SPEC_DIR/.state.json"
41
- [ ! -f "$STATE_FILE" ] && { echo "✗ Missing $STATE_FILE"; exit 1; }
42
- ```
43
-
44
- ## Flag parsing
45
-
46
- ```bash
47
- # $ARGUMENTS is the raw argument string
48
- FLAG_PHASE=$(echo "$ARGUMENTS" | grep -oP -- '--phase=\K[^\s]+' || true)
49
- FLAG_UNTIL=$(echo "$ARGUMENTS" | grep -oP -- '--until=\K[^\s]+' || true)
50
- FLAG_REVIEW=$(echo "$ARGUMENTS" | grep -oP -- '--review(?:=[^\s]+)?' || true)
51
- FLAG_REGENERATE=$(echo "$ARGUMENTS" | grep -q -- '--regenerate' && echo "1" || echo "0")
52
-
53
- # Rule: --phase and --until are mutually exclusive
54
- if [ -n "$FLAG_PHASE" ] && [ -n "$FLAG_UNTIL" ]; then
55
- echo "✗ --phase and --until cannot be combined. Pick one.";
56
- exit 1;
57
- fi
58
- ```
59
-
60
- ## Phase resolution
61
-
62
- The ordered pipeline is `research → requirements → design → tasks`. Resolve which phases to run:
63
-
64
- - No flags → start at `state.json.phase`, run forward to `tasks`.
65
- - `--phase=design` → run only `design`.
66
- - `--phase=design,tasks` → run `design` then `tasks`.
67
- - `--until=design` → start at `state.json.phase`, stop after `design`.
68
- - `--regenerate` (no other phase flag) → same as default but clear existing output for each phase before running.
69
- - `--regenerate --phase=X` → clear `X`'s output, re-run only `X`.
70
-
71
- Read and update `.state.json.phase` after each phase succeeds.
36
+ Use `references/preflight-and-routing.md` for:
72
37
 
73
- ## Phase execution
38
+ - `.flow/`, active spec, and `.state.json` checks
39
+ - flag parsing and invalid flag combinations
40
+ - ordered phase routing and `--regenerate` scope resolution
74
41
 
75
- For each phase in the resolved list, dispatch a subagent via the `Agent` tool:
42
+ ## Phase Resolution
76
43
 
77
- ### research `flow-researcher`
78
- Inputs: spec goal + one-line description from `.state.json`.
79
- Output: `research.md` covering problem space, prior art (library candidates via `context7`), constraints, technical recommendation.
44
+ The ordered pipeline is still `research -> requirements -> design -> tasks`.
45
+ The exact routing rules and stopping points are defined in
46
+ `references/preflight-and-routing.md`.
80
47
 
81
- **Dispatch prompt prefix (MANDATORY)**:
82
- ```
83
- CRITICAL OUTPUT PROTOCOL: Your FIRST action must be calling Write tool with the full research.md content. Do NOT explain, narrate, or preview. After Write succeeds, output EXACTLY 3 lines:
84
- ✓ research.md generated
85
- Recommendations: N
86
- Next: /curdx-flow:spec --phase=requirements
48
+ ## Phase Dispatch
87
49
 
88
- FORBIDDEN: explanations, summaries, findings lists. The file is the deliverable.
89
- ---
90
- ```
50
+ Phase-specific prompts, mandatory output protocols, and post-phase state updates
51
+ live in `references/phase-execution.md`.
91
52
 
92
- ### requirements → `flow-product-designer`
93
- Inputs: `research.md`.
94
- Output: `requirements.md` with user stories (US-NN), acceptance criteria (AC-N.N), functional requirements (FR-NN), non-functional requirements (NFR-*).
53
+ Use this phase-to-agent mapping:
95
54
 
96
- **Dispatch prompt prefix (MANDATORY)**:
97
- ```
98
- CRITICAL OUTPUT PROTOCOL: Your FIRST action must be calling Write tool with the full requirements.md content. Do NOT explain, narrate, or preview. After Write succeeds, output EXACTLY 4 lines:
99
- requirements.md generated
100
- User stories: N
101
- Functional requirements: N
102
- Next: /curdx-flow:spec --phase=design
55
+ | Phase | Agent | Output |
56
+ |-------|-------|--------|
57
+ | `research` | `flow-researcher` | `research.md` |
58
+ | `requirements` | `flow-product-designer` | `requirements.md` |
59
+ | `design` | `flow-architect` | `design.md` |
60
+ | `tasks` | `flow-planner` | `tasks.md` |
103
61
 
104
- FORBIDDEN: explanations, summaries, US/AC lists. The file is the deliverable.
105
- ---
106
- ```
62
+ After each dispatch, run the landing guard from
63
+ `references/artifact-landing.md`. Never advance phase state based only on the
64
+ agent's narrative response.
107
65
 
108
- ### design `flow-architect`
109
- Inputs: `research.md` + `requirements.md`.
110
- Output: `design.md` with architecture decisions (AD-NN), component boundaries, data models, error-path design, mermaid diagrams (when they clarify). Uses `sequential-thinking` MCP proportional to the genuine tradeoff surface.
66
+ ## Optional Planning Review
111
67
 
112
- **Dispatch prompt prefix (MANDATORY)**:
113
- ```
114
- CRITICAL OUTPUT PROTOCOL: Your FIRST action must be calling Write tool with the full design.md content. Do NOT explain, narrate, or preview. After Write succeeds, output EXACTLY 4 lines:
115
- ✓ design.md generated
116
- Architecture decisions: N
117
- Components: N
118
- Next: /curdx-flow:spec --phase=tasks
68
+ If `--review` is present, use the dimension-expansion and aggregation protocol
69
+ from `references/planning-review.md`.
119
70
 
120
- FORBIDDEN: explanations, summaries, AD lists, tech stack lists, warnings. The file is the deliverable.
121
- ---
122
- ```
71
+ The review output lands at:
123
72
 
124
- ### tasks → `flow-planner`
125
- Inputs: all three prior files + `.flow/PROJECT.md` tech stack.
126
- Output: `tasks.md` — POC-First 5-phase decomposition with per-task Verify commands, multi-source coverage audit against FR/AC/AD/Research/Decisions.
127
-
128
- **Dispatch prompt prefix (MANDATORY)**:
129
- ```
130
- CRITICAL OUTPUT PROTOCOL: Your FIRST action must be calling Write tool with the full tasks.md content. Do NOT explain, narrate, or preview. After Write succeeds, output EXACTLY 5 lines:
131
- ✓ tasks.md generated
132
- Total tasks: N
133
- Coverage audit: PASS
134
- Phases: 1-5
135
- Next: /curdx-flow:implement
136
-
137
- FORBIDDEN: explanations, summaries, task lists. The file is the deliverable.
138
- ---
139
- ```
140
-
141
- After each phase completes successfully, update `.state.json`:
142
-
143
- ```json
144
- {
145
- "phase": "<just-completed-phase>",
146
- "phase_status": { "<phase>": "completed" },
147
- "updated": "<ISO8601 timestamp>"
148
- }
149
- ```
150
-
151
- ### Artifact landing check (mandatory after every phase)
152
-
153
- Sub-agent responses can be truncated by the model's output-length limit, which means the `Write` tool call for the phase's Markdown artifact may never fire. Do NOT trust the agent's return value alone — always verify the file actually landed.
154
-
155
- For each phase just dispatched, run:
156
-
157
- ```bash
158
- ARTIFACT=".flow/specs/$SPEC_NAME/<phase>.md"
159
- if [ ! -f "$ARTIFACT" ]; then
160
- echo "⚠ $ARTIFACT did not land. Re-dispatching <phase> agent with an explicit 'write the file' prompt."
161
- # Re-dispatch the same agent, but in the prompt, front-load:
162
- # "Your ONLY job is to call the Write tool with the full <phase>.md content now.
163
- # Do not explain. Do not narrate. Write the file and stop."
164
- # This pattern produces an artifact even when prior verbosity caused truncation.
165
- fi
166
-
167
- # Minimum-size sanity check — if the file is <500 bytes, the write likely truncated
168
- if [ -f "$ARTIFACT" ] && [ "$(wc -c < "$ARTIFACT" | tr -d ' ')" -lt 500 ]; then
169
- echo "⚠ $ARTIFACT looks truncated (<500 bytes). Re-dispatching to complete it."
170
- fi
171
- ```
172
-
173
- Only advance `.state.json.phase` after both the file exists AND passes the size sanity check. If a re-dispatch also fails to produce the artifact, stop and surface the issue to the user instead of silently advancing — that prevents later phases from consuming an empty upstream file.
174
-
175
- ## Optional planning review
176
-
177
- If `--review` (or `--review=<dims>`) is present:
178
-
179
- 1. **Precondition**: `design.md` must exist. If missing, error: "Design missing. Run `/curdx-flow:spec --phase=design` first."
180
- 2. Parse the dims: `all` expands to `ceo,eng,design,dx`.
181
- 3. Dispatch review agents in parallel via `Agent` (one per dim):
182
-
183
- | Dim | Agent | Focus |
184
- |-----|-------|-------|
185
- | `ceo` | `flow-architect` (review mode) | Strategic: scope fit, ROI, opportunity cost |
186
- | `eng` | `flow-architect` (review mode) | Engineering: architecture lock-in, risk, technical debt |
187
- | `design` | `flow-ux-designer` | UX / UI / accessibility / design system |
188
- | `dx` | `flow-architect` (review mode) | Developer experience: naming, comments, structure, error handling, setup, types, tests, dev loop |
189
-
190
- 4. Aggregate findings into `.flow/specs/<active>/spec-review.md` with one section per dim and a consolidated verdict (GO / GO-WITH-CHANGES / HOLD).
73
+ - `.flow/specs/<active>/spec-review.md`
191
74
 
192
75
  ## Reporting
193
76
 
194
- Final console output:
77
+ Use `references/reporting.md` for the final user-visible summary and next-step
78
+ handoff.
195
79
 
196
- ```
197
- ✓ Spec <name> refreshed
198
- Phases run: research, requirements, design, tasks
199
- Review dims: ceo, eng, design, dx (if --review was used)
200
- Files:
201
- .flow/specs/<name>/research.md
202
- .flow/specs/<name>/requirements.md
203
- .flow/specs/<name>/design.md
204
- .flow/specs/<name>/tasks.md
205
- .flow/specs/<name>/spec-review.md (if --review was used)
206
-
207
- Next: /curdx-flow:implement
208
- ```
80
+ ## Common Invocations
209
81
 
210
- ## Common invocations
211
-
212
- ```
213
- /curdx-flow:spec # full spec from current state
214
- /curdx-flow:spec --phase=design # re-run only design (e.g., after requirements changed)
215
- /curdx-flow:spec --phase=design,tasks # re-run design and tasks
216
- /curdx-flow:spec --until=design # run up through design, stop (human review checkpoint)
217
- /curdx-flow:spec --review # full spec + all 4 planning dimensions
218
- /curdx-flow:spec --review=eng,dx # full spec + engineering + DX review only
219
- /curdx-flow:spec --regenerate # clear all four phases and rebuild
220
- /curdx-flow:spec --regenerate --phase=tasks # only rebuild tasks (keep research/requirements/design)
82
+ ```text
83
+ /curdx-flow:spec
84
+ /curdx-flow:spec --phase=design
85
+ /curdx-flow:spec --phase=design,tasks
86
+ /curdx-flow:spec --until=design
87
+ /curdx-flow:spec --review
88
+ /curdx-flow:spec --review=eng,dx
89
+ /curdx-flow:spec --regenerate
90
+ /curdx-flow:spec --regenerate --phase=tasks
221
91
  ```
222
92
 
223
93
  ## References
224
94
 
225
- - Agents: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-researcher.md`, `flow-product-designer.md`, `flow-architect.md`, `flow-planner.md`, `flow-ux-designer.md`
226
- - Knowledge: `@${CLAUDE_PLUGIN_ROOT}/knowledge/spec-driven-development.md`, `poc-first-workflow.md`
95
+ - Agents: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-researcher.md`,
96
+ `flow-product-designer.md`, `flow-architect.md`, `flow-planner.md`,
97
+ `flow-ux-designer.md`
98
+ - Knowledge: `@${CLAUDE_PLUGIN_ROOT}/knowledge/spec-driven-development.md`,
99
+ `poc-first-workflow.md`
227
100
  - Preamble: `@${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md`
@@ -0,0 +1,31 @@
1
+ # Artifact Landing Check — Mandatory After Every Phase
2
+
3
+ Sub-agent responses can be truncated before the `Write` tool call happens. Do
4
+ not trust the agent response alone.
5
+
6
+ ## Landing Guard
7
+
8
+ ```bash
9
+ ARTIFACT=".flow/specs/$SPEC_NAME/<phase>.md"
10
+ if [ ! -f "$ARTIFACT" ]; then
11
+ echo "⚠ $ARTIFACT did not land. Re-dispatching <phase> agent with an explicit 'write the file' prompt."
12
+ fi
13
+
14
+ if [ -f "$ARTIFACT" ] && [ "$(wc -c < "$ARTIFACT" | tr -d ' ')" -lt 500 ]; then
15
+ echo "⚠ $ARTIFACT looks truncated (<500 bytes). Re-dispatching to complete it."
16
+ fi
17
+ ```
18
+
19
+ ## Re-dispatch Rule
20
+
21
+ If the artifact is missing or obviously truncated, front-load the retry prompt
22
+ with:
23
+
24
+ ```text
25
+ Your ONLY job is to call the Write tool with the full <phase>.md content now.
26
+ Do not explain. Do not narrate. Write the file and stop.
27
+ ```
28
+
29
+ Only advance `.state.json.phase` after the file exists and passes the size
30
+ sanity check. If a second dispatch still fails, stop and surface the problem to
31
+ the user rather than silently continuing.
@@ -0,0 +1,50 @@
1
+ # Phase Execution — Dispatch Contracts
2
+
3
+ Each phase writes exactly one artifact. The file is the deliverable; agent
4
+ commentary is not.
5
+
6
+ Shared runtime references:
7
+
8
+ - `${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-output-discipline.md`
9
+ - `${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-summary-contracts.md`
10
+
11
+ ## Phase Map
12
+
13
+ | Phase | Agent | Inputs | Output |
14
+ |-------|-------|--------|--------|
15
+ | `research` | `flow-researcher` | spec goal + one-line description from `.state.json` | `research.md` |
16
+ | `requirements` | `flow-product-designer` | `research.md` | `requirements.md` |
17
+ | `design` | `flow-architect` | `research.md` + `requirements.md` | `design.md` |
18
+ | `tasks` | `flow-planner` | all prior artifacts + `.flow/PROJECT.md` | `tasks.md` |
19
+
20
+ ## Shared Dispatch Rule
21
+
22
+ Every phase dispatch must explicitly enforce the same two rules:
23
+
24
+ 1. The first substantive action is the `Write` call for the final artifact.
25
+ 2. After the write lands, emit only the matching summary contract from
26
+ `${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-summary-contracts.md`.
27
+
28
+ Do not inline previews, rationale summaries, or duplicate artifact content in
29
+ the orchestration skill.
30
+
31
+ ## Phase Output Contracts
32
+
33
+ | Phase | Artifact | Summary contract | Next line |
34
+ |-------|----------|------------------|-----------|
35
+ | `research` | `research.md` | `research.md` section | `Next: /curdx-flow:spec --phase=requirements` |
36
+ | `requirements` | `requirements.md` | `requirements.md` section | `Next: /curdx-flow:spec --phase=design` |
37
+ | `design` | `design.md` | `design.md` section | `Next: /curdx-flow:spec --phase=tasks` |
38
+ | `tasks` | `tasks.md` | `tasks.md` section | `Next: /curdx-flow:implement` |
39
+
40
+ ## Post-Phase State Update
41
+
42
+ After the artifact lands and passes landing checks, update `.state.json`:
43
+
44
+ ```json
45
+ {
46
+ "phase": "<just-completed-phase>",
47
+ "phase_status": { "<phase>": "completed" },
48
+ "updated": "<ISO8601 timestamp>"
49
+ }
50
+ ```
@@ -0,0 +1,31 @@
1
+ # Planning Review — Optional Multi-Dimension Pass
2
+
3
+ Use this only when `--review` is present.
4
+
5
+ ## Preconditions
6
+
7
+ - `design.md` must exist
8
+ - Bare `--review` expands to `ceo,eng,design,dx`
9
+ - `all` also expands to `ceo,eng,design,dx`
10
+
11
+ ## Dimension Map
12
+
13
+ | Dim | Agent | Focus |
14
+ |-----|-------|-------|
15
+ | `ceo` | `flow-architect` (review mode) | Strategic scope fit, ROI, opportunity cost |
16
+ | `eng` | `flow-architect` (review mode) | Lock-in risk, architecture debt, technical risk |
17
+ | `design` | `flow-ux-designer` | UX, UI, accessibility, design system fit |
18
+ | `dx` | `flow-architect` (review mode) | Naming, structure, setup, types, tests, developer loop |
19
+
20
+ ## Aggregation
21
+
22
+ Dispatch one review agent per dimension, aggregate findings into:
23
+
24
+ ```text
25
+ .flow/specs/<active>/spec-review.md
26
+ ```
27
+
28
+ The report must contain:
29
+
30
+ - one section per requested dimension
31
+ - a consolidated verdict: `GO`, `GO-WITH-CHANGES`, or `HOLD`
@@ -0,0 +1,46 @@
1
+ # Spec Preflight and Routing — Resolve What Runs
2
+
3
+ Before dispatching any phase:
4
+
5
+ ```bash
6
+ [ ! -d ".flow" ] && {
7
+ echo "✗ Not a CurdX-Flow project. Run /curdx-flow:init first.";
8
+ exit 1;
9
+ }
10
+
11
+ SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
12
+ if [ -z "$SPEC_NAME" ]; then
13
+ echo "✗ No active spec. Run /curdx-flow:start <name> \"<goal>\" first.";
14
+ exit 1;
15
+ fi
16
+ SPEC_DIR=".flow/specs/$SPEC_NAME"
17
+ STATE_FILE="$SPEC_DIR/.state.json"
18
+ [ ! -f "$STATE_FILE" ] && { echo "✗ Missing $STATE_FILE"; exit 1; }
19
+
20
+ FLAG_PHASE=$(echo "$ARGUMENTS" | grep -oP -- '--phase=\K[^\s]+' || true)
21
+ FLAG_UNTIL=$(echo "$ARGUMENTS" | grep -oP -- '--until=\K[^\s]+' || true)
22
+ FLAG_REVIEW=$(echo "$ARGUMENTS" | grep -oP -- '--review(?:=[^\s]+)?' || true)
23
+ FLAG_REGENERATE=$(echo "$ARGUMENTS" | grep -q -- '--regenerate' && echo "1" || echo "0")
24
+
25
+ if [ -n "$FLAG_PHASE" ] && [ -n "$FLAG_UNTIL" ]; then
26
+ echo "✗ --phase and --until cannot be combined. Pick one.";
27
+ exit 1;
28
+ fi
29
+ ```
30
+
31
+ The ordered pipeline is:
32
+
33
+ ```text
34
+ research -> requirements -> design -> tasks
35
+ ```
36
+
37
+ Routing rules:
38
+
39
+ - no flags -> start at `.state.json.phase`, run forward to `tasks`
40
+ - `--phase=design` -> run only `design`
41
+ - `--phase=design,tasks` -> run `design` then `tasks`
42
+ - `--until=design` -> start at `.state.json.phase`, stop after `design`
43
+ - `--regenerate` -> clear targeted phase output before rerunning it
44
+
45
+ Advance `.state.json.phase` only after the targeted artifact lands and passes
46
+ `references/artifact-landing.md`.
@@ -0,0 +1,21 @@
1
+ # Spec Reporting — Final Summary and Handoff
2
+
3
+ End with a compact execution summary:
4
+
5
+ ```text
6
+ ✓ Spec <name> refreshed
7
+ Phases run: research, requirements, design, tasks
8
+ Review dims: ceo, eng, design, dx (if --review was used)
9
+ Files:
10
+ .flow/specs/<name>/research.md
11
+ .flow/specs/<name>/requirements.md
12
+ .flow/specs/<name>/design.md
13
+ .flow/specs/<name>/tasks.md
14
+ .flow/specs/<name>/spec-review.md (if --review was used)
15
+
16
+ Next: /curdx-flow:implement
17
+ ```
18
+
19
+ Do not summarize the full content of the artifacts inline. The files are the
20
+ deliverables; the closing message only confirms what ran and where the outputs
21
+ landed.