@bhargavvc/sdd-cc 1.30.1 → 1.35.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (242) hide show
  1. package/README.ja-JP.md +144 -110
  2. package/README.ko-KR.md +143 -107
  3. package/README.md +183 -112
  4. package/README.pt-BR.md +90 -52
  5. package/README.zh-CN.md +141 -101
  6. package/agents/sdd-advisor-researcher.md +23 -0
  7. package/agents/sdd-ai-researcher.md +133 -0
  8. package/agents/sdd-code-fixer.md +516 -0
  9. package/agents/sdd-code-reviewer.md +355 -0
  10. package/agents/sdd-codebase-mapper.md +3 -3
  11. package/agents/sdd-debugger.md +17 -5
  12. package/agents/sdd-doc-verifier.md +201 -0
  13. package/agents/sdd-doc-writer.md +602 -0
  14. package/agents/sdd-domain-researcher.md +153 -0
  15. package/agents/sdd-eval-auditor.md +164 -0
  16. package/agents/sdd-eval-planner.md +154 -0
  17. package/agents/sdd-executor.md +87 -4
  18. package/agents/sdd-framework-selector.md +160 -0
  19. package/agents/sdd-intel-updater.md +314 -0
  20. package/agents/sdd-nyquist-auditor.md +1 -1
  21. package/agents/sdd-phase-researcher.md +71 -4
  22. package/agents/sdd-plan-checker.md +100 -6
  23. package/agents/sdd-planner.md +145 -206
  24. package/agents/sdd-project-researcher.md +25 -2
  25. package/agents/sdd-research-synthesizer.md +3 -3
  26. package/agents/sdd-roadmapper.md +6 -6
  27. package/agents/sdd-security-auditor.md +128 -0
  28. package/agents/sdd-ui-auditor.md +43 -3
  29. package/agents/sdd-ui-checker.md +5 -5
  30. package/agents/sdd-ui-researcher.md +27 -4
  31. package/agents/sdd-user-profiler.md +2 -2
  32. package/agents/sdd-verifier.md +142 -22
  33. package/bin/install.js +2145 -545
  34. package/commands/sdd/add-backlog.md +5 -5
  35. package/commands/sdd/add-tests.md +2 -2
  36. package/commands/sdd/ai-integration-phase.md +36 -0
  37. package/commands/sdd/analyze-dependencies.md +34 -0
  38. package/commands/sdd/audit-fix.md +33 -0
  39. package/commands/sdd/autonomous.md +7 -2
  40. package/commands/sdd/cleanup.md +5 -0
  41. package/commands/sdd/code-review-fix.md +52 -0
  42. package/commands/sdd/code-review.md +55 -0
  43. package/commands/sdd/complete-milestone.md +6 -6
  44. package/commands/sdd/debug.md +22 -9
  45. package/commands/sdd/discuss-phase.md +7 -2
  46. package/commands/sdd/do.md +1 -1
  47. package/commands/sdd/docs-update.md +48 -0
  48. package/commands/sdd/eval-review.md +32 -0
  49. package/commands/sdd/execute-phase.md +4 -0
  50. package/commands/sdd/explore.md +27 -0
  51. package/commands/sdd/fast.md +2 -2
  52. package/commands/sdd/from-sdd2.md +45 -0
  53. package/commands/sdd/help.md +2 -0
  54. package/commands/sdd/import.md +36 -0
  55. package/commands/sdd/intel.md +179 -0
  56. package/commands/sdd/join-discord.md +2 -1
  57. package/commands/sdd/manager.md +1 -0
  58. package/commands/sdd/map-codebase.md +3 -3
  59. package/commands/sdd/new-milestone.md +1 -1
  60. package/commands/sdd/new-project.md +5 -1
  61. package/commands/sdd/new-workspace.md +1 -1
  62. package/commands/sdd/next.md +2 -0
  63. package/commands/sdd/plan-milestone-gaps.md +2 -2
  64. package/commands/sdd/plan-phase.md +6 -1
  65. package/commands/sdd/plant-seed.md +1 -1
  66. package/commands/sdd/profile-user.md +1 -1
  67. package/commands/sdd/quick.md +5 -3
  68. package/commands/sdd/reapply-patches.md +230 -42
  69. package/commands/sdd/research-phase.md +3 -3
  70. package/commands/sdd/review-backlog.md +1 -0
  71. package/commands/sdd/review.md +6 -3
  72. package/commands/sdd/scan.md +26 -0
  73. package/commands/sdd/secure-phase.md +35 -0
  74. package/commands/sdd/ship.md +1 -1
  75. package/commands/sdd/thread.md +5 -5
  76. package/commands/sdd/undo.md +34 -0
  77. package/commands/sdd/verify-work.md +1 -1
  78. package/commands/sdd/workstreams.md +17 -11
  79. package/hooks/dist/sdd-check-update.js +33 -8
  80. package/hooks/dist/sdd-context-monitor.js +17 -8
  81. package/hooks/dist/sdd-phase-boundary.sh +27 -0
  82. package/hooks/dist/sdd-prompt-guard.js +1 -0
  83. package/hooks/dist/sdd-read-guard.js +82 -0
  84. package/hooks/dist/sdd-session-state.sh +33 -0
  85. package/hooks/dist/sdd-statusline.js +137 -15
  86. package/hooks/dist/sdd-validate-commit.sh +47 -0
  87. package/hooks/dist/sdd-workflow-guard.js +4 -4
  88. package/hooks/sdd-check-update.js +139 -0
  89. package/hooks/sdd-context-monitor.js +165 -0
  90. package/hooks/sdd-phase-boundary.sh +27 -0
  91. package/hooks/sdd-prompt-guard.js +97 -0
  92. package/hooks/sdd-read-guard.js +82 -0
  93. package/hooks/sdd-session-state.sh +33 -0
  94. package/hooks/sdd-statusline.js +241 -0
  95. package/hooks/sdd-validate-commit.sh +47 -0
  96. package/hooks/sdd-workflow-guard.js +94 -0
  97. package/package.json +3 -3
  98. package/scripts/build-hooks.js +18 -7
  99. package/scripts/prompt-injection-scan.sh +1 -0
  100. package/scripts/rebrand-gsd-to-sdd.sh +221 -220
  101. package/scripts/run-tests.cjs +5 -1
  102. package/scripts/sync-upstream.sh +1 -1
  103. package/sdd/bin/lib/commands.cjs +79 -17
  104. package/sdd/bin/lib/config.cjs +90 -48
  105. package/sdd/bin/lib/core.cjs +452 -87
  106. package/sdd/bin/lib/docs.cjs +267 -0
  107. package/sdd/bin/lib/frontmatter.cjs +381 -336
  108. package/sdd/bin/lib/init.cjs +110 -16
  109. package/sdd/bin/lib/intel.cjs +660 -0
  110. package/sdd/bin/lib/learnings.cjs +378 -0
  111. package/sdd/bin/lib/milestone.cjs +42 -11
  112. package/sdd/bin/lib/model-profiles.cjs +17 -15
  113. package/sdd/bin/lib/phase.cjs +367 -288
  114. package/sdd/bin/lib/profile-output.cjs +106 -10
  115. package/sdd/bin/lib/roadmap.cjs +146 -115
  116. package/sdd/bin/lib/schema-detect.cjs +238 -0
  117. package/sdd/bin/lib/sdd2-import.cjs +511 -0
  118. package/sdd/bin/lib/security.cjs +124 -3
  119. package/sdd/bin/lib/state.cjs +648 -264
  120. package/sdd/bin/lib/template.cjs +8 -4
  121. package/sdd/bin/lib/verify.cjs +209 -28
  122. package/sdd/bin/lib/workstream.cjs +7 -3
  123. package/sdd/bin/sdd-tools.cjs +184 -12
  124. package/sdd/contexts/dev.md +21 -0
  125. package/sdd/contexts/research.md +22 -0
  126. package/sdd/contexts/review.md +22 -0
  127. package/sdd/references/agent-contracts.md +79 -0
  128. package/sdd/references/ai-evals.md +156 -0
  129. package/sdd/references/ai-frameworks.md +186 -0
  130. package/sdd/references/artifact-types.md +113 -0
  131. package/sdd/references/common-bug-patterns.md +114 -0
  132. package/sdd/references/context-budget.md +49 -0
  133. package/sdd/references/continuation-format.md +25 -25
  134. package/sdd/references/domain-probes.md +125 -0
  135. package/sdd/references/few-shot-examples/plan-checker.md +73 -0
  136. package/sdd/references/few-shot-examples/verifier.md +109 -0
  137. package/sdd/references/gate-prompts.md +100 -0
  138. package/sdd/references/gates.md +70 -0
  139. package/sdd/references/git-integration.md +1 -1
  140. package/sdd/references/ios-scaffold.md +123 -0
  141. package/sdd/references/model-profile-resolution.md +2 -0
  142. package/sdd/references/model-profiles.md +24 -18
  143. package/sdd/references/planner-gap-closure.md +62 -0
  144. package/sdd/references/planner-reviews.md +39 -0
  145. package/sdd/references/planner-revision.md +87 -0
  146. package/sdd/references/planning-config.md +252 -0
  147. package/sdd/references/revision-loop.md +97 -0
  148. package/sdd/references/thinking-models-debug.md +44 -0
  149. package/sdd/references/thinking-models-execution.md +50 -0
  150. package/sdd/references/thinking-models-planning.md +62 -0
  151. package/sdd/references/thinking-models-research.md +50 -0
  152. package/sdd/references/thinking-models-verification.md +55 -0
  153. package/sdd/references/thinking-partner.md +96 -0
  154. package/sdd/references/ui-brand.md +4 -4
  155. package/sdd/references/universal-anti-patterns.md +63 -0
  156. package/sdd/references/verification-overrides.md +227 -0
  157. package/sdd/references/workstream-flag.md +56 -3
  158. package/sdd/templates/AI-SPEC.md +246 -0
  159. package/sdd/templates/DEBUG.md +1 -1
  160. package/sdd/templates/SECURITY.md +61 -0
  161. package/sdd/templates/UAT.md +4 -4
  162. package/sdd/templates/VALIDATION.md +4 -4
  163. package/sdd/templates/claude-md.md +32 -9
  164. package/sdd/templates/config.json +4 -0
  165. package/sdd/templates/debug-subagent-prompt.md +1 -1
  166. package/sdd/templates/dev-preferences.md +1 -1
  167. package/sdd/templates/discovery.md +2 -2
  168. package/sdd/templates/phase-prompt.md +1 -1
  169. package/sdd/templates/planner-subagent-prompt.md +3 -3
  170. package/sdd/templates/project.md +1 -1
  171. package/sdd/templates/research.md +1 -1
  172. package/sdd/templates/state.md +2 -2
  173. package/sdd/workflows/add-phase.md +8 -8
  174. package/sdd/workflows/add-tests.md +12 -9
  175. package/sdd/workflows/add-todo.md +5 -3
  176. package/sdd/workflows/ai-integration-phase.md +284 -0
  177. package/sdd/workflows/analyze-dependencies.md +96 -0
  178. package/sdd/workflows/audit-fix.md +157 -0
  179. package/sdd/workflows/audit-milestone.md +11 -11
  180. package/sdd/workflows/audit-uat.md +2 -2
  181. package/sdd/workflows/autonomous.md +195 -27
  182. package/sdd/workflows/check-todos.md +12 -10
  183. package/sdd/workflows/cleanup.md +2 -0
  184. package/sdd/workflows/code-review-fix.md +497 -0
  185. package/sdd/workflows/code-review.md +515 -0
  186. package/sdd/workflows/complete-milestone.md +56 -22
  187. package/sdd/workflows/diagnose-issues.md +10 -3
  188. package/sdd/workflows/discovery-phase.md +5 -3
  189. package/sdd/workflows/discuss-phase-assumptions.md +24 -6
  190. package/sdd/workflows/discuss-phase-power.md +291 -0
  191. package/sdd/workflows/discuss-phase.md +173 -21
  192. package/sdd/workflows/do.md +23 -21
  193. package/sdd/workflows/docs-update.md +1155 -0
  194. package/sdd/workflows/eval-review.md +155 -0
  195. package/sdd/workflows/execute-phase.md +594 -38
  196. package/sdd/workflows/execute-plan.md +67 -96
  197. package/sdd/workflows/explore.md +139 -0
  198. package/sdd/workflows/fast.md +5 -5
  199. package/sdd/workflows/forensics.md +2 -2
  200. package/sdd/workflows/health.md +4 -4
  201. package/sdd/workflows/help.md +122 -119
  202. package/sdd/workflows/import.md +276 -0
  203. package/sdd/workflows/inbox.md +387 -0
  204. package/sdd/workflows/insert-phase.md +7 -7
  205. package/sdd/workflows/list-phase-assumptions.md +4 -4
  206. package/sdd/workflows/list-workspaces.md +2 -2
  207. package/sdd/workflows/manager.md +35 -32
  208. package/sdd/workflows/map-codebase.md +7 -5
  209. package/sdd/workflows/milestone-summary.md +2 -2
  210. package/sdd/workflows/new-milestone.md +17 -9
  211. package/sdd/workflows/new-project.md +50 -25
  212. package/sdd/workflows/new-workspace.md +7 -5
  213. package/sdd/workflows/next.md +67 -11
  214. package/sdd/workflows/note.md +9 -7
  215. package/sdd/workflows/pause-work.md +75 -12
  216. package/sdd/workflows/plan-milestone-gaps.md +8 -8
  217. package/sdd/workflows/plan-phase.md +294 -42
  218. package/sdd/workflows/plant-seed.md +6 -3
  219. package/sdd/workflows/pr-branch.md +42 -14
  220. package/sdd/workflows/profile-user.md +9 -7
  221. package/sdd/workflows/progress.md +45 -45
  222. package/sdd/workflows/quick.md +195 -47
  223. package/sdd/workflows/remove-phase.md +6 -6
  224. package/sdd/workflows/remove-workspace.md +3 -1
  225. package/sdd/workflows/research-phase.md +2 -2
  226. package/sdd/workflows/resume-project.md +12 -12
  227. package/sdd/workflows/review.md +109 -9
  228. package/sdd/workflows/scan.md +102 -0
  229. package/sdd/workflows/secure-phase.md +166 -0
  230. package/sdd/workflows/session-report.md +2 -2
  231. package/sdd/workflows/settings.md +38 -12
  232. package/sdd/workflows/ship.md +21 -9
  233. package/sdd/workflows/stats.md +1 -1
  234. package/sdd/workflows/transition.md +23 -23
  235. package/sdd/workflows/ui-phase.md +15 -7
  236. package/sdd/workflows/ui-review.md +29 -4
  237. package/sdd/workflows/undo.md +314 -0
  238. package/sdd/workflows/update.md +171 -20
  239. package/sdd/workflows/validate-phase.md +6 -4
  240. package/sdd/workflows/verify-phase.md +210 -6
  241. package/sdd/workflows/verify-work.md +83 -9
  242. package/sdd/commands/sdd/workstreams.md +0 -63
@@ -0,0 +1,276 @@
1
+ # Import Workflow
2
+
3
+ External plan ingestion with conflict detection and agent delegation.
4
+
5
+ - **--from**: Import external plan → conflict detection → write PLAN.md → validate via sdd-plan-checker
6
+
7
+ Future: `--prd` mode (PRD extraction into PROJECT.md + REQUIREMENTS.md + ROADMAP.md) is planned for a follow-up PR.
8
+
9
+ ---
10
+
11
+ <step name="banner">
12
+
13
+ Display the stage banner:
14
+
15
+ ```
16
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
17
+ SDD ► IMPORT
18
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
19
+ ```
20
+
21
+ </step>
22
+
23
+ <step name="parse_arguments">
24
+
25
+ Parse `$ARGUMENTS` to determine the execution mode:
26
+
27
+ - If `--from` is present: extract FILEPATH (the next token after `--from`), set MODE=plan
28
+ - If `--prd` is present: display message that `--prd` is not yet implemented and exit:
29
+ ```
30
+ SDD > --prd mode is planned for a future release. Use --from to import plan files.
31
+ ```
32
+ - If neither flag is found: display usage and exit:
33
+
34
+ ```
35
+ Usage: /sdd-import --from <path>
36
+
37
+ --from <path> Import an external plan file into SDD format
38
+ ```
39
+
40
+ **Validate the file path:**
41
+
42
+ Verify the path does not contain traversal sequences and the file exists:
43
+
44
+ ```bash
45
+ case "{FILEPATH}" in
46
+ *..* ) echo "SECURITY_ERROR: path contains traversal sequence"; exit 1 ;;
47
+ esac
48
+ test -f "{FILEPATH}" || echo "FILE_NOT_FOUND"
49
+ ```
50
+
51
+ If FILE_NOT_FOUND: display error and exit:
52
+
53
+ ```
54
+ ╔══════════════════════════════════════════════════════════════╗
55
+ ║ ERROR ║
56
+ ╚══════════════════════════════════════════════════════════════╝
57
+
58
+ File not found: {FILEPATH}
59
+
60
+ **To fix:** Verify the file path and try again.
61
+ ```
62
+
63
+ </step>
64
+
65
+ ---
66
+
67
+ ## Path A: MODE=plan (--from)
68
+
69
+ <step name="plan_load_context">
70
+
71
+ Load project context for conflict detection:
72
+
73
+ 1. Read `.planning/ROADMAP.md` — extract phase structure, phase numbers, dependencies
74
+ 2. Read `.planning/PROJECT.md` — extract project constraints, tech stack, scope boundaries.
75
+ **If PROJECT.md does not exist:** skip constraint checks that rely on it and display:
76
+ ```
77
+ SDD > Note: No PROJECT.md found. Conflict checks against project constraints will be skipped.
78
+ ```
79
+ 3. Read `.planning/REQUIREMENTS.md` — extract existing requirements for overlap and contradiction checks.
80
+ **If REQUIREMENTS.md does not exist:** skip requirement conflict checks and continue.
81
+ 4. Glob for all CONTEXT.md files across phase directories:
82
+ ```bash
83
+ find .planning/phases/ -name "*-CONTEXT.md" -o -name "CONTEXT.md" 2>/dev/null
84
+ ```
85
+ Read each CONTEXT.md found — extract locked decisions (any decision in a `<decisions>` block)
86
+
87
+ Store loaded context for conflict detection in the next step.
88
+
89
+ </step>
90
+
91
+ <step name="plan_read_input">
92
+
93
+ Read the imported file at FILEPATH.
94
+
95
+ Determine the format:
96
+ - **SDD PLAN.md format**: Has YAML frontmatter with `phase:`, `plan:`, `type:` fields
97
+ - **Freeform document**: Any other format (markdown spec, design doc, task list, etc.)
98
+
99
+ Extract from the imported content:
100
+ - **Phase target**: Which phase this plan belongs to (from frontmatter or inferred from content)
101
+ - **Plan objectives**: What the plan aims to accomplish
102
+ - **Tasks listed**: Individual work items described in the plan
103
+ - **Files modified**: Any files mentioned as targets
104
+ - **Dependencies**: Any referenced prerequisites
105
+
106
+ </step>
107
+
108
+ <step name="plan_conflict_detection">
109
+
110
+ Run conflict checks against the loaded project context. Output as a plain-text conflict report using [BLOCKER], [WARNING], and [INFO] labels. Do NOT use markdown tables (no `|---|` format).
111
+
112
+ ### BLOCKER checks (any one prevents import):
113
+
114
+ - Plan targets a phase number that does not exist in ROADMAP.md → [BLOCKER]
115
+ - Plan specifies a tech stack that contradicts PROJECT.md constraints → [BLOCKER]
116
+ - Plan contradicts a locked decision in any CONTEXT.md `<decisions>` block → [BLOCKER]
117
+ - Plan contradicts an existing requirement in REQUIREMENTS.md → [BLOCKER]
118
+
119
+ ### WARNING checks (user confirmation required):
120
+
121
+ - Plan partially overlaps existing requirement coverage in REQUIREMENTS.md → [WARNING]
122
+ - Plan has `depends_on` referencing plans that are not yet complete → [WARNING]
123
+ - Plan modifies files that overlap with existing incomplete plans → [WARNING]
124
+ - Plan phase number conflicts with existing phase numbering in ROADMAP.md → [WARNING]
125
+
126
+ ### INFO checks (informational, no action needed):
127
+
128
+ - Plan uses a library not currently in the project tech stack → [INFO]
129
+ - Plan adds a new phase to the ROADMAP.md structure → [INFO]
130
+
131
+ Display the full Conflict Detection Report:
132
+
133
+ ```
134
+ ## Conflict Detection Report
135
+
136
+ ### BLOCKERS ({N})
137
+
138
+ [BLOCKER] {Short title}
139
+ Found: {what the imported plan says}
140
+ Expected: {what project context requires}
141
+ → {Specific action to resolve}
142
+
143
+ ### WARNINGS ({N})
144
+
145
+ [WARNING] {Short title}
146
+ Found: {what was detected}
147
+ Impact: {what could go wrong}
148
+ → {Suggested action}
149
+
150
+ ### INFO ({N})
151
+
152
+ [INFO] {Short title}
153
+ Note: {relevant information}
154
+ ```
155
+
156
+ **If any [BLOCKER] exists:**
157
+
158
+ Display:
159
+ ```
160
+ SDD > BLOCKED: {N} blockers must be resolved before import can proceed.
161
+ ```
162
+
163
+ Exit WITHOUT writing any files. This is the safety gate — no PLAN.md is written when blockers exist.
164
+
165
+ **If only WARNINGS and/or INFO (no blockers):**
166
+
167
+
168
+ **Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
169
+ Ask via AskUserQuestion using the approve-revise-abort pattern:
170
+ - question: "Review the warnings above. Proceed with import?"
171
+ - header: "Approve?"
172
+ - options: Approve | Abort
173
+
174
+ If user selects "Abort": exit cleanly with message "Import cancelled."
175
+
176
+ </step>
177
+
178
+ <step name="plan_convert">
179
+
180
+ Convert the imported content to SDD PLAN.md format.
181
+
182
+ Ensure the PLAN.md has all required frontmatter fields:
183
+ ```yaml
184
+ ---
185
+ phase: "{NN}-{slug}"
186
+ plan: "{NN}-{MM}"
187
+ type: "feature|refactor|config|test|docs"
188
+ wave: 1
189
+ depends_on: []
190
+ files_modified: []
191
+ autonomous: true
192
+ must_haves:
193
+ truths: []
194
+ artifacts: []
195
+ ---
196
+ ```
197
+
198
+ **Reject PBR naming conventions in source content:**
199
+ If the imported plan references PBR plan naming (e.g., `PLAN-01.md`, `plan-01.md`), rename all references to SDD `{NN}-{MM}-PLAN.md` convention during conversion.
200
+
201
+ Apply SDD naming convention for the output filename:
202
+ - Format: `{NN}-{MM}-PLAN.md` (e.g., `04-01-PLAN.md`)
203
+ - NEVER use `PLAN-01.md`, `plan-01.md`, or any other format
204
+ - NN = phase number (zero-padded), MM = plan number within the phase (zero-padded)
205
+
206
+ Determine the target directory:
207
+ ```
208
+ .planning/phases/{NN}-{slug}/
209
+ ```
210
+
211
+ If the directory does not exist, create it:
212
+ ```bash
213
+ mkdir -p ".planning/phases/{NN}-{slug}/"
214
+ ```
215
+
216
+ Write the PLAN.md file to the target directory.
217
+
218
+ </step>
219
+
220
+ <step name="plan_validate">
221
+
222
+ Delegate validation to sdd-plan-checker:
223
+
224
+ ```
225
+ Task({
226
+ subagent_type: "sdd-plan-checker",
227
+ prompt: "Validate: .planning/phases/{phase}/{plan}-PLAN.md — check frontmatter completeness, task structure, and SDD conventions. Report any issues."
228
+ })
229
+ ```
230
+
231
+ If the checker returns errors:
232
+ - Display the errors to the user
233
+ - Ask the user to resolve issues before the plan is considered imported
234
+ - Do not delete the written file — the user can fix and re-validate manually
235
+
236
+ If the checker returns clean:
237
+ - Display: "Plan validation passed"
238
+
239
+ </step>
240
+
241
+ <step name="plan_finalize">
242
+
243
+ Update `.planning/ROADMAP.md` to reflect the new plan:
244
+ - Add the plan to the Plans list under the correct phase section
245
+ - Include the plan name and description
246
+
247
+ Update `.planning/STATE.md` if appropriate (e.g., increment total plan count).
248
+
249
+ Commit the imported plan and updated files:
250
+ ```bash
251
+ node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs({phase}): import plan from {basename FILEPATH}" --files .planning/phases/{phase}/{plan}-PLAN.md .planning/ROADMAP.md
252
+ ```
253
+
254
+ Display completion:
255
+ ```
256
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
257
+ SDD ► IMPORT COMPLETE
258
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
259
+ ```
260
+
261
+ Show: plan filename written, phase directory, validation result, next steps.
262
+
263
+ </step>
264
+
265
+ ---
266
+
267
+ ## Anti-Patterns
268
+
269
+ Do NOT:
270
+ - Use markdown tables (`|---|`) in the conflict detection report — use plain-text [BLOCKER]/[WARNING]/[INFO] labels
271
+ - Write PLAN.md files as `PLAN-01.md` or `plan-01.md` — always use `{NN}-{MM}-PLAN.md`
272
+ - Use `pbr:plan-checker` or `pbr:planner` — use `sdd-plan-checker` and `sdd-planner`
273
+ - Write `.planning/.active-skill` — this is a PBR pattern with no SDD equivalent
274
+ - Reference `pbr-tools`, `pbr:`, or `PLAN-BUILD-RUN` anywhere
275
+ - Write any PLAN.md file when blockers exist — the safety gate must hold
276
+ - Skip path validation on the --from file argument
@@ -0,0 +1,387 @@
1
+ <purpose>
2
+ Triage and review all open GitHub issues and PRs against project contribution templates.
3
+ Produces a structured report showing compliance status for each item, flags missing
4
+ required fields, identifies label gaps, and optionally takes action (label, comment, close).
5
+ </purpose>
6
+
7
+ <required_reading>
8
+ Before starting, read these project files to understand the review criteria:
9
+ - `.github/ISSUE_TEMPLATE/feature_request.yml` — required fields for feature issues
10
+ - `.github/ISSUE_TEMPLATE/enhancement.yml` — required fields for enhancement issues
11
+ - `.github/ISSUE_TEMPLATE/chore.yml` — required fields for chore issues
12
+ - `.github/ISSUE_TEMPLATE/bug_report.yml` — required fields for bug reports
13
+ - `.github/PULL_REQUEST_TEMPLATE/feature.md` — required checklist for feature PRs
14
+ - `.github/PULL_REQUEST_TEMPLATE/enhancement.md` — required checklist for enhancement PRs
15
+ - `.github/PULL_REQUEST_TEMPLATE/fix.md` — required checklist for fix PRs
16
+ - `CONTRIBUTING.md` — the issue-first rule and approval gates
17
+ </required_reading>
18
+
19
+ <process>
20
+
21
+ <step name="preflight">
22
+ Verify prerequisites:
23
+
24
+ 1. **`gh` CLI available and authenticated?**
25
+ ```bash
26
+ which gh && gh auth status 2>&1
27
+ ```
28
+ If not available: print setup instructions and exit.
29
+
30
+ 2. **Detect repository:**
31
+ If `--repo` flag provided, use that. Otherwise:
32
+ ```bash
33
+ gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null
34
+ ```
35
+ If no repo detected: error — must be in a git repo with a GitHub remote.
36
+
37
+ 3. **Parse flags:**
38
+ - `--issues` → set REVIEW_ISSUES=true, REVIEW_PRS=false
39
+ - `--prs` → set REVIEW_ISSUES=false, REVIEW_PRS=true
40
+ - `--label` → set AUTO_LABEL=true
41
+ - `--close-incomplete` → set AUTO_CLOSE=true
42
+ - Default (no flags): review both issues and PRs, report only (no auto-actions)
43
+ </step>
44
+
45
+ <step name="fetch_issues">
46
+ Skip if REVIEW_ISSUES=false.
47
+
48
+ Fetch all open issues:
49
+ ```bash
50
+ gh issue list --state open --json number,title,labels,body,author,createdAt,updatedAt --limit 100
51
+ ```
52
+
53
+ For each issue, classify by labels and body content:
54
+
55
+ | Label/Pattern | Type | Template |
56
+ |---|---|---|
57
+ | `feature-request` | Feature | feature_request.yml |
58
+ | `enhancement` | Enhancement | enhancement.yml |
59
+ | `bug` | Bug | bug_report.yml |
60
+ | `type: chore` | Chore | chore.yml |
61
+ | No matching label | Unknown | Flag for manual triage |
62
+
63
+ If an issue has no type label, attempt to classify from the body content:
64
+ - Contains "### Feature name" → likely Feature
65
+ - Contains "### What existing feature" → likely Enhancement
66
+ - Contains "### What happened?" → likely Bug
67
+ - Contains "### What is the maintenance task?" → likely Chore
68
+ - Cannot determine → mark as `needs-triage`
69
+ </step>
70
+
71
+ <step name="review_issues">
72
+ Skip if REVIEW_ISSUES=false.
73
+
74
+ For each classified issue, review against its template requirements.
75
+
76
+ **Feature Request Review Checklist:**
77
+ - [ ] Pre-submission checklist present (4 checkboxes)
78
+ - [ ] Feature name provided
79
+ - [ ] Type of addition selected
80
+ - [ ] Problem statement filled (not placeholder text)
81
+ - [ ] What is being added described with examples
82
+ - [ ] Full scope of changes listed (files created/modified/systems)
83
+ - [ ] User stories present (minimum 2)
84
+ - [ ] Acceptance criteria present (testable conditions)
85
+ - [ ] Applicable runtimes selected
86
+ - [ ] Breaking changes assessment present
87
+ - [ ] Maintenance burden described
88
+ - [ ] Alternatives considered (not empty)
89
+ - **Label check:** Has `needs-review` label? Has `approved-feature` label?
90
+ - **Gate check:** If PR exists linking this issue, does issue have `approved-feature`?
91
+
92
+ **Enhancement Review Checklist:**
93
+ - [ ] Pre-submission checklist present (4 checkboxes)
94
+ - [ ] What is being improved identified
95
+ - [ ] Current behavior described with examples
96
+ - [ ] Proposed behavior described with examples
97
+ - [ ] Reason and benefit articulated (not vague)
98
+ - [ ] Scope of changes listed
99
+ - [ ] Breaking changes assessed
100
+ - [ ] Alternatives considered
101
+ - [ ] Area affected selected
102
+ - **Label check:** Has `needs-review` label? Has `approved-enhancement` label?
103
+ - **Gate check:** If PR exists linking this issue, does issue have `approved-enhancement`?
104
+
105
+ **Bug Report Review Checklist:**
106
+ - [ ] SDD Version provided
107
+ - [ ] Runtime selected
108
+ - [ ] OS selected
109
+ - [ ] Node.js version provided
110
+ - [ ] Description of what happened
111
+ - [ ] Expected behavior described
112
+ - [ ] Steps to reproduce provided
113
+ - [ ] Frequency selected
114
+ - [ ] Severity/impact selected
115
+ - [ ] PII checklist confirmed
116
+ - **Label check:** Has `needs-triage` or `confirmed-bug` label?
117
+
118
+ **Chore Review Checklist:**
119
+ - [ ] Pre-submission checklist confirmed (no user-facing changes)
120
+ - [ ] Maintenance task described
121
+ - [ ] Type of maintenance selected
122
+ - [ ] Current state described with specifics
123
+ - [ ] Proposed work listed
124
+ - [ ] Acceptance criteria present
125
+ - [ ] Area affected selected
126
+ - **Label check:** Has `needs-triage` label?
127
+
128
+ **Scoring:** For each issue, calculate a completeness percentage:
129
+ - Count required fields present vs. total required fields
130
+ - Score = (present / total) * 100
131
+ - Status: COMPLETE (100%), MOSTLY COMPLETE (75-99%), INCOMPLETE (50-74%), REJECT (<50%)
132
+ </step>
133
+
134
+ <step name="fetch_prs">
135
+ Skip if REVIEW_PRS=false.
136
+
137
+ Fetch all open PRs:
138
+ ```bash
139
+ gh pr list --state open --json number,title,labels,body,author,headRefName,baseRefName,isDraft,createdAt,reviewDecision,statusCheckRollup --limit 100
140
+ ```
141
+
142
+ For each PR, classify by body content and linked issue:
143
+
144
+ | Body Pattern | Type | Template |
145
+ |---|---|---|
146
+ | Contains "## Feature PR" or "## Feature summary" | Feature PR | feature.md |
147
+ | Contains "## Enhancement PR" or "## What this enhancement improves" | Enhancement PR | enhancement.md |
148
+ | Contains "## Fix PR" or "## What was broken" | Fix PR | fix.md |
149
+ | Uses default template | Wrong Template | Flag — must use typed template |
150
+ | Cannot determine | Unknown | Flag for manual review |
151
+
152
+ Also check for linked issues:
153
+ ```bash
154
+ gh pr view {number} --json body -q '.body' | grep -oE '(Closes|Fixes|Resolves) #[0-9]+'
155
+ ```
156
+ </step>
157
+
158
+ <step name="review_prs">
159
+ Skip if REVIEW_PRS=false.
160
+
161
+ For each classified PR, review against its template requirements.
162
+
163
+ **Feature PR Review Checklist:**
164
+ - [ ] Uses feature PR template (not default)
165
+ - [ ] Issue linked with `Closes #NNN`
166
+ - [ ] Linked issue exists and has `approved-feature` label
167
+ - [ ] Feature summary present
168
+ - [ ] New files table filled
169
+ - [ ] Modified files table filled
170
+ - [ ] Implementation notes present
171
+ - [ ] Spec compliance checklist present (acceptance criteria from issue)
172
+ - [ ] Test coverage described
173
+ - [ ] Platforms tested checked (macOS, Windows, Linux)
174
+ - [ ] Runtimes tested checked
175
+ - [ ] Scope confirmation checked
176
+ - [ ] Full checklist completed
177
+ - [ ] Breaking changes section filled
178
+ - **CI check:** All status checks passing?
179
+ - **Review check:** Has review approval?
180
+
181
+ **Enhancement PR Review Checklist:**
182
+ - [ ] Uses enhancement PR template (not default)
183
+ - [ ] Issue linked with `Closes #NNN`
184
+ - [ ] Linked issue exists and has `approved-enhancement` label
185
+ - [ ] What is improved described
186
+ - [ ] Before/after provided
187
+ - [ ] Implementation approach described
188
+ - [ ] Verification method described
189
+ - [ ] Platforms tested checked
190
+ - [ ] Runtimes tested checked
191
+ - [ ] Scope confirmation checked
192
+ - [ ] Full checklist completed
193
+ - [ ] Breaking changes section filled
194
+ - **CI check:** All status checks passing?
195
+
196
+ **Fix PR Review Checklist:**
197
+ - [ ] Uses fix PR template (not default)
198
+ - [ ] Issue linked with `Fixes #NNN`
199
+ - [ ] Linked issue exists and has `confirmed-bug` label
200
+ - [ ] What was broken described
201
+ - [ ] What the fix does described
202
+ - [ ] Root cause explained
203
+ - [ ] Verification method described
204
+ - [ ] Regression test added (or explained why not)
205
+ - [ ] Platforms tested checked
206
+ - [ ] Runtimes tested checked
207
+ - [ ] Full checklist completed
208
+ - [ ] Breaking changes section filled
209
+ - **CI check:** All status checks passing?
210
+
211
+ **Cross-cutting PR Checks (all types):**
212
+ - [ ] PR title is descriptive (not just "fix" or "update")
213
+ - [ ] One concern per PR (not mixing fix + enhancement)
214
+ - [ ] No unrelated formatting changes visible in diff
215
+ - [ ] CHANGELOG.md updated
216
+ - [ ] Not using `--no-verify` or skipping hooks
217
+
218
+ **Scoring:** Same as issues — completeness percentage per PR.
219
+ </step>
220
+
221
+ <step name="check_gates">
222
+ Cross-reference issues and PRs to enforce the issue-first rule:
223
+
224
+ For each open PR:
225
+ 1. Extract linked issue number from body
226
+ 2. If no linked issue: **GATE VIOLATION** — PR has no issue
227
+ 3. If linked issue exists, check its labels:
228
+ - Feature PR → issue must have `approved-feature`
229
+ - Enhancement PR → issue must have `approved-enhancement`
230
+ - Fix PR → issue must have `confirmed-bug`
231
+ 4. If label is missing: **GATE VIOLATION** — PR opened before approval
232
+
233
+ Report gate violations prominently — these are the most important findings because
234
+ the project auto-closes PRs without proper approval gates.
235
+ </step>
236
+
237
+ <step name="generate_report">
238
+ Produce a structured triage report:
239
+
240
+ ```
241
+ ===================================================================
242
+ SDD INBOX TRIAGE — {repo} — {date}
243
+ ===================================================================
244
+
245
+ SUMMARY
246
+ -------
247
+ Open issues: {count} Open PRs: {count}
248
+ Features: {n} Feature PRs: {n}
249
+ Enhancements:{n} Enhancement PRs: {n}
250
+ Bugs: {n} Fix PRs: {n}
251
+ Chores: {n} Wrong template: {n}
252
+ Unclassified:{n} No linked issue: {n}
253
+
254
+ GATE VIOLATIONS (action required)
255
+ ---------------------------------
256
+ {For each violation:}
257
+ PR #{number}: {title}
258
+ Problem: {description — e.g., "No approved-feature label on linked issue #45"}
259
+ Action: {what to do — e.g., "Close PR or approve issue #45 first"}
260
+
261
+ ISSUES NEEDING ATTENTION
262
+ ------------------------
263
+ {For each issue sorted by completeness score, lowest first:}
264
+ #{number} [{type}] {title}
265
+ Score: {percentage}% complete
266
+ Missing: {list of missing required fields}
267
+ Labels: {current labels} → Suggested: {recommended labels}
268
+ Age: {days since created}
269
+
270
+ PRS NEEDING ATTENTION
271
+ ---------------------
272
+ {For each PR sorted by completeness score, lowest first:}
273
+ #{number} [{type}] {title}
274
+ Score: {percentage}% complete
275
+ Missing: {list of missing checklist items}
276
+ CI: {passing/failing/pending}
277
+ Review: {approved/changes_requested/none}
278
+ Linked issue: #{issue_number} ({issue_status})
279
+ Age: {days since created}
280
+
281
+ READY TO MERGE
282
+ --------------
283
+ {PRs that are 100% complete, CI passing, approved:}
284
+ #{number} {title} — ready
285
+
286
+ STALE ITEMS (>30 days, no activity)
287
+ ------------------------------------
288
+ {Issues and PRs with no updates in 30+ days}
289
+
290
+ ===================================================================
291
+ ```
292
+
293
+ Write this report to `.planning/INBOX-TRIAGE.md` if a `.planning/` directory exists,
294
+ otherwise print to console only.
295
+ </step>
296
+
297
+ <step name="auto_actions">
298
+ Only execute if `--label` or `--close-incomplete` flags were set.
299
+
300
+ **If --label:**
301
+ For each issue/PR where labels are missing or incorrect:
302
+ ```bash
303
+ gh issue edit {number} --add-label "{label}"
304
+ ```
305
+ Or:
306
+ ```bash
307
+ gh pr edit {number} --add-label "{label}"
308
+ ```
309
+
310
+ Label recommendations:
311
+ - Unclassified issues → add `needs-triage`
312
+ - Feature issues without review → add `needs-review`
313
+ - Enhancement issues without review → add `needs-review`
314
+ - Bug reports without triage → add `needs-triage`
315
+ - PRs with gate violations → add `gate-violation`
316
+
317
+ **If --close-incomplete:**
318
+ For issues scoring below 50% completeness:
319
+ ```bash
320
+ gh issue close {number} --comment "Closed by SDD inbox triage: this issue is missing required fields per the issue template. Missing: {list}. Please reopen with a complete submission. See CONTRIBUTING.md for requirements."
321
+ ```
322
+
323
+ For PRs with gate violations:
324
+ ```bash
325
+ gh pr close {number} --comment "Closed by SDD inbox triage: this PR does not meet the issue-first requirement. {specific violation}. See CONTRIBUTING.md for the correct process."
326
+ ```
327
+
328
+ Always confirm with the user before closing anything:
329
+
330
+ **Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
331
+
332
+ ```
333
+ AskUserQuestion:
334
+ question: "Found {N} items to close. Review the list above — proceed with closing?"
335
+ options:
336
+ - label: "Close all"
337
+ description: "Close all {N} non-compliant items with explanation comments"
338
+ - label: "Let me pick"
339
+ description: "I'll choose which ones to close"
340
+ - label: "Skip"
341
+ description: "Don't close anything — report only"
342
+ ```
343
+ </step>
344
+
345
+ <step name="report">
346
+ ```
347
+ ───────────────────────────────────────────────────────────────
348
+
349
+ ## Inbox Triage Complete
350
+
351
+ Reviewed: {issue_count} issues, {pr_count} PRs
352
+ Gate violations: {violation_count}
353
+ Ready to merge: {ready_count}
354
+ Needing attention: {attention_count}
355
+ Stale (30+ days): {stale_count}
356
+ {If report saved: "Report saved to .planning/INBOX-TRIAGE.md"}
357
+
358
+ Next steps:
359
+ - Review gate violations first — these block the contribution pipeline
360
+ - Address incomplete submissions (comment or close)
361
+ - Merge ready PRs
362
+ - Triage unclassified issues
363
+
364
+ ───────────────────────────────────────────────────────────────
365
+ ```
366
+ </step>
367
+
368
+ </process>
369
+
370
+ <offer_next>
371
+ After triage:
372
+
373
+ - /sdd-review — Run cross-AI peer review on a specific phase plan
374
+ - /sdd-ship — Create a PR from completed work
375
+ - /sdd-progress — See overall project state
376
+ - /sdd-inbox --label — Re-run with auto-labeling enabled
377
+ </offer_next>
378
+
379
+ <success_criteria>
380
+ - [ ] All open issues fetched and classified by type
381
+ - [ ] Each issue reviewed against its template requirements
382
+ - [ ] All open PRs fetched and classified by type
383
+ - [ ] Each PR reviewed against its template checklist
384
+ - [ ] Issue-first gate violations identified
385
+ - [ ] Structured report generated with scores and action items
386
+ - [ ] Auto-actions executed only when flagged and user-confirmed
387
+ </success_criteria>