@codewizard-dt/bootstrap 5.3.0 → 6.0.1
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/LICENSE.md +105 -0
- package/README.md +22 -3
- package/bin/cli.js +16 -0
- package/lib/hooks/README.md +124 -3
- package/lib/hooks/claude-settings-guard.js +8 -2
- package/lib/prompts/README.md +1 -1
- package/lib/prompts/migrate-wiki.md +7 -7
- package/lib/scripts/README.md +111 -10
- package/lib/scripts/bootstrap-prefs-tui.js +1222 -0
- package/lib/scripts/install-global.sh +137 -6
- package/lib/scripts/migrate-project.sh +53 -11
- package/lib/scripts/rename-wiki-ids.js +232 -0
- package/lib/scripts/templates/CLAUDE-wiki.md +6 -6
- package/lib/scripts/templates/bootstrap-prefs-schema.json +11 -2
- package/lib/scripts/templates/settings-deny.json +1 -1
- package/lib/scripts/templates/settings-sandbox-unattended.json +36 -0
- package/lib/scripts/templates/settings-sandbox.json +7 -0
- package/lib/scripts/templates/wiki/conventions.md +9 -9
- package/lib/scripts/templates/wiki/dashboard.html +527 -23
- package/lib/scripts/templates/wiki/index.md +2 -2
- package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +1 -1
- package/lib/scripts/templates/wiki/work/decisions/index.md +12 -4
- package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +11 -9
- package/lib/scripts/templates/wiki/work/requirements/index.md +12 -4
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +8 -8
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +11 -3
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +7 -5
- package/lib/scripts/templates/wiki/work/tasks/index.md +1 -1
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +16 -8
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +3 -3
- package/lib/scripts/wiki-dashboard-server.js +98 -0
- package/lib/skills/README.md +27 -22
- package/lib/skills/_shared/ARCHIVE-WORK-ITEM.md +103 -0
- package/lib/skills/_shared/ID-RESOLUTION.md +142 -0
- package/lib/skills/_shared/SKILL-BOILERPLATE.md +50 -0
- package/lib/skills/adr-assess/SKILL.md +112 -0
- package/lib/skills/{decision-create → adr-create}/SKILL.md +26 -26
- package/lib/skills/adr-deprecate/SKILL.md +190 -0
- package/lib/skills/adr-extract/SKILL.md +255 -0
- package/lib/skills/{decision-finalize → adr-finalize}/SKILL.md +38 -38
- package/lib/skills/{decision-next → adr-next}/SKILL.md +20 -19
- package/lib/skills/{decision-walkthrough → adr-walkthrough}/SKILL.md +23 -29
- package/lib/skills/architecture-audit/SKILL.md +1 -1
- package/lib/skills/autopilot/SKILL.md +110 -0
- package/lib/skills/bootstrap-config/SKILL.md +1 -1
- package/lib/skills/bug-assess/SKILL.md +3 -3
- package/lib/skills/bug-close/SKILL.md +13 -27
- package/lib/skills/{bug-file → bug-create}/SKILL.md +10 -14
- package/lib/skills/bug-triage/SKILL.md +5 -19
- package/lib/skills/demo/SKILL.md +1 -1
- package/lib/skills/extract-feature/SKILL.md +3 -3
- package/lib/skills/git-commit/SKILL.md +4 -4
- package/lib/skills/port-feature/SKILL.md +3 -3
- package/lib/skills/power-mode/SKILL.md +42 -49
- package/lib/skills/prd-assess/SKILL.md +105 -0
- package/lib/skills/{req-compile → prd-compile}/SKILL.md +6 -13
- package/lib/skills/{req-create → prd-create}/SKILL.md +19 -19
- package/lib/skills/prd-deprecate/SKILL.md +173 -0
- package/lib/skills/{req-finalize → prd-finalize}/SKILL.md +20 -29
- package/lib/skills/primer/SKILL.md +2 -2
- package/lib/skills/research/SKILL.md +3 -3
- package/lib/skills/roadmap-assess/SKILL.md +20 -20
- package/lib/skills/roadmap-create/SKILL.md +19 -29
- package/lib/skills/roadmap-next/SKILL.md +16 -28
- package/lib/skills/security-audit/SKILL.md +1 -1
- package/lib/skills/tackle/SKILL.md +13 -15
- package/lib/skills/{task-audit → task-assess}/SKILL.md +34 -44
- package/lib/skills/task-close/SKILL.md +73 -0
- package/lib/skills/{task-add → task-create}/SKILL.md +25 -24
- package/lib/skills/uat-assess/SKILL.md +124 -0
- package/lib/skills/uat-auto/SKILL.md +9 -7
- package/lib/skills/uat-auto-plus/SKILL.md +2 -2
- package/lib/skills/{uat-generate → uat-create}/SKILL.md +10 -12
- package/lib/skills/uat-skip/SKILL.md +5 -9
- package/lib/skills/uat-walk/SKILL.md +2 -2
- package/lib/skills/uat-walk/UAT-CORE.md +29 -16
- package/lib/skills/update-docs/SKILL.md +1 -1
- package/lib/skills/usage-report/SKILL.md +52 -0
- package/lib/skills/usage-report/scripts/pricing.json +22 -0
- package/lib/skills/usage-report/scripts/usage-report.js +518 -0
- package/lib/skills/whats-next/SKILL.md +177 -0
- package/lib/skills/wiki-archive/SKILL.md +12 -23
- package/lib/skills/wiki-lint/SKILL.md +23 -13
- package/lib/skills/wiki-query/SKILL.md +1 -1
- package/lib/skills/wiki-rotate-log/SKILL.md +1 -1
- package/lib/skills/wiki-tidy/SKILL.md +6 -9
- package/package.json +3 -3
- package/lib/scripts/templates/wiki/work/decisions/archive/index.md +0 -10
- package/lib/scripts/templates/wiki/work/requirements/archive/index.md +0 -10
- package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +0 -10
- package/lib/skills/req-extract-decisions/SKILL.md +0 -241
- package/lib/skills/req-retire/SKILL.md +0 -185
- package/lib/skills/req-update/SKILL.md +0 -265
- package/lib/skills/task-trash/SKILL.md +0 -115
- package/lib/skills/task-update/SKILL.md +0 -136
|
@@ -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.
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
---
|
|
2
|
-
name:
|
|
2
|
+
name: prd-finalize
|
|
3
3
|
description: Run completeness audit on a draft requirement, resolve gaps via Q&A, and flip status to approved
|
|
4
4
|
category: planning
|
|
5
5
|
model: claude-sonnet-5
|
|
6
6
|
effort: high
|
|
7
|
-
argument-hint: <path/to/
|
|
7
|
+
argument-hint: <path/to/prd.md, NNNN-slug, or NNNN>
|
|
8
8
|
disable-model-invocation: false
|
|
9
9
|
user-invocable: true
|
|
10
10
|
---
|
|
@@ -15,7 +15,7 @@ user-invocable: true
|
|
|
15
15
|
|
|
16
16
|
Take a single **draft** requirement, surface every required-field gap or unresolved placeholder, resolve those gaps with the user, confirm stakeholder review, then flip the requirement's `status` from `draft` to `approved` in frontmatter.
|
|
17
17
|
|
|
18
|
-
Once a requirement is approved, it is **immutable in substance**.
|
|
18
|
+
Once a requirement is approved, it is **immutable in substance**. An approved requirement is locked in substance; changes are made by editing the file directly, or by creating a new requirement with `/prd-create` and deprecating the old one with `/prd-deprecate`. This command is the one-way gate into that immutable state — get the audit right.
|
|
19
19
|
|
|
20
20
|
**Check `wiki/work/requirements/lifecycle.md` first.** It defines the required-non-empty fields, the status lifecycle, the file template, and the anti-patterns this audit must catch.
|
|
21
21
|
|
|
@@ -29,14 +29,7 @@ Once a requirement is approved, it is **immutable in substance**. Future scope c
|
|
|
29
29
|
|
|
30
30
|
### Step 1: Resolve the requirement file
|
|
31
31
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
| Input form | Resolution |
|
|
35
|
-
|------------|------------|
|
|
36
|
-
| `<path>` (e.g. `wiki/work/requirements/REQ-003-search.md`) | Use as-is |
|
|
37
|
-
| `<NNN-slug>` (e.g. `003-search`) | Search `wiki/work/requirements/` for `NNN-slug.md` |
|
|
38
|
-
| `<NNN>` (e.g. `3` or `003`) | Pad to 3 digits; `mcp__serena__find_file` with mask `NNN-*.md` in `wiki/work/requirements/` |
|
|
39
|
-
| Empty / missing | List every requirement with `status: draft` across `wiki/work/requirements/` and ask the user via `AskUserQuestion` to pick one |
|
|
32
|
+
Resolve the file per ~/.claude/skills/_shared/ID-RESOLUTION.md — family: requirements · scope: active · ambiguous: interactive · empty: list every requirement with `status: draft` across `wiki/work/requirements/` and ask the user via `AskUserQuestion` to pick one
|
|
40
33
|
|
|
41
34
|
If the file cannot be located, **stop** and report — do not invent or create.
|
|
42
35
|
|
|
@@ -49,7 +42,7 @@ If the file cannot be located, **stop** and report — do not invent or create.
|
|
|
49
42
|
| Current Status | Action |
|
|
50
43
|
|----------------|--------|
|
|
51
44
|
| `draft` | Continue to Step 3 |
|
|
52
|
-
| `approved` | Stop. Tell the user the requirement is already approved and
|
|
45
|
+
| `approved` | Stop. Tell the user the requirement is already approved and locked in substance; any change is made by editing the file directly, or by creating a new requirement and deprecating this one with `/prd-deprecate` |
|
|
53
46
|
| `retired` | Stop. The requirement is no longer authoritative; finalizing makes no sense |
|
|
54
47
|
| `superseded` | Stop. A successor requirement has replaced this one — finalize the successor instead |
|
|
55
48
|
|
|
@@ -86,7 +79,7 @@ Inspect the file section by section and build a gap report. Required-field gaps
|
|
|
86
79
|
Output to the user **before any edits** as a tabular summary — never bullets:
|
|
87
80
|
|
|
88
81
|
```
|
|
89
|
-
File: wiki/work/requirements/
|
|
82
|
+
File: wiki/work/requirements/PRD-0003-search.md
|
|
90
83
|
Title: Federated search across knowledge bases
|
|
91
84
|
Current status: draft
|
|
92
85
|
Required-field gaps: N
|
|
@@ -130,7 +123,7 @@ If the user genuinely lacks an answer to a required-field gap, **do not fabricat
|
|
|
130
123
|
|
|
131
124
|
### Step 5: Apply edits
|
|
132
125
|
|
|
133
|
-
|
|
126
|
+
Edit only — see `~/.claude/skills/_shared/SKILL-BOILERPLATE.md` § Edit hygiene.
|
|
134
127
|
|
|
135
128
|
Apply edits in this order:
|
|
136
129
|
|
|
@@ -168,11 +161,11 @@ Before flipping the status edit, use `AskUserQuestion` to ask the user explicitl
|
|
|
168
161
|
| User answer | Action |
|
|
169
162
|
|-------------|--------|
|
|
170
163
|
| Yes — stakeholders have reviewed | Continue; apply the `status: draft` → `status: approved` edit. |
|
|
171
|
-
| No — they have not | **Stop.** Leave `status: draft` in place. Report what's blocking and suggest the user circulate the draft before re-running `/
|
|
164
|
+
| No — they have not | **Stop.** Leave `status: draft` in place. Report what's blocking and suggest the user circulate the draft before re-running `/prd-finalize`. |
|
|
172
165
|
|
|
173
166
|
### Step 8: Update the wiki index
|
|
174
167
|
|
|
175
|
-
Edit `wiki/work/requirements/index.md` to update this requirement's row (status text `draft` → `approved`; approved is still active so the row stays):
|
|
168
|
+
Edit `wiki/work/requirements/index.md` to update this requirement's row (status text `draft` → `approved`; approved is still active, so the row stays under `## Active`; only `/prd-deprecate` moves a PRD to `## Closed`):
|
|
176
169
|
|
|
177
170
|
| Column | New value |
|
|
178
171
|
|--------|-----------|
|
|
@@ -182,21 +175,21 @@ If this requirement's row does not yet exist in the index table, insert a new ro
|
|
|
182
175
|
|
|
183
176
|
| Column | Format |
|
|
184
177
|
|--------|--------|
|
|
185
|
-
| `ID` | `[
|
|
178
|
+
| `ID` | `[PRD-NNNN](requirements/PRD-NNNN-slug.md)` |
|
|
186
179
|
| `Title` | The requirement's initiative title |
|
|
187
180
|
| `Status` | `approved` |
|
|
188
181
|
| `Created` | The requirement's `created:` date |
|
|
189
182
|
| `Owner` | The requirement's confirmed owner |
|
|
190
|
-
| `Linked Decisions` | `—` (filled later by `/
|
|
191
|
-
| `Linked Tasks` | `—` (filled later by `/task-
|
|
183
|
+
| `Linked Decisions` | `—` (filled later by `/adr-extract`) |
|
|
184
|
+
| `Linked Tasks` | `—` (filled later by `/task-create --req`) |
|
|
192
185
|
|
|
193
186
|
Append to `wiki/log.md`:
|
|
194
187
|
|
|
195
188
|
```
|
|
196
|
-
## [YYYY-MM-DD]
|
|
189
|
+
## [YYYY-MM-DD] prd-approved | PRD-NNNN <title>
|
|
197
190
|
```
|
|
198
191
|
|
|
199
|
-
Use `Read` then `Edit` for the index update
|
|
192
|
+
Use `Read` then `Edit` for the index update.
|
|
200
193
|
|
|
201
194
|
### Step 9: Refresh the hot cache
|
|
202
195
|
|
|
@@ -222,9 +215,8 @@ Suggested next steps:
|
|
|
222
215
|
|
|
223
216
|
| Suggestion | When to use it |
|
|
224
217
|
|------------|----------------|
|
|
225
|
-
| `/
|
|
226
|
-
| `/task-
|
|
227
|
-
| `/req-update <file> <change>` | If a scope change surfaces post-approval — appends an `## Amendment N` block; never rewrites |
|
|
218
|
+
| `/adr-extract <file>` | The default next step — extract Architecturally Significant Requirements and propose ADR candidates |
|
|
219
|
+
| `/task-create --req PRD-NNNN <description>` | Only when the requirement's scope is small enough to skip decisions entirely |
|
|
228
220
|
|
|
229
221
|
Do **not** auto-create downstream artifacts — present them as suggestions only.
|
|
230
222
|
|
|
@@ -234,7 +226,7 @@ Do **not** auto-create downstream artifacts — present them as suggestions only
|
|
|
234
226
|
|
|
235
227
|
1. **Tables not bullets** — every audit summary, gap report, and re-audit checklist uses tables
|
|
236
228
|
2. **One Edit per gap** — keep edits surgical; do not rewrite whole sections to fix a single placeholder cell
|
|
237
|
-
3. **Never alter approved requirements** — refuse to run on a target whose status is `approved`, `retired`, or `superseded`;
|
|
229
|
+
3. **Never alter approved requirements** — refuse to run on a target whose status is `approved`, `retired`, or `superseded`; tell the user changes to an approved requirement are made by editing the file directly, or by creating a new requirement and deprecating the old one with `/prd-deprecate`
|
|
238
230
|
4. **Status flip is the LAST edit** — apply it only after the Step 6 re-audit checklist passes AND the Step 7 stakeholder gate returns yes
|
|
239
231
|
5. **Never fabricate content** — if the user lacks an answer for a required-field gap, leave `status: draft`, report which gaps remain, and stop
|
|
240
232
|
6. **Present tense, full sentences** when filling content
|
|
@@ -245,7 +237,6 @@ Do **not** auto-create downstream artifacts — present them as suggestions only
|
|
|
245
237
|
|
|
246
238
|
1. **Status flip is one-way and final** — only flip to `approved` after every Step 6 checklist item passes AND Step 7 stakeholder confirmation returns yes
|
|
247
239
|
2. **Re-audit MUST run before flipping** — the Step 6 checklist is mandatory; never skip it
|
|
248
|
-
3. **Never
|
|
249
|
-
4. **
|
|
250
|
-
5. **
|
|
251
|
-
6. **No fabrication** — refuse to fill content the user could not supply
|
|
240
|
+
3. **Never auto-create downstream artifacts** — `/adr-extract`, `/task-create`, decisions, and tasks are user-invoked
|
|
241
|
+
4. **Maximum 3 sub-processes at a time** if delegating any sub-step
|
|
242
|
+
5. **No fabrication** — refuse to fill content the user could not supply
|
|
@@ -75,10 +75,10 @@ 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-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.
|
|
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`/`pending-uat` 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).
|
|
82
|
-
3. Consistency check: every active task file (frontmatter `status: todo` or `
|
|
82
|
+
3. Consistency check: every active task file (frontmatter `status: todo`, `in-progress` or `pending-uat`) should have exactly one bullet line in `index.md`, and every bullet in `index.md` should point to a real active task file. If you spot drift (an active task file with no line, a line pointing at a moved/trashed/archived file, or a `done`/`trashed` task still listed), report a one-line warning to the user listing what's off, but do NOT auto-fix — the skill that mutated state without updating the index is the bug.
|
|
83
83
|
|
|
84
84
|
See `wiki/work/tasks/lifecycle.md` for the active status set and frontmatter schema.
|
|
@@ -137,7 +137,7 @@ For each viable approach, present:
|
|
|
137
137
|
### 4d. Next Steps
|
|
138
138
|
|
|
139
139
|
Suggest concrete next steps:
|
|
140
|
-
- If the user wants to proceed: `To create a task: /task-
|
|
140
|
+
- If the user wants to proceed: `To create a task: /task-create <description based on findings>`
|
|
141
141
|
- If more research is needed: Identify specific areas that need deeper investigation
|
|
142
142
|
- If a decision is needed: Frame the decision clearly with the trade-offs
|
|
143
143
|
|
|
@@ -268,13 +268,13 @@ node ~/.claude/bootstrap-prefs.js --get research.autoIngest --project . 2>/dev/n
|
|
|
268
268
|
- A 2–4 bullet summary of the recommendation
|
|
269
269
|
- **If Phase 5b ingested the report**: say so, and name the wiki pages it created or updated — do not also suggest `/wiki-ingest`, it already ran.
|
|
270
270
|
- **Otherwise**: that the report is now a `raw/` ground-truth source: **"Run `/wiki-ingest raw/research/<slug>/index.md` to synthesize this research into the knowledge base."**
|
|
271
|
-
- Any follow-on `/task-
|
|
271
|
+
- Any follow-on `/task-create` or `/adr-create` suggested by the findings
|
|
272
272
|
|
|
273
273
|
**If nothing was persisted** (stored `false`, a per-run `--no-save`/`--no-persist` override, or a declined `ask`), tell the user:
|
|
274
274
|
- That no files were written, and which of the three reasons applies
|
|
275
275
|
- The same 2–4 bullet summary of the recommendation
|
|
276
276
|
- Skip the `/wiki-ingest` suggestion entirely — there is no `raw/` file to ingest, and Phase 5b never ran either
|
|
277
|
-
- Any follow-on `/task-
|
|
277
|
+
- Any follow-on `/task-create` or `/adr-create` suggested by the findings
|
|
278
278
|
|
|
279
279
|
---
|
|
280
280
|
|
|
@@ -18,7 +18,7 @@ This skill is read-mostly: it never upgrades inline placeholders to task files a
|
|
|
18
18
|
|
|
19
19
|
## Step 1: Discover active roadmaps
|
|
20
20
|
|
|
21
|
-
`list_dir` `wiki/work/roadmaps/` for `.md` files **directly** in it
|
|
21
|
+
`list_dir` `wiki/work/roadmaps/` for `.md` files **directly** in it; skip `lifecycle.md`, `index.md`, `README.md`, and ignore any legacy `archive/` directory. Finished roadmaps stay in the directory, so `Read` each file's frontmatter and keep only those with `status: active` — closed (`status: done`) roadmaps are skipped. None found → STOP: `No roadmaps found in wiki/work/roadmaps/. Use /roadmap-create <topic> to draft one.`
|
|
22
22
|
|
|
23
23
|
A single active roadmap is still worth assessing — don't short-circuit to `/roadmap-next`; the status update in Step 6d is useful on its own.
|
|
24
24
|
|
|
@@ -26,31 +26,31 @@ A single active roadmap is still worth assessing — don't short-circuit to `/ro
|
|
|
26
26
|
|
|
27
27
|
For each file, run the **Parse a roadmap** procedure defined in `lib/skills/roadmap-next/SKILL.md` — do not restate it here, follow it as written. In addition to what that procedure captures, also extract from frontmatter: `owner`, `tags`, `linked_requirements`, `linked_decisions`, `created`, `updated`.
|
|
28
28
|
|
|
29
|
-
Also scan the roadmap body for inline typed links referencing decisions (e.g. `rel::[[
|
|
29
|
+
Also scan the roadmap body for inline typed links referencing decisions (e.g. `rel::[[ADR-0003#D2]]`, `implements::[[ADR-0003]]`, or the legacy `DEC-` forms) — a decision can gate a roadmap without being listed in `linked_decisions`. Merge these into the same per-roadmap decision-reference set.
|
|
30
30
|
|
|
31
31
|
Do **not** run the Upgrade-inline-items or Parallelism-analysis procedures from that same file — those materialize task files, which is out of scope here. This step only reads.
|
|
32
32
|
|
|
33
|
-
## Step 3: Auto-
|
|
33
|
+
## Step 3: Auto-close fully-complete roadmaps
|
|
34
34
|
|
|
35
|
-
For any roadmap where `total > 0` and `done == total`: run the **
|
|
35
|
+
For any roadmap where `total > 0` and `done == total`: run the **Close a fully-complete roadmap** procedure defined in `lib/skills/roadmap-next/SKILL.md` — do not restate it here, follow it as written. Record the filename in `closed`. Drop it from the set being ranked — a `done` roadmap has no priority left to weigh.
|
|
36
36
|
|
|
37
|
-
If every discovered roadmap was
|
|
37
|
+
If every discovered roadmap was closed this step, STOP and report: `All roadmaps complete — closed: <list>. Nothing active to assess.`
|
|
38
38
|
|
|
39
39
|
## Step 4: Outstanding decision check
|
|
40
40
|
|
|
41
41
|
Before weighing priority or dependencies, check whether any remaining roadmap is gated on a decision that hasn't been finalized yet — an unresolved decision means the roadmap isn't truly ready to work, regardless of how it otherwise ranks.
|
|
42
42
|
|
|
43
|
-
For every remaining roadmap, take its merged decision-reference set from Step 2 (`linked_decisions` frontmatter + inline `rel::[[DEC-...]]` links). Each reference is a Decision Group file (`DEC-NNNN`) and, ideally, a specific decision block within it (`DEC-NNNN#DM`, e.g. `#D2`). For each unique reference:
|
|
43
|
+
For every remaining roadmap, take its merged decision-reference set from Step 2 (`linked_decisions` frontmatter + inline `rel::[[ADR-...]]` / legacy `rel::[[DEC-...]]` links). Each reference is a Decision Group file (`ADR-NNNN`, or legacy `DEC-NNNN`) and, ideally, a specific decision block within it (`ADR-NNNN#DM` or legacy `DEC-NNNN#DM`, e.g. `#D2`). For each unique reference:
|
|
44
44
|
|
|
45
|
-
1. `find_file` / `Read` the Decision Group file in `wiki/work/decisions/` (
|
|
46
|
-
2. Find the `## DM. <title>` block matching the referenced `#DM`. If the roadmap referenced only `DEC-NNNN` with no `#DM`, treat every `proposed` block in that group as a separate outstanding decision.
|
|
45
|
+
1. `find_file` / `Read` the Decision Group file in `wiki/work/decisions/` (if not found in the directory, fall back to a legacy `archive/` per the ID-RESOLUTION.md legacy-fallback rule). Missing file → note as a broken reference, don't block on it.
|
|
46
|
+
2. Find the `## DM. <title>` block matching the referenced `#DM`. If the roadmap referenced only `ADR-NNNN` (or legacy `DEC-NNNN`) with no `#DM`, treat every `proposed` block in that group as a separate outstanding decision.
|
|
47
47
|
3. Read that block's `Status:` field (`proposed | accepted | superseded`).
|
|
48
|
-
4. If `Status: superseded`, the block is annotated `superseded by DEC-NNNN#DM` — follow that pointer to the current decision's block and re-check its status instead of stopping at the superseded one.
|
|
49
|
-
5. If the resolved status is `proposed` (not yet `accepted`), record it as an **outstanding decision** blocking that roadmap: `{roadmap,
|
|
48
|
+
4. If `Status: superseded`, the block is annotated `superseded by ADR-NNNN#DM` (or legacy `superseded by DEC-NNNN#DM`) — follow that pointer to the current decision's block and re-check its status instead of stopping at the superseded one.
|
|
49
|
+
5. If the resolved status is `proposed` (not yet `accepted`), record it as an **outstanding decision** blocking that roadmap: `{roadmap, ADR-NNNN#DM, title, file path}` (use the resolved file's own `id:`).
|
|
50
50
|
|
|
51
51
|
Deduplicate by decision so a shared unresolved decision blocking multiple roadmaps is only reported once per roadmap it actually gates.
|
|
52
52
|
|
|
53
|
-
This step is read-only — never run `/
|
|
53
|
+
This step is read-only — never run `/adr-finalize` yourself; surface the blockers so the user can resolve them (or explicitly choose to proceed anyway).
|
|
54
54
|
|
|
55
55
|
## Step 5: Cross-roadmap dependency analysis
|
|
56
56
|
|
|
@@ -78,10 +78,10 @@ An outstanding decision (Step 4) does **not** change a roadmap's rank — it cha
|
|
|
78
78
|
|
|
79
79
|
Print, in this order:
|
|
80
80
|
|
|
81
|
-
### 6a.
|
|
81
|
+
### 6a. Closed this run (omit if `closed` is empty)
|
|
82
82
|
|
|
83
83
|
```
|
|
84
|
-
|
|
84
|
+
Moved to Closed in wiki/work/roadmaps/index.md (fully complete):
|
|
85
85
|
• <filename> — done
|
|
86
86
|
```
|
|
87
87
|
|
|
@@ -90,11 +90,11 @@ Archived to wiki/work/roadmaps/archive/ (fully complete):
|
|
|
90
90
|
```
|
|
91
91
|
## Warning: Outstanding Decisions
|
|
92
92
|
|
|
93
|
-
These roadmaps are gated on decisions still `proposed` — resolve via `/
|
|
93
|
+
These roadmaps are gated on decisions still `proposed` — resolve via `/adr-finalize <file>#<DM>` before treating the roadmap as ready to work:
|
|
94
94
|
|
|
95
95
|
| Decision | Status | Blocks Roadmap | Title |
|
|
96
96
|
|----------|--------|-----------------|-------|
|
|
97
|
-
|
|
|
97
|
+
| ADR-0003#D2 | proposed | ROADMAP-009 — <title> | <decision title> |
|
|
98
98
|
```
|
|
99
99
|
|
|
100
100
|
### 6c. Prioritized Roadmaps
|
|
@@ -108,7 +108,7 @@ These roadmaps are gated on decisions still `proposed` — resolve via `/decisio
|
|
|
108
108
|
| 2 | ROADMAP-MMM — <title> | M/N | <one sentence> | ROADMAP-NNNN (Phase X blocks it) |
|
|
109
109
|
```
|
|
110
110
|
|
|
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
|
|
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 ADR-NNNN#DM` appended here even if it has no roadmap-to-roadmap dependency.
|
|
112
112
|
|
|
113
113
|
### 6d. Status update per roadmap
|
|
114
114
|
|
|
@@ -124,10 +124,10 @@ One block per roadmap, in ranked order:
|
|
|
124
124
|
|
|
125
125
|
Base `Status` on progress momentum and whether items remain `inline` (unmaterialized) vs `task-link` — call out roadmaps that are still mostly inline placeholders, since `/roadmap-next` needs to run on them before real progress can be tracked.
|
|
126
126
|
|
|
127
|
-
If the roadmap has an outstanding decision from Step 4, set `Status: blocked — awaiting decision(s):
|
|
127
|
+
If the roadmap has an outstanding decision from Step 4, set `Status: blocked — awaiting decision(s): ADR-NNNN#DM` and replace `Next` with the decision-resolution action instead of `/roadmap-next`:
|
|
128
128
|
|
|
129
129
|
```
|
|
130
|
-
- Next: `/
|
|
130
|
+
- Next: `/adr-finalize wiki/work/decisions/ADR-NNNN-slug.md#DM`
|
|
131
131
|
```
|
|
132
132
|
|
|
133
133
|
### 6e. Dependency cycles (omit if none found)
|
|
@@ -143,7 +143,7 @@ These roadmaps block each other — resolve the cycle manually before treating e
|
|
|
143
143
|
|
|
144
144
|
## Constraints
|
|
145
145
|
|
|
146
|
-
- Read-only except the Step 3 auto-
|
|
147
|
-
- Permitted tools: `list_dir`, `find_file`, `Read`, `Edit`, `
|
|
146
|
+
- Read-only except the Step 3 auto-close procedure (status flip + index/log updates) — never flip checkboxes, never upgrade inline items, never create task files, never finalize decisions. That is `/roadmap-next`'s and `/adr-finalize`'s job once the user acts on this report.
|
|
147
|
+
- Permitted tools: `list_dir`, `find_file`, `Read`, `Edit`, `AskUserQuestion` (only if genuinely needed to disambiguate — this skill should normally run to completion without prompting).
|
|
148
148
|
- Never bash reads (`cat`/`find`/`grep`/`sed`/`ls`).
|
|
149
149
|
- Keep the report terse — no preamble, no closing summary beyond the tables above.
|
|
@@ -19,7 +19,7 @@ The hard boundary:
|
|
|
19
19
|
|
|
20
20
|
> *A roadmap shows order. A task contains implementation steps. Never smuggle step-level detail into a roadmap item.*
|
|
21
21
|
|
|
22
|
-
If a checkbox starts growing sub-bullets like "run `pnpm install`" or "edit `src/foo.ts`", that content belongs in a real task file — created via `/task-
|
|
22
|
+
If a checkbox starts growing sub-bullets like "run `pnpm install`" or "edit `src/foo.ts`", that content belongs in a real task file — created via `/task-create` (or `/task-create --roadmap ROADMAP-NNNN` to auto-link). Redirect the user when this happens.
|
|
23
23
|
|
|
24
24
|
This skill drives a **short** Socratic Q&A session via `AskUserQuestion`. Roadmap creation is execution planning, not product strategy — keep questions focused and tight. Aim for one or two batched `AskUserQuestion` rounds plus per-phase follow-ups, not a full PRD-style interrogation.
|
|
25
25
|
|
|
@@ -33,7 +33,7 @@ This skill drives a **short** Socratic Q&A session via `AskUserQuestion`. Roadma
|
|
|
33
33
|
|
|
34
34
|
Write a roadmap when work spans multiple discrete units, ordering matters, and you want at-a-glance visibility of what's next.
|
|
35
35
|
|
|
36
|
-
If the topic is a single task with several steps, **stop and tell the user** — the task file's own `## Steps` checklist already serves that purpose. Suggest `/task-
|
|
36
|
+
If the topic is a single task with several steps, **stop and tell the user** — the task file's own `## Steps` checklist already serves that purpose. Suggest `/task-create` instead.
|
|
37
37
|
|
|
38
38
|
---
|
|
39
39
|
|
|
@@ -57,10 +57,8 @@ If the topic is a single task with several steps, **stop and tell the user** —
|
|
|
57
57
|
|
|
58
58
|
Roadmaps live at `wiki/work/roadmaps/ROADMAP-NNNN-slug.md`. Numbers are 4-digit zero-padded.
|
|
59
59
|
|
|
60
|
-
1.
|
|
61
|
-
2. **
|
|
62
|
-
3. Take `max + 1`, zero-pad the result to 4 digits. In a brand-new project the first roadmap is `ROADMAP-0001`; in this repo, continue from the current max (do not restart at 1).
|
|
63
|
-
4. **Derive the file slug** — names the **initiative**. Lowercase, dash-separated, ≤ 60 chars:
|
|
60
|
+
1. Allocate the next ID per `~/.claude/skills/_shared/SKILL-BOILERPLATE.md` § Number allocation (family: `wiki/work/roadmaps/`, prefix: `ROADMAP-`, also scan `index.md` for reserved IDs).
|
|
61
|
+
2. **Derive the file slug** — names the **initiative**. Lowercase, dash-separated, ≤ 60 chars:
|
|
64
62
|
- "Ship the billing portal" → `ROADMAP-0001-ship-billing-portal.md`
|
|
65
63
|
- "Migrate to Postgres 17" → `ROADMAP-0004-migrate-postgres-17.md`
|
|
66
64
|
|
|
@@ -75,7 +73,7 @@ Walk through the elicitations below. Batch related questions into a single `AskU
|
|
|
75
73
|
| 1 | **Goal** | 1-2 sentences describing the destination — what state will the system be in when every box is checked? | "Make X better"; vague aspiration with no observable end state |
|
|
76
74
|
| 2 | **Phases (2-5)** | Each phase is a short name capturing an execution stage. Order matters | One mega-phase ("Build it"); >5 phases (suggests over-planning) |
|
|
77
75
|
| 3 | **Owner** | One named person or role accountable for execution | "The team", "everyone", missing owner |
|
|
78
|
-
| 4 | **Linked PRD / ADRs (may be empty)** | Existing `PRD-
|
|
76
|
+
| 4 | **Linked PRD / ADRs (may be empty)** | Existing `PRD-NNNN` or `ADR-NNNN#DM` references (legacy `REQ-NNNN` / `DEC-NNNN#DM` also accepted), or `—` if standalone | Inventing references that don't exist |
|
|
79
77
|
|
|
80
78
|
**Suggested first batch (one `AskUserQuestion` call covering all four)**:
|
|
81
79
|
|
|
@@ -89,18 +87,18 @@ Then **per-phase**, in a single follow-up `AskUserQuestion` round (one question
|
|
|
89
87
|
|
|
90
88
|
| # | Elicitation | Quality bar |
|
|
91
89
|
|---|-------------|-------------|
|
|
92
|
-
| 5 | **Phase N items** | For each phase, the user names (a) any existing tasks (`TASK-NNNN` or slug fragments) that belong in this phase, and (b) any inline placeholder items. Items may be empty if the user wants to fill in later by editing the roadmap file directly or via `/task-
|
|
90
|
+
| 5 | **Phase N items** | For each phase, the user names (a) any existing tasks (`TASK-NNNN` or slug fragments) that belong in this phase, and (b) any inline placeholder items. Items may be empty if the user wants to fill in later by editing the roadmap file directly or via `/task-create --roadmap ROADMAP-NNNN` — but **at least one phase must contain at least one item** (a roadmap with zero items is not a roadmap) |
|
|
93
91
|
|
|
94
92
|
When the user supplies a task reference:
|
|
95
93
|
|
|
96
94
|
- Look it up in `wiki/work/tasks/` via `mcp__serena__find_file` to confirm it exists. The link must read `[[TASK-NNNN: <task title>]]`.
|
|
97
95
|
- If the user supplies a task reference that does **not** exist, treat it as an inline placeholder (do not fabricate a link). Note in the per-phase clarification that a task file must be created before this item can be worked on — it will be created automatically when `/roadmap-next` is run.
|
|
98
96
|
|
|
99
|
-
**Inline placeholders**: items without a corresponding task file are written as `- [ ] <description>`. They are valid at creation time because tasks may not exist yet. However, **inline items cannot be worked on** — `/roadmap-next` will automatically invoke `/task-
|
|
97
|
+
**Inline placeholders**: items without a corresponding task file are written as `- [ ] <description>`. They are valid at creation time because tasks may not exist yet. However, **inline items cannot be worked on** — `/roadmap-next` will automatically invoke `/task-create` to create a task file for each inline item before surfacing it. The roadmap item is then upgraded to a task-link in place.
|
|
100
98
|
|
|
101
99
|
**Redirection rule**: if the user starts spelling out implementation detail under an item (file paths, function names, sub-steps), respond:
|
|
102
100
|
|
|
103
|
-
> That sounds like task content, not a roadmap item. Roadmaps show *ordering*. The *how* belongs in a task file — file one with `/task-
|
|
101
|
+
> That sounds like task content, not a roadmap item. Roadmaps show *ordering*. The *how* belongs in a task file — file one with `/task-create --roadmap ROADMAP-NNNN <description>` and the roadmap will auto-link to it.
|
|
104
102
|
|
|
105
103
|
Then re-ask for a single checkbox-sized item.
|
|
106
104
|
|
|
@@ -121,13 +119,7 @@ If the user requests edits, loop back to the relevant Step 3 elicitation, re-ask
|
|
|
121
119
|
|
|
122
120
|
### Step 5: Re-verify the next available number — IMMEDIATELY before writing
|
|
123
121
|
|
|
124
|
-
The number determined in Step 2 may now be stale (other roadmaps created mid-session, the
|
|
125
|
-
|
|
126
|
-
- `mcp__serena__list_dir` on `wiki/work/roadmaps/` **and** `wiki/work/roadmaps/archive/` (skip either that doesn't exist)
|
|
127
|
-
- `mcp__serena__search_for_pattern` against `wiki/work/roadmaps/index.md` for `ROADMAP-\d{3}` entries
|
|
128
|
-
- Collect the numeric value from every `ROADMAP-<digits>-` prefix across both directories, regardless of digit count (existing files are 3-digit; new ones are 4-digit) — ignore leading zeros when comparing. Take `max + 1`, zero-pad the result to 4 digits.
|
|
129
|
-
- If the number you planned to use in Step 4 has been taken, silently bump to the new next-available number and use it. Do not re-prompt the user.
|
|
130
|
-
- **Never call `Write` before completing this re-scan.**
|
|
122
|
+
The number determined in Step 2 may now be stale (other roadmaps created mid-session, the index may list reservations not yet on disk). Repeat § Number allocation step 6 (same family and prefix as Step 2); never call `Write` before completing it. If the planned number has been taken, silently bump to the next free number and do not re-prompt the user.
|
|
131
123
|
|
|
132
124
|
### Step 6: Write the roadmap file
|
|
133
125
|
|
|
@@ -163,18 +155,16 @@ Loop back to Step 3 instead — do not silently invent content.
|
|
|
163
155
|
|
|
164
156
|
### Step 7: Update the roadmap index
|
|
165
157
|
|
|
166
|
-
Edit `wiki/work/roadmaps/index.md` to add a new bullet line
|
|
158
|
+
Edit `wiki/work/roadmaps/index.md` to add a new bullet line under `## Active` (a flat list, no table; finished roadmaps live under `## Closed`).
|
|
167
159
|
|
|
168
|
-
1. `Read` `wiki/work/roadmaps/index.md` to locate the
|
|
169
|
-
2. If the placeholder line (`_(none yet)_` or a "no roadmaps yet" note) exists
|
|
160
|
+
1. `Read` `wiki/work/roadmaps/index.md` to locate the `## Active` list.
|
|
161
|
+
2. If the placeholder line (`_(none yet)_` or a "no roadmaps yet" note) exists under `## Active`, **replace** it with the new line. Otherwise **append** the new line under `## Active` in numerical order. Never add it under `## Closed`.
|
|
170
162
|
3. Use the entry format documented at the top of `index.md`:
|
|
171
163
|
|
|
172
164
|
`- [ROADMAP-NNNN — <title>](ROADMAP-NNNN-slug.md) — <one-line summary> · 0/<total> items checked`
|
|
173
165
|
|
|
174
166
|
where `<title>` is the roadmap's H1 sub-title (without any `Roadmap NNN:` prefix), `<one-line summary>` is a short description of the goal, and `<total>` is the count of `- [ ]` checkboxes you just wrote across all phases.
|
|
175
167
|
|
|
176
|
-
Use `Edit` (not `sed`, `awk`, `echo >>`, or any shell redirection). See `wiki/guides/mcp-tools.md`.
|
|
177
|
-
|
|
178
168
|
### Step 8: Refresh the hot cache
|
|
179
169
|
|
|
180
170
|
The new roadmap is durable, cross-session-relevant wiki state. Run the **Hot Cache Refresh** procedure — defined in `/wiki-ingest` Step 8 (`lib/skills/wiki-ingest/SKILL.md`) — to regenerate `wiki/hot.md` in full, surfacing this roadmap under Recent Changes and its first wave under Active Threads. Do not restate the procedure here; follow it as written.
|
|
@@ -190,12 +180,12 @@ Print a tabular summary:
|
|
|
190
180
|
| Phases | N |
|
|
191
181
|
| Total items | M (task-link: X, inline: Y) |
|
|
192
182
|
| Owner | <name> |
|
|
193
|
-
| Linked PRD | PRD-
|
|
183
|
+
| Linked PRD | PRD-NNNN or `—` |
|
|
194
184
|
| Linked ADRs | list or `—` |
|
|
195
185
|
| Index updated | yes (1 row added) |
|
|
196
|
-
| Suggested next steps | `/roadmap-next wiki/work/roadmaps/ROADMAP-NNNN-slug.md` — surfaces the first item and creates task files for any inline placeholders • `/task-
|
|
186
|
+
| Suggested next steps | `/roadmap-next wiki/work/roadmaps/ROADMAP-NNNN-slug.md` — surfaces the first item and creates task files for any inline placeholders • `/task-create --roadmap ROADMAP-NNNN <description>` — file a new task auto-linked to this roadmap |
|
|
197
187
|
|
|
198
|
-
If any phase was left empty by design (user plans to fill it in later by editing the roadmap file directly or via `/task-
|
|
188
|
+
If any phase was left empty by design (user plans to fill it in later by editing the roadmap file directly or via `/task-create --roadmap ROADMAP-NNNN`), note it in a separate **Gaps** section so the user can address it before execution begins.
|
|
199
189
|
|
|
200
190
|
If the roadmap contains any inline placeholder items (items without a task-link), include a **Placeholders** section listing them:
|
|
201
191
|
|
|
@@ -212,7 +202,7 @@ This is informational only — no action required now.
|
|
|
212
202
|
1. **Tables, not bullets, for every preview and summary in the conversation.** The roadmap file itself uses checklists (that's its format), but every Q&A preview and Step 8 report uses tables.
|
|
213
203
|
2. **Phase names are short and execution-flavored.** "Foundation", "API", "Tests", "Release" — not "Phase where we figure out the database stuff".
|
|
214
204
|
3. **Items are single checkbox-sized.** No sub-bullets, no indented steps, no embedded code blocks. If an item needs detail, it's a task — file one. Items without a task file are written as inline placeholders (`- [ ] <description>`) and are valid at creation time, but will be converted to task-links automatically by `/roadmap-next` before they can be worked on.
|
|
215
|
-
4. **Task-link items must use `[[TASK-NNNN: <title>]]` format.** The `TASK-NNNN:` prefix is required so the auto-checkoff machinery can detect references. Path-based markdown links break when files move to `archive/`; wiki-style ID links never do.
|
|
205
|
+
4. **Task-link items must use `[[TASK-NNNN: <title>]]` format.** The `TASK-NNNN:` prefix is required so the auto-checkoff machinery can detect references. Path-based markdown links break when task files move to `archive/`; wiki-style ID links never do.
|
|
216
206
|
5. **At least one phase must contain at least one item.** An empty roadmap is a hard fail — loop back to Step 3 #5.
|
|
217
207
|
6. **Never invent task references.** If the user says "TASK-42" and no `042-*.md` file exists, render it as an inline placeholder, not a `[[TASK-NNNN: ...]]` wiki link.
|
|
218
208
|
|
|
@@ -222,7 +212,7 @@ This is informational only — no action required now.
|
|
|
222
212
|
|
|
223
213
|
1. **Refuse to write the file if any required field is empty or fails its quality bar** (Goal, Owner, ≥1 phase with ≥1 item). Loop back to Step 3 — do not silently fill gaps with invented content.
|
|
224
214
|
2. **Never invent task links.** Every `[[TASK-NNNN: ...]]` wiki link must correspond to a real file under `wiki/work/tasks/`. Verify with `mcp__serena__find_file` before rendering.
|
|
225
|
-
3.
|
|
226
|
-
4. **Never auto-create downstream artifacts.** This skill creates exactly one roadmap file (plus the index row edit). Do **not** create tasks, PRDs, or ADRs as a side effect — the user can file tasks afterward via `/task-
|
|
215
|
+
3. Edit only — see `~/.claude/skills/_shared/SKILL-BOILERPLATE.md` § Edit hygiene.
|
|
216
|
+
4. **Never auto-create downstream artifacts.** This skill creates exactly one roadmap file (plus the index row edit). Do **not** create tasks, PRDs, or ADRs as a side effect — the user can file tasks afterward via `/task-create --roadmap ROADMAP-NNNN`.
|
|
227
217
|
5. **Redirect step-level detail to task territory** — if the user starts specifying *how* under an item, restate the question as "what's the single checkable unit?" and re-elicit.
|
|
228
|
-
6. **Status starts as `active` and stays there.** This skill never writes `done`. The flip from `active` → `done` is a manual decision the human makes when every box is `[x]`. After flipping, the file
|
|
218
|
+
6. **Status starts as `active` and stays there.** This skill never writes `done`. The flip from `active` → `done` is a manual decision the human makes when every box is `[x]`. After flipping, the file stays in place and its index row moves from `## Active` to `## Closed` — `/roadmap-next` and `/roadmap-assess` do this automatically when every box is checked.
|