@codewizard-dt/bootstrap 4.0.0 → 5.3.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 (53) hide show
  1. package/README.md +18 -60
  2. package/lib/prompts/README.md +0 -1
  3. package/lib/scripts/README.md +1 -2
  4. package/lib/scripts/migrate-project.sh +1 -1
  5. package/lib/scripts/setup-project.sh +0 -1
  6. package/lib/scripts/sync-wiki-scaffold.sh +3 -15
  7. package/lib/scripts/templates/CLAUDE-wiki.md +4 -4
  8. package/lib/scripts/templates/bootstrap-prefs-schema.json +1 -1
  9. package/lib/scripts/templates/wiki/conventions.md +4 -2
  10. package/lib/scripts/templates/wiki/dashboard.html +2 -2
  11. package/lib/scripts/templates/wiki/index.md +4 -4
  12. package/lib/scripts/templates/wiki/work/requirements/index.md +1 -1
  13. package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +2 -2
  14. package/lib/scripts/templates/wiki/work/roadmaps/index.md +1 -1
  15. package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +4 -4
  16. package/lib/scripts/templates/wiki/work/tasks/index.md +1 -1
  17. package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +6 -6
  18. package/lib/scripts/templates/wiki/work/uat/index.md +1 -1
  19. package/lib/scripts/templates/wiki/work/uat/lifecycle.md +4 -4
  20. package/lib/scripts/wiki-dashboard-server.js +1 -1
  21. package/lib/skills/README.md +2 -1
  22. package/lib/skills/architecture-audit/SKILL.md +228 -0
  23. package/lib/skills/bug-close/SKILL.md +5 -2
  24. package/lib/skills/bug-file/SKILL.md +24 -6
  25. package/lib/skills/decision-create/SKILL.md +7 -2
  26. package/lib/skills/demo/SKILL.md +10 -10
  27. package/lib/skills/elevator-pitch/SKILL.md +1 -1
  28. package/lib/skills/extract-feature/SKILL.md +29 -87
  29. package/lib/skills/marp-slideshow/SKILL.md +2 -2
  30. package/lib/skills/port-feature/SKILL.md +28 -83
  31. package/lib/skills/power-mode/SKILL.md +10 -10
  32. package/lib/skills/primer/SKILL.md +1 -1
  33. package/lib/skills/req-compile/SKILL.md +2 -2
  34. package/lib/skills/req-create/SKILL.md +13 -9
  35. package/lib/skills/req-extract-decisions/SKILL.md +10 -10
  36. package/lib/skills/req-finalize/SKILL.md +3 -3
  37. package/lib/skills/req-retire/SKILL.md +10 -10
  38. package/lib/skills/req-update/SKILL.md +4 -4
  39. package/lib/skills/roadmap-assess/SKILL.md +7 -7
  40. package/lib/skills/roadmap-create/SKILL.md +26 -22
  41. package/lib/skills/roadmap-next/SKILL.md +10 -10
  42. package/lib/skills/security-audit/SKILL.md +3 -0
  43. package/lib/skills/tackle/SKILL.md +3 -3
  44. package/lib/skills/task-add/SKILL.md +41 -22
  45. package/lib/skills/task-audit/SKILL.md +2 -2
  46. package/lib/skills/task-trash/SKILL.md +4 -4
  47. package/lib/skills/uat-auto/SKILL.md +2 -1
  48. package/lib/skills/uat-generate/SKILL.md +22 -22
  49. package/lib/skills/uat-skip/SKILL.md +21 -21
  50. package/lib/skills/uat-walk/SKILL.md +1 -1
  51. package/lib/skills/uat-walk/UAT-CORE.md +6 -6
  52. package/lib/skills/wiki-lint/SKILL.md +28 -1
  53. package/package.json +1 -1
@@ -21,7 +21,7 @@ The first whitespace-separated token is the **input path** (required). An option
21
21
 
22
22
  **Output path resolution rules** (apply in order):
23
23
 
24
- 1. **No output path provided** → write to `.docs/MARP/<input-stem>.slides.md` (create `.docs/MARP/` if it doesn't exist). Do **not** place the deck next to the input file.
24
+ 1. **No output path provided** → write to `wiki/marp/<input-stem>.slides.md` (create `wiki/marp/` if it doesn't exist). Do **not** place the deck next to the input file.
25
25
  2. **Output path provided** → always normalize the filename so it ends in `.slides.md`, even if the user didn't say so:
26
26
  - `deck` → `deck.slides.md`
27
27
  - `deck.md` → `deck.slides.md` (strip the trailing `.md`, then append `.slides.md`)
@@ -190,7 +190,7 @@ Before calling `Write`, mentally verify:
190
190
  - [ ] Speaker notes (HTML comments) are present where the source had context that didn't fit on-slide
191
191
  - [ ] Footer / header are short (one line, no Markdown that breaks YAML — wrap in quotes if it contains `:` or `#`)
192
192
  - [ ] Output filename ends in `.slides.md` (always — append/normalize even if the user-supplied path didn't include it)
193
- - [ ] If the user did **not** supply an output path, the deck is written to `.docs/MARP/<input-stem>.slides.md` (not next to the source)
193
+ - [ ] If the user did **not** supply an output path, the deck is written to `wiki/marp/<input-stem>.slides.md` (not next to the source)
194
194
 
195
195
  ## Phase 5 — Write & Confirm
196
196
 
@@ -33,7 +33,7 @@ Assess a specific feature or area of functionality in an external (source) proje
33
33
  - Confirm the source directory exists: use `mcp__serena__find_file` or Bash `ls <source-path>` to verify it is accessible
34
34
 
35
35
  3. **Clarifying questions** (ask before proceeding if ambiguous):
36
- - Should the port plan produce a task file in `wiki/work/tasks/`, a report in `.docs/port/`, or both?
36
+ - Is this port substantial enough to warrant a roadmap (multiple ordered steps spanning several files/integration points) via `/roadmap-create`, or small enough for a single task via `/task-add`? Default to a roadmap once Phase 3's porting steps exceed ~3 steps or touch more than one integration point.
37
37
  - Is there a preferred output level of detail (high-level steps vs. file-by-file implementation plan)?
38
38
  - Are there any known constraints (e.g., "must stay in TypeScript", "no new dependencies")?
39
39
 
@@ -201,107 +201,52 @@ List risks that could complicate the port:
201
201
 
202
202
  ---
203
203
 
204
- ## Phase 4: Produce the Port Plan
204
+ ## Phase 4: Produce the Port Roadmap
205
205
 
206
- ### 4a. Write the Port Plan File
206
+ ### 4a. Present the Full Analysis
207
207
 
208
- Write a structured port plan to `.docs/port/<kebab-feature-name>.md`:
208
+ Present the complete assessment in the conversation as structured tables/sections — this is working analysis for the roadmap and any task files, not a standalone persisted document:
209
209
 
210
- ```markdown
211
- ---
212
- source-project: <source-path>
213
- feature: <feature name>
214
- assessed: <YYYY-MM-DD>
215
- effort: <Low / Medium / High / Very High>
216
- status: draft
217
- ---
218
-
219
- # Port Plan: <Feature Name>
220
-
221
- > **Source**: `<source-path>`
222
- > **Feature**: <functionality description>
223
- > **Overall effort**: <Low / Medium / High / Very High>
224
- > **Summary**: <One sentence on what this port involves.>
225
-
226
- ## Source Feature Summary
227
-
228
- <Condensed version of the Source Feature Inventory from Phase 1c>
229
-
230
- ## Target Project Context
231
-
232
- <Condensed version of the Target Project Profile from Phase 2d>
233
-
234
- ## Technology Mapping
235
-
236
- <Table from 3a>
237
-
238
- ## Complexity Breakdown
239
-
240
- <Table from 3b>
241
-
242
- ## Dependency Changes
243
-
244
- <Table from 3c>
245
-
246
- ## Integration Points
247
-
248
- <Bullet list from 3d>
210
+ - **Source Feature Summary** — condensed Phase 1c inventory
211
+ - **Target Project Context** — condensed Phase 2d profile
212
+ - **Technology Mapping** — table from 3a
213
+ - **Complexity Breakdown** — table from 3b
214
+ - **Dependency Changes** — table from 3c
215
+ - **Integration Points** — bullets from 3d
216
+ - **Risks** — table from 3e
217
+ - **Porting Steps** — ordered, dependency-respecting steps; for each: title, effort (Direct/Adapt/Rewrite), files affected (create/modify/delete), what to do, and definition of done
249
218
 
250
- ## Risks
219
+ ### 4b. Decide: Roadmap or Single Task
251
220
 
252
- <Table from 3e>
221
+ - **≤3 porting steps, single integration point** → skip the roadmap. Go straight to `/task-add "Port <feature name> from <source-path>"`, carrying the full step detail (files affected, what to do, definition of done) into the task's steps, then skip to Phase 5.
222
+ - **>3 steps, multiple integration points, or the user asked for a roadmap in Phase 0** → continue to 4c.
253
223
 
254
- ## Porting Steps
224
+ ### 4c. Delegate to `/roadmap-create`
255
225
 
256
- Ordered, dependency-respecting steps. Each step is concrete and actionable.
226
+ > **Delegate to `/roadmap-create Port <feature name> from <source-path>`**
257
227
 
258
- ### Step 1: <title>
228
+ Feed `/roadmap-create`'s own Socratic Q&A from the analysis already gathered, rather than making the user re-derive it from scratch:
259
229
 
260
- **Effort**: <Direct / Adapt / Rewrite>
261
- **Files affected**:
262
- - `<target file path>` — <create / modify / delete>
263
-
264
- **What to do**:
265
- <Specific instructions: what to copy, what to change, how to adapt the API, what conventions to follow>
266
-
267
- **Definition of done**: <How to know this step is complete>
268
-
269
- ---
270
-
271
- ### Step 2: <title>
272
-
273
- … (repeat for each step)
274
-
275
- ---
276
-
277
- ## Suggested Next Actions
278
-
279
- - To create a task from this plan: `/task-add "Port <feature name> from <source-path>" --roadmap <if applicable>`
280
- - To explore the source further: use Read on `<most important source file>`
281
- - If a dependency decision is needed: <frame the specific decision>
282
- ```
283
-
284
- ### 4b. Optionally Create a Task File
285
-
286
- If the user requested a task file (or if the plan is actionable enough to execute), suggest:
287
-
288
- ```
289
- /task-add "Port <feature name> from <source-project-name>"
290
- ```
230
+ | Elicitation | Answer to supply |
231
+ |---|---|
232
+ | Goal | The one/two-sentence port summary + overall effort verdict from 3b |
233
+ | Phases | Group the ordered Porting Steps from 4a into 2-5 execution-flavored phases (e.g. "Dependencies", "Core port", "Integration", "Tests") — never one phase per step |
234
+ | Owner | Ask the user if not already known |
235
+ | Linked PRD/ADRs | Any `wiki/work/requirements/` or `wiki/work/decisions/` entries found during Phase 2a/2c |
291
236
 
292
- And note what context from the port plan should be included in the task.
237
+ Each Porting Step becomes one roadmap item — an inline placeholder (`- [ ] <step title>`) under its phase, per `/roadmap-create`'s item-format rules. **Do not embed the step's file list / what-to-do / definition-of-done in the roadmap item** — that detail belongs in the task file created for it via `/task-add --roadmap ROADMAP-NNNN <step title>` (or automatically when `/roadmap-next` runs).
293
238
 
294
239
  ---
295
240
 
296
241
  ## Phase 5: Report to User
297
242
 
298
- After writing the plan file:
243
+ After the roadmap (or single task) is created:
299
244
 
300
- 1. State the path written: `.docs/port/<kebab-feature-name>.md`
245
+ 1. State what was created: the roadmap path (`wiki/work/roadmaps/ROADMAP-NNNN-slug.md`) or the single task command run
301
246
  2. Give a one-line overall effort verdict (e.g., "Medium effort — 4 files to adapt, 1 rewrite, no new dependencies required")
302
247
  3. List the top 3 porting steps in brief
303
248
  4. Call out the single biggest risk or blocker
304
- 5. Suggest the most useful next action (task creation, further exploration, or a specific decision to make)
249
+ 5. Suggest the most useful next action (`/roadmap-next ROADMAP-NNNN`, further exploration, or a specific dependency decision to make)
305
250
 
306
251
  ---
307
252
 
@@ -19,8 +19,8 @@ Use this skill to drive tasks or roadmaps to completion using a parallel agent t
19
19
  **Trigger:** `/power-mode <path>` with no additional instructions.
20
20
 
21
21
  Inspect the path argument:
22
- - Path contains `roadmap` or matches `ROADMAP-NNN` → **Roadmap-to-Completion Orchestrator** (see below)
23
- - Path contains `task` or matches `TASK-NNN` → **Single-Task Executor** (see below)
22
+ - Path contains `roadmap` or matches `ROADMAP-NNNN` → **Roadmap-to-Completion Orchestrator** (see below)
23
+ - Path contains `task` or matches `TASK-NNNN` → **Single-Task Executor** (see below)
24
24
 
25
25
  ---
26
26
 
@@ -57,7 +57,7 @@ All agent call examples below omit this footer for brevity — it is always requ
57
57
 
58
58
  ## Single-Task Executor
59
59
 
60
- **Trigger:** `/power-mode <path/to/TASK-NNN.md>` with no additional instructions.
60
+ **Trigger:** `/power-mode <path/to/TASK-NNNN.md>` with no additional instructions.
61
61
 
62
62
  **Goal:** Drive one task through the full tackle → UAT-generate → UAT-auto pipeline exactly once, then stop.
63
63
 
@@ -67,7 +67,7 @@ All agent call examples below omit this footer for brevity — it is always requ
67
67
 
68
68
  ```
69
69
  Agent({
70
- description: "Tackle <TASK-NNN>",
70
+ description: "Tackle <TASK-NNNN>",
71
71
  prompt: "Run /tackle <task-path>. [append team member footer]",
72
72
  mode: "bypassPermissions"
73
73
  })
@@ -79,7 +79,7 @@ Wait for the agent to complete.
79
79
 
80
80
  ```
81
81
  Agent({
82
- description: "UAT generate <TASK-NNN>",
82
+ description: "UAT generate <TASK-NNNN>",
83
83
  prompt: "Run /uat-generate <task-path>. [append team member footer]",
84
84
  mode: "bypassPermissions"
85
85
  })
@@ -91,7 +91,7 @@ Wait for the agent to complete.
91
91
 
92
92
  ```
93
93
  Agent({
94
- description: "UAT auto <TASK-NNN>",
94
+ description: "UAT auto <TASK-NNNN>",
95
95
  prompt: "Run /uat-auto <uat-path> (infer the UAT file path from the task path — same NNN slug, under wiki/work/uat/).
96
96
 
97
97
  Note: on all-pass, /uat-auto's own UAT-CORE Closure procedure already flips the task to done, archives both files, removes index rows, and auto-checks the matching roadmap checkbox (if any) — you do not need to instruct any of that here; it happens natively. Just wait for it to complete and report its summary.
@@ -109,7 +109,7 @@ Done. No further iteration.
109
109
 
110
110
  ## Roadmap-to-Completion Orchestrator
111
111
 
112
- **Trigger:** `/power-mode <path/to/ROADMAP-NNN.md>` with no additional instructions.
112
+ **Trigger:** `/power-mode <path/to/ROADMAP-NNNN.md>` with no additional instructions.
113
113
 
114
114
  **Goal:** Drive the roadmap to completion — every item through the full tackle → UAT-generate → UAT-auto pipeline — looping through waves of parallelizable work until no implementation work remains.
115
115
 
@@ -150,7 +150,7 @@ Run tackle → UAT-generate → UAT-auto for all tasks in the current wave. Appl
150
150
 
151
151
  Phase 1 — Tackle (parallel, minimum 5 agents when 5+ collision-safe tasks available):
152
152
  ```
153
- Agent({ description: "Tackle TASK-NNN", prompt: "Run /tackle <path>. [append team member footer]", mode: "bypassPermissions" })
153
+ Agent({ description: "Tackle TASK-NNNN", prompt: "Run /tackle <path>. [append team member footer]", mode: "bypassPermissions" })
154
154
  Agent({ description: "Tackle TASK-MMM", prompt: "Run /tackle <path>. [append team member footer]", mode: "bypassPermissions" })
155
155
  // ... one per task, all in the same message
156
156
  ```
@@ -159,7 +159,7 @@ Wait for all to complete.
159
159
 
160
160
  Phase 2 — Generate UAT tests (parallel, read-only):
161
161
  ```
162
- Agent({ description: "UAT generate TASK-NNN", prompt: "Run /uat-generate <task-path>. [append team member footer]", mode: "bypassPermissions" })
162
+ Agent({ description: "UAT generate TASK-NNNN", prompt: "Run /uat-generate <task-path>. [append team member footer]", mode: "bypassPermissions" })
163
163
  // ... one per task, all in the same message
164
164
  ```
165
165
 
@@ -168,7 +168,7 @@ Wait for all to complete.
168
168
  Phase 3 — Run UATs (parallel when UAT files don't collide):
169
169
  ```
170
170
  Agent({
171
- description: "UAT auto TASK-NNN",
171
+ description: "UAT auto TASK-NNNN",
172
172
  prompt: "Run /uat-auto <uat-path>.
173
173
 
174
174
  Note: on all-pass, /uat-auto's own UAT-CORE Closure procedure already flips the task to done, archives both files, removes index rows, and auto-checks the matching roadmap checkbox — no need to instruct any of that here.
@@ -75,7 +75,7 @@ See `wiki/guides/mcp-tools.md` for the complete Serena memory reference.
75
75
 
76
76
  ## Step 4: Check the Task Index
77
77
 
78
- `/tackle` no-args mode surveys active tasks by reading `wiki/work/tasks/index.md` — a flat bullet list of active items (`- [TASK-NNN — Title](TASK-NNN-slug.md) — one-line summary · status`), one line per `todo`/`in-progress` task. There is no table to "bootstrap"; do a lightweight consistency check so that survey stays trustworthy.
78
+ `/tackle` no-args mode surveys active tasks by reading `wiki/work/tasks/index.md` — a flat bullet list of active items (`- [TASK-NNNN — Title](TASK-NNNN-slug.md) — one-line summary · status`), one line per `todo`/`in-progress` task. There is no table to "bootstrap"; do a lightweight consistency check so that survey stays trustworthy.
79
79
 
80
80
  1. Use `mcp__serena__list_dir` on `wiki/work/tasks/` to list task files (top-level only, not `archive/`). If the directory is empty or has no task files, skip this step.
81
81
  2. Read `wiki/work/tasks/index.md` (use `Read` — markdown).
@@ -22,7 +22,7 @@ intent discovered mid-build — but zero *preventable* ones. This skill encodes
22
22
  It inherits the global manifesto (least code, simplest architecture, maximal correctness,
23
23
  no docs unless asked). This is the *how-to-build*; the manifesto is *what good looks like*.
24
24
 
25
- **Input:** a project dir with a `wiki/work/requirements/REQ-NNN-slug.md` (REQ) file + a project `CLAUDE.md`
25
+ **Input:** a project dir with a `wiki/work/requirements/REQ-NNNN-slug.md` (REQ) file + a project `CLAUDE.md`
26
26
  (stack, hosting, boundaries).
27
27
  **Output:** code — a typed boundary contract, *failing* oracle stubs, and the answered batched
28
28
  forks. Not documentation.
@@ -49,7 +49,7 @@ Parse `$ARGUMENTS` to find the requirement file:
49
49
  | `<path>` (e.g. `wiki/work/requirements/REQ-003-onboarding.md`) | Use as-is |
50
50
  | `<NNN-slug>` (e.g. `003-onboarding`) | `mcp__serena__find_file` with mask `003-onboarding.md` under `wiki/work/requirements/` |
51
51
  | `<NNN>` (e.g. `3` or `003`) | Pad to 3 digits; `mcp__serena__find_file` with mask `NNN-*.md` under `wiki/work/requirements/` |
52
- | Empty / missing | Look for any `wiki/work/requirements/REQ-NNN-slug.md` with `status: approved`; if ambiguous, ask via `AskUserQuestion` |
52
+ | Empty / missing | Look for any `wiki/work/requirements/REQ-NNNN-slug.md` with `status: approved`; if ambiguous, ask via `AskUserQuestion` |
53
53
 
54
54
  **Verify the requirement has `status: approved`** before proceeding. If `draft`, tell the user to run `/req-finalize <path>` first. If `retired` or `superseded`, refuse — no system should be built against a cancelled requirement.
55
55
 
@@ -33,7 +33,7 @@ Write when there's a real problem worth aligning on, more than one decision area
33
33
  3. Read `CLAUDE.md`, `PROJECT_STATUS.md` (if present), `wiki/work/requirements/lifecycle.md` (authoritative template/lifecycle/anti-patterns), and a sample of recent requirements for local conventions.
34
34
 
35
35
  ## Step 2: Locate directory, assign number
36
- Requirements live at `wiki/work/requirements/REQ-NNN-slug.md` (3-digit zero-padded). `list_dir` both `wiki/work/requirements/` and `wiki/work/requirements/archive/` (skip either that doesn't exist) — highest prefix across both + 1 (first is `REQ-001`). Never re-use a number; retired requirements keep theirs forever. Derive the slug — names the **initiative**, lowercase dash-separated ≤60 chars (e.g. "Self-serve billing portal" → `REQ-004-self-serve-billing-portal.md`). Confirm number + slug via `AskUserQuestion` if non-obvious.
36
+ Requirements live at `wiki/work/requirements/REQ-NNNN-slug.md` (4-digit zero-padded). `list_dir` both `wiki/work/requirements/` and `wiki/work/requirements/archive/` (skip either that doesn't exist) — highest prefix across both + 1 (first is `REQ-0001`). Never re-use a number; retired requirements keep theirs forever. Derive the slug — names the **initiative**, lowercase dash-separated ≤60 chars (e.g. "Self-serve billing portal" → `REQ-0004-self-serve-billing-portal.md`). Confirm number + slug via `AskUserQuestion` if non-obvious.
37
37
 
38
38
  ## Step 3: Research (optional, scoped)
39
39
  For an unfamiliar product space, run a **lightweight** `/research` for **product context only**:
@@ -68,13 +68,17 @@ Walk the elicitations **in order**. Batch related ones into a single round when
68
68
  ## Step 5: Preview and confirm before writing
69
69
  Present a **tabular preview** of every elicited section; user confirms via `AskUserQuestion` (*Approve and write* / *Edit specific section* / *Cancel*). **Do not write until explicit approval.** Preview must include at least: Header (Title, status `draft`, Owner, Stakeholders, Tags), Problem Statement (full), Personas (table), User Stories (`US-N` titles + AC counts), Success Metrics (full table), Goals→Metrics (full table showing the link), Non-Goals (full table), Constraints/Assumptions/Open Questions (tables or "(empty — none elicited)"). Edits → loop back to the relevant Step 4 elicitation and re-present.
70
70
 
71
+ ### Step 5a: Re-verify next requirement number — IMMEDIATELY before writing
72
+
73
+ Re-run the scan from Step 2. If the number planned earlier is now taken, silently bump to the new next-available number. **Never call `Write` before completing this re-scan.**
74
+
71
75
  ## Step 6: Write the file
72
- After confirmation, `Write` `wiki/work/requirements/REQ-NNN-slug.md`.
76
+ After confirmation, `Write` `wiki/work/requirements/REQ-NNNN-slug.md`.
73
77
 
74
78
  ```yaml
75
79
  ---
76
- id: REQ-NNN
77
- aliases: [REQ-NNN]
80
+ id: REQ-NNNN
81
+ aliases: [REQ-NNNN]
78
82
  type: requirement
79
83
  status: draft
80
84
  created: YYYY-MM-DD
@@ -86,21 +90,21 @@ tags: [<tag1>, <tag2>]
86
90
  ---
87
91
  ```
88
92
 
89
- Sections in order: `# REQ-NNN: <Title>` · `## Problem Statement` · `## Goals` (table, every row links a Success Metric ID) · `## Non-Goals` (≥1 row) · `## Personas` (table) · `## User Stories` (each `### US-N. <title>` with the story sentence + an AC table) · `## Success Metrics` (table) · `## Constraints` / `## Assumptions` / `## Open Questions` (table or "(none — placeholder retained)") · `## Linked Decisions` (empty, retain explanatory blockquote) · `## Linked Tasks` (empty, blockquote) · `## Notes` (empty) · `## Amendments` (empty, `<!-- Amendments appear here as ## Amendment 1, ## Amendment 2, etc. -->`).
93
+ Sections in order: `# REQ-NNNN: <Title>` · `## Problem Statement` · `## Goals` (table, every row links a Success Metric ID) · `## Non-Goals` (≥1 row) · `## Personas` (table) · `## User Stories` (each `### US-N. <title>` with the story sentence + an AC table) · `## Success Metrics` (table) · `## Constraints` / `## Assumptions` / `## Open Questions` (table or "(none — placeholder retained)") · `## Linked Decisions` (empty, retain explanatory blockquote) · `## Linked Tasks` (empty, blockquote) · `## Notes` (empty) · `## Amendments` (empty, `<!-- Amendments appear here as ## Amendment 1, ## Amendment 2, etc. -->`).
90
94
 
91
95
  **Refuse to write** if any required-non-empty field is missing or fails its bar — loop back to Step 4.
92
96
 
93
97
  ## Step 7: Update indexes + log (`Edit` only, never `sed`/`awk`/`echo >>`)
94
- Update `wiki/work/requirements/index.md` — if the placeholder row `_No requirements yet …_` exists, **replace** it; else **append** in ascending REQ order. Row/columns: `ID` = `[REQ-NNN](../work/requirements/REQ-NNN-slug.md)` · `Title` · `Status` = `draft` · `Created` = `YYYY-MM-DD` · `Owner` · `Linked Decisions` = `—` · `Linked Tasks` = `—`. Append to `wiki/log.md`: `## [YYYY-MM-DD] req-create | REQ-NNN <title>`.
98
+ Append (or replace the placeholder row) in `wiki/work/requirements/index.md` using the format documented at the top of that file: `- [REQ-NNNN — Title](REQ-NNNN-slug.md) — one-line summary · status`, in ascending REQ order. Append to `wiki/log.md`: `## [YYYY-MM-DD] req-create | REQ-NNNN <title>`.
95
99
 
96
100
  ## Step 8: Cross-link related artifacts
97
- If prompted by an existing task/research note/reference, link both ways (`Read` then `Edit`, never `sed`): source artifact gets `**Requirement**: REQ-NNN ([file](<relative-link>))` in a sensible section; the new requirement references the source in `## Notes` (e.g. "Originated from `wiki/work/tasks/TASK-012-runbook-triage.md`"). No related artifact → skip.
101
+ If prompted by an existing task/research note/reference, link both ways (`Read` then `Edit`, never `sed`): source artifact gets `**Requirement**: REQ-NNNN ([file](<relative-link>))` in a sensible section; the new requirement references the source in `## Notes` (e.g. "Originated from `wiki/work/tasks/TASK-012-runbook-triage.md`"). No related artifact → skip.
98
102
 
99
103
  ## Step 9: Update memory if appropriate
100
- `mcp__serena__write_memory` only for a **non-obvious** product insight future sessions benefit from (a genuinely new persona; a regulatory constraint; a known product gotcha) — skip self-evident ones or conjecture. Topic-hierarchical name (`product/personas/sre-oncall`, `product/constraints/soc2-admin-logging`), referencing `REQ-NNN` in the body.
104
+ `mcp__serena__write_memory` only for a **non-obvious** product insight future sessions benefit from (a genuinely new persona; a regulatory constraint; a known product gotcha) — skip self-evident ones or conjecture. Topic-hierarchical name (`product/personas/sre-oncall`, `product/constraints/soc2-admin-logging`), referencing `REQ-NNNN` in the body.
101
105
 
102
106
  ## Step 10: Report
103
- Tabular summary: File path, Status (`draft`), Personas/User Stories/Success Metrics/Non-Goals counts, Constraints/Assumptions/Open Questions (populated/empty per section), index updated (1 row), log appended, cross-links (list or *none*), memory (name or *skipped*), suggested next step `/req-finalize wiki/work/requirements/REQ-NNN-slug.md`. Note any placeholder-reduced field under a **Gaps** section for the user to address before `/req-finalize`.
107
+ Tabular summary: File path, Status (`draft`), Personas/User Stories/Success Metrics/Non-Goals counts, Constraints/Assumptions/Open Questions (populated/empty per section), index updated (1 row), log appended, cross-links (list or *none*), memory (name or *skipped*), suggested next step `/req-finalize wiki/work/requirements/REQ-NNNN-slug.md`. Note any placeholder-reduced field under a **Gaps** section for the user to address before `/req-finalize`.
104
108
 
105
109
  ---
106
110
 
@@ -134,7 +134,7 @@ For **each proposed group**, ask: "Create this as a decision now?" with options:
134
134
  | `merge into <Gx>` | Combine this group with another listed group |
135
135
  | `split` | Break this group into multiple smaller groups |
136
136
  | `skip — already covered` | Drop the group; the ASR is handled by an existing decision |
137
- | `skip — non-architectural` | Drop the group; handle directly via `/task-add --req REQ-NNN` |
137
+ | `skip — non-architectural` | Drop the group; handle directly via `/task-add --req REQ-NNNN` |
138
138
 
139
139
  ### Step 7: Update the requirement's `## Linked Decisions` section
140
140
 
@@ -161,7 +161,7 @@ Also update the requirement's frontmatter `updated` to today's date. Both edits
161
161
  Append to `wiki/log.md`:
162
162
 
163
163
  ```
164
- ## [YYYY-MM-DD] req-extract-decisions | REQ-NNN <title> — N ASRs identified
164
+ ## [YYYY-MM-DD] req-extract-decisions | REQ-NNNN <title> — N ASRs identified
165
165
  ```
166
166
 
167
167
  ### Step 8: Update existing decisions that reuse requirement ASRs
@@ -172,8 +172,8 @@ For each affected decision file:
172
172
 
173
173
  1. `Read` the file
174
174
  2. Locate the target decision's `### Links` section
175
- 3. Check whether `Source REQ: REQ-NNN` already exists — **skip if present** (idempotent)
176
- 4. `Edit` to append: `- Source REQ: [REQ-NNN](../requirements/NNN-slug.md)`
175
+ 3. Check whether `Source REQ: REQ-NNNN` already exists — **skip if present** (idempotent)
176
+ 4. `Edit` to append: `- Source REQ: [REQ-NNNN](../requirements/NNN-slug.md)`
177
177
 
178
178
  Touch only the target decision's `### Links`. Do not modify any decision's status, metadata, or content beyond the `### Links` append.
179
179
 
@@ -183,7 +183,7 @@ Print a tabular completion report:
183
183
 
184
184
  | Field | Value |
185
185
  |-------|-------|
186
- | Requirement | `REQ-NNN <title>` |
186
+ | Requirement | `REQ-NNNN <title>` |
187
187
  | ASRs identified | count |
188
188
  | ASRs covered by existing decisions | count (linked back) |
189
189
  | New decision groups proposed | count |
@@ -198,10 +198,10 @@ Then list the **next-action commands**, one per confirmed new group:
198
198
 
199
199
  ```
200
200
  To create the proposed decisions, run each:
201
- /decision-create group: search-infrastructure (from REQ-NNN)
202
- /decision-create hris-integration (from REQ-NNN)
201
+ /decision-create group: search-infrastructure (from REQ-NNNN)
202
+ /decision-create hris-integration (from REQ-NNNN)
203
203
 
204
- After each /decision-create completes, return to REQ-NNN's `## Linked Decisions` table
204
+ After each /decision-create completes, return to REQ-NNNN's `## Linked Decisions` table
205
205
  and update the placeholder row with the actual wikilink [[NNNN-slug|DEC-NNNN#DM]].
206
206
  ```
207
207
 
@@ -209,7 +209,7 @@ If any ASRs were skipped as non-architectural, also surface:
209
209
 
210
210
  ```
211
211
  The following ASRs are best handled directly as tasks (no decision needed):
212
- /task-add --req REQ-NNN "<short description for ASR Ax>"
212
+ /task-add --req REQ-NNNN "<short description for ASR Ax>"
213
213
  ```
214
214
 
215
215
  The skill does **not** auto-invoke `/decision-create` or `/task-add`. It surfaces the commands; the user runs them.
@@ -223,7 +223,7 @@ The skill does **not** auto-invoke `/decision-create` or `/task-add`. It surface
223
223
  3. **Never invent ASRs.** Every entry in the ASR table must trace to a specific requirement section, quoted or paraphrased verbatim.
224
224
  4. **Boundary rule is enforced strictly.** Requirements ask for outcomes, decisions admit trade-offs. If a candidate ASR sounds like a solution, reformulate it as the underlying outcome.
225
225
  5. **Requirement edits are surgical.** Use `Read` then `Edit` to update only the `## Linked Decisions` table and the `updated` field. Never rewrite the file.
226
- 6. **Idempotent back-links.** If `Source REQ: REQ-NNN` already exists in a decision's `### Links`, skip the edit. Re-running this skill against the same requirement must not duplicate links.
226
+ 6. **Idempotent back-links.** If `Source REQ: REQ-NNNN` already exists in a decision's `### Links`, skip the edit. Re-running this skill against the same requirement must not duplicate links.
227
227
  7. **Wikilinks for existing decisions.** Use `[[NNNN-slug\|DEC-NNNN#DM]]` format in the `## Linked Decisions` table.
228
228
 
229
229
  ---
@@ -182,7 +182,7 @@ If this requirement's row does not yet exist in the index table, insert a new ro
182
182
 
183
183
  | Column | Format |
184
184
  |--------|--------|
185
- | `ID` | `[REQ-NNN](requirements/NNN-slug.md)` |
185
+ | `ID` | `[REQ-NNNN](requirements/NNN-slug.md)` |
186
186
  | `Title` | The requirement's initiative title |
187
187
  | `Status` | `approved` |
188
188
  | `Created` | The requirement's `created:` date |
@@ -193,7 +193,7 @@ If this requirement's row does not yet exist in the index table, insert a new ro
193
193
  Append to `wiki/log.md`:
194
194
 
195
195
  ```
196
- ## [YYYY-MM-DD] req-approved | REQ-NNN <title>
196
+ ## [YYYY-MM-DD] req-approved | REQ-NNNN <title>
197
197
  ```
198
198
 
199
199
  Use `Read` then `Edit` for the index update — never `echo >>` or `sed`.
@@ -223,7 +223,7 @@ Suggested next steps:
223
223
  | Suggestion | When to use it |
224
224
  |------------|----------------|
225
225
  | `/req-extract-decisions <file>` | The default next step — extract Architecturally Significant Requirements and propose decision candidates |
226
- | `/task-add --req REQ-NNN <description>` | Only when the requirement's scope is small enough to skip decisions entirely |
226
+ | `/task-add --req REQ-NNNN <description>` | Only when the requirement's scope is small enough to skip decisions entirely |
227
227
  | `/req-update <file> <change>` | If a scope change surfaces post-approval — appends an `## Amendment N` block; never rewrites |
228
228
 
229
229
  Do **not** auto-create downstream artifacts — present them as suggestions only.
@@ -3,7 +3,7 @@ name: req-retire
3
3
  description: Retire a requirement — set status to retired in frontmatter, document the reason, move to archive/, append a log entry.
4
4
  category: planning
5
5
  model: claude-haiku-4-5-20251001
6
- argument-hint: <wiki/work/requirements/REQ-NNN-slug.md, NNN-slug, or NNN> [reason]
6
+ argument-hint: <wiki/work/requirements/REQ-NNNN-slug.md, NNN-slug, or NNN> [reason]
7
7
  disable-model-invocation: false
8
8
  user-invocable: true
9
9
  ---
@@ -12,7 +12,7 @@ user-invocable: true
12
12
 
13
13
  # Retire Requirement
14
14
 
15
- Set a requirement's `status` to `retired`, document why, then move the file to `wiki/work/requirements/archive/`. After archiving, cross-references using `[[REQ-NNN]]` remain valid — the ID is stable regardless of file location.
15
+ Set a requirement's `status` to `retired`, document why, then move the file to `wiki/work/requirements/archive/`. After archiving, cross-references using `[[REQ-NNNN]]` remain valid — the ID is stable regardless of file location.
16
16
 
17
17
  This skill is a focused shortcut for the retirement flow. For amendments that don't touch status, use `/req-update`. For supersession (a new requirement replaces this one), use `/req-update` with supersession intent or pass `status: superseded` instructions here.
18
18
 
@@ -50,8 +50,8 @@ If the file cannot be located, **stop** and report.
50
50
  |----------------|--------|
51
51
  | `draft` | Continue — may be retired before approval |
52
52
  | `approved` | Continue — most common case |
53
- | `retired` | **STOP.** Tell the user: "REQ-NNN is already retired. No action needed." |
54
- | `superseded` | **STOP.** Tell the user: "REQ-NNN is already superseded. No action needed." |
53
+ | `retired` | **STOP.** Tell the user: "REQ-NNNN is already retired. No action needed." |
54
+ | `superseded` | **STOP.** Tell the user: "REQ-NNNN is already superseded. No action needed." |
55
55
 
56
56
  3. **Check for downstream artifacts** in `## Linked Decisions` and `## Linked Tasks`:
57
57
  - List any linked decisions and their current status
@@ -74,7 +74,7 @@ Use `AskUserQuestion` to confirm. Show:
74
74
  Ask the user:
75
75
 
76
76
  1. **"Retire this requirement? (yes / no)"**
77
- 2. **"Reason for retiring REQ-NNN?"** (if not provided in `$ARGUMENTS` — required, one line or more)
77
+ 2. **"Reason for retiring REQ-NNNN?"** (if not provided in `$ARGUMENTS` — required, one line or more)
78
78
 
79
79
  If the user says **No**, STOP. Do not proceed.
80
80
 
@@ -113,7 +113,7 @@ git mv wiki/work/requirements/<file>.md wiki/work/requirements/archive/<file>.md
113
113
  Then append to `wiki/work/requirements/archive/index.md`:
114
114
 
115
115
  ```
116
- | [[REQ-NNN]] | <Title> | retired | YYYY-MM-DD |
116
+ | [[REQ-NNNN]] | <Title> | retired | YYYY-MM-DD |
117
117
  ```
118
118
 
119
119
  Use `Read` then `Edit` for the archive index append — never `echo >>`.
@@ -123,7 +123,7 @@ Use `Read` then `Edit` for the archive index append — never `echo >>`.
123
123
  Append one entry to `wiki/log.md`:
124
124
 
125
125
  ```
126
- ## [YYYY-MM-DD] req-retired | REQ-NNN <title> — reason: <one-line summary of reason>
126
+ ## [YYYY-MM-DD] req-retired | REQ-NNNN <title> — reason: <one-line summary of reason>
127
127
  ```
128
128
 
129
129
  Use `Read` then `Edit` — never `echo >>` or `sed`.
@@ -150,8 +150,8 @@ Print a tabular summary:
150
150
 
151
151
  | Field | Value |
152
152
  |-------|-------|
153
- | Requirement | `REQ-NNN <title>` |
154
- | File path | `wiki/work/requirements/REQ-NNN-slug.md` → `wiki/work/requirements/archive/REQ-NNN-slug.md` |
153
+ | Requirement | `REQ-NNNN <title>` |
154
+ | File path | `wiki/work/requirements/REQ-NNNN-slug.md` → `wiki/work/requirements/archive/REQ-NNNN-slug.md` |
155
155
  | Old status | `draft` or `approved` |
156
156
  | New status | `retired` |
157
157
  | Reason | <one-line summary> |
@@ -167,7 +167,7 @@ Print a tabular summary:
167
167
 
168
168
  1. Use tables for the downstream artifacts list and the completion report — never paragraph prose.
169
169
  2. **One `Edit` call per change** — never bulk rewrites.
170
- 3. **After archiving, cross-references using `[[REQ-NNN]]` remain valid** — the ID is stable regardless of file location.
170
+ 3. **After archiving, cross-references using `[[REQ-NNNN]]` remain valid** — the ID is stable regardless of file location.
171
171
  4. **The skill never auto-retires or auto-deprecates downstream artifacts** — it surfaces them with suggested commands.
172
172
  5. **The retirement reason in `## Notes` is permanent** — it is the audit trail for why this requirement was retired.
173
173
 
@@ -61,8 +61,8 @@ If the **change instructions are empty**, use `AskUserQuestion` to elicit them b
61
61
  |--------|--------|
62
62
  | `draft` | Continue to Step 3 (you will take the **direct-edit branch** in Step 4) |
63
63
  | `approved` | Continue to Step 3 (you will take the **amendment branch** in Step 4); also check if the user intends to retire (see retiring branch below) |
64
- | `retired` | **STOP.** Tell the user: "REQ-NNN is retired. Run `/req-create` for any new scope." |
65
- | `superseded` | **STOP.** Tell the user: "REQ-NNN was superseded. Update the successor requirement instead." |
64
+ | `retired` | **STOP.** Tell the user: "REQ-NNNN is retired. Run `/req-create` for any new scope." |
65
+ | `superseded` | **STOP.** Tell the user: "REQ-NNNN was superseded. Update the successor requirement instead." |
66
66
 
67
67
  **Retiring branch** (when the user indicates they want to mark the requirement as retired):
68
68
  1. Ask for the retirement reason via `AskUserQuestion`
@@ -70,7 +70,7 @@ If the **change instructions are empty**, use `AskUserQuestion` to elicit them b
70
70
  3. Append reason to `## Notes` section: *"Retired YYYY-MM-DD: <reason>"*
71
71
  4. Update `updated` in frontmatter to today's date
72
72
  5. Remove the requirement's row from `wiki/work/requirements/index.md` (terminal status — active index only)
73
- 6. Append to `wiki/log.md`: `## [YYYY-MM-DD] req-retired | REQ-NNN <title> — <reason>`
73
+ 6. Append to `wiki/log.md`: `## [YYYY-MM-DD] req-retired | REQ-NNNN <title> — <reason>`
74
74
  7. Skip to Step 10 (report)
75
75
 
76
76
  ---
@@ -204,7 +204,7 @@ Apply each marker with one `Edit` call. Use unique surrounding text in `old_stri
204
204
  Append to `wiki/log.md`:
205
205
 
206
206
  ```
207
- ## [YYYY-MM-DD] req-updated | REQ-NNN <title> — Amendment N
207
+ ## [YYYY-MM-DD] req-updated | REQ-NNNN <title> — Amendment N
208
208
  ```
209
209
 
210
210
  ---
@@ -54,9 +54,9 @@ This step is read-only — never run `/decision-finalize` yourself; surface the
54
54
 
55
55
  ## Step 5: Cross-roadmap dependency analysis
56
56
 
57
- For every remaining roadmap's `task-link` items (skip `inline` items — no task file exists yet to inspect): `Read` the task file, find `## Dependencies` / `## Blocked by` / `depends_on::` / `blocks::` refs, extract `TASK-NNN` IDs.
57
+ For every remaining roadmap's `task-link` items (skip `inline` items — no task file exists yet to inspect): `Read` the task file, find `## Dependencies` / `## Blocked by` / `depends_on::` / `blocks::` refs, extract `TASK-NNNN` IDs.
58
58
 
59
- For each referenced `TASK-NNN`, check whether it belongs to a *different* roadmap (scan the parsed item lists from Step 2 for that ID). If so, record a directed edge `blocking_roadmap → blocked_roadmap` (the roadmap holding the prerequisite task blocks the roadmap holding the dependent task).
59
+ For each referenced `TASK-NNNN`, check whether it belongs to a *different* roadmap (scan the parsed item lists from Step 2 for that ID). If so, record a directed edge `blocking_roadmap → blocked_roadmap` (the roadmap holding the prerequisite task blocks the roadmap holding the dependent task).
60
60
 
61
61
  Also note — but do not treat as a hard edge — soft relatedness: roadmaps sharing a `linked_requirements` or `linked_decisions` entry. If a shared linked decision's text explicitly states a sequence ("do X before Y", "requires X shipped first"), `Read` that decision file and promote it to a hard edge instead.
62
62
 
@@ -70,7 +70,7 @@ Order the remaining roadmaps, highest priority first, using this precedence:
70
70
  2. **Functional priority** — a judgment call from each roadmap's `## Goal`, `tags`, and any linked requirement's priority/severity field (`Read` it if present). Goals that unblock or protect other work (infra, security, load-bearing bug fixes) outrank polish or nice-to-have goals. Record a one-sentence rationale per roadmap in the report — this is a judgment call the user can override, not a fact.
71
71
  3. **Momentum** (tie-break only — never overrides #1 or #2) — a higher `done/total` ratio ranks slightly higher; finishing in-flight work compounds value faster than starting a new thread.
72
72
 
73
- If two or more roadmaps are genuinely indistinguishable on all three signals, keep their existing relative order (`ROADMAP-NNN` ascending) rather than guessing.
73
+ If two or more roadmaps are genuinely indistinguishable on all three signals, keep their existing relative order (`ROADMAP-NNNN` ascending) rather than guessing.
74
74
 
75
75
  An outstanding decision (Step 4) does **not** change a roadmap's rank — it changes what "next" means for it. A blocked roadmap can still be #1 in priority; it's just not actionable via `/roadmap-next` until the decision resolves. Reflect that in the rank table's `Depends on` column and in the Step 6d status block.
76
76
 
@@ -104,8 +104,8 @@ These roadmaps are gated on decisions still `proposed` — resolve via `/decisio
104
104
 
105
105
  | Rank | Roadmap | Progress | Priority rationale | Depends on |
106
106
  |------|---------|----------|---------------------|------------|
107
- | 1 | ROADMAP-NNN — <title> | M/N | <one sentence> | — |
108
- | 2 | ROADMAP-MMM — <title> | M/N | <one sentence> | ROADMAP-NNN (Phase X blocks it) |
107
+ | 1 | ROADMAP-NNNN — <title> | M/N | <one sentence> | — |
108
+ | 2 | ROADMAP-MMM — <title> | M/N | <one sentence> | ROADMAP-NNNN (Phase X blocks it) |
109
109
  ```
110
110
 
111
111
  `Depends on` lists the hard-edge blockers found in Step 5, or `—` if none. A roadmap with an outstanding decision also gets `Blocked by DEC-NNNN#DM` appended here even if it has no roadmap-to-roadmap dependency.
@@ -115,7 +115,7 @@ These roadmaps are gated on decisions still `proposed` — resolve via `/decisio
115
115
  One block per roadmap, in ranked order:
116
116
 
117
117
  ```
118
- ### ROADMAP-NNN — <title>
118
+ ### ROADMAP-NNNN — <title>
119
119
  - Owner: <owner, or "unassigned">
120
120
  - Progress: M/N items checked
121
121
  - Status: <active — on track | active — stalled | active — mostly inline placeholders, not yet materialized | blocked — awaiting decision(s)>
@@ -135,7 +135,7 @@ If the roadmap has an outstanding decision from Step 4, set `Status: blocked —
135
135
  ```
136
136
  ## Warning: Dependency Cycle
137
137
 
138
- ROADMAP-NNN → ROADMAP-MMM → ROADMAP-NNN
138
+ ROADMAP-NNNN → ROADMAP-MMM → ROADMAP-NNNN
139
139
  These roadmaps block each other — resolve the cycle manually before treating either as higher priority.
140
140
  ```
141
141