@codewizard-dt/bootstrap 5.1.0 → 6.0.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 (95) hide show
  1. package/README.md +11 -3
  2. package/bin/cli.js +16 -0
  3. package/lib/hooks/README.md +124 -3
  4. package/lib/hooks/claude-settings-guard.js +8 -2
  5. package/lib/prompts/README.md +1 -1
  6. package/lib/prompts/migrate-wiki.md +7 -7
  7. package/lib/scripts/README.md +111 -10
  8. package/lib/scripts/bootstrap-prefs-tui.js +1222 -0
  9. package/lib/scripts/install-global.sh +137 -6
  10. package/lib/scripts/migrate-project.sh +52 -10
  11. package/lib/scripts/rename-wiki-ids.js +232 -0
  12. package/lib/scripts/templates/CLAUDE-wiki.md +6 -6
  13. package/lib/scripts/templates/bootstrap-prefs-schema.json +11 -2
  14. package/lib/scripts/templates/settings-sandbox-unattended.json +36 -0
  15. package/lib/scripts/templates/settings-sandbox.json +7 -0
  16. package/lib/scripts/templates/wiki/conventions.md +12 -10
  17. package/lib/scripts/templates/wiki/dashboard.html +527 -23
  18. package/lib/scripts/templates/wiki/index.md +2 -2
  19. package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +1 -1
  20. package/lib/scripts/templates/wiki/work/decisions/index.md +12 -4
  21. package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +11 -9
  22. package/lib/scripts/templates/wiki/work/requirements/index.md +12 -4
  23. package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +8 -8
  24. package/lib/scripts/templates/wiki/work/roadmaps/index.md +11 -3
  25. package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +7 -5
  26. package/lib/scripts/templates/wiki/work/tasks/index.md +1 -1
  27. package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +16 -8
  28. package/lib/scripts/templates/wiki/work/uat/lifecycle.md +3 -3
  29. package/lib/scripts/wiki-dashboard-server.js +98 -0
  30. package/lib/skills/README.md +27 -22
  31. package/lib/skills/_shared/ARCHIVE-WORK-ITEM.md +103 -0
  32. package/lib/skills/_shared/ID-RESOLUTION.md +142 -0
  33. package/lib/skills/_shared/SKILL-BOILERPLATE.md +50 -0
  34. package/lib/skills/adr-assess/SKILL.md +112 -0
  35. package/lib/skills/{decision-create → adr-create}/SKILL.md +27 -26
  36. package/lib/skills/adr-deprecate/SKILL.md +190 -0
  37. package/lib/skills/adr-extract/SKILL.md +255 -0
  38. package/lib/skills/{decision-finalize → adr-finalize}/SKILL.md +38 -38
  39. package/lib/skills/{decision-next → adr-next}/SKILL.md +20 -19
  40. package/lib/skills/{decision-walkthrough → adr-walkthrough}/SKILL.md +23 -29
  41. package/lib/skills/architecture-audit/SKILL.md +24 -3
  42. package/lib/skills/autopilot/SKILL.md +110 -0
  43. package/lib/skills/bootstrap-config/SKILL.md +1 -1
  44. package/lib/skills/bug-assess/SKILL.md +3 -3
  45. package/lib/skills/bug-close/SKILL.md +15 -26
  46. package/lib/skills/{bug-file → bug-create}/SKILL.md +25 -15
  47. package/lib/skills/bug-triage/SKILL.md +5 -19
  48. package/lib/skills/demo/SKILL.md +11 -11
  49. package/lib/skills/elevator-pitch/SKILL.md +1 -1
  50. package/lib/skills/extract-feature/SKILL.md +29 -87
  51. package/lib/skills/git-commit/SKILL.md +4 -4
  52. package/lib/skills/marp-slideshow/SKILL.md +2 -2
  53. package/lib/skills/port-feature/SKILL.md +28 -83
  54. package/lib/skills/power-mode/SKILL.md +42 -49
  55. package/lib/skills/prd-assess/SKILL.md +105 -0
  56. package/lib/skills/{req-compile → prd-compile}/SKILL.md +6 -13
  57. package/lib/skills/{req-create → prd-create}/SKILL.md +19 -19
  58. package/lib/skills/prd-deprecate/SKILL.md +173 -0
  59. package/lib/skills/{req-finalize → prd-finalize}/SKILL.md +20 -29
  60. package/lib/skills/primer/SKILL.md +2 -2
  61. package/lib/skills/research/SKILL.md +3 -3
  62. package/lib/skills/roadmap-assess/SKILL.md +20 -20
  63. package/lib/skills/roadmap-create/SKILL.md +23 -29
  64. package/lib/skills/roadmap-next/SKILL.md +16 -28
  65. package/lib/skills/security-audit/SKILL.md +3 -3
  66. package/lib/skills/tackle/SKILL.md +13 -15
  67. package/lib/skills/{task-audit → task-assess}/SKILL.md +34 -44
  68. package/lib/skills/task-close/SKILL.md +73 -0
  69. package/lib/skills/{task-add → task-create}/SKILL.md +44 -24
  70. package/lib/skills/uat-assess/SKILL.md +124 -0
  71. package/lib/skills/uat-auto/SKILL.md +9 -6
  72. package/lib/skills/uat-auto-plus/SKILL.md +2 -2
  73. package/lib/skills/{uat-generate → uat-create}/SKILL.md +10 -12
  74. package/lib/skills/uat-skip/SKILL.md +5 -9
  75. package/lib/skills/uat-walk/SKILL.md +2 -2
  76. package/lib/skills/uat-walk/UAT-CORE.md +29 -16
  77. package/lib/skills/update-docs/SKILL.md +1 -1
  78. package/lib/skills/usage-report/SKILL.md +52 -0
  79. package/lib/skills/usage-report/scripts/pricing.json +22 -0
  80. package/lib/skills/usage-report/scripts/usage-report.js +518 -0
  81. package/lib/skills/whats-next/SKILL.md +177 -0
  82. package/lib/skills/wiki-archive/SKILL.md +12 -23
  83. package/lib/skills/wiki-lint/SKILL.md +42 -5
  84. package/lib/skills/wiki-query/SKILL.md +1 -1
  85. package/lib/skills/wiki-rotate-log/SKILL.md +1 -1
  86. package/lib/skills/wiki-tidy/SKILL.md +6 -9
  87. package/package.json +1 -1
  88. package/lib/scripts/templates/wiki/work/decisions/archive/index.md +0 -10
  89. package/lib/scripts/templates/wiki/work/requirements/archive/index.md +0 -10
  90. package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +0 -10
  91. package/lib/skills/req-extract-decisions/SKILL.md +0 -241
  92. package/lib/skills/req-retire/SKILL.md +0 -185
  93. package/lib/skills/req-update/SKILL.md +0 -265
  94. package/lib/skills/task-trash/SKILL.md +0 -115
  95. package/lib/skills/task-update/SKILL.md +0 -136
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  name: power-mode
3
- description: Orchestrator for parallel agent teams. When invoked with a roadmap file path, drives every item through the full tackle → uat-generate → uat-auto pipeline until complete. When invoked with a task file path, runs that pipeline once and stops.
3
+ description: Orchestrator for parallel agent teams. When invoked with a roadmap file path, drives every item through the full tackle → uat-create → uat-auto pipeline until complete. When invoked with a task file path, runs that pipeline once in the current session and stops.
4
4
  category: executing
5
5
  model: claude-sonnet-5
6
- argument-hint: "[roadmap-file-path | task-file-path]"
6
+ argument-hint: "[roadmap-file-path | task-file-path | TASK-NNNN]"
7
7
  disable-model-invocation: false
8
8
  user-invocable: true
9
9
  ---
@@ -20,7 +20,8 @@ Use this skill to drive tasks or roadmaps to completion using a parallel agent t
20
20
 
21
21
  Inspect the path argument:
22
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)
23
+ - Path contains `task` or matches `TASK-NNNN` → **Single-Task Executor** (a pointer at the tackle → uat-create → uat-auto pipeline; see below)
24
+ - A task **ID** instead of a path (`TASK-0086`, `task 86`) → resolve it to its file with `find_file` on `TASK-<zero-padded NNNN>-*.md` under `wiki/work/tasks/`, then run the **Single-Task Executor** on that path. A bare number with no `TASK`/`ROADMAP` prefix is ambiguous — stop and ask which one is meant.
24
25
 
25
26
  ---
26
27
 
@@ -55,55 +56,45 @@ All agent call examples below omit this footer for brevity — it is always requ
55
56
 
56
57
  ---
57
58
 
58
- ## Single-Task Executor
59
-
60
- **Trigger:** `/power-mode <path/to/TASK-NNNN.md>` with no additional instructions.
61
-
62
- **Goal:** Drive one task through the full tackle → UAT-generate → UAT-auto pipeline exactly once, then stop.
59
+ ## Agent Lifecycle — Reap Finished and Idle Agents (CRITICAL)
63
60
 
64
- **AUTONOMOUS EXECUTION MANDATE:** Execute all three phases without pausing, asking questions, or awaiting approval. The only valid stopping point is after `/uat-auto` completes and the file-move housekeeping is done.
61
+ Named agents become teammates that **persist after their work is done** — a finished or idle agent keeps its panel row and process until it is explicitly shut down. Never leave them lingering. You are responsible for fully terminating every agent you spawn.
65
62
 
66
- **Phase 1 — Tackle**
67
-
68
- ```
69
- Agent({
70
- description: "Tackle <TASK-NNNN>",
71
- prompt: "Run /tackle <task-path>. [append team member footer]",
72
- mode: "bypassPermissions"
73
- })
74
- ```
63
+ **Reap sweep — run at each of these points:**
64
+ - Immediately after every "Wait for all to complete" (end of each phase)
65
+ - At the end of every wave, before returning to Step 1
66
+ - Periodically while waiting on long-running agents (roughly every few minutes of wall-clock time, or whenever you are notified an agent finished)
67
+ - Before the final report / stopping point
75
68
 
76
- Wait for the agent to complete.
69
+ **Sweep procedure:**
70
+ 1. Call `ListAgents` to enumerate the agents you spawned this run.
71
+ 2. For each agent that is **finished** (reported completion, or its result already arrived) or **idle** (no activity and awaiting input it will never get), collect its report first, then terminate it:
72
+ - `SendMessage` the agent a shutdown request (e.g. "Work complete — shut down now."), and confirm it disappears from `ListAgents`.
73
+ - If it is still listed afterwards, or is hung/stuck, stop it with `TaskStop` using its task ID.
74
+ 3. Re-run `ListAgents` and verify that no finished or idle agent from a completed phase remains. Repeat step 2 until the list is clean.
77
75
 
78
- **Phase 2 — Generate UAT tests**
76
+ **Rules:**
77
+ - Never terminate an agent that is still actively working — only finished or idle ones.
78
+ - Never begin the next phase or wave while finished/idle agents from the previous one are still alive.
79
+ - Never spawn a replacement for a stuck agent without terminating the stuck one first.
80
+ - Do not treat "the agent returned its result" as termination — it is not. Termination is confirmed only when the agent no longer appears in `ListAgents`.
81
+ - The final state on stopping must be **zero** power-mode agents remaining.
79
82
 
80
- ```
81
- Agent({
82
- description: "UAT generate <TASK-NNNN>",
83
- prompt: "Run /uat-generate <task-path>. [append team member footer]",
84
- mode: "bypassPermissions"
85
- })
86
- ```
83
+ ---
87
84
 
88
- Wait for the agent to complete.
85
+ ## Single-Task Executor
89
86
 
90
- **Phase 3 — Run UATs**
87
+ **Trigger:** `/power-mode <path/to/TASK-NNNN.md>` (or a `TASK-NNNN` ID, resolved per Dispatch) with no additional instructions.
91
88
 
92
- ```
93
- Agent({
94
- description: "UAT auto <TASK-NNNN>",
95
- prompt: "Run /uat-auto <uat-path> (infer the UAT file path from the task path — same NNN slug, under wiki/work/uat/).
89
+ A single task has nothing to parallelize, so this mode is only a pointer — no agent team, no reap sweep. Same autonomous mandate as the roadmap loop: take the task to completion. Run these three skills in order in the current session (Skill tool), without pausing, asking questions, or awaiting approval between them:
96
90
 
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.
91
+ 1. `/tackle <task-path>`
92
+ 2. `/uat-create <task-path>`
93
+ 3. `/uat-auto <uat-path>` — same NNNN slug, under `wiki/work/uat/`
98
94
 
99
- UAT tests recorded as [FAIL: auto-judge: UI test requires human verification] do NOT block task completion — /uat-auto does not run UI tests. Treat these as an acceptable resting state, not a blocker.
95
+ Resume from the first incomplete stage by reading the task's `status:` — `todo`/`in-progress` starts at 1; `pending-uat` with no UAT file starts at 2, with one starts at 3; `done`/`trashed` → report and stop.
100
96
 
101
- If any tests remain as - [ ] Pass because stub indicators were detected, that's expected — /uat-auto leaves the task in place rather than closing it. Report the stub-detected tests in your summary. [append team member footer]",
102
- mode: "bypassPermissions"
103
- })
104
- ```
105
-
106
- Done. No further iteration.
97
+ Stop after `/uat-auto` returns. On all-pass, its own UAT-CORE Closure procedure handles task/UAT status, archiving, index rows, and the roadmap checkbox. UI tests are run in a real browser by `/uat-auto` through the Playwright MCP — expect them to pass or fail on evidence, not to be deferred wholesale. Tests left as `[FAIL: auto-judge: ... requires human verification]` (bare manual, visual-only UI Expected, Playwright unavailable) or stub-detected `- [ ] Pass` are an acceptable resting state, not a blocker — report them in the summary.
107
98
 
108
99
  ---
109
100
 
@@ -111,7 +102,7 @@ Done. No further iteration.
111
102
 
112
103
  **Trigger:** `/power-mode <path/to/ROADMAP-NNNN.md>` with no additional instructions.
113
104
 
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.
105
+ **Goal:** Drive the roadmap to completion — every item through the full tackle → UAT-create → UAT-auto pipeline — looping through waves of parallelizable work until no implementation work remains.
115
106
 
116
107
  **AUTONOMOUS EXECUTION MANDATE:** Once triggered, drive the roadmap to completion without stopping. Do NOT pause between waves to report progress or ask for permission to continue. The only valid stopping point is when `/roadmap-next` reports no items remaining. A roadmap item is complete once it has been through the full pipeline — UAT tests requiring human verification do NOT block loop progression.
117
108
 
@@ -137,16 +128,16 @@ For any item that is an inline placeholder (no existing task file link), spawn a
137
128
  ```
138
129
  Agent({
139
130
  description: "Create task for <item>",
140
- prompt: "Run /task-add for this roadmap item: '<item description>'. Link the resulting task back into the roadmap file at wiki/work/roadmaps/<file>. Run /research before writing the task. Make all scope, naming, and structuring decisions autonomously — infer reasonable defaults from the roadmap context and existing task files in wiki/work/tasks/. [append team member footer]",
131
+ prompt: "Run /task-create for this roadmap item: '<item description>'. Link the resulting task back into the roadmap file at wiki/work/roadmaps/<file>. Run /research before writing the task. Make all scope, naming, and structuring decisions autonomously — infer reasonable defaults from the roadmap context and existing task files in wiki/work/tasks/. [append team member footer]",
141
132
  mode: "bypassPermissions"
142
133
  })
143
134
  ```
144
135
 
145
- Wait for all task-creation agents to complete.
136
+ Wait for all task-creation agents to complete, then reap them (see Agent Lifecycle).
146
137
 
147
138
  **Step 3 — Three-phase pipeline for the wave**
148
139
 
149
- Run tackle → UAT-generate → UAT-auto for all tasks in the current wave. Apply the Parallelization Mandate at every phase.
140
+ Run tackle → UAT-create → UAT-auto for all tasks in the current wave. Apply the Parallelization Mandate at every phase.
150
141
 
151
142
  Phase 1 — Tackle (parallel, minimum 5 agents when 5+ collision-safe tasks available):
152
143
  ```
@@ -159,7 +150,7 @@ Wait for all to complete.
159
150
 
160
151
  Phase 2 — Generate UAT tests (parallel, read-only):
161
152
  ```
162
- Agent({ description: "UAT generate TASK-NNNN", prompt: "Run /uat-generate <task-path>. [append team member footer]", mode: "bypassPermissions" })
153
+ Agent({ description: "UAT create TASK-NNNN", prompt: "Run /uat-create <task-path>. [append team member footer]", mode: "bypassPermissions" })
163
154
  // ... one per task, all in the same message
164
155
  ```
165
156
 
@@ -173,12 +164,14 @@ Agent({
173
164
 
174
165
  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.
175
166
 
176
- UAT tests recorded as [FAIL: auto-judge: UI test requires human verification] do NOT block this step. If stub-detected tests remain, that's /uat-auto's own expected behavior — it leaves the file in place; report the stubs. [append team member footer]",
167
+ UI tests (UAT-UI-*) MUST be run with the Playwright MCP — load its deferred tools via ToolSearch (query 'playwright browser') and follow /uat-auto's browser channel (UAT-CORE Step 4 channel 3). Do NOT record a UI test as needing human verification without having attempted the browser run; the only acceptable deferrals are a visual-only Expected or Playwright genuinely unavailable (say which in your report).
168
+
169
+ Tests recorded as [FAIL: auto-judge: ... requires human verification] for those reasons, or bare manual cases, do NOT block this step. If stub-detected tests remain, that's /uat-auto's own expected behavior — it leaves the file in place; report the stubs. [append team member footer]",
177
170
  mode: "bypassPermissions"
178
171
  })
179
172
  ```
180
173
 
181
- **Step 4 — Repeat**
174
+ **Step 4 — Reap and repeat**
182
175
 
183
- Immediately return to Step 1. No pausing, no reporting, no confirmation. Loop until `/roadmap-next` reports no items remaining.
176
+ Run the reap sweep (see Agent Lifecycle): terminate every finished or idle agent from this wave and verify via `ListAgents` that none remain. Then immediately return to Step 1. No pausing, no reporting, no confirmation. Loop until `/roadmap-next` reports no items remaining, then run a final reap sweep so zero power-mode agents remain.
184
177
 
@@ -0,0 +1,105 @@
1
+ ---
2
+ name: prd-assess
3
+ description: Survey all active PRDs together — flag approved requirements with no downstream ADRs or tasks and stale drafts, detect blocking open decisions, and rank them into one prioritized list with a status update for each
4
+ category: researching
5
+ model: claude-sonnet-5
6
+ disable-model-invocation: false
7
+ user-invocable: true
8
+ ---
9
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
10
+
11
+ # PRD Assessment
12
+
13
+ Assess every active PRD in `wiki/work/requirements/` together — this is the multi-PRD counterpart to `/prd-finalize` (drafts) and `/adr-extract` (approved requirements needing decisions), which each operate on exactly one PRD you've already picked. Use this skill first when several requirements exist and you need to decide which to advance next.
14
+
15
+ This skill is strictly read-only: it never flips a status, never creates a file, and never asks questions. Acting on a PRD is the job of the commands named in each `Next` line.
16
+
17
+ ---
18
+
19
+ ## Step 1: Discover active PRDs
20
+
21
+ Read the Family table in `lib/skills/_shared/ID-RESOLUTION.md` for the requirements directory and prefixes — do not hardcode them. Legacy `REQ-` files coexist with `PRD-` files until migrated, so match both prefixes.
22
+
23
+ `list_dir` the requirements directory for `.md` files **directly** in it (ignore every subdirectory); skip `lifecycle.md`, `index.md`, `README.md`. None found → STOP: `No active PRDs found in wiki/work/requirements/. Use /prd-create <idea> to draft one.`
24
+
25
+ Read the status names and which are terminal from `wiki/work/requirements/lifecycle.md` (currently `draft | approved | retired`, with `retired` terminal). Decide active vs. closed by each file's `status:`, never by location. Closed PRDs are excluded from ranking and counted once in the report footer. If nothing is active after this filter, STOP with the same empty-family text.
26
+
27
+ ## Step 2: Parse every active PRD
28
+
29
+ `Read` each file in full and extract:
30
+
31
+ - **Frontmatter**: `id`, `aliases`, `title`, `status`, `owner`, `created`, `updated`, `tags`, `stakeholders`.
32
+ - **Amendments**: each `## Amendment N` block (count and latest date).
33
+
34
+ A `status:` outside the lifecycle's enum is reported in Step 5c, and the PRD is ranked as a fresh draft.
35
+
36
+ ## Step 3: Downstream and blocking analysis
37
+
38
+ For each active PRD, `search_for_pattern` for its ID and every alias (under both prefixes) across `wiki/work/decisions/`, `wiki/work/tasks/`, and `wiki/work/roadmaps/`. Count a hit whether it is frontmatter (`linked_requirements`, `linked_prds`), a typed link (`derived_from::`, `implements::`, `relates_to::`), or a plain `[[…]]` link. Record per PRD: linked ADR groups, linked tasks, linked roadmaps.
39
+
40
+ For each linked ADR group, `Read` it and resolve every `## D1.`-style block's `Status:` as laid out in `wiki/work/decisions/lifecycle.md`. If a block is `superseded`, follow its `superseded by` pointer to the successor block and re-check that status instead. Any resolved block still `proposed` is an **open decision** blocking the PRD: record `{PRD, ADR-NNNN#DM, title}`. A missing linked file is a broken reference — note it, don't block on it.
41
+
42
+ ## Step 4: Rank PRDs
43
+
44
+ **Stale-draft threshold: 30 days** — a draft is stale when `updated` is more than 30 days before today.
45
+
46
+ Order the active PRDs, highest priority first, using this precedence:
47
+
48
+ 1. **Approved with no linked ADRs and no linked tasks** — approved but nothing downstream exists; oldest `updated` first.
49
+ 2. **Approved and blocked by open decisions** — at least one linked ADR block is still `proposed` (Step 3).
50
+ 3. **Stale drafts** — `status: draft` with `updated` older than 30 days.
51
+ 4. **Fresh drafts.**
52
+ 5. **Approved and fully flowing** — every linked ADR block accepted and at least one task exists; needs nothing.
53
+
54
+ Tie-break within a tier: oldest `updated`, then ID ascending. Record a one-sentence rationale per PRD — a judgment call the user can override, not a fact.
55
+
56
+ ## Step 5: Report
57
+
58
+ Print, in this order:
59
+
60
+ ### 5a. Prioritized PRDs
61
+
62
+ ```
63
+ ## Prioritized PRDs
64
+
65
+ | Rank | PRD | Status | Updated | Rationale | Blocks / Blocked by |
66
+ |------|-----|--------|---------|-----------|---------------------|
67
+ | 1 | PRD-NNNN — <title> | approved | YYYY-MM-DD | <one sentence> | no downstream items |
68
+ | 2 | PRD-MMMM — <title> | approved | YYYY-MM-DD | <one sentence> | blocked by ADR-NNNN#DM |
69
+ ```
70
+
71
+ `Blocks / Blocked by` lists open decisions from Step 3 and, for flowing PRDs, the linked task/roadmap; `—` if none.
72
+
73
+ ### 5b. Status update per PRD
74
+
75
+ One block per PRD, in ranked order:
76
+
77
+ ```
78
+ ### PRD-NNNN — <title>
79
+ - Owner: <owner, or "unassigned">
80
+ - Status: <draft | approved> — <fresh | stale | unlinked | blocked | flowing>
81
+ - Summary: <one line>
82
+ - Next: <see below>
83
+ ```
84
+
85
+ `Next` by state:
86
+
87
+ - Approved, unlinked → `/adr-extract <file>`, or `/task-create <description>` when the PRD needs no architectural decision
88
+ - Approved, blocked → `/adr-finalize <adr-file>#DM`
89
+ - Draft → `/prd-finalize <file>`; a stale draft: or `/prd-deprecate <file>` if abandoned
90
+ - Flowing → none needed; cite the linked task/roadmap
91
+
92
+ ### 5c. Warnings (omit if none found)
93
+
94
+ Flag, each as its own short block: broken references from Step 3, and PRDs with an unrecognized `status:`.
95
+
96
+ Footer, when Step 1 excluded any closed PRD: `Closed: N (not assessed)`.
97
+
98
+ ---
99
+
100
+ ## Constraints
101
+
102
+ - Read-only — no exception. No file edits, no shell, no prompts, no log or index changes, no status flips. `/prd-finalize`, `/adr-extract`, `/adr-finalize`, and `/task-create` are the follow-up actions the user runs once they act on this report.
103
+ - Permitted tools: `list_dir`, `find_file`, `search_for_pattern`, `Read`.
104
+ - Never bash reads (`cat`/`find`/`grep`/`sed`/`ls`).
105
+ - Keep the report terse — no preamble, no closing summary beyond the tables above.
@@ -1,9 +1,9 @@
1
1
  ---
2
- name: req-compile
2
+ name: prd-compile
3
3
  description: >-
4
4
  Compile a requirement into a running, production-grade, delightful system with minimal human time —
5
5
  by routing every claim to its cheapest re-runnable check and building the dominant oracle
6
- first. Use this whenever a project has a wiki/work/requirements/ REQ file to build or execute
6
+ first. Use this whenever a project has a wiki/work/requirements/ PRD file to build or execute
7
7
  ("build this per the requirement", "execute the spec", "turn these requirements into a working
8
8
  system"), when scaffolding or resuming a greenfield build from a requirements document, or in
9
9
  a build's closing phase to harvest corrections back into the method. Pairs with
@@ -13,7 +13,7 @@ model: claude-opus-5
13
13
  effort: high
14
14
  ---
15
15
 
16
- # req-compile
16
+ # prd-compile
17
17
 
18
18
  Turn a requirement into a working system that **self-verifies**, surfacing the human only where no
19
19
  machine can decide. The aim is not zero human corrections — some are irreducible taste, or
@@ -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-NNNN-slug.md` (REQ) file + a project `CLAUDE.md`
25
+ **Input:** a project dir with a `wiki/work/requirements/PRD-NNNN-slug.md` (PRD) 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.
@@ -42,16 +42,9 @@ feature usually splits across several oracles. Build the **dominant** oracle fir
42
42
 
43
43
  ## Locating the requirement
44
44
 
45
- Parse `$ARGUMENTS` to find the requirement file:
45
+ Resolve the file per ~/.claude/skills/_shared/ID-RESOLUTION.md — family: requirements · scope: active · ambiguous: interactive · empty: look for any `wiki/work/requirements/PRD-NNNN-slug.md` with `status: approved`; if ambiguous, ask via `AskUserQuestion`
46
46
 
47
- | Input form | Resolution |
48
- |------------|------------|
49
- | `<path>` (e.g. `wiki/work/requirements/REQ-003-onboarding.md`) | Use as-is |
50
- | `<NNN-slug>` (e.g. `003-onboarding`) | `mcp__serena__find_file` with mask `003-onboarding.md` under `wiki/work/requirements/` |
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-NNNN-slug.md` with `status: approved`; if ambiguous, ask via `AskUserQuestion` |
53
-
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.
47
+ **Verify the requirement has `status: approved`** before proceeding. If `draft`, tell the user to run `/prd-finalize <path>` first. If `retired` or `superseded`, refuse — no system should be built against a cancelled requirement.
55
48
 
56
49
  ## The loop
57
50
 
@@ -1,6 +1,6 @@
1
1
  ---
2
- name: req-create
3
- description: Draft a new requirement in wiki/work/requirements/ via Socratic Q&A capturing problem, personas, user stories, success metrics, and non-goals
2
+ name: prd-create
3
+ description: Draft a new PRD in wiki/work/requirements/ via Socratic Q&A capturing problem, personas, user stories, success metrics, and non-goals
4
4
  category: planning
5
5
  model: claude-sonnet-5
6
6
  effort: high
@@ -9,11 +9,11 @@ disable-model-invocation: false
9
9
  user-invocable: true
10
10
  ---
11
11
  **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
12
- **Check `wiki/work/requirements/lifecycle.md`** for the REQ template, status lifecycle, required-non-empty fields, and anti-patterns this skill enforces; **`wiki/work/requirements/index.md`** for the index row format.
12
+ **Check `wiki/work/requirements/lifecycle.md`** for the PRD template, status lifecycle, required-non-empty fields, and anti-patterns this skill enforces; **`wiki/work/requirements/index.md`** for the index row format.
13
13
 
14
- # Create Requirement
14
+ # Create PRD
15
15
 
16
- Create a **Requirement** (REQ) — **what to build and why** from a product perspective: problem, personas, desired outcomes, explicit non-goals. Requirements sit **upstream** of decisions and tasks; they define *what* and *why*, never *how*.
16
+ Create a **PRD** — **what to build and why** from a product perspective: problem, personas, desired outcomes, explicit non-goals. Requirements sit **upstream** of decisions and tasks; they define *what* and *why*, never *how*.
17
17
 
18
18
  > *A requirement never justifies architecture. A decision never redefines product scope.* (Joel Parker Henderson's REQ↔Decision pattern)
19
19
 
@@ -23,7 +23,7 @@ If the user specifies file paths, libraries, schemas, or frameworks, **redirect*
23
23
 
24
24
  ## When to write
25
25
 
26
- Write when there's a real problem worth aligning on, more than one decision area, multiple stakeholders, and the *what* is not obvious from the codebase. For a bug fix, refactor, one-line config change, or a pure *how* question — **stop and tell the user**; suggest `/task-add` or `/decision-create`.
26
+ Write when there's a real problem worth aligning on, more than one decision area, multiple stakeholders, and the *what* is not obvious from the codebase. For a bug fix, refactor, one-line config change, or a pure *how* question — **stop and tell the user**; suggest `/task-create` or `/adr-create`.
27
27
 
28
28
  ---
29
29
 
@@ -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-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.
36
+ Requirements live at `wiki/work/requirements/PRD-NNNN-slug.md` (4-digit zero-padded). Allocate the next ID per `~/.claude/skills/_shared/SKILL-BOILERPLATE.md` § Number allocation (family: `wiki/work/requirements/`, prefix: `PRD-`, no index scan; also count legacy `REQ` filenames). Derive the slug — names the **initiative**, lowercase dash-separated ≤60 chars (e.g. "Self-serve billing portal" → `PRD-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**:
@@ -63,22 +63,22 @@ Walk the elicitations **in order**. Batch related ones into a single round when
63
63
 
64
64
  **Suggested batching:** (1) Problem, Personas · (2) User Stories+AC, Success Metrics · (3) Goals, Non-Goals, Constraints, Assumptions · (4) Owner, Stakeholders, Tags, Open Questions. Adjust as the conversation flows — the rule is *every elicitation passes its bar before Step 5*.
65
65
 
66
- **Redirection rule:** if the user answers with implementation specifics (file paths, function names, libraries, schema fields), respond: *"That sounds like an architectural decision, not a product requirement. Let's keep this to what and why; how is captured later in a decision via `/decision-create` after `/req-finalize` and `/req-extract-decisions`."* Then re-ask for the user-visible behavior/outcome.
66
+ **Redirection rule:** if the user answers with implementation specifics (file paths, function names, libraries, schema fields), respond: *"That sounds like an architectural decision, not a product requirement. Let's keep this to what and why; how is captured later in a decision via `/adr-create` after `/prd-finalize` and `/adr-extract`."* Then re-ask for the user-visible behavior/outcome.
67
67
 
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
71
  ### Step 5a: Re-verify next requirement number — IMMEDIATELY before writing
72
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.**
73
+ Repeat § Number allocation step 6 (same family and prefix as Step 2); never call `Write` before completing it.
74
74
 
75
75
  ## Step 6: Write the file
76
- After confirmation, `Write` `wiki/work/requirements/REQ-NNNN-slug.md`.
76
+ After confirmation, `Write` `wiki/work/requirements/PRD-NNNN-slug.md`.
77
77
 
78
78
  ```yaml
79
79
  ---
80
- id: REQ-NNNN
81
- aliases: [REQ-NNNN]
80
+ id: PRD-NNNN
81
+ aliases: [PRD-NNNN]
82
82
  type: requirement
83
83
  status: draft
84
84
  created: YYYY-MM-DD
@@ -90,21 +90,21 @@ tags: [<tag1>, <tag2>]
90
90
  ---
91
91
  ```
92
92
 
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. -->`).
93
+ Sections in order: `# PRD-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).
94
94
 
95
95
  **Refuse to write** if any required-non-empty field is missing or fails its bar — loop back to Step 4.
96
96
 
97
- ## Step 7: Update indexes + log (`Edit` only, never `sed`/`awk`/`echo >>`)
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>`.
97
+ ## Step 7: Update indexes + log (`Edit` only)
98
+ Append (or replace the placeholder row) under `## Active` in `wiki/work/requirements/index.md` (a new draft is always Active; `/prd-deprecate` later moves it to `## Closed`) using the format documented at the top of that file: `- [PRD-NNNN — Title](PRD-NNNN-slug.md) — one-line summary · status`, in ascending ID order. Append to `wiki/log.md`: `## [YYYY-MM-DD] prd-create | PRD-NNNN <title>`.
99
99
 
100
100
  ## Step 8: Cross-link related artifacts
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.
101
+ If prompted by an existing task/research note/reference, link both ways (`Read` then `Edit`): source artifact gets `**Requirement**: PRD-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.
102
102
 
103
103
  ## Step 9: Update memory if appropriate
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.
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 `PRD-NNNN` in the body.
105
105
 
106
106
  ## Step 10: Report
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`.
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 `/prd-finalize wiki/work/requirements/PRD-NNNN-slug.md`. Note any placeholder-reduced field under a **Gaps** section for the user to address before `/prd-finalize`.
108
108
 
109
109
  ---
110
110
 
@@ -122,7 +122,7 @@ Tabular summary: File path, Status (`draft`), Personas/User Stories/Success Metr
122
122
  1. **Max 3 sub-processes at a time** if delegating Step 3 research; **always terminate processes when done**.
123
123
  2. **Refuse to write if any required-non-empty field is empty or fails its bar** — loop back to Step 4.
124
124
  3. **Never invent personas, metrics, user stories, or non-goals** — every entry from user-confirmed `AskUserQuestion` input.
125
- 4. **Never `sed`/`awk`/`echo >>`/shell redirection to edit markdown** — always `Read` then `Edit`.
125
+ 4. Edit only — see `~/.claude/skills/_shared/SKILL-BOILERPLATE.md` § Edit hygiene.
126
126
  5. **Tags non-empty is mandatory** — refuse to write if Step 4 #11 yielded zero tags.
127
127
  6. **Never auto-create downstream artifacts** — exactly one requirement file (+ index + log + cross-link edits); no decisions, tasks, or research notes as a side effect.
128
128
  7. **Redirect implementation talk to decision territory** — restate as *what*/*why* and re-elicit.
@@ -0,0 +1,173 @@
1
+ ---
2
+ name: prd-deprecate
3
+ description: Deprecate a PRD — set status to retired in frontmatter, document the reason, move its index row to Closed, append a log entry. Status-only: the file never moves.
4
+ category: planning
5
+ model: claude-haiku-4-5-20251001
6
+ argument-hint: <wiki/work/requirements/PRD-NNNN-slug.md, PRD-NNNN, NNN-slug, or NNN> [reason]
7
+ disable-model-invocation: false
8
+ user-invocable: true
9
+ ---
10
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
11
+ **Read `wiki/work/requirements/lifecycle.md` first** — it defines the PRD lifecycle and terminal states.
12
+
13
+ # Deprecate PRD
14
+
15
+ Set a PRD's `status` to `retired`, document why, and move its row in the family index from Active to Closed. The file stays in `wiki/work/requirements/`, so cross-references using `[[PRD-NNNN]]` (and legacy `[[REQ-NNNN]]` links, which still resolve) are unaffected.
16
+
17
+ This skill is a focused shortcut for the deprecation flow. For supersession (a new PRD replaces this one), create the new PRD with `/prd-create`, then deprecate the old one here.
18
+
19
+
20
+
21
+ ---
22
+
23
+ **PRD**: $ARGUMENTS
24
+
25
+ ---
26
+
27
+ ## Instructions
28
+
29
+ ### Step 1: Resolve the PRD file
30
+
31
+ Parse `$ARGUMENTS`:
32
+ - **First token(s)** — the file reference: `<path>`, `PRD-NNNN`, `<NNN-slug>`, or `<NNN>`
33
+ - **Remaining text** — optional reason for deprecation (may be elicited in Step 3 if absent)
34
+
35
+ Resolve the file per ~/.claude/skills/_shared/ID-RESOLUTION.md — family: requirements · scope: active · ambiguous: interactive · empty: list every PRD in `wiki/work/requirements/` and ask the user via `AskUserQuestion` to pick
36
+
37
+ An item still sitting in a legacy holding folder from the older layout is already terminal: if the resolver STOPs and the ID appears in that legacy folder's index, report "already retired" instead of "not found".
38
+
39
+ If the file cannot be located, **stop** and report.
40
+
41
+ ### Step 2: Read the PRD and verify status
42
+
43
+ 1. **Read** the PRD file with `Read`.
44
+ 2. **Check `status:` in frontmatter:**
45
+
46
+ | Current status | Action |
47
+ |----------------|--------|
48
+ | `draft` | Continue — may be deprecated before approval |
49
+ | `approved` | Continue — most common case |
50
+ | `retired` | **STOP.** Tell the user: "PRD-NNNN is already retired. No action needed." |
51
+ | `superseded` | **STOP.** Tell the user: "PRD-NNNN is already superseded. No action needed." |
52
+
53
+ 3. **Check for downstream artifacts** in `## Linked Decisions` and `## Linked Tasks`:
54
+ - List any linked decisions and their current status
55
+ - List any linked tasks and their current status
56
+ - Build a downstream artifacts table for Step 3
57
+
58
+ ### Step 3: Confirm with the user
59
+
60
+ Use `AskUserQuestion` to confirm. Show:
61
+
62
+ - The PRD file to be deprecated (full path, ID, title)
63
+ - Current status
64
+ - Downstream artifacts table (if any linked decisions or tasks exist):
65
+
66
+ | Artifact | Type | Current status | Suggested action |
67
+ |----------|------|----------------|------------------|
68
+ | `[[0007-auth\|ADR-0007#D2]]` | linked decision | accepted | Review independently — accepted decisions are immutable; if no longer needed, write a deprecating successor with `/adr-create deprecate <topic> (supersedes ADR-0007#D2)` |
69
+ | `[[004-billing\|TASK-004]]` | linked task | todo | Run `/task-close wiki/work/tasks/TASK-004-billing.md` if the task is also cancelled |
70
+
71
+ Ask the user:
72
+
73
+ 1. **"Deprecate this PRD? (yes / no)"**
74
+ 2. **"Reason for deprecating PRD-NNNN?"** (if not provided in `$ARGUMENTS` — required, one line or more)
75
+
76
+ If the user says **No**, STOP. Do not proceed.
77
+
78
+ **Do NOT ask whether to deprecate linked decisions or tasks** — they are surfaced as suggestions only. This skill never auto-cascades.
79
+
80
+ ### Step 4: Apply the deprecation edits
81
+
82
+ Edit only — see `~/.claude/skills/_shared/SKILL-BOILERPLATE.md` § Edit hygiene.
83
+
84
+ Apply in this order:
85
+
86
+ 1. **Update `status: <current>` → `status: retired`** in frontmatter.
87
+ 2. **Update `updated: YYYY-MM-DD`** in frontmatter to today's date.
88
+ 3. **Append the deprecation reason to `## Notes`**:
89
+ - If `## Notes` already has content, append a new paragraph.
90
+ - If `## Notes` is empty or has only a placeholder, replace the placeholder with the deprecation entry:
91
+ ```
92
+ **Deprecated [YYYY-MM-DD]**: <reason provided by user>
93
+ ```
94
+ - If the `## Notes` section does not exist, add it at the end of the file.
95
+
96
+ ### Step 5: Move the row from Active to Closed in the family index
97
+
98
+ `retired` is a terminal status — **move the PRD's row from Active to Closed** in `wiki/work/requirements/index.md`. This is the in-place close mechanic defined once in `~/.claude/skills/_shared/ARCHIVE-WORK-ITEM.md` § In-place close (roadmaps, decisions, requirements) with `family: requirements`, `terminal_status: retired` — this step is that section's step 2 (Step 4 already did its step 1 and Step 6 writes its own log entry):
99
+
100
+ 1. Delete the row from the Active section.
101
+ 2. Add the same entry under a `## Closed` heading, using the Active bullet format with the terminal status as the last ` · ` segment:
102
+
103
+ ```
104
+ - [PRD-NNNN — Title](PRD-NNNN-slug.md) — one-line summary · retired
105
+ ```
106
+
107
+ If the index has no `## Closed` heading yet, create it at the end of the file (with the entry-format line if the Active section carries one). Keep Closed rows in numeric-ID order.
108
+
109
+ Use `Read` then `Edit`. If the row is already absent from Active, note it and continue.
110
+
111
+ ### Step 6: Append to wiki/log.md
112
+
113
+ Append one entry to `wiki/log.md`:
114
+
115
+ ```
116
+ ## [YYYY-MM-DD] prd-deprecated | PRD-NNNN <title> — reason: <one-line summary of reason>
117
+ ```
118
+
119
+ Use `Read` then `Edit`.
120
+
121
+ ### Step 7: Surface downstream artifacts for independent action
122
+
123
+ Print the downstream artifacts table from Step 3 again, with suggested next-action commands:
124
+
125
+ ```
126
+ Linked decisions and tasks surfaced for independent review:
127
+
128
+ To act on linked tasks (each independently):
129
+ /task-close wiki/work/tasks/TASK-004-billing.md # if task is also cancelled
130
+
131
+ To act on linked decisions (each independently):
132
+ # Accepted decisions are immutable — write a deprecating successor:
133
+ /adr-create deprecate <topic> (supersedes ADR-0007#D2)
134
+ # Proposed decisions may be left, finalized, or abandoned
135
+ ```
136
+
137
+ ### Step 8: Report completion
138
+
139
+ Print a tabular summary:
140
+
141
+ | Field | Value |
142
+ |-------|-------|
143
+ | PRD | `PRD-NNNN <title>` |
144
+ | File path | `wiki/work/requirements/PRD-NNNN-slug.md` (unchanged) |
145
+ | Old status | `draft` or `approved` |
146
+ | New status | `retired` |
147
+ | Reason | <one-line summary> |
148
+ | Family index updated | yes (row moved to Closed) |
149
+ | wiki/log.md entry | yes |
150
+ | Linked decisions surfaced | count |
151
+ | Linked tasks surfaced | count |
152
+
153
+ ---
154
+
155
+ ## Output Formatting Rules
156
+
157
+ 1. Use tables for the downstream artifacts list and the completion report — never paragraph prose.
158
+ 2. **One `Edit` call per change** — never bulk rewrites.
159
+ 3. **The file never moves**, so all ID cross-references remain valid.
160
+ 4. **The skill never auto-deprecates or auto-retires downstream artifacts** — it surfaces them with suggested commands.
161
+ 5. **The deprecation reason in `## Notes` is permanent** — it is the audit trail for why this PRD was deprecated.
162
+
163
+ ---
164
+
165
+ ## CRITICAL Rules
166
+
167
+ 1. **Status-only.** Set `status: retired` in frontmatter and update the index; **never move the file**.
168
+ 2. **Never auto-cascade** to linked decisions or tasks. Surface them as suggestions only.
169
+ 3. **Confirm with the user before any edits** — `AskUserQuestion` is mandatory in Step 3.
170
+ 4. **Deprecation reason is required** — refuse to deprecate without a documented reason.
171
+ 5. **Refuse if already retired or superseded** — these are terminal states; running again is a no-op, not an error.
172
+ 6. Maximum 3 sub-processes at a time if delegating any step.
173
+ 7. Always terminate background processes when done.