@codewizard-dt/bootstrap 2.21.0 → 3.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/scripts/README.md +6 -4
- package/lib/scripts/backfill-wiki-aliases.js +161 -0
- package/lib/scripts/install-obsidian.sh +69 -2
- package/lib/scripts/lib.sh +10 -4
- package/lib/scripts/templates/bootstrap-prefs-schema.json +12 -3
- package/lib/scripts/templates/file-suggestion.sh +6 -4
- package/lib/scripts/templates/obsidian/graph.json +23 -0
- package/lib/scripts/templates/wiki/work/bugs/archive/index.md +4 -0
- package/lib/scripts/templates/wiki/work/decisions/archive/index.md +4 -0
- package/lib/scripts/templates/wiki/work/requirements/archive/index.md +4 -0
- package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +4 -0
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +1 -1
- package/lib/scripts/templates/wiki/work/tasks/archive/index.md +4 -0
- package/lib/scripts/templates/wiki/work/uat/archive/index.md +4 -0
- package/lib/skills/README.md +2 -2
- package/lib/skills/bug-file/SKILL.md +1 -0
- package/lib/skills/decision-create/SKILL.md +5 -0
- package/lib/skills/req-create/SKILL.md +1 -0
- package/lib/skills/roadmap-assess/SKILL.md +111 -0
- package/lib/skills/roadmap-create/SKILL.md +3 -2
- package/lib/skills/roadmap-next/SKILL.md +32 -52
- package/lib/skills/task-add/SKILL.md +1 -0
- package/lib/skills/uat-generate/SKILL.md +1 -0
- package/package.json +1 -1
- package/lib/skills/roadmap-add/SKILL.md +0 -238
package/lib/scripts/README.md
CHANGED
|
@@ -20,11 +20,12 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
|
|
|
20
20
|
|
|
21
21
|
| Script | Used by | Purpose |
|
|
22
22
|
|--------|---------|---------|
|
|
23
|
-
| `lib.sh` | Every script above | Shared bash library: `resolve_project_dir` (path resolution + validation), `mcp_installed`/`serena_installed`/`detect_installed_mcps` (MCP state checks), `run_project_sync` (the common setup/update sequence: `install-global.sh --skip-mcps` first — hooks/skills/deny-list/hooks-wiring/fileSuggestion, offline-safe — then the guarded interactive MCP install, wiki scaffold, gitignore, MCP-tools guide, Serena bootstrap), and `prompt_yn`/`prompt_scope` (interactive prompt helpers). |
|
|
23
|
+
| `lib.sh` | Every script above | Shared bash library: `resolve_project_dir` (path resolution + validation), `mcp_installed`/`serena_installed`/`detect_installed_mcps` (MCP state checks), `run_project_sync` (the common setup/update sequence: `install-global.sh --skip-mcps` first — hooks/skills/deny-list/hooks-wiring/fileSuggestion, offline-safe — then the guarded interactive MCP install, wiki scaffold, gitignore, the wiki-alias backfill, Obsidian, MCP-tools guide, Serena bootstrap), and `prompt_yn`/`prompt_scope` (interactive prompt helpers). |
|
|
24
24
|
| `install-mcps.sh` | `install-global.sh`, `setup-project.sh`, `update-project.sh` | Installs Brave Search, Context7, Playwright, and (when a project dir is given) Serena. Two modes: non-interactive (`install-global.sh`'s default — installs everything missing at user scope) and `--interactive --project-dir <dir>` (prompts per-MCP and asks for scope, used by `setup`/`update`). Playwright has a dedicated conflict flow: registered as `playwright` (user scope) by default; when a project ships its own `playwright`, a git-tracked `.mcp.json` is never modified (interactive options: register ours as `playwright-shared` + disable the project entry machine-locally via `disabledMcpjsonServers` in `.claude/settings.local.json` / register alongside / skip), while a machine-local registration can be replaced or kept (ours then uses the alternate name). Non-interactive conflicts are left untouched with a hint. |
|
|
25
25
|
| `sync-wiki-scaffold.sh` | `setup-project.sh`, `update-project.sh`, `migrate-project.sh` | Scaffolds an **empty** wiki into the target project from `templates/wiki/`: creates `raw/` + all `wiki/` family directories, lifecycle docs, per-family `index.md`, and stub `index.md`/`log.md`. Copy-once for project-owned files; always-refreshes `conventions.md` and `lifecycle.md`. Delivers guides from `raw/guides/` tier-wise into `wiki/guides/`: `command-anti-patterns.md` required (always refreshed); `evals-framework.md` + `type-checking-templates/` optional (`--interactive` prompts on first delivery, sticky refresh once present — legacy `.docs/guides/` presence counts, opt out by deleting); migrates legacy `.docs/guides/` (template-owned files removed or relocated, deprecated `task-spec.md` deleted, empty dirs pruned). Also delivers the `## LLM Wiki` section and `.env` safety policy (copy-once, sentinel-guarded, from `templates/CLAUDE-wiki.md` / `templates/CLAUDE-env-safety.md`) into the target's `CLAUDE.md` — when a `CLAUDE.md` already exists without the schema, prompts whether to modify it or write `CLAUDE.local.md` instead (non-interactive default: `CLAUDE.local.md`). |
|
|
26
26
|
| `build-mcp-guide.sh` | `setup-project.sh`, `update-project.sh`, `migrate-project.sh` | Assembles `wiki/guides/mcp-tools.md` in the target project from the per-server stub files in `templates/guides/stubs/`, including only the sections for MCPs actually installed. |
|
|
27
27
|
| `bootstrap-serena.sh` | `setup-project.sh`, `update-project.sh` | Headlessly triggers `.serena/project.yml` creation via `claude --print` and enables the optional Serena tools needed by this template's workflow. Preflights `claude` and `python3`. |
|
|
28
|
+
| `backfill-wiki-aliases.js` | `lib.sh` (`run_project_sync`, unguarded — invoked via `node`, not direct exec) | Zero-dependency Node script that re-runs TASK-064's one-time sweep on every `setup`/`update`: scans every `wiki/work/<family>/` file (active + `archive/`, all 6 families) for one that carries `id:` but no `aliases:` yet, and inserts `aliases: [<id>]` immediately after the `id:` line. Idempotent and additive-only — a file that already has `aliases:` (inline or block-list form) is left completely untouched, never corrected or overwritten. Fixes drift (a hand-authored file, an older bootstrap checkout, a merge) that would otherwise leave a bare `[[TASK-NNN]]`-style wikilink dead in Obsidian — see `wiki/knowledge/sources/obsidian-alias-link-resolution.md` for why. Deliberately **out of scope: `wiki/knowledge/`** — a knowledge page's filename already equals its `id:` slug, so its wikilinks already resolve on Obsidian's plain filename match with no alias needed, and existing knowledge-page aliases are curated alternate names a script has no safe way to invent. Always exits 0 (same contract as `merge-settings-deny.js`/`merge-settings-hooks.js`) — warns and skips on anything unexpected rather than aborting the caller. |
|
|
28
29
|
| `merge-gitignore.sh` | `setup-project.sh`, `update-project.sh` | Fully interactive `.gitignore` merge — **nothing is ever added without asking**. The packaged template's titled sections are offered one by one (`Add/update .gitignore section '<title>' (N new line(s))? [y/N]`); sections with nothing new are skipped silently. Non-interactive runs (or no tty) change nothing at all. Never touches existing project content. Also offers (git repos only) to keep `.serena/`/`raw/`/`wiki/` out of git via **`.git/info/exclude`** — never `.gitignore`, which would blind Serena on the wiki (see `wiki/knowledge/concepts/git-ignore-tool-visibility.md`); per-machine and idempotent. `info/exclude` *is* honored by ripgrep-class walkers and the `@` file picker, so every machine-local exclusion this script manages — the wiki/agent-state dirs AND the `.claude/bootstrap-prefs.*` files, whichever of its prompts get answered and in whichever order — is written under **one shared, generic sentinel** (`# bootstrap machine-local (autocomplete-visible)`) that the `fileSuggestion` picker installed by `install-global.sh` reads back to restore `@`-autocomplete. The sentinel line itself is written proactively on every interactive run against a git repo, even if every exclude-affecting prompt is declined, so the anchor is always there regardless of which preferences got set; a project still carrying the old, separately-named pre-unification header is repaired onto the shared sentinel automatically. |
|
|
29
30
|
| `merge-settings-deny.js` | `install-global.sh` | Zero-dependency Node script that merges the canonical permission deny list (`templates/settings-deny.json` — `Bash(...)` command patterns plus `Edit(...)`/`Read(...)` file-tool patterns) into `~/.claude/settings.json` `permissions.deny`. Entries are opaque strings, so any rule form the permission system accepts merges unchanged. Additive union only: missing entries are appended, user entries are never removed or reordered, all other settings keys pass through untouched. Atomic write, preserves existing indentation, and always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. A second mode, `--set-key <name> --set-value <json>`, merges a single top-level settings key instead of the deny list (used to register `fileSuggestion`): absent → set; already deep-equal → no-op; present but different → one-line warning and skip, never a clobber. Supplying `--set-key` skips the deny merge entirely; a malformed `--set-value` exits 1, since that is a call-site bug rather than a user's file. |
|
|
30
31
|
| `merge-settings-hooks.js` | `install-global.sh` | Zero-dependency Node sibling of `merge-settings-deny.js` (deliberately not a new mode of it — different, block-and-entry-aware semantics) that merges the canonical hook wiring (`templates/settings-hooks.json`) into the `hooks` key of `~/.claude/settings.json` with a "template owns its blocks" model: repo-owned entries (a `command` under `~/.claude/hooks/` whose basename appears in the template) are created or updated in place; matcher drift on a pure-owned block is adopted (a matcher rename ships without duplicating the block); user/foreign blocks and entries are never modified, reordered, or removed; a repo hook found relocated into a mixed block is warned about but not duplicated; no empty placeholder blocks are ever written. Always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. |
|
|
@@ -367,7 +368,7 @@ real `lib/scripts/` file or one real `lib/skills/<name>/SKILL.md`, so
|
|
|
367
368
|
`"install-global.sh, /git-commit"` fails the suite by construction. Where a
|
|
368
369
|
run-time prompt exists, it is documented in the key's `detail`.
|
|
369
370
|
|
|
370
|
-
### The key registry — all
|
|
371
|
+
### The key registry — all 23 entries
|
|
371
372
|
|
|
372
373
|
Every key in `templates/bootstrap-prefs-schema.json`, grouped by `consumer` —
|
|
373
374
|
`installer` first, then `skill` — which is the same grouping and the same order
|
|
@@ -376,7 +377,7 @@ schema's `default` field; `unset` in that column means `default: null`, i.e. the
|
|
|
376
377
|
key resolves to `unset` until it is answered. This table is transcribed from the
|
|
377
378
|
JSON; if the two ever disagree, the JSON is right and this table is a bug.
|
|
378
379
|
|
|
379
|
-
#### `consumer: installer` —
|
|
380
|
+
#### `consumer: installer` — 17 entries, read by the setup/update scripts
|
|
380
381
|
|
|
381
382
|
| Key | Scope | Consumer | Values | Default | Asked by | What it does |
|
|
382
383
|
|-----|-------|----------|--------|---------|----------|--------------|
|
|
@@ -394,7 +395,8 @@ JSON; if the two ever disagree, the JSON is right and this table is a bug.
|
|
|
394
395
|
| `mcp.context7Scope` | global | installer | `user \| project` | `unset` | `lib.sh` | Registration scope for the Context7 MCP |
|
|
395
396
|
| `mcp.playwright` | global | installer | `true \| false` | `unset` | `install-mcps.sh` | Install the Playwright MCP for browser automation and UI testing |
|
|
396
397
|
| `obsidian.installApp` | global | installer | `true \| false` | `unset` | `install-obsidian.sh` | Install the Obsidian desktop app via the native package manager |
|
|
397
|
-
| `obsidian.plugins` | project | installer | `true \| false` | `unset` | `install-obsidian.sh` | Install the bundled Obsidian plugin set (Dataview, Graph Link Types, Breadcrumbs) |
|
|
398
|
+
| `obsidian.plugins` | project | installer | `true \| false` | `unset` | `install-obsidian.sh` | Install the bundled Obsidian plugin set (Dataview, Graph Link Types, Breadcrumbs, Front Matter Title, Alias Linker) |
|
|
399
|
+
| `obsidian.graphDefaults` | project | installer | `true \| false` | `unset` | `install-obsidian.sh` | Install default graph-view styling (`.obsidian/graph.json`) |
|
|
398
400
|
| `skills.pruneOrphans` | global | installer | `true \| false` | `unset` | `install-global.sh` | Delete stale skill folders in `~/.claude/skills/` left by the wiki rename |
|
|
399
401
|
|
|
400
402
|
The two **(pattern)** rows carry `"dynamic": true` and are key *families*, not
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Backfill `aliases: [<id>]` onto every wiki/work/ work-item file that has an
|
|
3
|
+
// id: field but no aliases: field yet — a repeatable version of TASK-064's
|
|
4
|
+
// one-time sweep (see
|
|
5
|
+
// wiki/work/tasks/archive/TASK-064-backfill-work-item-aliases.md), run on
|
|
6
|
+
// every setup/update so drift (a hand-authored file, an older bootstrap
|
|
7
|
+
// checkout, a merge) gets corrected automatically instead of silently
|
|
8
|
+
// reintroducing dead Obsidian wikilinks. Root cause is documented in
|
|
9
|
+
// wiki/knowledge/sources/obsidian-alias-link-resolution.md: Obsidian's
|
|
10
|
+
// wikilink click-resolver matches only real filenames, never frontmatter, so
|
|
11
|
+
// a work-item file named "<ID>-slug.md" never resolves a bare "[[<ID>]]"
|
|
12
|
+
// link unless its frontmatter carries a matching alias (the Alias Linker
|
|
13
|
+
// plugin, bundled by install-obsidian.sh, is what makes that fallback work).
|
|
14
|
+
//
|
|
15
|
+
// SCOPE: wiki/work/<family>/ only (requirements, decisions, roadmaps, tasks,
|
|
16
|
+
// uat, bugs), both the active directory and archive/. Knowledge pages
|
|
17
|
+
// (wiki/knowledge/) are deliberately NOT covered — a knowledge page's
|
|
18
|
+
// filename already equals its id: slug (e.g. serena-mcp-scope.md has
|
|
19
|
+
// id: serena-mcp-scope), so every existing `[[serena-mcp-scope]]`-style link
|
|
20
|
+
// already resolves on Obsidian's plain filename match, the very first step
|
|
21
|
+
// of resolution, before aliases: is ever consulted. Knowledge-page aliases
|
|
22
|
+
// are curated alternate names (e.g. id: andrej-karpathy -> aliases:
|
|
23
|
+
// [Karpathy]) added at ingest time by human/LLM judgment, not a mechanical
|
|
24
|
+
// function of id: or title: — a script has no safe value to invent there.
|
|
25
|
+
//
|
|
26
|
+
// IDEMPOTENT AND ADDITIVE-ONLY: a file that already has an aliases: field
|
|
27
|
+
// (any value) is left untouched — this only fills a gap, it never corrects
|
|
28
|
+
// or overwrites an existing alias.
|
|
29
|
+
//
|
|
30
|
+
// Always exits 0 — the caller (lib.sh's run_project_sync) must never abort a
|
|
31
|
+
// setup/update over a wiki content backfill. Warns to stderr and skips on
|
|
32
|
+
// anything unexpected (a project with no wiki/work/ yet, an unreadable or
|
|
33
|
+
// unwritable file, a malformed id: line) rather than failing.
|
|
34
|
+
//
|
|
35
|
+
// Usage: backfill-wiki-aliases.js <path-to-project>
|
|
36
|
+
|
|
37
|
+
'use strict';
|
|
38
|
+
|
|
39
|
+
const fs = require('fs');
|
|
40
|
+
const path = require('path');
|
|
41
|
+
|
|
42
|
+
const FAMILIES = ['requirements', 'decisions', 'roadmaps', 'tasks', 'uat', 'bugs'];
|
|
43
|
+
const EXCLUDED_BASENAMES = new Set(['index.md', 'lifecycle.md', '.gitkeep']);
|
|
44
|
+
|
|
45
|
+
/** Recursively collect every .md file under `dir` (active + archive/, since
|
|
46
|
+
* archive/ lives inside each family dir), skipping excluded meta filenames
|
|
47
|
+
* and the wiki/work/uat/screenshots/ directory (not a work-item directory). */
|
|
48
|
+
function collectMarkdownFiles(dir) {
|
|
49
|
+
if (!fs.existsSync(dir)) return [];
|
|
50
|
+
const out = [];
|
|
51
|
+
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
|
52
|
+
if (entry.name === 'screenshots') continue; // wiki/work/uat/screenshots/
|
|
53
|
+
const full = path.join(dir, entry.name);
|
|
54
|
+
if (entry.isDirectory()) {
|
|
55
|
+
out.push(...collectMarkdownFiles(full));
|
|
56
|
+
} else if (entry.isFile() && entry.name.endsWith('.md') && !EXCLUDED_BASENAMES.has(entry.name)) {
|
|
57
|
+
out.push(full);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
return out;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** Extract the frontmatter block from a file's text as
|
|
64
|
+
* { open, block, close, index }, where `index` is the offset of `open` in
|
|
65
|
+
* `text` and `open + block + close` is the exact original frontmatter
|
|
66
|
+
* substring (delimiters included) — enough to splice a change back in
|
|
67
|
+
* without disturbing anything before or after it. Returns null if the file
|
|
68
|
+
* has no `---`-delimited frontmatter at all. */
|
|
69
|
+
function extractFrontmatter(text) {
|
|
70
|
+
const match = text.match(/^(---\r?\n)([\s\S]*?\r?\n)(---\r?\n)/);
|
|
71
|
+
if (!match) return null;
|
|
72
|
+
return { open: match[1], block: match[2], close: match[3], index: match.index };
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
function parseId(block) {
|
|
76
|
+
const match = block.match(/^id:\s*(\S+)\s*$/m);
|
|
77
|
+
return match ? match[1] : null;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
function hasAliases(block) {
|
|
81
|
+
return /^aliases:/m.test(block);
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** Insert `aliases: [<id>]` as a new line immediately after the id: line
|
|
85
|
+
* inside the frontmatter block, preserving the file's own line-ending style.
|
|
86
|
+
* Returns the whole updated file text, or null if the id: line could not be
|
|
87
|
+
* located inside the block (should not happen once parseId succeeded, but
|
|
88
|
+
* guarded rather than assumed). */
|
|
89
|
+
function insertAliases(text, fm, id) {
|
|
90
|
+
const eol = fm.open.includes('\r\n') ? '\r\n' : '\n';
|
|
91
|
+
const newBlock = fm.block.replace(/^(id:\s*\S+\s*)$/m, (line) => `${line}${eol}aliases: [${id}]`);
|
|
92
|
+
if (newBlock === fm.block) return null;
|
|
93
|
+
const before = text.slice(0, fm.index);
|
|
94
|
+
const after = text.slice(fm.index + fm.open.length + fm.block.length + fm.close.length);
|
|
95
|
+
return `${before}${fm.open}${newBlock}${fm.close}${after}`;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
function backfillProject(projectDir) {
|
|
99
|
+
const workRoot = path.join(projectDir, 'wiki', 'work');
|
|
100
|
+
if (!fs.existsSync(workRoot)) {
|
|
101
|
+
console.log(' wiki/work/ not found — nothing to backfill.');
|
|
102
|
+
return;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
let totalUpdated = 0;
|
|
106
|
+
for (const family of FAMILIES) {
|
|
107
|
+
const files = collectMarkdownFiles(path.join(workRoot, family));
|
|
108
|
+
|
|
109
|
+
for (const file of files) {
|
|
110
|
+
let text;
|
|
111
|
+
try {
|
|
112
|
+
text = fs.readFileSync(file, 'utf8');
|
|
113
|
+
} catch (err) {
|
|
114
|
+
console.error(` Warning: could not read ${path.relative(projectDir, file)} (${err.message})`);
|
|
115
|
+
continue;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
const fm = extractFrontmatter(text);
|
|
119
|
+
if (!fm) continue; // no frontmatter — not a work-item file
|
|
120
|
+
const id = parseId(fm.block);
|
|
121
|
+
if (id === null) continue; // meta-like file with no id: — nothing to backfill
|
|
122
|
+
if (hasAliases(fm.block)) continue; // already has aliases: — idempotent skip
|
|
123
|
+
|
|
124
|
+
const next = insertAliases(text, fm, id);
|
|
125
|
+
if (next === null) {
|
|
126
|
+
console.error(` Warning: could not locate an id: line to backfill in ${path.relative(projectDir, file)}`);
|
|
127
|
+
continue;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
try {
|
|
131
|
+
fs.writeFileSync(file, next);
|
|
132
|
+
} catch (err) {
|
|
133
|
+
console.error(` Warning: could not write ${path.relative(projectDir, file)} (${err.message})`);
|
|
134
|
+
continue;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
console.log(` + aliases: [${id}] -> ${path.relative(projectDir, file)}`);
|
|
138
|
+
totalUpdated++;
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
if (totalUpdated === 0) {
|
|
143
|
+
console.log(' wiki/work/ aliases: all work-item files already up to date.');
|
|
144
|
+
} else {
|
|
145
|
+
console.log(` wiki/work/ aliases: backfilled ${totalUpdated} file${totalUpdated === 1 ? '' : 's'}.`);
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
const projectDir = process.argv[2];
|
|
150
|
+
if (!projectDir) {
|
|
151
|
+
console.error('Usage: backfill-wiki-aliases.js <path-to-project>');
|
|
152
|
+
process.exit(0); // never abort the caller over a usage slip either
|
|
153
|
+
} else {
|
|
154
|
+
try {
|
|
155
|
+
backfillProject(projectDir);
|
|
156
|
+
} catch (err) {
|
|
157
|
+
console.error(` Warning: wiki alias backfill failed unexpectedly (${err.message}) — skipping.`);
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
process.exit(0);
|
|
@@ -26,6 +26,24 @@ PLUGIN_GRAPH_LINK_TYPES="natefrisch01/Graph-Link-Types"
|
|
|
26
26
|
# Breadcrumbs — verify SkepticMystic/breadcrumbs is still the maintained fork
|
|
27
27
|
# at install time (vs. a community fork) before relying on this constant.
|
|
28
28
|
PLUGIN_BREADCRUMBS="SkepticMystic/breadcrumbs"
|
|
29
|
+
# Displays a note's frontmatter `title` (matching this repo's own convention
|
|
30
|
+
# on every index.md and knowledge page) in place of the bare filename across
|
|
31
|
+
# the file explorer, tabs, search, and — the reason it's bundled here — the
|
|
32
|
+
# graph view. Installed/enabled like the other three, but
|
|
33
|
+
# its own per-surface toggles (Explorer, Graph, etc.) default OFF inside the
|
|
34
|
+
# plugin's own settings and are NOT scripted here: its internal data.json
|
|
35
|
+
# settings schema is undocumented/unversioned, so hardcoding it would be the
|
|
36
|
+
# same class of silent-failure risk BUG-0011 already taught this file to
|
|
37
|
+
# avoid. See the one-time manual step noted alongside the install below.
|
|
38
|
+
PLUGIN_FRONT_MATTER_TITLE="snezhig/obsidian-front-matter-title"
|
|
39
|
+
# Patches Obsidian's link-lookup step with an alias fallback (tries real
|
|
40
|
+
# filename resolution first, then a note's `aliases:` frontmatter) — the
|
|
41
|
+
# plugin half of ROADMAP-008's wikilink-resolution fix; the `aliases:`
|
|
42
|
+
# frontmatter half is scripted elsewhere. Self-described "experimental" in
|
|
43
|
+
# its own manifest.json and less widely used than the other four bundled
|
|
44
|
+
# plugins — verify johannrichard/alias-linker is still maintained at
|
|
45
|
+
# install time before relying on this constant.
|
|
46
|
+
PLUGIN_ALIAS_LINKER="johannrichard/alias-linker"
|
|
29
47
|
|
|
30
48
|
_install_obsidian_app() {
|
|
31
49
|
local os
|
|
@@ -227,6 +245,25 @@ _enable_obsidian_plugin() {
|
|
|
227
245
|
' "$vault_dir" "$id" || true
|
|
228
246
|
}
|
|
229
247
|
|
|
248
|
+
_install_obsidian_graph_defaults() {
|
|
249
|
+
local vault_dir="$1"
|
|
250
|
+
|
|
251
|
+
if ! mkdir -p "$vault_dir/.obsidian"; then
|
|
252
|
+
echo " WARNING: failed to create $vault_dir/.obsidian — skipping graph defaults." >&2
|
|
253
|
+
return
|
|
254
|
+
fi
|
|
255
|
+
|
|
256
|
+
if [ -f "$vault_dir/.obsidian/graph.json" ]; then
|
|
257
|
+
echo " .obsidian/graph.json already present — leaving your customization in place, skipping."
|
|
258
|
+
return 0
|
|
259
|
+
fi
|
|
260
|
+
|
|
261
|
+
if ! cp "$SCRIPT_DIR/templates/obsidian/graph.json" "$vault_dir/.obsidian/graph.json"; then
|
|
262
|
+
echo " WARNING: failed to install graph defaults — skipping." >&2
|
|
263
|
+
return
|
|
264
|
+
fi
|
|
265
|
+
}
|
|
266
|
+
|
|
230
267
|
# ---------------------------------------------------------------------------
|
|
231
268
|
# App install gate
|
|
232
269
|
#
|
|
@@ -266,7 +303,7 @@ if [ -z "$PROJECT_DIR" ]; then
|
|
|
266
303
|
else
|
|
267
304
|
install_plugins=false
|
|
268
305
|
if [ "$INTERACTIVE" = true ]; then
|
|
269
|
-
if prompt_yn_sticky obsidian.plugins "$PROJECT_DIR" "Install recommended Obsidian plugins (Dataview, Graph Link Types, Breadcrumbs) into this project's vault config? [Y/n]: "; then
|
|
306
|
+
if prompt_yn_sticky obsidian.plugins "$PROJECT_DIR" "Install recommended Obsidian plugins (Dataview, Graph Link Types, Breadcrumbs, Front Matter Title, Alias Linker) into this project's vault config? [Y/n]: "; then
|
|
270
307
|
install_plugins=true
|
|
271
308
|
fi
|
|
272
309
|
else
|
|
@@ -280,7 +317,7 @@ else
|
|
|
280
317
|
fi
|
|
281
318
|
|
|
282
319
|
if [ "$install_plugins" = true ]; then
|
|
283
|
-
for plugin_repo in "$PLUGIN_DATAVIEW" "$PLUGIN_GRAPH_LINK_TYPES" "$PLUGIN_BREADCRUMBS"; do
|
|
320
|
+
for plugin_repo in "$PLUGIN_DATAVIEW" "$PLUGIN_GRAPH_LINK_TYPES" "$PLUGIN_BREADCRUMBS" "$PLUGIN_FRONT_MATTER_TITLE" "$PLUGIN_ALIAS_LINKER"; do
|
|
284
321
|
plugin_id="$(_install_obsidian_plugin "$PROJECT_DIR" "$plugin_repo")" || plugin_id=""
|
|
285
322
|
if [ -n "$plugin_id" ]; then
|
|
286
323
|
_enable_obsidian_plugin "$PROJECT_DIR" "$plugin_id" || true
|
|
@@ -288,7 +325,37 @@ else
|
|
|
288
325
|
# Empty $plugin_id means _install_obsidian_plugin already warned
|
|
289
326
|
# internally — just move on to the next plugin.
|
|
290
327
|
done
|
|
328
|
+
echo " NOTE: Front Matter Title is installed and enabled, but its per-surface display toggles default OFF inside its own settings — open Settings -> Front Matter Title in Obsidian and enable 'Graph' (and 'Explorer' if wanted) once to see frontmatter titles instead of filenames."
|
|
291
329
|
else
|
|
292
330
|
echo " Skipping Obsidian plugin install."
|
|
293
331
|
fi
|
|
294
332
|
fi
|
|
333
|
+
|
|
334
|
+
# ---------------------------------------------------------------------------
|
|
335
|
+
# Graph defaults install gate
|
|
336
|
+
#
|
|
337
|
+
# obsidian.graphDefaults is a project-scoped key — the vault root is $PROJECT_DIR,
|
|
338
|
+
# so its prompt_yn_sticky/prefs_get selector is "$PROJECT_DIR" itself (never
|
|
339
|
+
# --global), per the selector-consistency rule documented on prompt_yn_sticky
|
|
340
|
+
# in lib.sh. No $PROJECT_DIR means no vault to install into, so skip outright
|
|
341
|
+
# rather than guessing a location.
|
|
342
|
+
# ---------------------------------------------------------------------------
|
|
343
|
+
if [ -z "$PROJECT_DIR" ]; then
|
|
344
|
+
echo " WARNING: no --project-dir given — skipping Obsidian graph defaults install."
|
|
345
|
+
else
|
|
346
|
+
if [ "$INTERACTIVE" = true ]; then
|
|
347
|
+
if prompt_yn_sticky obsidian.graphDefaults "$PROJECT_DIR" "Install default graph-view styling (.obsidian/graph.json — colors wiki/knowledge and wiki/work/* by family, scopes the graph to wiki/knowledge and wiki/work only)? [Y/n]: "; then
|
|
348
|
+
_install_obsidian_graph_defaults "$PROJECT_DIR"
|
|
349
|
+
else
|
|
350
|
+
echo " Skipping Obsidian graph defaults install."
|
|
351
|
+
fi
|
|
352
|
+
else
|
|
353
|
+
# Same non-interactive mirroring as the app-install gate above, applied
|
|
354
|
+
# to the project-scoped key: only a stored `false` skips.
|
|
355
|
+
if [ "$(prefs_get obsidian.graphDefaults "$PROJECT_DIR")" = "false" ]; then
|
|
356
|
+
echo " obsidian.graphDefaults: skipped (remembered decline — change with /bootstrap-config)"
|
|
357
|
+
else
|
|
358
|
+
_install_obsidian_graph_defaults "$PROJECT_DIR"
|
|
359
|
+
fi
|
|
360
|
+
fi
|
|
361
|
+
fi
|
package/lib/scripts/lib.sh
CHANGED
|
@@ -142,10 +142,12 @@ detect_installed_mcps() {
|
|
|
142
142
|
# install-global.sh --skip-mcps), then attempt the interactive MCP install
|
|
143
143
|
# (guarded — a failure only warns and continues, it does not abort the rest
|
|
144
144
|
# of the sync), sync the wiki scaffold (tiered guide delivery — --interactive
|
|
145
|
-
# enables the optional-guide prompts), merge the .gitignore,
|
|
146
|
-
#
|
|
147
|
-
#
|
|
148
|
-
#
|
|
145
|
+
# enables the optional-guide prompts), merge the .gitignore, backfill
|
|
146
|
+
# aliases: onto any wiki/work/ file that has drifted without one (unguarded —
|
|
147
|
+
# backfill-wiki-aliases.js always exits 0 on its own, same contract as
|
|
148
|
+
# merge-settings-deny.js/merge-settings-hooks.js), build the MCP-tools guide
|
|
149
|
+
# for the detected MCPs, then bootstrap Serena's project.yml. Prints the same
|
|
150
|
+
# section headers and blank-line separators the two scripts printed inline.
|
|
149
151
|
# ---------------------------------------------------------------------------
|
|
150
152
|
run_project_sync() {
|
|
151
153
|
local project_dir script_dir installed_mcps
|
|
@@ -167,6 +169,10 @@ run_project_sync() {
|
|
|
167
169
|
"$script_dir/merge-gitignore.sh" --interactive "$project_dir"
|
|
168
170
|
echo ""
|
|
169
171
|
|
|
172
|
+
echo "Backfilling wiki work-item aliases..."
|
|
173
|
+
node "$script_dir/backfill-wiki-aliases.js" "$project_dir"
|
|
174
|
+
echo ""
|
|
175
|
+
|
|
170
176
|
echo "Checking Obsidian setup..."
|
|
171
177
|
if ! "$script_dir/install-obsidian.sh" --interactive --project-dir "$project_dir"; then
|
|
172
178
|
echo "Warning: Obsidian install failed — continuing; re-run update to retry." >&2
|
|
@@ -104,7 +104,7 @@
|
|
|
104
104
|
"scope": "global",
|
|
105
105
|
"consumer": "installer",
|
|
106
106
|
"summary": "Registration scope for the Context7 MCP",
|
|
107
|
-
"detail": "Asked by prompt_scope in lib.sh:
|
|
107
|
+
"detail": "Asked by prompt_scope in lib.sh:410 ('Scope for context7 — [u]ser (default) or [p]roject?'). prompt_scope emits exactly two answers, 'user' and 'project' — it has no local-scope branch, and any reply that does not begin with p or P falls through to user. 'user' registers Context7 once for every project on this machine; 'project' writes the registration into the current project's shareable .mcp.json.",
|
|
108
108
|
"values": "user | project",
|
|
109
109
|
"default": null,
|
|
110
110
|
"askedBy": "lib.sh"
|
|
@@ -130,8 +130,17 @@
|
|
|
130
130
|
"obsidian.plugins": {
|
|
131
131
|
"scope": "project",
|
|
132
132
|
"consumer": "installer",
|
|
133
|
-
"summary": "Install the bundled Obsidian plugin set (Dataview, Graph Link Types, Breadcrumbs)",
|
|
134
|
-
"detail": "Asked by install-obsidian.sh. This is a single bundled prompt covering all
|
|
133
|
+
"summary": "Install the bundled Obsidian plugin set (Dataview, Graph Link Types, Breadcrumbs, Front Matter Title, Alias Linker)",
|
|
134
|
+
"detail": "Asked by install-obsidian.sh. This is a single bundled prompt covering all five recommended community plugins together rather than one key per plugin. Dataview is a hard prerequisite for Graph Link Types and Breadcrumbs specifically — both read fields that Dataview indexes, so installing them separately would let a user accept one without Dataview and end up with a plugin that silently doesn't work. Front Matter Title has no such dependency (it reads frontmatter directly); it is bundled here purely for prompt-count simplicity, not because it needs Dataview. Alias Linker likewise has no Dataview dependency — it patches Obsidian's core link resolver directly rather than reading Dataview-indexed fields — but it is self-described 'experimental' upstream, and that experimental status is the reason it stays bundled under this same single consent gate rather than being broken out into its own key, consistent with Front Matter Title's 'bundled here purely for prompt-count simplicity' framing above. true installs and refreshes all five plugin folders into .obsidian/plugins/ and enables them in .obsidian/community-plugins.json on every run. false means the installer stops offering the bundle again until the key is changed or removed via /bootstrap-config. Plugin files live inside this project's own .obsidian/ directory, which is why this key is project scope, matching guides.*'s scope choice. Note: Front Matter Title's own per-surface display toggles (Graph, Explorer, etc.) default OFF inside its own settings and are not scripted by this installer — see install-obsidian.sh's printed note for the one-time manual step.",
|
|
135
|
+
"values": "true | false",
|
|
136
|
+
"default": null,
|
|
137
|
+
"askedBy": "install-obsidian.sh"
|
|
138
|
+
},
|
|
139
|
+
"obsidian.graphDefaults": {
|
|
140
|
+
"scope": "project",
|
|
141
|
+
"consumer": "installer",
|
|
142
|
+
"summary": "Install default graph-view styling (.obsidian/graph.json)",
|
|
143
|
+
"detail": "Asked by install-obsidian.sh. true installs and refreshes .obsidian/graph.json with default graph-view styling if the file is absent; false means the installer stops offering it 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.",
|
|
135
144
|
"values": "true | false",
|
|
136
145
|
"default": null,
|
|
137
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
|
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
{
|
|
2
|
+
"search": "(path:wiki/knowledge OR path:wiki/work) -path:lifecycle.md",
|
|
3
|
+
"colorGroups": [
|
|
4
|
+
{"query": "path:wiki/knowledge/sources", "color": {"a": 1, "rgb": 9484520}},
|
|
5
|
+
{"query": "path:wiki/knowledge/concepts", "color": {"a": 1, "rgb": 5935062}},
|
|
6
|
+
{"query": "path:wiki/knowledge/entities", "color": {"a": 1, "rgb": 3104680}},
|
|
7
|
+
{"query": "path:wiki/work/tasks", "color": {"a": 1, "rgb": 15906891}},
|
|
8
|
+
{"query": "path:wiki/work/bugs", "color": {"a": 1, "rgb": 14839866}},
|
|
9
|
+
{"query": "path:wiki/work/decisions", "color": {"a": 1, "rgb": 13930827}},
|
|
10
|
+
{"query": "path:wiki/work/roadmaps", "color": {"a": 1, "rgb": 13202990}},
|
|
11
|
+
{"query": "path:wiki/work/requirements", "color": {"a": 1, "rgb": 15243100}},
|
|
12
|
+
{"query": "path:wiki/work/uat", "color": {"a": 1, "rgb": 12082238}}
|
|
13
|
+
],
|
|
14
|
+
"collapse-filter": false,
|
|
15
|
+
"showTags": true,
|
|
16
|
+
"showAttachments": false,
|
|
17
|
+
"hideUnresolved": false,
|
|
18
|
+
"showOrphans": true,
|
|
19
|
+
"collapse-color-groups": false,
|
|
20
|
+
"collapse-display": false,
|
|
21
|
+
"showArrow": false,
|
|
22
|
+
"collapse-forces": false
|
|
23
|
+
}
|
|
@@ -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
|
|
|
@@ -87,6 +87,7 @@ Use `Write` to create `wiki/work/bugs/NNNN-<slug>.md`, following the frontmatter
|
|
|
87
87
|
- `linked_task:` — `"[[TASK-NNN]]"` if a task was mentioned (normalized from either `TASK-NNN` or `[[TASK-NNN]]` input); `"—"` otherwise
|
|
88
88
|
- `Reported`: today's date (`YYYY-MM-DD`)
|
|
89
89
|
- `Last updated`: today's date
|
|
90
|
+
- `aliases: [BUG-NNNN]` — mirrors this file's own id: field so Obsidian's wikilink resolver can find it by short ID (ROADMAP-008)
|
|
90
91
|
- Leave `Root Cause Analysis`, `Resolution`, and `Related` sections present but empty (the templated placeholder line under each `>` quote is fine)
|
|
91
92
|
|
|
92
93
|
### Step 7: Update the Bug Index
|
|
@@ -81,6 +81,11 @@ Group members may share evidence sources (Shared Context), but each block needs
|
|
|
81
81
|
Write to `wiki/work/decisions/DEC-NNNN-<group-slug>.md` using this template. **Tables only, mermaid for flows** — mandatory in every block.
|
|
82
82
|
|
|
83
83
|
````markdown
|
|
84
|
+
---
|
|
85
|
+
id: DEC-NNNN
|
|
86
|
+
aliases: [DEC-NNNN]
|
|
87
|
+
---
|
|
88
|
+
|
|
84
89
|
# DEC-NNNN: <Decision-Group Title>
|
|
85
90
|
|
|
86
91
|
> Decision Group covering <area-1>, <area-2>, <area-3>.
|
|
@@ -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
|
|
|
@@ -133,6 +133,7 @@ Use `Write` to create `wiki/work/roadmaps/NNN-slug.md` following the field table
|
|
|
133
133
|
| Field | Value at creation time |
|
|
134
134
|
|-------|------------------------|
|
|
135
135
|
| `Status` | `active` |
|
|
136
|
+
| `aliases` | `[ROADMAP-NNN]` — mirrors the file's own `id:` value |
|
|
136
137
|
| `Created` | Today's date (derive at runtime — use the conversation environment's `currentDate`, otherwise `date +%Y-%m-%d`) |
|
|
137
138
|
| `Last updated` | Same as `Created` |
|
|
138
139
|
| `Owner` | From Step 3 #3 |
|
|
@@ -190,7 +191,7 @@ Print a tabular summary:
|
|
|
190
191
|
| Index updated | yes (1 row added) |
|
|
191
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 |
|
|
192
193
|
|
|
193
|
-
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.
|
|
194
195
|
|
|
195
196
|
If the roadmap contains any inline placeholder items (items without a task-link), include a **Placeholders** section listing them:
|
|
196
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.0.1",
|
|
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.
|