@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.
- package/README.md +18 -60
- package/lib/prompts/README.md +0 -1
- package/lib/scripts/README.md +1 -2
- package/lib/scripts/migrate-project.sh +1 -1
- package/lib/scripts/setup-project.sh +0 -1
- package/lib/scripts/sync-wiki-scaffold.sh +3 -15
- package/lib/scripts/templates/CLAUDE-wiki.md +4 -4
- package/lib/scripts/templates/bootstrap-prefs-schema.json +1 -1
- package/lib/scripts/templates/wiki/conventions.md +4 -2
- package/lib/scripts/templates/wiki/dashboard.html +2 -2
- package/lib/scripts/templates/wiki/index.md +4 -4
- package/lib/scripts/templates/wiki/work/requirements/index.md +1 -1
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +2 -2
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +1 -1
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +4 -4
- package/lib/scripts/templates/wiki/work/tasks/index.md +1 -1
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +6 -6
- package/lib/scripts/templates/wiki/work/uat/index.md +1 -1
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +4 -4
- package/lib/scripts/wiki-dashboard-server.js +1 -1
- package/lib/skills/README.md +2 -1
- package/lib/skills/architecture-audit/SKILL.md +228 -0
- package/lib/skills/bug-close/SKILL.md +5 -2
- package/lib/skills/bug-file/SKILL.md +24 -6
- package/lib/skills/decision-create/SKILL.md +7 -2
- package/lib/skills/demo/SKILL.md +10 -10
- package/lib/skills/elevator-pitch/SKILL.md +1 -1
- package/lib/skills/extract-feature/SKILL.md +29 -87
- package/lib/skills/marp-slideshow/SKILL.md +2 -2
- package/lib/skills/port-feature/SKILL.md +28 -83
- package/lib/skills/power-mode/SKILL.md +10 -10
- package/lib/skills/primer/SKILL.md +1 -1
- package/lib/skills/req-compile/SKILL.md +2 -2
- package/lib/skills/req-create/SKILL.md +13 -9
- package/lib/skills/req-extract-decisions/SKILL.md +10 -10
- package/lib/skills/req-finalize/SKILL.md +3 -3
- package/lib/skills/req-retire/SKILL.md +10 -10
- package/lib/skills/req-update/SKILL.md +4 -4
- package/lib/skills/roadmap-assess/SKILL.md +7 -7
- package/lib/skills/roadmap-create/SKILL.md +26 -22
- package/lib/skills/roadmap-next/SKILL.md +10 -10
- package/lib/skills/security-audit/SKILL.md +3 -0
- package/lib/skills/tackle/SKILL.md +3 -3
- package/lib/skills/task-add/SKILL.md +41 -22
- package/lib/skills/task-audit/SKILL.md +2 -2
- package/lib/skills/task-trash/SKILL.md +4 -4
- package/lib/skills/uat-auto/SKILL.md +2 -1
- package/lib/skills/uat-generate/SKILL.md +22 -22
- package/lib/skills/uat-skip/SKILL.md +21 -21
- package/lib/skills/uat-walk/SKILL.md +1 -1
- package/lib/skills/uat-walk/UAT-CORE.md +6 -6
- package/lib/skills/wiki-lint/SKILL.md +28 -1
- 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
|
|
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
|
|
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
|
-
-
|
|
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
|
|
204
|
+
## Phase 4: Produce the Port Roadmap
|
|
205
205
|
|
|
206
|
-
### 4a.
|
|
206
|
+
### 4a. Present the Full Analysis
|
|
207
207
|
|
|
208
|
-
|
|
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
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
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
|
-
|
|
219
|
+
### 4b. Decide: Roadmap or Single Task
|
|
251
220
|
|
|
252
|
-
<
|
|
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
|
-
|
|
224
|
+
### 4c. Delegate to `/roadmap-create`
|
|
255
225
|
|
|
256
|
-
|
|
226
|
+
> **Delegate to `/roadmap-create Port <feature name> from <source-path>`**
|
|
257
227
|
|
|
258
|
-
|
|
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
|
-
|
|
261
|
-
|
|
262
|
-
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
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
|
-
|
|
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
|
|
243
|
+
After the roadmap (or single task) is created:
|
|
299
244
|
|
|
300
|
-
1. State the path
|
|
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 (
|
|
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-
|
|
23
|
-
- Path contains `task` or matches `TASK-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
76
|
+
After confirmation, `Write` `wiki/work/requirements/REQ-NNNN-slug.md`.
|
|
73
77
|
|
|
74
78
|
```yaml
|
|
75
79
|
---
|
|
76
|
-
id: REQ-
|
|
77
|
-
aliases: [REQ-
|
|
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-
|
|
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
|
-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
176
|
-
4. `Edit` to append: `- Source REQ: [REQ-
|
|
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-
|
|
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-
|
|
202
|
-
/decision-create hris-integration (from REQ-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
54
|
-
| `superseded` | **STOP.** Tell the user: "REQ-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
154
|
-
| File path | `wiki/work/requirements/REQ-
|
|
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-
|
|
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-
|
|
65
|
-
| `superseded` | **STOP.** Tell the user: "REQ-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
108
|
-
| 2 | ROADMAP-MMM — <title> | M/N | <one sentence> | ROADMAP-
|
|
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-
|
|
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-
|
|
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
|
|