@codewizard-dt/bootstrap 2.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (186) hide show
  1. package/.github/workflows/build.yml +88 -0
  2. package/.github/workflows/security.yml +24 -0
  3. package/.gitleaks.toml +15 -0
  4. package/README.md +472 -0
  5. package/bin/cli.js +47 -0
  6. package/lib/README.md +27 -0
  7. package/lib/hooks/README.md +316 -0
  8. package/lib/hooks/env-file-guard.js +45 -0
  9. package/lib/hooks/git-protected-ops-block.js +77 -0
  10. package/lib/hooks/lib/serena-languages.js +158 -0
  11. package/lib/hooks/lib/serena.js +787 -0
  12. package/lib/hooks/mv-absolute-path-block.js +53 -0
  13. package/lib/hooks/serena-bash-grep-block.js +501 -0
  14. package/lib/hooks/serena-edit-guard.js +74 -0
  15. package/lib/hooks/serena-first-glob-guard.js +94 -0
  16. package/lib/hooks/serena-first-guard.js +74 -0
  17. package/lib/hooks/serena-first-read-guard.js +167 -0
  18. package/lib/hooks/serena-pre-delegation.js +117 -0
  19. package/lib/hooks/serena-session-reset.js +45 -0
  20. package/lib/hooks/serena-usage-tracker.js +186 -0
  21. package/lib/hooks/serena-write-guard.js +58 -0
  22. package/lib/prompts/README.md +16 -0
  23. package/lib/prompts/migrate-wiki.md +111 -0
  24. package/lib/prompts/setup-deployment.md +322 -0
  25. package/lib/prompts/setup-design-system.md +162 -0
  26. package/lib/prompts/setup-strict-typechecks.md +139 -0
  27. package/lib/scripts/README.md +49 -0
  28. package/lib/scripts/bootstrap-serena.sh +145 -0
  29. package/lib/scripts/build-mcp-guide.sh +108 -0
  30. package/lib/scripts/install-global.sh +78 -0
  31. package/lib/scripts/install-mcps.sh +131 -0
  32. package/lib/scripts/lib.sh +154 -0
  33. package/lib/scripts/merge-gitignore.sh +65 -0
  34. package/lib/scripts/migrate-project.sh +273 -0
  35. package/lib/scripts/setup-deployment.sh +104 -0
  36. package/lib/scripts/setup-project.sh +55 -0
  37. package/lib/scripts/setup-runner.sh +99 -0
  38. package/lib/scripts/setup-strict-typechecks.sh +29 -0
  39. package/lib/scripts/startup.sh +42 -0
  40. package/lib/scripts/sync-wiki-scaffold.sh +104 -0
  41. package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
  42. package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
  43. package/lib/scripts/templates/gitignore +136 -0
  44. package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
  45. package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
  46. package/lib/scripts/templates/guides/stubs/context7.md +26 -0
  47. package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
  48. package/lib/scripts/templates/guides/stubs/serena.md +219 -0
  49. package/lib/scripts/templates/wiki/conventions.md +100 -0
  50. package/lib/scripts/templates/wiki/dashboard.html +1733 -0
  51. package/lib/scripts/templates/wiki/hot.md +21 -0
  52. package/lib/scripts/templates/wiki/index.md +46 -0
  53. package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
  54. package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
  55. package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
  56. package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
  57. package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
  58. package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
  59. package/lib/scripts/templates/wiki/log.md +14 -0
  60. package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
  61. package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
  62. package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
  63. package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
  64. package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
  65. package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
  66. package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
  67. package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
  68. package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
  69. package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
  70. package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
  71. package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
  72. package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
  73. package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
  74. package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
  75. package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
  76. package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
  77. package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
  78. package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
  79. package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
  80. package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
  81. package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
  82. package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
  83. package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
  84. package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
  85. package/lib/scripts/update-project.sh +75 -0
  86. package/lib/scripts/wiki-dashboard-server.js +146 -0
  87. package/lib/skills/README.md +146 -0
  88. package/lib/skills/anti-slop/SKILL.md +183 -0
  89. package/lib/skills/bug-close/SKILL.md +136 -0
  90. package/lib/skills/bug-file/SKILL.md +114 -0
  91. package/lib/skills/bug-triage/SKILL.md +140 -0
  92. package/lib/skills/company-align/SKILL.md +203 -0
  93. package/lib/skills/debug-logs/SKILL.md +129 -0
  94. package/lib/skills/decision-create/SKILL.md +220 -0
  95. package/lib/skills/decision-finalize/SKILL.md +181 -0
  96. package/lib/skills/decision-next/SKILL.md +129 -0
  97. package/lib/skills/decision-walkthrough/SKILL.md +169 -0
  98. package/lib/skills/demo/SKILL.md +183 -0
  99. package/lib/skills/elevator-pitch/SKILL.md +125 -0
  100. package/lib/skills/eval-create/SKILL.md +344 -0
  101. package/lib/skills/eval-gap/SKILL.md +150 -0
  102. package/lib/skills/eval-run/SKILL.md +214 -0
  103. package/lib/skills/extract-feature/SKILL.md +344 -0
  104. package/lib/skills/flashcard/SKILL.md +513 -0
  105. package/lib/skills/frontend-taste/SKILL.md +184 -0
  106. package/lib/skills/gap-assess/SKILL.md +97 -0
  107. package/lib/skills/git-commit/SKILL.md +164 -0
  108. package/lib/skills/lint/SKILL.md +99 -0
  109. package/lib/skills/marp-slideshow/SKILL.md +212 -0
  110. package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
  111. package/lib/skills/now/SKILL.md +36 -0
  112. package/lib/skills/port-feature/SKILL.md +315 -0
  113. package/lib/skills/power-mode/SKILL.md +184 -0
  114. package/lib/skills/primer/SKILL.md +84 -0
  115. package/lib/skills/project-readme/SKILL.md +166 -0
  116. package/lib/skills/req-compile/SKILL.md +131 -0
  117. package/lib/skills/req-create/SKILL.md +124 -0
  118. package/lib/skills/req-extract-decisions/SKILL.md +241 -0
  119. package/lib/skills/req-finalize/SKILL.md +251 -0
  120. package/lib/skills/req-retire/SKILL.md +185 -0
  121. package/lib/skills/req-update/SKILL.md +265 -0
  122. package/lib/skills/research/SKILL.md +250 -0
  123. package/lib/skills/research-company/SKILL.md +345 -0
  124. package/lib/skills/roadmap-add/SKILL.md +238 -0
  125. package/lib/skills/roadmap-create/SKILL.md +223 -0
  126. package/lib/skills/roadmap-next/SKILL.md +132 -0
  127. package/lib/skills/security-audit/SKILL.md +246 -0
  128. package/lib/skills/serena-config/SKILL.md +92 -0
  129. package/lib/skills/simplify/SKILL.md +227 -0
  130. package/lib/skills/tackle/SKILL.md +156 -0
  131. package/lib/skills/task-add/SKILL.md +208 -0
  132. package/lib/skills/task-audit/SKILL.md +294 -0
  133. package/lib/skills/task-trash/SKILL.md +115 -0
  134. package/lib/skills/task-update/SKILL.md +136 -0
  135. package/lib/skills/uat-auto/SKILL.md +69 -0
  136. package/lib/skills/uat-auto-plus/SKILL.md +115 -0
  137. package/lib/skills/uat-generate/SKILL.md +289 -0
  138. package/lib/skills/uat-skip/SKILL.md +169 -0
  139. package/lib/skills/uat-walk/SKILL.md +164 -0
  140. package/lib/skills/uat-walk/UAT-CORE.md +140 -0
  141. package/lib/skills/update-docs/SKILL.md +75 -0
  142. package/lib/skills/wiki-archive/SKILL.md +96 -0
  143. package/lib/skills/wiki-ingest/SKILL.md +139 -0
  144. package/lib/skills/wiki-lint/SKILL.md +131 -0
  145. package/lib/skills/wiki-query/SKILL.md +71 -0
  146. package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
  147. package/lib/skills/wiki-tidy/SKILL.md +107 -0
  148. package/package.json +32 -0
  149. package/raw/.gitkeep +0 -0
  150. package/raw/design-principles.md +65 -0
  151. package/raw/guides/command-anti-patterns.md +79 -0
  152. package/raw/guides/deployment-strategy.md +448 -0
  153. package/raw/guides/evals-framework.md +452 -0
  154. package/raw/guides/mcp-tools.md +335 -0
  155. package/raw/guides/task-spec.md +79 -0
  156. package/raw/guides/type-checking-templates/README.md +112 -0
  157. package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
  158. package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
  159. package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
  160. package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
  161. package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
  162. package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
  163. package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
  164. package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
  165. package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
  166. package/raw/harness-notes.md +20 -0
  167. package/raw/house-style/components/Badge.tsx +16 -0
  168. package/raw/house-style/components/Button.tsx +32 -0
  169. package/raw/house-style/components/Card.tsx +26 -0
  170. package/raw/house-style/components/Chip.tsx +57 -0
  171. package/raw/house-style/components/IconButton.tsx +67 -0
  172. package/raw/house-style/components/Modal.tsx +18 -0
  173. package/raw/house-style/components/Stepper.tsx +141 -0
  174. package/raw/house-style/components/icons.tsx +128 -0
  175. package/raw/house-style/preview/src/index.css +46 -0
  176. package/raw/house-style/tokens/tailwind.preset.ts +49 -0
  177. package/raw/house-style/tokens/tokens.json +62 -0
  178. package/raw/llm-wiki-2.md +162 -0
  179. package/raw/llm-wiki.md +75 -0
  180. package/raw/research/dark-mode-theme/index.md +85 -0
  181. package/raw/research/dark-mode-theme/sources.md +49 -0
  182. package/raw/research/serena-mcp-disconnect/index.md +81 -0
  183. package/raw/research/serena-mcp-disconnect/sources.md +87 -0
  184. package/raw/research/wiki-tooling-improvements/index.md +126 -0
  185. package/raw/research/wiki-tooling-improvements/sources.md +73 -0
  186. package/raw/software-factory-case-study.pdf +0 -0
@@ -0,0 +1,238 @@
1
+ ---
2
+ name: roadmap-add
3
+ description: Append a new item (task link or inline) to an existing roadmap in wiki/work/roadmaps/, optionally under a named phase
4
+ category: planning
5
+ model: claude-haiku-4-5-20251001
6
+ argument-hint: <ROADMAP-NNN> [--phase "<name>"] [--task NNN | <task path> | <inline text>]
7
+ disable-model-invocation: false
8
+ user-invocable: true
9
+ ---
10
+ **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
11
+
12
+ $ARGUMENTS
13
+
14
+ ---
15
+
16
+ # Add to Roadmap
17
+
18
+ Append a new `- [ ]` checklist item to an existing roadmap file in `wiki/work/roadmaps/`. The item is either a **task-link item** (when a task file is resolvable) or an **inline item** (free-form text). The new item is placed under a named phase, or — by default — at the end of the last existing phase. The roadmap's `Last updated` field and the index `Progress` denominator in `wiki/work/roadmaps/index.md` are kept in sync.
19
+
20
+ ---
21
+
22
+ ## Inline Placeholders
23
+
24
+ Roadmap items fall into two categories:
25
+ - **Task-link items** — `- [ ] [[TASK-NNN: <title>]]` — backed by a real task file; can be worked on immediately with `/tackle`.
26
+ - **Inline placeholder items** — `- [ ] <free-form description>` — no task file exists yet; valid to add, but **cannot be tackled** until `/roadmap-next` automatically creates a task file for them.
27
+
28
+ When adding an inline item, include a note in the Step 8 report reminding the user that this placeholder will be upgraded to a task-link automatically when `/roadmap-next` runs.
29
+
30
+ ---
31
+
32
+ ## Step 1: Parse `$ARGUMENTS`
33
+
34
+ The first whitespace-separated token is the roadmap reference. Everything after it is the item spec, possibly prefixed with flags.
35
+
36
+ Detect, in order:
37
+
38
+ | Token / pattern | Meaning |
39
+ |-----------------|---------|
40
+ | `ROADMAP-NNN`, `NNN`, or `wiki/work/roadmaps/NNN-slug.md` (first token) | Roadmap reference — resolve in Step 2 |
41
+ | `--phase "<name>"` (anywhere after the first token) | Target phase name — strip from remaining args |
42
+ | `--task NNN` (anywhere after the first token) | Task-number lookup — strip from remaining args |
43
+ | `wiki/work/tasks/NNN-slug.md` or `wiki/work/tasks/archive/NNN-slug.md` | Task-path lookup — entire remaining args **is** the path |
44
+ | anything else | Inline item text (free-form) |
45
+
46
+ Mirror the flag-detection style used by `lib/skills/task-add/SKILL.md` (which detects `--adr` and `--prd` in similar fashion). Treat each flag as a removable token; what remains after stripping flags is either the inline text or fallback text accompanying `--task NNN`.
47
+
48
+ If `$ARGUMENTS` is empty, or the roadmap reference is missing, **stop** and ask the user via `AskUserQuestion` to supply both the roadmap ID and the item to add.
49
+
50
+ ---
51
+
52
+ ## Step 2: Resolve the roadmap file
53
+
54
+ Use Serena to locate the target roadmap.
55
+
56
+ | Input form | Resolution |
57
+ |------------|------------|
58
+ | Full path (e.g. `wiki/work/roadmaps/003-billing-overhaul.md`) | Use as-is. Verify the file exists with `mcp__serena__find_file` |
59
+ | `ROADMAP-NNN` (e.g. `ROADMAP-003`) | Strip prefix, then resolve as `NNN` below |
60
+ | `NNN` (e.g. `003` or `3`) | Pad to 3 digits. Use `mcp__serena__list_dir` on `wiki/work/roadmaps/` and pick the file whose name starts with `NNN-` |
61
+
62
+ If no file matches, **stop** and report the available roadmaps from `mcp__serena__list_dir` so the user can correct the reference.
63
+
64
+ If multiple files match a bare `NNN` (should not happen — numbers are unique — but defensive), use `AskUserQuestion` to disambiguate.
65
+
66
+ ---
67
+
68
+ ## Step 3: If the arg is a task reference, resolve the task title
69
+
70
+ Only perform this step when the remaining args after flag-stripping are either:
71
+ - A task path (`wiki/work/tasks/NNN-slug.md` or `wiki/work/tasks/archive/NNN-slug.md`), or
72
+ - `--task NNN` (then look up the task file).
73
+
74
+ Otherwise skip to Step 4 with the remaining text as the inline-item body.
75
+
76
+ ### 3a. Locate the task file
77
+
78
+ | Input | Action |
79
+ |-------|--------|
80
+ | Task path | Verify with `mcp__serena__find_file`. If missing, see 3c |
81
+ | `--task NNN` | Pad `NNN` to 3 digits. Search `wiki/work/tasks/` first, then `wiki/work/tasks/archive/`. If neither has a match, see 3c |
82
+
83
+ ### 3b. Extract the H1 title
84
+
85
+ `Read` the task file. The first non-empty line should look like:
86
+
87
+ ```markdown
88
+ # 014: User Table Schema
89
+ ```
90
+
91
+ Strip the leading `# NNN: ` prefix; the remainder is the **task title** (e.g. `User Table Schema`).
92
+
93
+ Build the item line using the stable wiki-link format:
94
+
95
+ ```markdown
96
+ - [ ] [[TASK-NNN: <task title>]]
97
+ ```
98
+
99
+ ### 3c. Task file not found
100
+
101
+ If the task path or `--task NNN` lookup fails, use `AskUserQuestion` to ask:
102
+
103
+ > Task file not found at `<path/or/NNN>`. Append as an inline item using the remaining text, or cancel?
104
+
105
+ If the user picks **inline**, use the original free-form remainder text (excluding flags) as the inline body. If the user picks **cancel**, stop with no edits.
106
+
107
+ ---
108
+
109
+ ## Step 4: Determine the target phase
110
+
111
+ `Read` the resolved roadmap file.
112
+
113
+ Scan for `## Phase N: <name>` headers in order. Build a list of `(phase_number, phase_name, line_range)` triples.
114
+
115
+ | Condition | Target phase |
116
+ |-----------|--------------|
117
+ | `--phase "<name>"` was given and a phase with that exact name exists | Use that phase |
118
+ | `--phase "<name>"` was given and no matching phase exists | Create a new phase at the end of the file (see Step 5b) |
119
+ | `--phase` was **not** given and at least one phase exists | Use the **last** phase in file order |
120
+ | `--phase` was **not** given and **no** phases exist | Create `## Phase 1: Backlog` (see Step 5b) |
121
+
122
+ Phase-name matching is case-sensitive and exact on the text after `## Phase N: `. Trim surrounding whitespace before comparing.
123
+
124
+ ---
125
+
126
+ ## Step 5: Compose and insert the new item
127
+
128
+ The new item line is exactly one of:
129
+
130
+ ```markdown
131
+ - [ ] [[TASK-NNN: <title>]]
132
+ ```
133
+
134
+ or
135
+
136
+ ```markdown
137
+ - [ ] <free-form inline text>
138
+ ```
139
+
140
+ ### 5a. Idempotency check
141
+
142
+ Within the target phase's line range, look for any existing line whose full text after `- [ ] ` or `- [x] ` matches the new item body exactly. If a duplicate exists, **stop** and tell the user:
143
+
144
+ > Item already present in `<phase name>`. No changes made.
145
+
146
+ Do not proceed to edits or index updates.
147
+
148
+ ### 5b. Insert into an existing phase
149
+
150
+ Use `Edit` to insert the new item at the **end** of the target phase — immediately before the next `## ` header, or before any `## Notes` section, or at end of file if the target phase is the last block.
151
+
152
+ - Choose an `old_string` that is the **last existing item line** of the phase, so the `new_string` is `<old_string>\n<new item line>`.
153
+ - If the phase currently has no items (only a header and optional intent line), choose the phase's last existing line (header or intent) as `old_string` and append the new item line after a blank line.
154
+
155
+ ### 5c. Create a new phase
156
+
157
+ Only when the target phase does not exist (either `--phase "<name>"` named a new phase, or no phases exist at all):
158
+
159
+ 1. Determine the new phase number: `max(existing phase numbers) + 1`, or `1` if none exist.
160
+ 2. Build the block:
161
+
162
+ ```markdown
163
+
164
+ ## Phase <N>: <phase name>
165
+
166
+ - [ ] <new item line body>
167
+ ```
168
+
169
+ 3. Use `Edit` to insert this block:
170
+ - **Before** any `## Notes` section if one exists (use the `## Notes` line as `old_string`, prepend the new block).
171
+ - Otherwise at end of file (use the file's last non-empty line as `old_string`, append the new block).
172
+
173
+ Never use `Write` for a full-file rewrite. Always `Edit`.
174
+
175
+ ---
176
+
177
+ ## Step 6: Update the roadmap's `Last updated` field
178
+
179
+ Use `Edit` to change the `**Last updated**: YYYY-MM-DD` line to today's date. Use the date from the environment context. If the line is already today's date, skip silently.
180
+
181
+ ---
182
+
183
+ ## Step 7: Update the Index in `wiki/work/roadmaps/index.md`
184
+
185
+ `Read` `wiki/work/roadmaps/index.md`. Locate the Index table row whose `File` cell matches `[ROADMAP-NNN](NNN-slug.md)` for the just-edited roadmap.
186
+
187
+ The `Progress` cell is formatted `M/N`. Use `Edit` to bump the **denominator only**: `M/N` → `M/N+1`.
188
+
189
+ | Case | Action |
190
+ |------|--------|
191
+ | Row exists with `M/N` | Replace with `M/(N+1)` |
192
+ | Row missing (roadmap was never indexed) | Print a warning that the index is out of sync; do not invent a row — that is `/roadmap-create`'s job |
193
+ | Index still shows the placeholder `_No roadmaps yet — ..._` row | Print a warning; do not modify the placeholder |
194
+
195
+ ---
196
+
197
+ ## Step 8: Report completion
198
+
199
+ Print a single tabular summary:
200
+
201
+ | Field | Value |
202
+ |-------|-------|
203
+ | Roadmap | `<path>` |
204
+ | Phase | `<phase name>` (new or existing) |
205
+ | Item type | `task-link` or `inline (placeholder — task pending)` |
206
+ | Item body | `<the line just inserted, minus the leading "- [ ] ">` |
207
+ | Index updated | `M/N → M/N+1` (or `skipped — <reason>`) |
208
+ | Last updated | today's date |
209
+
210
+ If the added item is an inline placeholder, append this note after the table:
211
+
212
+ > **Note:** This item has no task file yet and cannot be worked on directly. Run `/roadmap-next` to automatically create a task file for it and convert it to a task-link.
213
+
214
+ ---
215
+
216
+ ## Anti-Patterns
217
+
218
+ | Anti-Pattern | Remedy |
219
+ |--------------|--------|
220
+ | Editing the roadmap with `sed`, `awk`, `echo >>`, or `cat <<EOF` | **Never.** Always use `Read` + `Edit`. See `.docs/guides/mcp-tools.md` |
221
+ | Using `Write` to rewrite the whole roadmap file | Use surgical `Edit` calls only |
222
+ | Inventing a task title when the task file is missing | Ask via `AskUserQuestion` whether to fall back to inline, or cancel |
223
+ | Bumping the `Progress` numerator | This skill **never** touches the numerator — that is auto-checkoff's job (`/tackle`, `/uat-walk`, `/uat-auto`, `/uat-auto-plus`, `/uat-skip`) |
224
+ | Auto-flipping `Status: active` → `done` | This skill never changes status. Only humans flip status |
225
+ | Silently duplicating an existing item | Idempotency check in Step 5a — stop with a "already present" message |
226
+ | Re-numbering existing phases when adding a new one | Append the new phase at the end with `N+1`; never shuffle prior phase numbers |
227
+
228
+ ---
229
+
230
+ ## CRITICAL Rules
231
+
232
+ 1. **Always `Read` then `Edit`** — never `sed`, `echo >>`, `cat <<EOF`, or shell redirection.
233
+ 2. **`Write` is forbidden for this skill** — every change is a surgical `Edit`.
234
+ 3. **The skill never checks boxes** — it only adds unchecked `- [ ]` items. Auto-checkoff is owned by `/tackle` and the UAT skills.
235
+ 4. **The skill never changes `Status:`** — that flip is intentionally manual.
236
+ 5. **Index numerator stays untouched** — only the denominator increments here.
237
+ 6. **Idempotency before edits** — duplicate items abort the run with a friendly message; no edits, no index bump.
238
+ 7. **Stable IDs only** — task-link items use `[[TASK-NNN: title]]` wiki-link format, not file-path markdown links. Path-based links break on archive; ID-based links never do.
@@ -0,0 +1,223 @@
1
+ ---
2
+ name: roadmap-create
3
+ description: Create a structured execution-plan roadmap in wiki/work/roadmaps/ via short Socratic Q&A — captures goal, phases, and the initial hybrid (task-link OR inline) checklist
4
+ category: planning
5
+ model: claude-sonnet-4-6
6
+ argument-hint: <initiative/goal description>
7
+ disable-model-invocation: false
8
+ user-invocable: true
9
+ ---
10
+ **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
11
+ **Read `wiki/work/roadmaps/lifecycle.md` first — it is authoritative for the roadmap frontmatter schema, status lifecycle, and ID/filename rules. The file template, item-format rules, index format, and anti-patterns are specified inline in this skill below.**
12
+ **Run `/research <topic>` on the roadmap topic BEFORE any Q&A or file creation. Do not skip this step.**
13
+
14
+ # Create Roadmap
15
+
16
+ Create a new **Roadmap** — a structured, phased execution checklist that sits **orthogonal** to the PRD → ADR → Task pipeline. A roadmap answers exactly one question: *in what sequence will we execute the work?*
17
+
18
+ The hard boundary:
19
+
20
+ > *A roadmap shows order. A task contains implementation steps. Never smuggle step-level detail into a roadmap item.*
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-add` (or `/task-add --roadmap ROADMAP-NNN` to auto-link). Redirect the user when this happens.
23
+
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
+
26
+ ---
27
+
28
+ **Topic**: $ARGUMENTS
29
+
30
+ ---
31
+
32
+ ## When to write a Roadmap
33
+
34
+ Write a roadmap when work spans multiple discrete units, ordering matters, and you want at-a-glance visibility of what's next.
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-add` instead.
37
+
38
+ ---
39
+
40
+ ## Instructions
41
+
42
+ ### Step 1: Parse the topic and recall project context
43
+
44
+ 1. **Extract** the core initiative from `$ARGUMENTS`. If it is too vague (e.g. "auth", "cleanup", "the next thing"), use `AskUserQuestion` to narrow it before any other work.
45
+ 2. **Invoke `/research <topic>`** — run the research skill on the roadmap topic now. Do not proceed to Step 2 until this completes. Use its findings to inform phase ordering, known constraints, and item content throughout the Q&A.
46
+ 3. **Recall Serena memories** that may inform the execution order:
47
+ - `mcp__serena__list_memories`
48
+ - `mcp__serena__read_memory` for any topic-relevant memory (sequencing constraints, prior roadmaps, known dependency rules)
49
+ 3. **Read project context**:
50
+ - `CLAUDE.md` (project conventions)
51
+ - `wiki/work/roadmaps/lifecycle.md` (frontmatter schema, status lifecycle — authoritative)
52
+ - A sample of recent roadmaps in `wiki/work/roadmaps/` to learn local conventions
53
+ - The active-task bullets in `wiki/work/tasks/index.md` so you know what task files already exist and can be linked
54
+
55
+ ### Step 2: Locate the roadmap directory and assign a number
56
+
57
+ Roadmaps live at `wiki/work/roadmaps/NNN-slug.md`. Numbers are 3-digit zero-padded.
58
+
59
+ 1. **Use `mcp__serena__list_dir` on `wiki/work/roadmaps/` and `wiki/work/roadmaps/archive/`** (skip either that doesn't exist) to scan existing files. Collect every `NNN-` prefix from **both** directories — completed roadmaps move to `archive/` but keep their original number forever.
60
+ 2. **Use `mcp__serena__search_for_pattern`** against `wiki/work/roadmaps/index.md` for `ROADMAP-\d{3}` entries — these may reserve numbers not yet on disk.
61
+ 3. Take `max + 1`, zero-pad to 3 digits. The first roadmap is `001`.
62
+ 4. **Derive the file slug** — names the **initiative**. Lowercase, dash-separated, ≤ 60 chars:
63
+ - "Ship the billing portal" → `001-ship-billing-portal.md`
64
+ - "Migrate to Postgres 17" → `004-migrate-postgres-17.md`
65
+
66
+ Confirm the chosen number and slug with the user via `AskUserQuestion` only if either is non-obvious.
67
+
68
+ ### Step 3: Socratic Q&A via `AskUserQuestion` (short — this is the heart of this skill)
69
+
70
+ Walk through the elicitations below. Batch related questions into a single `AskUserQuestion` round (max 4 questions per call) to minimize round-trips. For each elicitation, the table names the **quality bar** the answer must clear. If the user's answer fails the bar, ask a follow-up — do **not** silently accept a weak answer or invent better content yourself.
71
+
72
+ | # | Elicitation | Quality bar | Anti-pattern to reject (re-ask) |
73
+ |---|-------------|-------------|---------------------------------|
74
+ | 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 |
75
+ | 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) |
76
+ | 3 | **Owner** | One named person or role accountable for execution | "The team", "everyone", missing owner |
77
+ | 4 | **Linked PRD / ADRs (may be empty)** | Existing `PRD-NNN` or `DEC-NNNN#DM` references, or `—` if standalone | Inventing references that don't exist |
78
+
79
+ **Suggested first batch (one `AskUserQuestion` call covering all four)**:
80
+
81
+ | Batch | Questions covered |
82
+ |-------|-------------------|
83
+ | 1 | Goal, Phases, Owner, Linked PRD/ADRs |
84
+
85
+ Then **per-phase**, in a single follow-up `AskUserQuestion` round (one question per phase, up to 4 — split into multiple rounds only if there are 5 phases):
86
+
87
+ | # | Elicitation | Quality bar |
88
+ |---|-------------|-------------|
89
+ | 5 | **Phase N items** | For each phase, the user names (a) any existing tasks (`TASK-NNN` 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 via `/roadmap-add` — but **at least one phase must contain at least one item** (a roadmap with zero items is not a roadmap) |
90
+
91
+ When the user supplies a task reference:
92
+
93
+ - Look it up in `wiki/work/tasks/` via `mcp__serena__find_file` to confirm it exists. The link must read `[[TASK-NNN: <task title>]]`.
94
+ - 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.
95
+
96
+ **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-add` to create a task file for each inline item before surfacing it. The roadmap item is then upgraded to a task-link in place.
97
+
98
+ **Redirection rule**: if the user starts spelling out implementation detail under an item (file paths, function names, sub-steps), respond:
99
+
100
+ > That sounds like task content, not a roadmap item. Roadmaps show *ordering*. The *how* belongs in a task file — file one with `/task-add --roadmap ROADMAP-NNN <description>` and the roadmap will auto-link to it.
101
+
102
+ Then re-ask for a single checkbox-sized item.
103
+
104
+ ### Step 4: Present the plan and confirm before writing
105
+
106
+ Before writing the file, present a **tabular preview** of the roadmap:
107
+
108
+ | Section | Preview format |
109
+ |---------|---------------|
110
+ | Header | Title, Status (`active`), Owner, Linked PRD, Linked ADRs, Tags |
111
+ | Goal | Full text |
112
+ | Phases | Table of `Phase N` → `Name` → `# items` (task-link + inline counts) |
113
+ | Per-phase items | One sub-list per phase showing each item's rendered form (`[[TASK-NNN: title]]` or inline text) |
114
+
115
+ The user confirms via `AskUserQuestion` with options like *Approve and write*, *Edit specific phase*, *Cancel*. Do **not** write the file until the user explicitly approves.
116
+
117
+ If the user requests edits, loop back to the relevant Step 3 elicitation, re-ask, and re-present.
118
+
119
+ ### Step 5: Re-verify the next available number — IMMEDIATELY before writing
120
+
121
+ The number determined in Step 2 may now be stale (other roadmaps created mid-session, the README Index may list reservations not yet on disk). Do a fresh scan now:
122
+
123
+ - `mcp__serena__list_dir` on `wiki/work/roadmaps/` **and** `wiki/work/roadmaps/archive/` (skip either that doesn't exist)
124
+ - `mcp__serena__search_for_pattern` against `wiki/work/roadmaps/index.md` for `ROADMAP-\d{3}` entries
125
+ - Collect every `NNN-` prefix from both directories, take `max + 1`, zero-pad to 3 digits
126
+ - 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.
127
+ - **Never call `Write` before completing this re-scan.**
128
+
129
+ ### Step 6: Write the roadmap file
130
+
131
+ Use `Write` to create `wiki/work/roadmaps/NNN-slug.md` following the field table below and the item-rendering rules **exactly**; the frontmatter must match the schema in `wiki/work/roadmaps/lifecycle.md`.
132
+
133
+ | Field | Value at creation time |
134
+ |-------|------------------------|
135
+ | `Status` | `active` |
136
+ | `Created` | Today's date (derive at runtime — use the conversation environment's `currentDate`, otherwise `date +%Y-%m-%d`) |
137
+ | `Last updated` | Same as `Created` |
138
+ | `Owner` | From Step 3 #3 |
139
+ | `Linked PRD` | From Step 3 #4, or `—` |
140
+ | `Linked ADRs` | From Step 3 #4, or `—` |
141
+ | `Tags` | 1-3 short area tags inferred from the topic (e.g. `auth`, `billing`, `infra`). If the user did not name any, propose tags during Step 4's confirmation rather than inventing them silently |
142
+ | `## Goal` | From Step 3 #1 |
143
+ | `## Phase N: <name>` | One block per phase from Step 3 #2, each containing the items from Step 3 #5. **At least one phase must contain at least one item.** |
144
+ | `## Notes` | Empty placeholder line (the section header is retained for future use) |
145
+
146
+ **Item rendering rules**:
147
+
148
+ - Task-link item: `- [ ] [[TASK-NNN: <task title>]]`
149
+ - Inline item: `- [ ] <free-form description>`
150
+
151
+ **Refuse to write** if:
152
+
153
+ - The Goal is missing or vague
154
+ - The Owner is missing or "the team"/"everyone"
155
+ - Every phase is empty (zero items total)
156
+
157
+ Loop back to Step 3 instead — do not silently invent content.
158
+
159
+ ### Step 7: Update the roadmap index
160
+
161
+ Edit `wiki/work/roadmaps/index.md` to add a new bullet line (active items only — a flat list, no table).
162
+
163
+ 1. `Read` `wiki/work/roadmaps/index.md` to locate the active-items list.
164
+ 2. If the placeholder line (`_(none yet)_` or a "no roadmaps yet" note) exists, **replace** it with the new line. Otherwise **append** the new line in numerical order.
165
+ 3. Use the entry format documented at the top of `index.md`:
166
+
167
+ `- [ROADMAP-NNN — <title>](NNN-slug.md) — <one-line summary> · 0/<total> items checked`
168
+
169
+ 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.
170
+
171
+ Use `Edit` (not `sed`, `awk`, `echo >>`, or any shell redirection). See `.docs/guides/mcp-tools.md`.
172
+
173
+ ### Step 8: Refresh the hot cache
174
+
175
+ 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.
176
+
177
+ ### Step 9: Report completion
178
+
179
+ Print a tabular summary:
180
+
181
+ | Field | Value |
182
+ |-------|-------|
183
+ | File path | `wiki/work/roadmaps/NNN-slug.md` |
184
+ | Status | `active` |
185
+ | Phases | N |
186
+ | Total items | M (task-link: X, inline: Y) |
187
+ | Owner | <name> |
188
+ | Linked PRD | PRD-NNN or `—` |
189
+ | Linked ADRs | list or `—` |
190
+ | Index updated | yes (1 row added) |
191
+ | Suggested next steps | `/roadmap-next wiki/work/roadmaps/NNN-slug.md` — surfaces the first item and creates task files for any inline placeholders • `/task-add --roadmap ROADMAP-NNN <description>` — file a new task auto-linked to this roadmap |
192
+
193
+ If any phase was left empty by design (user plans to fill via `/roadmap-add`), note it in a separate **Gaps** section so the user can address it before execution begins.
194
+
195
+ If the roadmap contains any inline placeholder items (items without a task-link), include a **Placeholders** section listing them:
196
+
197
+ > **Placeholders (task file pending):** These items will have task files created for them automatically when `/roadmap-next` runs. They cannot be tackled until a task file exists.
198
+ > - Phase N: "<item text>"
199
+ > - ...
200
+
201
+ This is informational only — no action required now.
202
+
203
+ ---
204
+
205
+ ## Output Formatting Rules (mandatory — these override any default style)
206
+
207
+ 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.
208
+ 2. **Phase names are short and execution-flavored.** "Foundation", "API", "Tests", "Release" — not "Phase where we figure out the database stuff".
209
+ 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.
210
+ 4. **Task-link items must use `[[TASK-NNN: <title>]]` format.** The `TASK-NNN:` 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.
211
+ 5. **At least one phase must contain at least one item.** An empty roadmap is a hard fail — loop back to Step 3 #5.
212
+ 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-NNN: ...]]` wiki link.
213
+
214
+ ---
215
+
216
+ ## CRITICAL Rules
217
+
218
+ 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.
219
+ 2. **Never invent task links.** Every `[[TASK-NNN: ...]]` wiki link must correspond to a real file under `wiki/work/tasks/`. Verify with `mcp__serena__find_file` before rendering.
220
+ 3. **Never use `sed`, `awk`, `echo >>`, or shell redirection to edit markdown.** Always `Read` then `Edit`. See `.docs/guides/mcp-tools.md`.
221
+ 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-add --roadmap ROADMAP-NNN`.
222
+ 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.
223
+ 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 may be moved to `wiki/work/roadmaps/archive/` — `/roadmap-next` will suggest this step.
@@ -0,0 +1,132 @@
1
+ ---
2
+ name: roadmap-next
3
+ description: Point at the first unchecked item(s) in a roadmap; create task files for inline placeholders; group items into parallelizable waves; auto-archive fully-checked roadmaps
4
+ category: researching
5
+ model: claude-haiku-4-5-20251001
6
+ argument-hint: "[path to roadmap file, NNN-slug, or number] (optional)"
7
+ disable-model-invocation: false
8
+ user-invocable: true
9
+ ---
10
+ **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
11
+
12
+ # Next Step
13
+
14
+ Surface unchecked roadmap items grouped into parallelizable waves and tell the user how to act. When a roadmap has all items checked, flip its status to `done` and move it to `archive/`.
15
+
16
+ **Roadmap Input**: $ARGUMENTS
17
+
18
+ ## Step 0: Mode
19
+ - `$ARGUMENTS` non-empty → **Single-Roadmap Mode** (resolve one file, Step 1S).
20
+ - `$ARGUMENTS` empty → **Scan Mode** (collect across all roadmaps, Step 1M).
21
+
22
+ ---
23
+
24
+ ## Shared procedures (used by both modes)
25
+
26
+ ### Parse a roadmap
27
+ `Read` the file (markdown). Extract: **phases** (`## Phase N: <name>` in order), **items** (`- [ ]` unchecked / `- [x]` checked), **status** (`- **Status**: active | done`), and the `roadmap_id` (`- **ID**: ROADMAP-NNN` front matter or filename prefix, e.g. `003-billing.md` → `ROADMAP-003`). Per item capture: `phase` (nearest preceding heading, or `(no phase)`), `checked`, `text`, `kind` (`task-link` if body starts `[[TASK-NNN`, else `inline`), `task_id` (from `[[TASK-NNN: title]]`), `task_path` (`find_file` `TASK-NNN-*` in `wiki/work/tasks/` — matches active or archived). Compute `total`, `done`. Collect unchecked items into `candidate_items`, **capped at 9 total**.
28
+
29
+ For each `candidate_items` item that is already `kind == 'task-link'` (skip this for `inline` items until after they're upgraded below): `Read` `task_path`'s frontmatter and store `task_status` (`todo | in-progress | pending-uat | done | trashed`, per [tasks lifecycle](../tasks/lifecycle.md)). If `task_status == 'pending-uat'`, also resolve `uat_path` — read the task's `uat:` frontmatter field if present and `find_file` it; if empty or not found, leave `uat_path` unset (implementation finished but `/uat-generate` hasn't run yet).
30
+
31
+ ### Upgrade inline items to task files
32
+ **All roadmap items must eventually be task files** — inline items are placeholders. For each `candidate_items` item with `kind == 'inline'`:
33
+ 1. Announce: `Inline item found: "<text>"[ (in <roadmap_title>)] — checking for an existing task before creating one.`
34
+ 2. **Check for an existing task:** `Read` `wiki/work/tasks/index.md`, scan its active-item bullets for one whose title/summary plausibly covers the intent; if likely, `Read` that task to confirm. Found → use its `TASK-NNN` + path, skip to step 5 (do **not** call `task-add`).
35
+ 3. Else invoke `Skill` `task-add` with the item text as `args` (**no** `--roadmap` flag — the link is managed here to avoid a duplicate item).
36
+ 4. Extract the new task path + ID from task-add's summary (`File path` row); if parsing fails, `list_dir` `wiki/work/tasks/` for the newest `.md` not present before, and `Read` it to confirm `TASK-NNN` + title (from `# NNN: <title>`).
37
+ 5. `Edit` the roadmap: `- [ ] <item_text>` → `- [ ] [[TASK-NNN: <title>]]`.
38
+ 6. Update the record: `kind='task-link'`, `task_id`, `task_path` (from `find_file`). A freshly created task is always `status: todo` — set `task_status = 'todo'` directly, no need to re-read the file.
39
+
40
+ If `task-add` fails/cancels, **stop and report**: `Task creation cancelled for: "<text>"[ (in <roadmap_title>)]. Inline items cannot be worked on without a task file. Re-run /roadmap-next after /task-add <description>.`
41
+
42
+ ### Parallelism analysis → waves
43
+ After upgrades, for each item: `Read` its `task_path`, find `## Dependencies` / `## Blocked by`, extract `TASK-NNN` refs; an **active blocker** is a dep whose `TASK-NNN` also appears in `candidate_items`. Store as `blockers`. Topological sort: **Wave 1** = empty `blockers`; **Wave 2** = blockers all in Wave 1; **Wave 3** = blockers all in Wave 1∪2. Omit Wave 4+. **Cap each wave at 3 items** (document order); note overflow count. Store as `waves`.
44
+
45
+ ### Archive a fully-complete roadmap (`total > 0` and `done == total`) — run automatically, no prompt
46
+ 1. If `status: active`, `Edit` → `status: done`.
47
+ 2. Remove its row from `wiki/work/roadmaps/index.md` (active-only index).
48
+ 3. `git mv <roadmap_path> wiki/work/roadmaps/archive/<filename>` (Bash — `git mv` only).
49
+ 4. Append to `wiki/work/roadmaps/archive/index.md`: `| [[ROADMAP-NNN]] | <title> | done | YYYY-MM-DD |`.
50
+ 5. Append to `wiki/log.md`:
51
+ ```
52
+ ## [YYYY-MM-DD] archive | <ROADMAP-NNN> — completed, moved to archive
53
+ All items checked. Moved to wiki/work/roadmaps/archive/<filename>.
54
+ ```
55
+
56
+ ---
57
+
58
+ ## Single-Roadmap Mode
59
+
60
+ ### Step 1S: Resolve the file (`find_file`/`list_dir`, never bash)
61
+ | Input | Action |
62
+ |-------|--------|
63
+ | File path | confirm exists (`find_file`); missing → `Roadmap file not found: <path>` + STOP |
64
+ | `NNN-slug` | match in `wiki/work/roadmaps/`; none → `No roadmap matching '<input>' found…` + STOP |
65
+ | Number (`1`/`001`) | `list_dir`, match zero-padded prefix; ambiguous → list + `AskUserQuestion`; none → `No roadmap with number '<input>' found.` + STOP |
66
+
67
+ ### Step 2S–2.7S: Parse → upgrade inline items → parallelism analysis
68
+ Run the three shared procedures on the resolved file.
69
+
70
+ ### Step 3S: Report
71
+ - **All checked** (`done == total`, `total > 0`) → run the shared archive procedure, then report: `Progress: <total>/<total> — all done!` / `Status → done. Archived → wiki/work/roadmaps/archive/<filename>.`
72
+ - **Unchecked items remain** → progress line + one table per non-empty wave (every item is a task-link post-upgrade):
73
+ ```
74
+ Progress: <done>/<total>
75
+
76
+ **Wave 1** — ready now (run these in parallel):
77
+ | # | Phase | Item | Action |
78
+ |---|-------|------|--------|
79
+ | 1 | Phase N: name | TASK-NNN: item title | `/tackle <task_path>` |
80
+
81
+ **Wave 2** — start after Wave 1 completes: …
82
+ **Wave 3** — start after Wave 2 completes: …
83
+ ```
84
+ Only emit non-empty wave tables. Wave 1 > 3 items → show 3 + `(+N more ready — showing first 3)`. No `Manual` case — every item is a task-link.
85
+
86
+ **Action cell by `task_status`** (this is the fix for the tackle→UAT visibility gap — a `pending-uat` task needs testing, not more implementation):
87
+ - `todo` / `in-progress` (default) → `` `/tackle <task_path>` ``
88
+ - `pending-uat` with `uat_path` resolved → `` `/uat-walk <uat_path>` `` — annotate the Item cell with a trailing `⏳ awaiting UAT`
89
+ - `pending-uat` with no `uat_path` → `` `/uat-generate <task_path>` `` — annotate the Item cell with a trailing `⏳ awaiting UAT (no tests yet)`
90
+ - `task_path` not found → `` `/tackle <task_path>` `` with ` (file not found)` appended, regardless of status (can't read a status that isn't there)
91
+ - **Zero items** → `Roadmap has no checklist items yet. Add some with /roadmap-add <ROADMAP-NNN> <item>.`
92
+
93
+ ---
94
+
95
+ ## Scan Mode (no argument)
96
+
97
+ ### Step 1M: Discover roadmaps
98
+ `list_dir` `wiki/work/roadmaps/` for `.md` files **directly** in it (not `archive/`); sort ascending by filename; skip `lifecycle.md`, `index.md`, `README.md`. None → STOP: `No roadmaps found in wiki/work/roadmaps/. Use /roadmap-create <topic> to draft one.`
99
+
100
+ ### Step 2M: Collect + auto-archive
101
+ For each roadmap in sorted order: parse it (shared). If fully complete (`total > 0`, `done == total`) → run the shared archive procedure, record the filename in `archived_files`, add **no** items, continue. Otherwise append its unchecked items to the shared `candidate_items` (each also carrying `roadmap_file`, `roadmap_title` = `# <Title>` or filename, `roadmap_id`). **Stop collecting at 9 items total** — skip reading further files.
102
+
103
+ ### Step 2.5M–2.7M: Upgrade inline items → parallelism analysis
104
+ Run the shared upgrade + parallelism procedures over the full `candidate_items` (may span roadmaps; cross-roadmap items with no shared deps are naturally parallel).
105
+
106
+ ### Step 3M: Report
107
+ - If `archived_files` non-empty, prepend:
108
+ ```
109
+ Archived to wiki/work/roadmaps/archive/:
110
+ • <filename> — all items checked
111
+ ```
112
+ - If `candidate_items` empty after scanning → `All roadmap items are checked off. Nothing left to do.`
113
+ - Otherwise one table per non-empty wave (with a `Roadmap` column), plus a footer:
114
+ ```
115
+ **Wave 1** — ready now (run these in parallel):
116
+ | # | Roadmap | Phase | Item | Action |
117
+ |---|---------|-------|------|--------|
118
+ | 1 | ROADMAP-NNN · Title | Phase X: name | TASK-NNN: item title | `/tackle <task_path>` |
119
+
120
+ **Wave 2** — start after Wave 1 completes: …
121
+
122
+ Showing <shown_count> of <total_unchecked_scanned> unchecked item(s) across <files_scanned> roadmap(s).
123
+ ```
124
+ `total_unchecked_scanned` = all unchecked found before the 9-cap; `files_scanned` = files actually read. Same wave rules as Single mode (non-empty only, `(file not found)`, no `Manual` case), including the same **Action cell by `task_status`** rule (`pending-uat` → `/uat-walk`/`/uat-generate` with the `⏳ awaiting UAT` annotation instead of `/tackle`).
125
+
126
+ ---
127
+
128
+ ## Constraints
129
+ - **Never flip checkboxes.** The only permitted content writes are: (1) `Status: active → done` before archiving; (2) inline-placeholder → task-link replacement (upgrade step); (3) archive/log appends when archiving.
130
+ - Permitted tools: `list_dir`, `find_file`, `Read`, `Edit`, `Bash`, `AskUserQuestion`, `Skill` (only for `task-add` on inline items).
131
+ - `Bash` only for `git mv` when archiving. Never bash reads (`cat`/`find`/`grep`/`sed`/`ls`).
132
+ - Keep the final report terse — one block per wave, no preamble, no closing summary.