@codewizard-dt/bootstrap 2.23.0 → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/workflows/docker-harness.yml +26 -0
- package/lib/scripts/README.md +1 -0
- package/lib/scripts/install-obsidian.sh +182 -7
- package/lib/scripts/templates/bootstrap-prefs-schema.json +1 -1
- package/lib/scripts/templates/file-suggestion.sh +6 -4
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +1 -1
- package/lib/skills/README.md +2 -2
- package/lib/skills/git-commit/SKILL.md +34 -16
- package/lib/skills/roadmap-assess/SKILL.md +111 -0
- package/lib/skills/roadmap-create/SKILL.md +2 -2
- package/lib/skills/roadmap-next/SKILL.md +32 -52
- package/package.json +1 -1
- package/lib/skills/roadmap-add/SKILL.md +0 -238
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
name: Docker Fresh-Machine Harness
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
pull_request:
|
|
5
|
+
paths:
|
|
6
|
+
- "test/docker/fresh-machine/**"
|
|
7
|
+
- "lib/scripts/**"
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
fresh-machine:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
steps:
|
|
13
|
+
- name: Checkout repo
|
|
14
|
+
uses: actions/checkout@v4
|
|
15
|
+
|
|
16
|
+
- name: Build fresh-machine image
|
|
17
|
+
run: docker build -t bootstrap-claude-fresh-machine test/docker/fresh-machine
|
|
18
|
+
|
|
19
|
+
- name: Run setup mode
|
|
20
|
+
run: ./test/docker/fresh-machine/run.sh setup
|
|
21
|
+
|
|
22
|
+
- name: Run update mode
|
|
23
|
+
run: ./test/docker/fresh-machine/run.sh update
|
|
24
|
+
|
|
25
|
+
# TASK-071 (stale mode) and TASK-072 (idempotency check) are still `status: todo` —
|
|
26
|
+
# add their run.sh modes as additional steps here once those tasks land.
|
package/lib/scripts/README.md
CHANGED
|
@@ -39,6 +39,7 @@ These are **not** referenced by `bin/cli.js` or by any other script — they're
|
|
|
39
39
|
|--------|---------|
|
|
40
40
|
| `setup-runner.sh` | Generalized GitHub Actions self-hosted runner installer. Run as root on a target droplet: `RUNNER_TOKEN=<token> REPO_URL=<url> bash setup-runner.sh`. Registers the runner, installs it as a service, and configures GHCR login. |
|
|
41
41
|
| `startup.sh` | One-shot droplet bootstrap: updates apt, installs zsh/curl/make, and installs Docker + the Compose plugin from Docker's official apt repo. Typically run once before `setup-runner.sh` on a fresh VM. |
|
|
42
|
+
| [`test/docker/fresh-machine/`](../../test/docker/fresh-machine/README.md) | Docker-based harness that emulates running `setup`/`update` on a completely fresh machine with no prior Claude Code infrastructure. `./run.sh [shell\|setup\|update]`. |
|
|
42
43
|
|
|
43
44
|
## `templates/`
|
|
44
45
|
|
|
@@ -245,23 +245,198 @@ _enable_obsidian_plugin() {
|
|
|
245
245
|
' "$vault_dir" "$id" || true
|
|
246
246
|
}
|
|
247
247
|
|
|
248
|
+
# _graph_defaults_node <template> <graph_file> <fingerprint_file> <mode> <decisions_json>
|
|
249
|
+
# Shared plan/apply logic: plan lists diverged keys needing a decision (no writes); apply resolves them via <decisions_json> and writes graph.json + fingerprint sidecar (changed files only). Template keys come from the packaged template's own Object.keys(), never hardcoded.
|
|
250
|
+
_graph_defaults_node() {
|
|
251
|
+
node -e '
|
|
252
|
+
const fs = require("fs");
|
|
253
|
+
const crypto = require("crypto");
|
|
254
|
+
|
|
255
|
+
const [templatePath, graphFile, fingerprintFile, mode, decisionsRaw] = process.argv.slice(1);
|
|
256
|
+
|
|
257
|
+
const hashOf = (v) => crypto.createHash("sha256").update(JSON.stringify(v)).digest("hex");
|
|
258
|
+
|
|
259
|
+
let template;
|
|
260
|
+
try {
|
|
261
|
+
template = JSON.parse(fs.readFileSync(templatePath, "utf8"));
|
|
262
|
+
} catch (e) {
|
|
263
|
+
console.error(" WARNING: could not read/parse the packaged graph.json template — skipping graph defaults.");
|
|
264
|
+
process.exit(0);
|
|
265
|
+
}
|
|
266
|
+
const templateKeys = Object.keys(template);
|
|
267
|
+
|
|
268
|
+
let existing = {};
|
|
269
|
+
if (fs.existsSync(graphFile)) {
|
|
270
|
+
try {
|
|
271
|
+
existing = JSON.parse(fs.readFileSync(graphFile, "utf8"));
|
|
272
|
+
} catch (e) {
|
|
273
|
+
console.error(" WARNING: could not parse existing graph.json — treating it as empty.");
|
|
274
|
+
existing = {};
|
|
275
|
+
}
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
let fingerprint = {};
|
|
279
|
+
if (fs.existsSync(fingerprintFile)) {
|
|
280
|
+
try {
|
|
281
|
+
const raw = JSON.parse(fs.readFileSync(fingerprintFile, "utf8"));
|
|
282
|
+
if (raw && typeof raw === "object" && !Array.isArray(raw)) fingerprint = raw;
|
|
283
|
+
else throw new Error("unexpected shape");
|
|
284
|
+
} catch (e) {
|
|
285
|
+
console.error(" WARNING: could not parse .graph-defaults-fingerprint.json — treating it as empty.");
|
|
286
|
+
fingerprint = {};
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
let decisions = {};
|
|
291
|
+
if (decisionsRaw) {
|
|
292
|
+
try {
|
|
293
|
+
decisions = JSON.parse(decisionsRaw);
|
|
294
|
+
} catch (e) {
|
|
295
|
+
decisions = {};
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
const merged = Object.assign({}, existing);
|
|
300
|
+
const newFingerprint = {};
|
|
301
|
+
const pending = [];
|
|
302
|
+
const added = [];
|
|
303
|
+
const refreshed = [];
|
|
304
|
+
const unchanged = [];
|
|
305
|
+
const kept = [];
|
|
306
|
+
|
|
307
|
+
for (const key of templateKeys) {
|
|
308
|
+
const templateValue = template[key];
|
|
309
|
+
const templateHash = hashOf(templateValue);
|
|
310
|
+
const hasKey = Object.prototype.hasOwnProperty.call(existing, key);
|
|
311
|
+
const fp = fingerprint[key] && typeof fingerprint[key] === "object" ? fingerprint[key] : {};
|
|
312
|
+
|
|
313
|
+
if (!hasKey) {
|
|
314
|
+
// Case 1: key absent from the existing file.
|
|
315
|
+
merged[key] = templateValue;
|
|
316
|
+
newFingerprint[key] = { offeredHash: templateHash };
|
|
317
|
+
added.push(key);
|
|
318
|
+
continue;
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
const fileHash = hashOf(existing[key]);
|
|
322
|
+
|
|
323
|
+
if (fp.offeredHash && fileHash === fp.offeredHash) {
|
|
324
|
+
// Case 2: file still holds exactly what we last delivered.
|
|
325
|
+
merged[key] = templateValue;
|
|
326
|
+
newFingerprint[key] = { offeredHash: templateHash };
|
|
327
|
+
(fileHash === templateHash ? unchanged : refreshed).push(key);
|
|
328
|
+
continue;
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
if (!fp.offeredHash && fileHash === templateHash) {
|
|
332
|
+
// Case 3, unmodified branch: no sidecar yet, but the file already
|
|
333
|
+
// matches todays template — bootstrap the fingerprint silently.
|
|
334
|
+
merged[key] = templateValue;
|
|
335
|
+
newFingerprint[key] = { offeredHash: templateHash };
|
|
336
|
+
unchanged.push(key);
|
|
337
|
+
continue;
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
// Case 4 (including the bootstrapped-diverged branch of case 3): the
|
|
341
|
+
// file has diverged from what we last offered.
|
|
342
|
+
if (fp.declinedHash && templateHash === fp.declinedHash) {
|
|
343
|
+
// Already declined exactly this template value — stay sticky.
|
|
344
|
+
merged[key] = existing[key];
|
|
345
|
+
newFingerprint[key] = fp;
|
|
346
|
+
kept.push(key);
|
|
347
|
+
continue;
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
if (mode === "plan") {
|
|
351
|
+
pending.push(key);
|
|
352
|
+
continue;
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
if (Object.prototype.hasOwnProperty.call(decisions, key)) {
|
|
356
|
+
if (decisions[key] === true) {
|
|
357
|
+
merged[key] = templateValue;
|
|
358
|
+
newFingerprint[key] = { offeredHash: templateHash };
|
|
359
|
+
refreshed.push(key);
|
|
360
|
+
} else {
|
|
361
|
+
merged[key] = existing[key];
|
|
362
|
+
newFingerprint[key] = Object.assign({}, fp, { declinedHash: templateHash });
|
|
363
|
+
kept.push(key);
|
|
364
|
+
}
|
|
365
|
+
} else {
|
|
366
|
+
// Non-interactive, or a plan-only pass with no decision supplied:
|
|
367
|
+
// leave the file untouched and record nothing, so a later
|
|
368
|
+
// interactive run still offers this key.
|
|
369
|
+
merged[key] = existing[key];
|
|
370
|
+
if (fp.offeredHash) newFingerprint[key] = { offeredHash: fp.offeredHash };
|
|
371
|
+
kept.push(key);
|
|
372
|
+
}
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
if (mode === "plan") {
|
|
376
|
+
for (const key of pending) console.log(key);
|
|
377
|
+
process.exit(0);
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
const graphStr = JSON.stringify(merged, null, 2) + "\n";
|
|
381
|
+
const fingerprintStr = JSON.stringify(newFingerprint, null, 2) + "\n";
|
|
382
|
+
const existingGraphStr = fs.existsSync(graphFile) ? fs.readFileSync(graphFile, "utf8") : null;
|
|
383
|
+
const existingFingerprintStr = fs.existsSync(fingerprintFile) ? fs.readFileSync(fingerprintFile, "utf8") : null;
|
|
384
|
+
|
|
385
|
+
if (graphStr !== existingGraphStr) {
|
|
386
|
+
const tmp = graphFile + ".tmp-" + process.pid;
|
|
387
|
+
fs.writeFileSync(tmp, graphStr);
|
|
388
|
+
fs.renameSync(tmp, graphFile);
|
|
389
|
+
}
|
|
390
|
+
if (fingerprintStr !== existingFingerprintStr) {
|
|
391
|
+
const tmp = fingerprintFile + ".tmp-" + process.pid;
|
|
392
|
+
fs.writeFileSync(tmp, fingerprintStr);
|
|
393
|
+
fs.renameSync(tmp, fingerprintFile);
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
const parts = [];
|
|
397
|
+
if (added.length) parts.push(added.length + " added");
|
|
398
|
+
if (refreshed.length) parts.push(refreshed.length + " refreshed");
|
|
399
|
+
if (unchanged.length) parts.push(unchanged.length + " unchanged");
|
|
400
|
+
if (kept.length) parts.push(kept.length + " kept (your customization)");
|
|
401
|
+
console.log(" graph.json: " + (parts.length ? parts.join(", ") : "no changes") + ".");
|
|
402
|
+
' "$1" "$2" "$3" "$4" "$5"
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
# _install_obsidian_graph_defaults <vault_dir>
|
|
406
|
+
# Per-key sticky refresh (TASK-067) via a fingerprint sidecar, replacing the old whole-file write-if-absent check — never silently clobbers a genuinely user-diverged key. See _graph_defaults_node for the decision table.
|
|
248
407
|
_install_obsidian_graph_defaults() {
|
|
249
408
|
local vault_dir="$1"
|
|
409
|
+
local template="$SCRIPT_DIR/templates/obsidian/graph.json"
|
|
410
|
+
local graph_file="$vault_dir/.obsidian/graph.json"
|
|
411
|
+
local fingerprint_file="$vault_dir/.obsidian/.graph-defaults-fingerprint.json"
|
|
250
412
|
|
|
251
413
|
if ! mkdir -p "$vault_dir/.obsidian"; then
|
|
252
414
|
echo " WARNING: failed to create $vault_dir/.obsidian — skipping graph defaults." >&2
|
|
253
415
|
return
|
|
254
416
|
fi
|
|
255
417
|
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
418
|
+
local decisions="{}"
|
|
419
|
+
if [ "$INTERACTIVE" = true ]; then
|
|
420
|
+
local pending=() key
|
|
421
|
+
while IFS= read -r key; do
|
|
422
|
+
[ -n "$key" ] && pending+=("$key")
|
|
423
|
+
done < <(_graph_defaults_node "$template" "$graph_file" "$fingerprint_file" plan "{}")
|
|
260
424
|
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
425
|
+
if [ "${#pending[@]}" -gt 0 ]; then
|
|
426
|
+
local parts=() answer
|
|
427
|
+
for key in "${pending[@]}"; do
|
|
428
|
+
if prompt_yn " graph.json key '$key' differs from your saved customization — update to the new default? [y/N]: "; then
|
|
429
|
+
answer=true
|
|
430
|
+
else
|
|
431
|
+
answer=false
|
|
432
|
+
fi
|
|
433
|
+
parts+=("\"$key\":$answer")
|
|
434
|
+
done
|
|
435
|
+
decisions="{$(IFS=,; echo "${parts[*]}")}"
|
|
436
|
+
fi
|
|
264
437
|
fi
|
|
438
|
+
|
|
439
|
+
_graph_defaults_node "$template" "$graph_file" "$fingerprint_file" apply "$decisions"
|
|
265
440
|
}
|
|
266
441
|
|
|
267
442
|
# ---------------------------------------------------------------------------
|
|
@@ -140,7 +140,7 @@
|
|
|
140
140
|
"scope": "project",
|
|
141
141
|
"consumer": "installer",
|
|
142
142
|
"summary": "Install default graph-view styling (.obsidian/graph.json)",
|
|
143
|
-
"detail": "Asked by install-obsidian.sh. true installs and
|
|
143
|
+
"detail": "Asked by install-obsidian.sh. true installs .obsidian/graph.json and thereafter keeps it refreshed per template key (search, colorGroups, and the boilerplate display-flag keys) via a sidecar fingerprint file, .obsidian/.graph-defaults-fingerprint.json: a key untouched since the last delivery is silently refreshed to the current template value, a key the user has diverged from gets a one-time interactive prompt asking whether to update it to the new default (a decline is sticky and not re-asked until that key's template value itself changes again), and non-interactive runs never prompt and never record a decline. Force/layout keys (centerStrength, repelStrength, etc.) are never part of the template and are always left untouched regardless of this key. false means the installer stops offering the feature at all until the key is changed or removed via /bootstrap-config. This preference is independent of obsidian.plugins — accepting or declining one has no effect on the other. The file lives inside this project's own .obsidian/ directory, which is why this key is project scope, matching obsidian.plugins's scope choice.",
|
|
144
144
|
"values": "true | false",
|
|
145
145
|
"default": null,
|
|
146
146
|
"askedBy": "install-obsidian.sh"
|
|
@@ -68,12 +68,14 @@ list_base() {
|
|
|
68
68
|
# line (or EOF) in .git/info/exclude — expected values are .serena/, raw/,
|
|
69
69
|
# wiki/, and (skipped below by the `-d` check) the two bootstrap-prefs files.
|
|
70
70
|
sentinel_entries() {
|
|
71
|
-
|
|
71
|
+
common_dir=$(git rev-parse --git-common-dir 2>/dev/null) || return 0
|
|
72
|
+
exclude_file="$common_dir/info/exclude"
|
|
73
|
+
[ -f "$exclude_file" ] || return 0
|
|
72
74
|
awk -v sentinel="$SENTINEL" '
|
|
73
75
|
$0 == sentinel { in_block = 1; next }
|
|
74
76
|
in_block && /^[[:space:]]*#/ { in_block = 0 }
|
|
75
77
|
in_block { print }
|
|
76
|
-
'
|
|
78
|
+
' "$exclude_file"
|
|
77
79
|
}
|
|
78
80
|
|
|
79
81
|
list_reincluded() {
|
|
@@ -87,9 +89,9 @@ list_reincluded() {
|
|
|
87
89
|
[ -d "$dir" ] || continue
|
|
88
90
|
|
|
89
91
|
if have_rg; then
|
|
90
|
-
rg --files --no-ignore "$dir"
|
|
92
|
+
rg --files --no-ignore --follow "$dir"
|
|
91
93
|
else
|
|
92
|
-
find "$dir" -type f | sed 's|^\./||'
|
|
94
|
+
find -L "$dir" -type f | sed 's|^\./||'
|
|
93
95
|
fi
|
|
94
96
|
done
|
|
95
97
|
}
|
|
@@ -28,5 +28,5 @@ Active files are **never moved** after creation; state lives in the `status:` fr
|
|
|
28
28
|
active ──▶ done
|
|
29
29
|
```
|
|
30
30
|
|
|
31
|
-
- **active** — at least one unchecked item remains. Items are added
|
|
31
|
+
- **active** — at least one unchecked item remains. Items are added by editing the roadmap file directly, at creation via `/roadmap-create`, or via `/task-add --roadmap ROADMAP-NNN` (auto-links a new task); task-linked items auto-check when their task completes.
|
|
32
32
|
- **done** — every checklist item is checked. Completion is implicit; flip `status` to `done` when the last box is ticked.
|
package/lib/skills/README.md
CHANGED
|
@@ -40,8 +40,8 @@ Most skills operate on the LLM Wiki (`wiki/`, `raw/`) described in the root `CLA
|
|
|
40
40
|
| Skill | Purpose |
|
|
41
41
|
|-------|---------|
|
|
42
42
|
| `roadmap-create` | Create an execution-plan roadmap via short Socratic Q&A — goal, phases, hybrid task-link/inline checklist |
|
|
43
|
-
| `roadmap-
|
|
44
|
-
| `roadmap-next` | Point at the first unchecked
|
|
43
|
+
| `roadmap-assess` | Survey all active roadmaps together — cross-roadmap dependencies, prioritized list, status update per roadmap |
|
|
44
|
+
| `roadmap-next` | Point at the first unchecked item(s) in a single roadmap (argument required), grouped into parallelizable waves; auto-archive when fully checked |
|
|
45
45
|
|
|
46
46
|
## Tasks
|
|
47
47
|
|
|
@@ -31,7 +31,25 @@ Before committing, run the `/lint` workflow to catch and fix any diagnostics:
|
|
|
31
31
|
2. If any fixes were applied, they will be included in the commit automatically
|
|
32
32
|
3. If any issues were skipped (unfixable), warn the user before proceeding
|
|
33
33
|
|
|
34
|
-
## Step 2:
|
|
34
|
+
## Step 2: Condense Verbose Inline Comments
|
|
35
|
+
|
|
36
|
+
Scan every line this commit **adds or modifies** for comments more verbose than necessary, and rewrite them to the shortest form that keeps the essential point — ideally one line.
|
|
37
|
+
|
|
38
|
+
**Scope: diff-only, not whole-file.** Run `git diff HEAD` and look only at `+` lines. A comment already sitting untouched elsewhere in a file is out of scope — never touch a comment this commit did not add or modify.
|
|
39
|
+
|
|
40
|
+
**Never touch — leave exactly as-is:**
|
|
41
|
+
- **Structured documentation comments**, in any language: JSDoc/TSDoc (`/** ... */`, especially with `@param`/`@returns`/`@throws`/`@example`), Python docstrings (`"""..."""`/`'''...'''` directly under a `def`/`class`), Rust doc comments (`///`, `//!`), Go doc comments (the block directly above an exported declaration, starting with that declaration's own name), Java/C# Javadoc/XMLDoc blocks. These document an API's contract, not implementation rationale — condensing them destroys structure a doc generator or IDE tooltip depends on.
|
|
42
|
+
- **Repo-documented comment exceptions.** Before editing a file, check whether the target repo's own `CLAUDE.md` (nearest one up the directory tree) explicitly carves out a comment-density exception for that file or directory (e.g. this repo's own `CLAUDE.md`: `lib/hooks/*.js` carries inline rationale comments "by deliberate exception... do not strip them"). Skip any file covered by such an exception entirely.
|
|
43
|
+
- Comments already a single concise line.
|
|
44
|
+
|
|
45
|
+
**Condense everything else:**
|
|
46
|
+
- If a comment restates what the code already makes obvious (the *what*) with no *why* — delete it entirely. Matches this repo's own default: "if removing the comment wouldn't confuse a future reader, don't write it."
|
|
47
|
+
- If it explains a genuinely non-obvious *why* (a workaround, a hidden constraint, a subtle invariant) but spans more lines or words than necessary, rewrite it to the single shortest sentence that preserves that reason.
|
|
48
|
+
- Preserve the comment's position (same line for a trailing comment, same location for a block comment) and its language's comment syntax — only the wording and line count change.
|
|
49
|
+
|
|
50
|
+
Use `Edit` per file for every change — never `sed`/`awk`/shell rewrites.
|
|
51
|
+
|
|
52
|
+
## Step 3: Assess Changes
|
|
35
53
|
|
|
36
54
|
**Always run all three commands fresh.** Do not rely on session context, prior output, or anything produced earlier in the conversation — those reflect only a subset of what may have changed. The commit message must be based on the complete current working-tree state.
|
|
37
55
|
|
|
@@ -41,7 +59,7 @@ Run all three in parallel:
|
|
|
41
59
|
- `git diff HEAD` — see exact diffs for ALL staged and unstaged changes
|
|
42
60
|
- `git log --oneline -10` — see recent commit history for context
|
|
43
61
|
|
|
44
|
-
## Step
|
|
62
|
+
## Step 4: Summarize Changes and Recommend Semver Bump
|
|
45
63
|
|
|
46
64
|
Before touching any files or committing, output a summary block like this:
|
|
47
65
|
|
|
@@ -64,9 +82,9 @@ Use these semver rules to determine the bump:
|
|
|
64
82
|
| **minor** | New features or capabilities that are backward-compatible; new commands, skills, config options, or APIs added without breaking existing ones |
|
|
65
83
|
| **major** | Breaking changes — removed or renamed commands/APIs/config keys, changed behavior that callers must update for, deleted files that others depend on |
|
|
66
84
|
|
|
67
|
-
Print the summary. What happens next is decided by `gitCommit.versionBump` from Step 0 — see the table in Step
|
|
85
|
+
Print the summary. What happens next is decided by `gitCommit.versionBump` from Step 0 — see the table in Step 5. **Do not ask for confirmation here**; the only value that asks is `confirm`, and it asks in Step 5 where the manifest list is known.
|
|
68
86
|
|
|
69
|
-
## Step
|
|
87
|
+
## Step 5: Bump Version in Project Files
|
|
70
88
|
|
|
71
89
|
### Gate: `gitCommit.versionBump`
|
|
72
90
|
|
|
@@ -77,7 +95,7 @@ Its grammar is `auto | confirm | never` — there is deliberately **no `ask` val
|
|
|
77
95
|
| `auto` | Today's behavior. Detect every manifest and apply the bump to all of them, no confirmation. | **written** |
|
|
78
96
|
| `confirm` — approved | Bump exactly as `auto` does. | **written** |
|
|
79
97
|
| `confirm` — declined | Edit no manifest. | **omitted** |
|
|
80
|
-
| `never` | Touch **no** version file at all. Skip straight to Step
|
|
98
|
+
| `never` | Touch **no** version file at all. Skip straight to Step 6. | **omitted** |
|
|
81
99
|
| `unset` | Behave exactly as `auto` — that is today's behavior and an unanswered key must never change it. | **written** |
|
|
82
100
|
|
|
83
101
|
`confirm` prints the suggested bump **and the full list of manifest files that would change**, then asks once with `AskUserQuestion` before editing anything. Ask **every run** and **never persist the answer** — the standing choice is "keep asking me", so recording a reply would destroy it.
|
|
@@ -97,7 +115,7 @@ Report lines, each at most once per run:
|
|
|
97
115
|
|
|
98
116
|
Anything else stored under this key is a value from a newer bootstrap that this skill has no branch for: treat it as `unset`, and say which value you did not recognize.
|
|
99
117
|
|
|
100
|
-
For `auto`, `confirm`-approved, and `unset`, continue below. For `never` and `confirm`-declined, go to Step
|
|
118
|
+
For `auto`, `confirm`-approved, and `unset`, continue below. For `never` and `confirm`-declined, go to Step 6.
|
|
101
119
|
|
|
102
120
|
Find and update version numbers in project files.
|
|
103
121
|
|
|
@@ -118,7 +136,7 @@ Filter results:
|
|
|
118
136
|
|
|
119
137
|
**There is no "root only" rule.** A manifest anywhere in the tree counts. Monorepo layouts with no root-level manifest are normal — update every package found.
|
|
120
138
|
|
|
121
|
-
If **no files with a version field** are found anywhere in the repo, skip this step entirely and proceed to Step
|
|
139
|
+
If **no files with a version field** are found anywhere in the repo, skip this step entirely and proceed to Step 6.
|
|
122
140
|
|
|
123
141
|
### Bumping rules
|
|
124
142
|
|
|
@@ -134,7 +152,7 @@ Pre-release tags (e.g. `1.0.0-beta.1`) — strip the pre-release suffix and appl
|
|
|
134
152
|
|
|
135
153
|
Edit **every file** that contains a version using the Edit tool — do not stop at one. Then include all version-bump edits in the commit automatically (no separate commit needed).
|
|
136
154
|
|
|
137
|
-
## Step
|
|
155
|
+
## Step 6: Commit
|
|
138
156
|
|
|
139
157
|
### ⛔ Never create a branch — commit on the current branch
|
|
140
158
|
|
|
@@ -144,7 +162,7 @@ Edit **every file** that contains a version using the Edit tool — do not stop
|
|
|
144
162
|
- **ALWAYS use the `git-commit` bash alias.** Never use `git add` or `git commit` directly.
|
|
145
163
|
- Always commit ALL files unless they are in `.gitignore`
|
|
146
164
|
- Consider an appropriate commit message, let's call it `$message`
|
|
147
|
-
- Prefix the subject with the bump type in brackets — `[patch]`, `[minor]`, or `[major]` — **only if Step
|
|
165
|
+
- Prefix the subject with the bump type in brackets — `[patch]`, `[minor]`, or `[major]` — **only if Step 5 actually bumped a version**. If it did not (`never`, `confirm`-declined, or no manifest in the repo), the subject starts with the description and carries no bracket prefix
|
|
148
166
|
- Run: `git-commit "$message"`
|
|
149
167
|
|
|
150
168
|
### ⛔ No agent attribution — the user is the sole author
|
|
@@ -166,7 +184,7 @@ git-commit "[patch] Single-line subject describing the change"
|
|
|
166
184
|
git-commit "Single-line subject describing the change"
|
|
167
185
|
```
|
|
168
186
|
|
|
169
|
-
That's it. One pair of double quotes. One line. One argument. The only difference between the two forms is whether Step
|
|
187
|
+
That's it. One pair of double quotes. One line. One argument. The only difference between the two forms is whether Step 5 bumped a version.
|
|
170
188
|
|
|
171
189
|
**❌ Forbidden — every one of these patterns triggers an approval prompt:**
|
|
172
190
|
|
|
@@ -225,13 +243,13 @@ If the change feels too complex to summarize in one line, **make the subject mor
|
|
|
225
243
|
- ✅ `Allow standard tools for markdown editing; ban bash exploration commands` (no bump this run — the subject still carries its weight)
|
|
226
244
|
- ❌ `Update commands` (too vague — and vague is vague with or without a prefix)
|
|
227
245
|
- ❌ `[patch] Fix bug` (too vague)
|
|
228
|
-
- ❌ `[patch] Fix the login redirect` **when Step
|
|
246
|
+
- ❌ `[patch] Fix the login redirect` **when Step 5 bumped nothing** (the prefix is false)
|
|
229
247
|
|
|
230
248
|
Detailed reasoning, before/after examples, and rationale belong in **PR descriptions**, not in commit message bodies. The commit subject is the index entry; the PR is the encyclopedia.
|
|
231
249
|
|
|
232
|
-
## Step
|
|
250
|
+
## Step 7: Push (gated on `gitCommit.autoPush`)
|
|
233
251
|
|
|
234
|
-
Runs only after the commit in Step
|
|
252
|
+
Runs only after the commit in Step 6 succeeded. A failed commit means there is nothing to push.
|
|
235
253
|
|
|
236
254
|
| Value | What to do |
|
|
237
255
|
|-------|------------|
|
|
@@ -242,14 +260,14 @@ Runs only after the commit in Step 5 succeeded. A failed commit means there is n
|
|
|
242
260
|
|
|
243
261
|
### ⛔ The push is the plainest possible push
|
|
244
262
|
|
|
245
|
-
- **The Step
|
|
263
|
+
- **The Step 6 branch rule is unchanged and still absolute.** Never run `git branch`, `git checkout -b`, or `git switch -c`. Pushing an existing branch is all this step ever does.
|
|
246
264
|
- Never pass `--force`, `--force-with-lease`, `--set-upstream`/`-u`, `--all`, or `--tags`, and never name a different remote or refspec. Plain `git push`.
|
|
247
265
|
- If the push fails for any reason — no upstream configured, no remote, rejected non-fast-forward, no credentials — **stop and report it**. The commit already succeeded and is safe; do not retry with extra flags, do not set an upstream, and do not attempt to reconcile with a pull or rebase.
|
|
248
266
|
|
|
249
|
-
## Step
|
|
267
|
+
## Step 8: Final report
|
|
250
268
|
|
|
251
269
|
One short report at the end. Include, in this order:
|
|
252
270
|
|
|
253
271
|
1. The commit subject that was written.
|
|
254
|
-
2. Any of the once-only preference notes from Steps
|
|
272
|
+
2. Any of the once-only preference notes from Steps 5 and 7 that apply. Each appears **at most once per run**, here — not inline, and not repeated per file.
|
|
255
273
|
3. The push outcome (pushed / not pushed and why / push failed and how).
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: roadmap-assess
|
|
3
|
+
description: Survey all active roadmaps together — parse status and progress, detect cross-roadmap dependencies, and produce a single prioritized list with a status update for each roadmap
|
|
4
|
+
category: researching
|
|
5
|
+
model: claude-sonnet-5
|
|
6
|
+
disable-model-invocation: false
|
|
7
|
+
user-invocable: true
|
|
8
|
+
---
|
|
9
|
+
**Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
|
|
10
|
+
|
|
11
|
+
# Roadmap Assessment
|
|
12
|
+
|
|
13
|
+
Assess every active roadmap in `wiki/work/roadmaps/` together — this is the multi-roadmap counterpart to `/roadmap-next`, which now operates on exactly one roadmap you've already picked. Use this skill first when several roadmaps are active and you need to decide which to work next, based on the priority of the functionality each one delivers and the dependencies between them.
|
|
14
|
+
|
|
15
|
+
This skill is read-mostly: it never upgrades inline placeholders to task files and never touches checkboxes. Materializing and working items is `/roadmap-next`'s job once a roadmap has been selected.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Step 1: Discover active roadmaps
|
|
20
|
+
|
|
21
|
+
`list_dir` `wiki/work/roadmaps/` for `.md` files **directly** in it (not `archive/`); skip `lifecycle.md`, `index.md`, `README.md`. None found → STOP: `No roadmaps found in wiki/work/roadmaps/. Use /roadmap-create <topic> to draft one.`
|
|
22
|
+
|
|
23
|
+
A single active roadmap is still worth assessing — don't short-circuit to `/roadmap-next`; the status update in Step 6c is useful on its own.
|
|
24
|
+
|
|
25
|
+
## Step 2: Parse every roadmap
|
|
26
|
+
|
|
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
|
+
|
|
29
|
+
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.
|
|
30
|
+
|
|
31
|
+
## Step 3: Auto-archive fully-complete roadmaps
|
|
32
|
+
|
|
33
|
+
For any roadmap where `total > 0` and `done == total`: run the **Archive 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 `archived`. Drop it from the set being ranked — a `done` roadmap has no priority left to weigh.
|
|
34
|
+
|
|
35
|
+
If every discovered roadmap was archived this step, STOP and report: `All roadmaps complete — archived: <list>. Nothing active to assess.`
|
|
36
|
+
|
|
37
|
+
## Step 4: Cross-roadmap dependency analysis
|
|
38
|
+
|
|
39
|
+
For every remaining roadmap's `task-link` items (skip `inline` items — no task file exists yet to inspect): `Read` the task file, find `## Dependencies` / `## Blocked by` / `depends_on::` / `blocks::` refs, extract `TASK-NNN` IDs.
|
|
40
|
+
|
|
41
|
+
For each referenced `TASK-NNN`, check whether it belongs to a *different* roadmap (scan the parsed item lists from Step 2 for that ID). If so, record a directed edge `blocking_roadmap → blocked_roadmap` (the roadmap holding the prerequisite task blocks the roadmap holding the dependent task).
|
|
42
|
+
|
|
43
|
+
Also note — but do not treat as a hard edge — soft relatedness: roadmaps sharing a `linked_requirements` or `linked_decisions` entry. If a shared linked decision's text explicitly states a sequence ("do X before Y", "requires X shipped first"), `Read` that decision file and promote it to a hard edge instead.
|
|
44
|
+
|
|
45
|
+
Deduplicate edges. Walk the graph via DFS to detect cycles — if found, flag them in Step 6d rather than silently picking a winner.
|
|
46
|
+
|
|
47
|
+
## Step 5: Rank roadmaps
|
|
48
|
+
|
|
49
|
+
Order the remaining roadmaps, highest priority first, using this precedence:
|
|
50
|
+
|
|
51
|
+
1. **Hard dependency order** (from Step 4) — a roadmap that blocks another always outranks the one it blocks. Never violate this to satisfy #2 or #3.
|
|
52
|
+
2. **Functional priority** — a judgment call from each roadmap's `## Goal`, `tags`, and any linked requirement's priority/severity field (`Read` it if present). Goals that unblock or protect other work (infra, security, load-bearing bug fixes) outrank polish or nice-to-have goals. Record a one-sentence rationale per roadmap in the report — this is a judgment call the user can override, not a fact.
|
|
53
|
+
3. **Momentum** (tie-break only — never overrides #1 or #2) — a higher `done/total` ratio ranks slightly higher; finishing in-flight work compounds value faster than starting a new thread.
|
|
54
|
+
|
|
55
|
+
If two or more roadmaps are genuinely indistinguishable on all three signals, keep their existing relative order (`ROADMAP-NNN` ascending) rather than guessing.
|
|
56
|
+
|
|
57
|
+
## Step 6: Report
|
|
58
|
+
|
|
59
|
+
Print, in this order:
|
|
60
|
+
|
|
61
|
+
### 6a. Archived this run (omit if `archived` is empty)
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
Archived to wiki/work/roadmaps/archive/ (fully complete):
|
|
65
|
+
• <filename> — done
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### 6b. Prioritized Roadmaps
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
## Prioritized Roadmaps
|
|
72
|
+
|
|
73
|
+
| Rank | Roadmap | Progress | Priority rationale | Depends on |
|
|
74
|
+
|------|---------|----------|---------------------|------------|
|
|
75
|
+
| 1 | ROADMAP-NNN — <title> | M/N | <one sentence> | — |
|
|
76
|
+
| 2 | ROADMAP-MMM — <title> | M/N | <one sentence> | ROADMAP-NNN (Phase X blocks it) |
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`Depends on` lists the hard-edge blockers found in Step 4, or `—` if none.
|
|
80
|
+
|
|
81
|
+
### 6c. Status update per roadmap
|
|
82
|
+
|
|
83
|
+
One block per roadmap, in ranked order:
|
|
84
|
+
|
|
85
|
+
```
|
|
86
|
+
### ROADMAP-NNN — <title>
|
|
87
|
+
- Owner: <owner, or "unassigned">
|
|
88
|
+
- Progress: M/N items checked
|
|
89
|
+
- Status: <active — on track | active — stalled | active — mostly inline placeholders, not yet materialized>
|
|
90
|
+
- Next: `/roadmap-next wiki/work/roadmaps/NNN-slug.md`
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
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.
|
|
94
|
+
|
|
95
|
+
### 6d. Dependency cycles (omit if none found)
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
## Warning: Dependency Cycle
|
|
99
|
+
|
|
100
|
+
ROADMAP-NNN → ROADMAP-MMM → ROADMAP-NNN
|
|
101
|
+
These roadmaps block each other — resolve the cycle manually before treating either as higher priority.
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Constraints
|
|
107
|
+
|
|
108
|
+
- Read-only except the Step 3 auto-archive procedure (status flip + `git mv` + index/log updates) — never flip checkboxes, never upgrade inline items, never create task files. That is `/roadmap-next`'s job once the user picks a roadmap to work.
|
|
109
|
+
- Permitted tools: `list_dir`, `find_file`, `Read`, `Edit`, `Bash` (only for `git mv` during archiving), `AskUserQuestion` (only if genuinely needed to disambiguate — this skill should normally run to completion without prompting).
|
|
110
|
+
- Never bash reads (`cat`/`find`/`grep`/`sed`/`ls`).
|
|
111
|
+
- Keep the report terse — no preamble, no closing summary beyond the tables above.
|
|
@@ -86,7 +86,7 @@ Then **per-phase**, in a single follow-up `AskUserQuestion` round (one question
|
|
|
86
86
|
|
|
87
87
|
| # | Elicitation | Quality bar |
|
|
88
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-
|
|
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 by editing the roadmap file directly or via `/task-add --roadmap ROADMAP-NNN` — but **at least one phase must contain at least one item** (a roadmap with zero items is not a roadmap) |
|
|
90
90
|
|
|
91
91
|
When the user supplies a task reference:
|
|
92
92
|
|
|
@@ -191,7 +191,7 @@ Print a tabular summary:
|
|
|
191
191
|
| Index updated | yes (1 row added) |
|
|
192
192
|
| 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 |
|
|
193
193
|
|
|
194
|
-
If any phase was left empty by design (user plans to fill via `/roadmap-
|
|
194
|
+
If any phase was left empty by design (user plans to fill it in later by editing the roadmap file directly or via `/task-add --roadmap ROADMAP-NNN`), note it in a separate **Gaps** section so the user can address it before execution begins.
|
|
195
195
|
|
|
196
196
|
If the roadmap contains any inline placeholder items (items without a task-link), include a **Placeholders** section listing them:
|
|
197
197
|
|
|
@@ -1,35 +1,53 @@
|
|
|
1
1
|
---
|
|
2
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
|
|
3
|
+
description: Point at the first unchecked item(s) in a single roadmap; create task files for inline placeholders; group items into parallelizable waves; auto-archive when fully checked. Requires a roadmap argument — run /roadmap-assess first to see status and priority across all active roadmaps.
|
|
4
4
|
category: researching
|
|
5
5
|
model: claude-haiku-4-5-20251001
|
|
6
|
-
argument-hint:
|
|
6
|
+
argument-hint: <path to roadmap file, NNN-slug, or number>
|
|
7
7
|
disable-model-invocation: false
|
|
8
8
|
user-invocable: true
|
|
9
9
|
---
|
|
10
|
+
|
|
10
11
|
**Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
|
|
11
12
|
|
|
12
13
|
# Next Step
|
|
13
14
|
|
|
14
|
-
Surface unchecked roadmap
|
|
15
|
+
Surface unchecked items in a single roadmap, grouped into parallelizable waves, and tell the user how to act. When the roadmap has all items checked, flip its status to `done` and move it to `archive/`.
|
|
15
16
|
|
|
16
17
|
**Roadmap Input**: $ARGUMENTS
|
|
17
18
|
|
|
18
|
-
## Step 0:
|
|
19
|
-
|
|
20
|
-
|
|
19
|
+
## Step 0: Require an argument
|
|
20
|
+
|
|
21
|
+
This skill operates on exactly one roadmap — it no longer scans across all roadmaps. If `$ARGUMENTS` is empty, **stop** and report:
|
|
22
|
+
|
|
23
|
+
> `/roadmap-next` requires a roadmap (path, `NNN-slug`, or number). Run `/roadmap-assess` to see a prioritized status update across all active roadmaps, then re-run `/roadmap-next <ROADMAP-NNN>` on the one you want to work.
|
|
24
|
+
|
|
25
|
+
## Step 1: Resolve the file (`find_file`/`list_dir`, never bash)
|
|
26
|
+
|
|
27
|
+
| Input | Action |
|
|
28
|
+
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
29
|
+
| File path | confirm exists (`find_file`); missing → `Roadmap file not found: <path>` + STOP |
|
|
30
|
+
| `NNN-slug` | match in `wiki/work/roadmaps/`; none → `No roadmap matching '<input>' found…` + STOP |
|
|
31
|
+
| Number (`1`/`001`) | `list_dir`, match zero-padded prefix; ambiguous → list + `AskUserQuestion`; none → `No roadmap with number '<input>' found.` + STOP |
|
|
32
|
+
|
|
33
|
+
## Step 2: Parse → upgrade inline items → parallelism analysis
|
|
34
|
+
|
|
35
|
+
Run the three shared procedures below, in order, on the resolved file.
|
|
21
36
|
|
|
22
37
|
---
|
|
23
38
|
|
|
24
|
-
## Shared procedures (used by
|
|
39
|
+
## Shared procedures (also used by `/roadmap-assess`)
|
|
25
40
|
|
|
26
41
|
### Parse a roadmap
|
|
42
|
+
|
|
27
43
|
`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
44
|
|
|
29
45
|
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
46
|
|
|
31
47
|
### Upgrade inline items to task files
|
|
48
|
+
|
|
32
49
|
**All roadmap items must eventually be task files** — inline items are placeholders. For each `candidate_items` item with `kind == 'inline'`:
|
|
50
|
+
|
|
33
51
|
1. Announce: `Inline item found: "<text>"[ (in <roadmap_title>)] — checking for an existing task before creating one.`
|
|
34
52
|
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
53
|
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).
|
|
@@ -40,9 +58,11 @@ For each `candidate_items` item that is already `kind == 'task-link'` (skip this
|
|
|
40
58
|
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
59
|
|
|
42
60
|
### Parallelism analysis → waves
|
|
61
|
+
|
|
43
62
|
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
63
|
|
|
45
64
|
### Archive a fully-complete roadmap (`total > 0` and `done == total`) — run automatically, no prompt
|
|
65
|
+
|
|
46
66
|
1. If `status: active`, `Edit` → `status: done`.
|
|
47
67
|
2. Remove its row from `wiki/work/roadmaps/index.md` (active-only index).
|
|
48
68
|
3. `git mv <roadmap_path> wiki/work/roadmaps/archive/<filename>` (Bash — `git mv` only).
|
|
@@ -55,21 +75,11 @@ After upgrades, for each item: `Read` its `task_path`, find `## Dependencies` /
|
|
|
55
75
|
|
|
56
76
|
---
|
|
57
77
|
|
|
58
|
-
##
|
|
78
|
+
## Step 3: Report
|
|
59
79
|
|
|
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
80
|
- **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
81
|
- **Unchecked items remain** → progress line + one table per non-empty wave (every item is a task-link post-upgrade):
|
|
82
|
+
|
|
73
83
|
```
|
|
74
84
|
Progress: <done>/<total>
|
|
75
85
|
|
|
@@ -81,6 +91,7 @@ Run the three shared procedures on the resolved file.
|
|
|
81
91
|
**Wave 2** — start after Wave 1 completes: …
|
|
82
92
|
**Wave 3** — start after Wave 2 completes: …
|
|
83
93
|
```
|
|
94
|
+
|
|
84
95
|
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
96
|
|
|
86
97
|
**Action cell by `task_status`** (this is the fix for the tackle→UAT visibility gap — a `pending-uat` task needs testing, not more implementation):
|
|
@@ -88,44 +99,13 @@ Run the three shared procedures on the resolved file.
|
|
|
88
99
|
- `pending-uat` with `uat_path` resolved → `` `/uat-walk <uat_path>` `` — annotate the Item cell with a trailing `⏳ awaiting UAT`
|
|
89
100
|
- `pending-uat` with no `uat_path` → `` `/uat-generate <task_path>` `` — annotate the Item cell with a trailing `⏳ awaiting UAT (no tests yet)`
|
|
90
101
|
- `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
102
|
|
|
120
|
-
|
|
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`).
|
|
103
|
+
- **Zero items** → `Roadmap has no checklist items yet. Edit the roadmap file directly to add items, or link a new task to it with /task-add --roadmap <ROADMAP-NNN> <description>.`
|
|
125
104
|
|
|
126
105
|
---
|
|
127
106
|
|
|
128
107
|
## Constraints
|
|
108
|
+
|
|
129
109
|
- **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
110
|
- Permitted tools: `list_dir`, `find_file`, `Read`, `Edit`, `Bash`, `AskUserQuestion`, `Skill` (only for `task-add` on inline items).
|
|
131
111
|
- `Bash` only for `git mv` when archiving. Never bash reads (`cat`/`find`/`grep`/`sed`/`ls`).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@codewizard-dt/bootstrap",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "3.1.0",
|
|
4
4
|
"description": "Bootstrap Claude Code projects with an LLM Wiki, reusable skills, hooks, and MCP setup",
|
|
5
5
|
"homepage": "https://github.com/codewizard-dt/bootstrap-wiki#readme",
|
|
6
6
|
"bugs": {
|
|
@@ -1,238 +0,0 @@
|
|
|
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 `wiki/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 `wiki/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.
|