@codewizard-dt/bootstrap 5.1.0 → 5.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/scripts/templates/wiki/conventions.md +3 -1
- package/lib/skills/architecture-audit/SKILL.md +23 -2
- package/lib/skills/bug-close/SKILL.md +3 -0
- package/lib/skills/bug-file/SKILL.md +15 -1
- package/lib/skills/decision-create/SKILL.md +2 -1
- package/lib/skills/demo/SKILL.md +10 -10
- package/lib/skills/elevator-pitch/SKILL.md +1 -1
- package/lib/skills/extract-feature/SKILL.md +29 -87
- package/lib/skills/marp-slideshow/SKILL.md +2 -2
- package/lib/skills/port-feature/SKILL.md +28 -83
- package/lib/skills/roadmap-create/SKILL.md +4 -0
- package/lib/skills/security-audit/SKILL.md +2 -2
- package/lib/skills/task-add/SKILL.md +20 -1
- package/lib/skills/uat-auto/SKILL.md +2 -1
- package/lib/skills/uat-walk/SKILL.md +1 -1
- package/lib/skills/wiki-lint/SKILL.md +27 -0
- package/package.json +1 -1
|
@@ -34,7 +34,9 @@ supersedes::[[DEC-0003#D2]]
|
|
|
34
34
|
derived_from::[[sources/karpathy-llm-wiki]]
|
|
35
35
|
```
|
|
36
36
|
|
|
37
|
-
**Vocabulary:** `derived_from`, `supersedes`, `superseded_by`, `implements`, `uses`, `depends_on`, `contradicts`, `relates_to`, `caused`, `fixed`.
|
|
37
|
+
**Vocabulary:** `derived_from`, `supersedes`, `superseded_by`, `implements`, `uses`, `depends_on`, `contradicts`, `relates_to`, `caused`, `fixed`, `implemented_by`, `evolved_by`.
|
|
38
|
+
|
|
39
|
+
`implemented_by::[[TASK-NNNN]]` / `evolved_by::[[ROADMAP-NNNN]]` on a `knowledge/entities/components/` page — the inverse of a task's/roadmap's own `implements::`/`derived_from::` pointing at the concept.
|
|
38
40
|
|
|
39
41
|
This convention is **declared now but not backfilled** — use it on new and touched pages going forward; a future `/wiki-lint` pass can backfill the back-catalogue. Cost of starting now is zero; it just avoids accumulating a fresh pile of meaning-less links.
|
|
40
42
|
|
|
@@ -20,6 +20,7 @@ Structured architecture audit of this project's agentic/LLM system design. **Aud
|
|
|
20
20
|
2. **Find the agentic surface** — orchestrator/lead-agent entry points, subagent or worker definitions, tool/function registries, agent framework imports (`langgraph`, `crewai`, `autogen`, `@anthropic-ai/claude-agent-sdk`, `openai-agents`, `google-adk`, `@mastra/*`, `ai` (Vercel AI SDK)), any workflow/pipeline DSL.
|
|
21
21
|
3. **Establish the shape** — single agent, code-defined workflow, or multi-agent (and if multi-agent: how many roles, what topology connects them). This shape gates which checks below even apply.
|
|
22
22
|
4. **Note deployment context** — is this repo the LLM application itself, or (as with `bootstrap-claude`) tooling that configures agent behavior for other projects/sessions. Adjust "codebase" checks accordingly — e.g. for a Claude Code skill/subagent system, the orchestrator is a skill file, not application code.
|
|
23
|
+
5. **Diagram the topology** — sketch the actual control-flow graph found in the codebase: the orchestrator/lead node, each distinct subagent/role node, and any tool/data-store nodes material to control flow, with edges labeled by kind (`delegates`, `returns`, `invokes`). This becomes the Mermaid flowchart embedded in the report (see Reporting).
|
|
23
24
|
|
|
24
25
|
Use Serena `find_symbol` / `search_for_pattern` to locate code — never shell `grep`/`find`.
|
|
25
26
|
|
|
@@ -167,7 +168,20 @@ Individually-benign behavior in each agent can compound into an unwanted *global
|
|
|
167
168
|
|
|
168
169
|
## Reporting
|
|
169
170
|
|
|
170
|
-
**Output**: after compiling findings, write the full report to
|
|
171
|
+
**Output**: after compiling findings, write the full report to `wiki/reports/architecture-audit/<YYYY-MM-DD>.md` using the **Write** tool (create the directory if it doesn't exist). If a report for today already exists, write `<YYYY-MM-DD>-2.md` (then `-3`, …) rather than overwriting, so architecture posture is trackable over time rather than a one-off snapshot. Print the same report in the conversation as well; the file is a durable copy, not a replacement for the reply.
|
|
172
|
+
|
|
173
|
+
**Topology diagram**: every report embeds a Mermaid flowchart of the *actual* orchestration topology found in the codebase (from Setup step 5) — not an idealized one. Nodes: the orchestrator/lead agent, each distinct subagent/role, and any tool/data-store nodes material to control flow (group many similar tools into a single `Tools` node rather than enumerating each). Edges: label direction and kind (`delegates`, `returns`, `invokes`). If OT3 finds a peer-to-peer/mesh edge (agents communicating directly, bypassing the orchestrator), render it as a distinct dashed edge with a `⚠` label so the violation is visible in the diagram itself, not just called out in prose:
|
|
174
|
+
|
|
175
|
+
```mermaid
|
|
176
|
+
flowchart TD
|
|
177
|
+
U[User] --> O[Orchestrator]
|
|
178
|
+
O -->|delegates| A1[Subagent: Research]
|
|
179
|
+
O -->|delegates| A2[Subagent: Writer]
|
|
180
|
+
A1 -->|returns| O
|
|
181
|
+
A2 -->|returns| O
|
|
182
|
+
A1 -.->|⚠ direct handoff, bypasses orchestrator| A2
|
|
183
|
+
O --> T[(Tools / data stores)]
|
|
184
|
+
```
|
|
171
185
|
|
|
172
186
|
**Per-check status:** ✅ PASS (control exists & effective) · ⚠️ WARN (partial / has gaps) · ❌ FAIL (no evidence; at risk) · ℹ️ N/A (not applicable to this architecture) · 🔍 NEEDS-REVIEW (can't determine from code — flag for manual review).
|
|
173
187
|
|
|
@@ -177,6 +191,12 @@ Individually-benign behavior in each agent can compound into an unwanted *global
|
|
|
177
191
|
Architecture shape: [single agent / code-defined workflow / multi-agent — N roles, topology]
|
|
178
192
|
Categories audited: [list]
|
|
179
193
|
|
|
194
|
+
### Topology
|
|
195
|
+
```mermaid
|
|
196
|
+
flowchart TD
|
|
197
|
+
...
|
|
198
|
+
```
|
|
199
|
+
|
|
180
200
|
### [Category Name]
|
|
181
201
|
| Check | Status | Notes |
|
|
182
202
|
|-------|--------|-------|
|
|
@@ -204,4 +224,5 @@ Categories audited: [list]
|
|
|
204
224
|
6. **Scope to the repo** — don't speculate about external infra unless config files are present.
|
|
205
225
|
7. **One category at a time** — complete each fully before the next; don't interleave findings.
|
|
206
226
|
8. **Judge fit, not fashion** — a single agent that passes evaluation is not a finding against it; only flag multi-agent complexity, topology, or framework choice as a gap when it's mismatched to the actual task shape, not merely "not the newest pattern."
|
|
207
|
-
9. **Persist the report** — write it to
|
|
227
|
+
9. **Persist the report** — write it to `wiki/reports/architecture-audit/` (see Reporting) in addition to printing it; a report that only lives in the chat leaves no trail for the next audit to compare against.
|
|
228
|
+
10. **Diagram the topology** — every report includes a Mermaid flowchart of the actual control-flow graph (Setup step 5, Reporting § Topology diagram); mark any peer-to-peer/mesh edges distinctly so OT3 violations are visible in the picture, not just described in prose.
|
|
@@ -133,4 +133,7 @@ Print:
|
|
|
133
133
|
- Old status → new status; folder move (if any)
|
|
134
134
|
- Resolution summary: fix commit, regression test path
|
|
135
135
|
- For `verified`: a one-line clustering check — search `wiki/work/bugs/archive/` for the last 3 closes with overlapping `Tags` and surface them as "related recent closes" so the user can spot systemic issues.
|
|
136
|
+
- If the clustering check finds **2 or more** related recent closes (not counting the bug just closed), use `AskUserQuestion` to ask inline: `N related bugs closed recently with tag(s) <tags> — <BUG-NNNN titles>. File a regression-prevention task? (y/n)`
|
|
137
|
+
- On yes: invoke `Skill` `task-add` with a description referencing the clustered bug IDs and shared tag(s) (e.g. "Investigate recurring `<tag>` failures — see BUG-0003, BUG-0006, BUG-0009"). Do not pass `--roadmap` — there's no roadmap context here; the user can link one later via `/task-add --roadmap` if warranted.
|
|
138
|
+
- On no (or ≤1 related close): unchanged from today — print the clustering observation and stop, no prompt.
|
|
136
139
|
- For `fixed`: remind the user to re-run `/bug-close` once verification lands.
|
|
@@ -3,7 +3,7 @@ name: bug-file
|
|
|
3
3
|
description: File a new bug report in wiki/work/bugs/ with required-on-report fields and append it to the bug index
|
|
4
4
|
category: planning
|
|
5
5
|
model: claude-sonnet-5
|
|
6
|
-
argument-hint: <short bug description>
|
|
6
|
+
argument-hint: <short bug description> [--knowledge <slug>]
|
|
7
7
|
disable-model-invocation: false
|
|
8
8
|
user-invocable: true
|
|
9
9
|
---
|
|
@@ -53,6 +53,8 @@ For each missing required-on-report field, use `AskUserQuestion`. Batch related
|
|
|
53
53
|
|
|
54
54
|
**Exception**: if the user mentions a task in `$ARGUMENTS`, accept it in either `TASK-NNNN` or `[[TASK-NNNN]]` form and normalize to `"[[TASK-NNNN]]"` for the `linked_task:` frontmatter field. If no task is mentioned, set `linked_task: "—"`.
|
|
55
55
|
|
|
56
|
+
**Knowledge exception** (optional, non-required): if `$ARGUMENTS` contains `--knowledge <slug>` or a bare slug matching an existing page filename (without extension) in `wiki/knowledge/concepts/` or `wiki/knowledge/sources/`, use `mcp__serena__find_file` to search for `<slug>.md` (try the slug as given, and with `.md` appended if not already present) in those two directories. **If found**: store `(knowledge_file_path, knowledge_slug)` for Step 6. **If not found**: warn the user (e.g. "Knowledge page '<slug>' not found in wiki/knowledge/concepts/ or wiki/knowledge/sources/ — continuing without a knowledge link.") and continue — never block bug filing on a missing knowledge page. If no knowledge reference was given, skip this exception entirely (no `relates_to::` line is written in Step 6).
|
|
57
|
+
|
|
56
58
|
If the user cannot supply reliable Steps to Reproduce, STOP and tell them:
|
|
57
59
|
|
|
58
60
|
> Cannot file this bug yet — Steps to Reproduce are required. Capture a deterministic trigger first (a failing test, a screencast, a server log timestamp), then re-run `/bug-file`.
|
|
@@ -94,6 +96,18 @@ Use `Write` to create `wiki/work/bugs/BUG-NNNN-<slug>.md`, following the frontma
|
|
|
94
96
|
- `aliases: [BUG-NNNN]` — mirrors this file's own id: field so Obsidian's wikilink resolver can find it by short ID (ROADMAP-008)
|
|
95
97
|
- Leave `Root Cause Analysis`, `Resolution`, and `Related` sections present but empty (the templated placeholder line under each `>` quote is fine)
|
|
96
98
|
|
|
99
|
+
**Knowledge link** (only when the Step 3 exception resolved a knowledge reference): insert `relates_to::[[<slug>]]` as a typed link directly under the `# BUG-NNNN — <title>` H1 heading, before the body prose begins. Bug files have no other typed-link line near the top, so this is a new line, not an insertion alongside an existing one:
|
|
100
|
+
|
|
101
|
+
```markdown
|
|
102
|
+
# BUG-NNNN — <title>
|
|
103
|
+
|
|
104
|
+
relates_to::[[<slug>]]
|
|
105
|
+
|
|
106
|
+
<body prose begins here>
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
If no knowledge reference was given or resolved, omit the line entirely — do not write an empty placeholder.
|
|
110
|
+
|
|
97
111
|
### Step 7: Update the Bug Index
|
|
98
112
|
|
|
99
113
|
Append a bullet line to `wiki/work/bugs/index.md` (active items only — a flat list, no table). Insert in numeric order. Entry format (documented at the top of `index.md`):
|
|
@@ -31,6 +31,7 @@ See the lifecycle doc's "When to Write" / "When NOT to Write" tables. In short:
|
|
|
31
31
|
2. Decide single vs group (Step 1.5).
|
|
32
32
|
3. Recall Serena memories that may inform any decision: `list_memories` (filter by topic), `read_memory` for architecture/gotcha/integration memories touching the topic.
|
|
33
33
|
4. Read `CLAUDE.md`, `PROJECT_STATUS.md` (if present), `wiki/work/decisions/lifecycle.md`, and a sample of recent decisions for local conventions.
|
|
34
|
+
5. **Prior-art scan (optional, cheap — skip silently if nothing plausible turns up):** read `wiki/index.md`'s `### Concepts` and `### Sources` sections for titles/summaries matching the topic, then run `mcp__serena__search_for_pattern` for the topic's key terms across `wiki/knowledge/concepts/` and `wiki/knowledge/sources/`. This is a scan-and-surface check, not a `/research` substitute — don't widen it into a full research pass. Any candidate hit gets confirmed with the user in Step 4, never cited unconfirmed.
|
|
34
35
|
|
|
35
36
|
## Step 1.5: Single vs Decision Group triage
|
|
36
37
|
Use the lifecycle doc's "When to Group vs Split":
|
|
@@ -73,7 +74,7 @@ Prevents two parallel `accepted` decisions in one area (breaks the chain). Per p
|
|
|
73
74
|
Group members may share evidence sources (Shared Context), but each block needs its own drivers/options/consequences. If a block lacks evidence for an option/driver, **drop it** rather than fabricate; note the gap in Step 9.
|
|
74
75
|
|
|
75
76
|
## Step 4: Clarify with the user (mandatory)
|
|
76
|
-
`AskUserQuestion`, **per decision**, at minimum: (1) **Status** — strongly prefer `proposed` (default); may differ per block. (2) **Recommended option** — present research-backed rec with the comparison table; user confirms/overrides. (3) **Deciders** — owner of *this* decision (may differ per block; default git user). (4) **Tags (mandatory, non-empty)** — 1-3 short tags identifying this block's area (required for supersession detection). (5) **Supersedes** — if Step 2.5 surfaced candidates, ask which (if any): `DEC-NNNN#DM`, `none`, or "decide at finalize time".
|
|
77
|
+
`AskUserQuestion`, **per decision**, at minimum: (1) **Status** — strongly prefer `proposed` (default); may differ per block. (2) **Recommended option** — present research-backed rec with the comparison table; user confirms/overrides. (3) **Deciders** — owner of *this* decision (may differ per block; default git user). (4) **Tags (mandatory, non-empty)** — 1-3 short tags identifying this block's area (required for supersession detection). (5) **Supersedes** — if Step 2.5 surfaced candidates, ask which (if any): `DEC-NNNN#DM`, `none`, or "decide at finalize time". (6) **Prior art** — if Step 1's scan surfaced a candidate page, ask e.g. "Found `wiki/knowledge/concepts/<slug>.md` — relevant?"; on confirmation, add `derived_from::[[<slug>]]` to that decision's Shared Context or `### Context (decision-specific)`. Skip this question entirely when the scan found nothing plausible.
|
|
77
78
|
|
|
78
79
|
**Refuse to write the file if any block has empty `Tags`.** For groups, batch all decisions' questions in one `AskUserQuestion` when feasible, but keep questions per-decision.
|
|
79
80
|
|
package/lib/skills/demo/SKILL.md
CHANGED
|
@@ -11,7 +11,7 @@ user-invocable: true
|
|
|
11
11
|
|
|
12
12
|
# Demo
|
|
13
13
|
|
|
14
|
-
Audit the project's features, produce a **2-3 minute demo run book** at
|
|
14
|
+
Audit the project's features, produce a **2-3 minute demo run book** at `wiki/demo/runbook.md`, then generate a **Marp slideshow** from it at `wiki/demo/runbook.slides.md`.
|
|
15
15
|
|
|
16
16
|
---
|
|
17
17
|
|
|
@@ -27,7 +27,7 @@ Audit the project's features, produce a **2-3 minute demo run book** at `.docs/d
|
|
|
27
27
|
|
|
28
28
|
Use Serena MCP to explore the project. Never use `bash` commands for file exploration.
|
|
29
29
|
|
|
30
|
-
Start by reading Serena memories and the project's README, manifest, and
|
|
30
|
+
Start by reading Serena memories and the project's README, manifest, and `wiki/index.md` for planning context. Then browse the source tree and use `mcp__serena__get_symbols_overview` on key files to discover what the project actually does — routes, commands, exported functions, UI entry points.
|
|
31
31
|
|
|
32
32
|
Compile a **feature inventory** — a flat list of distinct, user-visible capabilities. For each feature note what it does and how to trigger it (a click path, a command, or a code example). Aim for around a dozen features; collapse trivial variations into a single entry.
|
|
33
33
|
|
|
@@ -47,7 +47,7 @@ Before designing the narrative, collect every stated requirement so the demo can
|
|
|
47
47
|
|
|
48
48
|
2. `wiki/work/decisions/` — scan accepted ADR decisions for capabilities they mandate or prohibit.
|
|
49
49
|
|
|
50
|
-
3. Any other requirements
|
|
50
|
+
3. Any other requirements-like pages in `wiki/knowledge/sources/` (ingested source summaries not already captured as formal requirements).
|
|
51
51
|
|
|
52
52
|
Produce a **requirements checklist** — a flat list of discrete, testable requirements drawn from those sources. Each entry should be one line, e.g. `REQ-01: User can sign up with email and password`. If no requirements documents exist, note that explicitly and continue.
|
|
53
53
|
|
|
@@ -75,7 +75,7 @@ End with a single closing sentence pointing to next steps or where to learn more
|
|
|
75
75
|
|
|
76
76
|
## Phase 4 — Write the Run Book
|
|
77
77
|
|
|
78
|
-
Create
|
|
78
|
+
Create `wiki/demo/` if it doesn't exist. Write `wiki/demo/runbook.md` using this template:
|
|
79
79
|
|
|
80
80
|
```markdown
|
|
81
81
|
# Demo Run Book — {Project Name}
|
|
@@ -145,7 +145,7 @@ Fill every placeholder with real project content. The run book must be self-cont
|
|
|
145
145
|
|
|
146
146
|
Invoke the `marp-slideshow` skill on the run book you just wrote:
|
|
147
147
|
|
|
148
|
-
> **Delegate to `/marp-slideshow
|
|
148
|
+
> **Delegate to `/marp-slideshow wiki/demo/runbook.md wiki/demo/`**
|
|
149
149
|
|
|
150
150
|
The deck must use a **GitHub dark style** — set the front-matter to a dark background (`#0d1117`) with light text (`#c9d1d9`) and accent color (`#58a6ff`). Write every slide as if you are speaking directly to a stakeholder: tell the story, don't transcribe the run book. One clear idea per slide; no bullet dumps. Speaker notes contain the verbatim spoken line from the run book.
|
|
151
151
|
|
|
@@ -153,11 +153,11 @@ If the `marp-slideshow` skill is not available, write the deck directly: use `ma
|
|
|
153
153
|
|
|
154
154
|
**Architecture diagrams**: If the project has a meaningful architecture worth showing (layered systems, data flows, service dependencies), follow this two-track approach — one format per destination:
|
|
155
155
|
|
|
156
|
-
- **Run book (Markdown)** — embed a fenced `mermaid` block directly in
|
|
156
|
+
- **Run book (Markdown)** — embed a fenced `mermaid` block directly in `wiki/demo/runbook.md` at the appropriate section. Keep each diagram small — no more than six or seven nodes. One layer per diagram.
|
|
157
157
|
- **Slides (SVG image)** — never embed a raw Mermaid code block in the slides. Instead:
|
|
158
|
-
1. Write the raw Mermaid source (no markdown wrapper) to
|
|
159
|
-
2. Render it to SVG via Bash: `npx @mermaid-js/mermaid-cli mmdc -i
|
|
160
|
-
3. Reference the rendered SVG in the slide: ` to `wiki/demo/<name>.mmd` (e.g. `architecture.mmd`, `data-flow.mmd`).
|
|
159
|
+
2. Render it to SVG via Bash: `npx @mermaid-js/mermaid-cli mmdc -i wiki/demo/<name>.mmd -o wiki/demo/<name>.svg`
|
|
160
|
+
3. Reference the rendered SVG in the slide: ``
|
|
161
161
|
|
|
162
162
|
One diagram per slide. Name `.mmd` files after their content (e.g. `system-overview.mmd`, `data-flow.mmd`).
|
|
163
163
|
|
|
@@ -168,7 +168,7 @@ One diagram per slide. Name `.mmd` files after their content (e.g. `system-overv
|
|
|
168
168
|
Print a short summary to the user:
|
|
169
169
|
|
|
170
170
|
- **Run book** — path, word count, and step count
|
|
171
|
-
- **Slideshow** — path, slide count, and render command (`npx @marp-team/marp-cli@latest
|
|
171
|
+
- **Slideshow** — path, slide count, and render command (`npx @marp-team/marp-cli@latest wiki/demo/runbook.slides.md`)
|
|
172
172
|
- **Requirements coverage** — table of all requirements, each marked Covered / Gap / Undocumented
|
|
173
173
|
- **Gaps** — requirements with no demo step, and features that exist but couldn't be cleanly demo'd
|
|
174
174
|
|
|
@@ -36,7 +36,7 @@ Use Serena MCP tools to explore the target project. You are looking for the stor
|
|
|
36
36
|
- **The best features** — identify the 2-3 features that are most impressive, most useful, or most surprising. Look for things with real numbers (command counts, time saved, steps eliminated), elegant abstractions, or capabilities that competitors don't have. These are the things you'd demo first to a skeptic.
|
|
37
37
|
- **The best part** — something that makes a developer or user think "oh that's clever."
|
|
38
38
|
|
|
39
|
-
Check: `package.json` (name, description), existing `README.md`, the top-level directory structure, and any
|
|
39
|
+
Check: `package.json` (name, description), existing `README.md`, the top-level directory structure, and any planning docs in `wiki/` (e.g. `wiki/index.md`, `wiki/work/requirements/`) or `CLAUDE.md` files for stated goals.
|
|
40
40
|
|
|
41
41
|
### 2. Write the pitch
|
|
42
42
|
|
|
@@ -35,7 +35,7 @@ The output document is formatted to be a valid "source project" for `/port-featu
|
|
|
35
35
|
3. **Clarifying questions** — ask before proceeding if any are ambiguous:
|
|
36
36
|
- **Output location**: Should the extracted module live as a subdirectory within this project (e.g., `packages/<module-name>/`) or as a stub for a new standalone repo? (Default: subdirectory)
|
|
37
37
|
- **Constraints**: Any hard constraints — must stay in the same language, no new dependencies, must preserve the current public API for backward compatibility?
|
|
38
|
-
- **Supplementary output**:
|
|
38
|
+
- **Supplementary output**: Is this extraction substantial enough to warrant a roadmap (multiple ordered steps) via `/roadmap-create`, or small enough for a single task via `/task-add`? Default to a roadmap once Phase 5's extraction steps exceed ~3 steps or missing test coverage must be backfilled first.
|
|
39
39
|
|
|
40
40
|
---
|
|
41
41
|
|
|
@@ -224,110 +224,52 @@ Classify each source file by porting effort:
|
|
|
224
224
|
|
|
225
225
|
---
|
|
226
226
|
|
|
227
|
-
## Phase 6:
|
|
227
|
+
## Phase 6: Produce the Extraction Roadmap
|
|
228
228
|
|
|
229
|
-
### 6a.
|
|
229
|
+
### 6a. Present the Full Analysis
|
|
230
230
|
|
|
231
|
-
|
|
231
|
+
Present the complete assessment in the conversation as structured tables/sections — this is working analysis for the roadmap and any task files, not a standalone persisted document:
|
|
232
232
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
proposed-module-path: <packages/<module-name> OR external repo name>
|
|
242
|
-
---
|
|
243
|
-
|
|
244
|
-
# Extraction Plan: <Feature Name>
|
|
245
|
-
|
|
246
|
-
> **Feature**: <feature description>
|
|
247
|
-
> **Extracted from**: `<absolute project path>`
|
|
248
|
-
> **Proposed module**: `<module path>`
|
|
249
|
-
> **Overall effort**: <Low / Medium / High / Very High>
|
|
250
|
-
> **Summary**: <One sentence on what this extraction involves.>
|
|
251
|
-
|
|
252
|
-
## Source Feature Inventory
|
|
253
|
-
|
|
254
|
-
<Phase 3 inventory — this section is read by /port-feature when this module is the source>
|
|
255
|
-
|
|
256
|
-
## Coupling Analysis
|
|
257
|
-
|
|
258
|
-
<Phase 2d coupling map table>
|
|
259
|
-
|
|
260
|
-
## Interface Specifications
|
|
261
|
-
|
|
262
|
-
<Phase 4a interface table>
|
|
263
|
-
|
|
264
|
-
## Proposed Module Structure
|
|
265
|
-
|
|
266
|
-
<Phase 4b directory tree with annotations>
|
|
267
|
-
|
|
268
|
-
## Technology Mapping
|
|
269
|
-
|
|
270
|
-
<Phase 4c table>
|
|
271
|
-
|
|
272
|
-
## Complexity Breakdown
|
|
273
|
-
|
|
274
|
-
<Phase 5c table>
|
|
233
|
+
- **Source Feature Inventory** — Phase 3 inventory (this is what must ultimately land in the extracted module's own `README.md` per Phase 4b — that file, not a wiki doc, is what `/port-feature` reads)
|
|
234
|
+
- **Coupling Analysis** — Phase 2d coupling map table
|
|
235
|
+
- **Interface Specifications** — Phase 4a interface table
|
|
236
|
+
- **Proposed Module Structure** — Phase 4b directory tree with annotations
|
|
237
|
+
- **Technology Mapping** — Phase 4c table
|
|
238
|
+
- **Complexity Breakdown** — Phase 5c table
|
|
239
|
+
- **Gap Analysis** — Phase 5a current-project changes + 5b missing test coverage
|
|
240
|
+
- **Extraction Steps** — ordered, dependency-respecting steps; for each: title, effort (Direct/Adapt/Rewrite), files affected (extract to target, create/move/refactor), what to do, and definition of done (tests pass, imports resolve, no references to old path)
|
|
275
241
|
|
|
276
|
-
|
|
242
|
+
### 6b. Decide: Roadmap or Single Task
|
|
277
243
|
|
|
278
|
-
|
|
244
|
+
- **≤3 extraction steps, no missing test coverage flagged in 5b** → skip the roadmap. Go straight to `/task-add "Extract <feature name> into standalone module"`, carrying the full step detail into the task's steps, then skip to Phase 7.
|
|
245
|
+
- **>3 steps, missing test coverage to backfill first, or the user asked for a roadmap in Phase 0** → continue to 6c.
|
|
279
246
|
|
|
280
|
-
|
|
247
|
+
### 6c. Delegate to `/roadmap-create`
|
|
281
248
|
|
|
282
|
-
|
|
249
|
+
> **Delegate to `/roadmap-create Extract <feature name> into standalone module`**
|
|
283
250
|
|
|
284
|
-
|
|
251
|
+
Feed `/roadmap-create`'s own Socratic Q&A from the analysis already gathered, rather than making the user re-derive it from scratch:
|
|
285
252
|
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
**Definition of done**: <How to know this step is complete — tests pass, imports resolve, no references to old path>
|
|
294
|
-
|
|
295
|
-
---
|
|
296
|
-
|
|
297
|
-
### Step 2: <title>
|
|
298
|
-
|
|
299
|
-
… (repeat for each step)
|
|
300
|
-
|
|
301
|
-
---
|
|
302
|
-
|
|
303
|
-
## Suggested Next Actions
|
|
304
|
-
|
|
305
|
-
- To create a task from this plan: `/task-add "Extract <feature name> into standalone module"`
|
|
306
|
-
- To port this module into another project after extraction: `/port-feature <proposed-module-path> <feature name>`
|
|
307
|
-
- If an interface decision is still open: <frame the specific decision clearly>
|
|
308
|
-
```
|
|
309
|
-
|
|
310
|
-
### 6b. Optionally Create a Task File
|
|
311
|
-
|
|
312
|
-
If the user requested a task file (or the plan is concrete enough to execute immediately):
|
|
313
|
-
|
|
314
|
-
```
|
|
315
|
-
/task-add "Extract <feature name> into standalone module"
|
|
316
|
-
```
|
|
253
|
+
| Elicitation | Answer to supply |
|
|
254
|
+
|---|---|
|
|
255
|
+
| Goal | The one/two-sentence extraction summary + overall effort verdict from 5c |
|
|
256
|
+
| Phases | Group the ordered Extraction Steps from 6a into 2-5 execution-flavored phases (e.g. "Backfill tests", "Define interfaces", "Extract core", "Wire adapters") — never one phase per step |
|
|
257
|
+
| Owner | Ask the user if not already known |
|
|
258
|
+
| Linked PRD/ADRs | Any `wiki/work/requirements/` or `wiki/work/decisions/` entries found during Phase 2a |
|
|
317
259
|
|
|
318
|
-
|
|
260
|
+
Each Extraction Step becomes one roadmap item — an inline placeholder (`- [ ] <step title>`) under its phase, per `/roadmap-create`'s item-format rules. **Do not embed the step's file list / what-to-do / definition-of-done in the roadmap item** — that detail belongs in the task file created for it via `/task-add --roadmap ROADMAP-NNNN <step title>` (or automatically when `/roadmap-next` runs).
|
|
319
261
|
|
|
320
262
|
---
|
|
321
263
|
|
|
322
264
|
## Phase 7: Report to User
|
|
323
265
|
|
|
324
|
-
After
|
|
266
|
+
After the roadmap (or single task) is created:
|
|
325
267
|
|
|
326
|
-
1. State the path
|
|
268
|
+
1. State what was created: the roadmap path (`wiki/work/roadmaps/ROADMAP-NNNN-slug.md`) or the single task command run
|
|
327
269
|
2. Give a one-line effort verdict (e.g., "High effort — 3 interfaces to design, 2 rewrites, 1 missing test suite")
|
|
328
270
|
3. List the top 3 extraction steps in brief
|
|
329
271
|
4. Call out the single biggest coupling risk or blocker
|
|
330
|
-
5. Suggest the most useful next action (
|
|
272
|
+
5. Suggest the most useful next action (`/roadmap-next ROADMAP-NNNN`, an interface decision to make, or `/port-feature` handoff once the module's own `README.md` is written)
|
|
331
273
|
|
|
332
274
|
---
|
|
333
275
|
|
|
@@ -338,7 +280,7 @@ After writing the plan file:
|
|
|
338
280
|
3. **No speculation** — every coupling point listed must be grounded in what you actually read from the codebase (Serena tool results), not assumed
|
|
339
281
|
4. **Interfaces for everything** — every `infra`, `direct-external`, `internal-coupling`, and `config` dependency must have a corresponding interface in the plan; none may be left as a concrete import in the extracted module's `core/`
|
|
340
282
|
5. **SOLID enforced** — each SOLID principle (SRP, OCP, LSP, ISP, DIP) must be explicitly addressed in Phase 4a; call out any violations with a mitigation
|
|
341
|
-
6. **port-feature compatibility** — Phase 3 inventory must match exactly the format `/port-feature` Phase 1c expects; the
|
|
283
|
+
6. **port-feature compatibility** — Phase 3 inventory must match exactly the format `/port-feature` Phase 1c expects; the extracted module's own `README.md` (Phase 4b) must be usable as a "source project" spec
|
|
342
284
|
7. **Brave Search rate limit** — 50 requests/second, parallel searches allowed (applies during Phase 1 research)
|
|
343
285
|
8. **Maximum 3 concurrent sub-processes** at a time
|
|
344
286
|
9. **Always terminate all processes when done** (dev servers, type checkers, long-running commands)
|
|
@@ -21,7 +21,7 @@ The first whitespace-separated token is the **input path** (required). An option
|
|
|
21
21
|
|
|
22
22
|
**Output path resolution rules** (apply in order):
|
|
23
23
|
|
|
24
|
-
1. **No output path provided** → write to
|
|
24
|
+
1. **No output path provided** → write to `wiki/marp/<input-stem>.slides.md` (create `wiki/marp/` if it doesn't exist). Do **not** place the deck next to the input file.
|
|
25
25
|
2. **Output path provided** → always normalize the filename so it ends in `.slides.md`, even if the user didn't say so:
|
|
26
26
|
- `deck` → `deck.slides.md`
|
|
27
27
|
- `deck.md` → `deck.slides.md` (strip the trailing `.md`, then append `.slides.md`)
|
|
@@ -190,7 +190,7 @@ Before calling `Write`, mentally verify:
|
|
|
190
190
|
- [ ] Speaker notes (HTML comments) are present where the source had context that didn't fit on-slide
|
|
191
191
|
- [ ] Footer / header are short (one line, no Markdown that breaks YAML — wrap in quotes if it contains `:` or `#`)
|
|
192
192
|
- [ ] Output filename ends in `.slides.md` (always — append/normalize even if the user-supplied path didn't include it)
|
|
193
|
-
- [ ] If the user did **not** supply an output path, the deck is written to
|
|
193
|
+
- [ ] If the user did **not** supply an output path, the deck is written to `wiki/marp/<input-stem>.slides.md` (not next to the source)
|
|
194
194
|
|
|
195
195
|
## Phase 5 — Write & Confirm
|
|
196
196
|
|
|
@@ -33,7 +33,7 @@ Assess a specific feature or area of functionality in an external (source) proje
|
|
|
33
33
|
- Confirm the source directory exists: use `mcp__serena__find_file` or Bash `ls <source-path>` to verify it is accessible
|
|
34
34
|
|
|
35
35
|
3. **Clarifying questions** (ask before proceeding if ambiguous):
|
|
36
|
-
-
|
|
36
|
+
- Is this port substantial enough to warrant a roadmap (multiple ordered steps spanning several files/integration points) via `/roadmap-create`, or small enough for a single task via `/task-add`? Default to a roadmap once Phase 3's porting steps exceed ~3 steps or touch more than one integration point.
|
|
37
37
|
- Is there a preferred output level of detail (high-level steps vs. file-by-file implementation plan)?
|
|
38
38
|
- Are there any known constraints (e.g., "must stay in TypeScript", "no new dependencies")?
|
|
39
39
|
|
|
@@ -201,107 +201,52 @@ List risks that could complicate the port:
|
|
|
201
201
|
|
|
202
202
|
---
|
|
203
203
|
|
|
204
|
-
## Phase 4: Produce the Port
|
|
204
|
+
## Phase 4: Produce the Port Roadmap
|
|
205
205
|
|
|
206
|
-
### 4a.
|
|
206
|
+
### 4a. Present the Full Analysis
|
|
207
207
|
|
|
208
|
-
|
|
208
|
+
Present the complete assessment in the conversation as structured tables/sections — this is working analysis for the roadmap and any task files, not a standalone persisted document:
|
|
209
209
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
# Port Plan: <Feature Name>
|
|
220
|
-
|
|
221
|
-
> **Source**: `<source-path>`
|
|
222
|
-
> **Feature**: <functionality description>
|
|
223
|
-
> **Overall effort**: <Low / Medium / High / Very High>
|
|
224
|
-
> **Summary**: <One sentence on what this port involves.>
|
|
225
|
-
|
|
226
|
-
## Source Feature Summary
|
|
227
|
-
|
|
228
|
-
<Condensed version of the Source Feature Inventory from Phase 1c>
|
|
229
|
-
|
|
230
|
-
## Target Project Context
|
|
231
|
-
|
|
232
|
-
<Condensed version of the Target Project Profile from Phase 2d>
|
|
233
|
-
|
|
234
|
-
## Technology Mapping
|
|
235
|
-
|
|
236
|
-
<Table from 3a>
|
|
237
|
-
|
|
238
|
-
## Complexity Breakdown
|
|
239
|
-
|
|
240
|
-
<Table from 3b>
|
|
241
|
-
|
|
242
|
-
## Dependency Changes
|
|
243
|
-
|
|
244
|
-
<Table from 3c>
|
|
245
|
-
|
|
246
|
-
## Integration Points
|
|
247
|
-
|
|
248
|
-
<Bullet list from 3d>
|
|
210
|
+
- **Source Feature Summary** — condensed Phase 1c inventory
|
|
211
|
+
- **Target Project Context** — condensed Phase 2d profile
|
|
212
|
+
- **Technology Mapping** — table from 3a
|
|
213
|
+
- **Complexity Breakdown** — table from 3b
|
|
214
|
+
- **Dependency Changes** — table from 3c
|
|
215
|
+
- **Integration Points** — bullets from 3d
|
|
216
|
+
- **Risks** — table from 3e
|
|
217
|
+
- **Porting Steps** — ordered, dependency-respecting steps; for each: title, effort (Direct/Adapt/Rewrite), files affected (create/modify/delete), what to do, and definition of done
|
|
249
218
|
|
|
250
|
-
|
|
219
|
+
### 4b. Decide: Roadmap or Single Task
|
|
251
220
|
|
|
252
|
-
<
|
|
221
|
+
- **≤3 porting steps, single integration point** → skip the roadmap. Go straight to `/task-add "Port <feature name> from <source-path>"`, carrying the full step detail (files affected, what to do, definition of done) into the task's steps, then skip to Phase 5.
|
|
222
|
+
- **>3 steps, multiple integration points, or the user asked for a roadmap in Phase 0** → continue to 4c.
|
|
253
223
|
|
|
254
|
-
|
|
224
|
+
### 4c. Delegate to `/roadmap-create`
|
|
255
225
|
|
|
256
|
-
|
|
226
|
+
> **Delegate to `/roadmap-create Port <feature name> from <source-path>`**
|
|
257
227
|
|
|
258
|
-
|
|
228
|
+
Feed `/roadmap-create`'s own Socratic Q&A from the analysis already gathered, rather than making the user re-derive it from scratch:
|
|
259
229
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
**Definition of done**: <How to know this step is complete>
|
|
268
|
-
|
|
269
|
-
---
|
|
270
|
-
|
|
271
|
-
### Step 2: <title>
|
|
272
|
-
|
|
273
|
-
… (repeat for each step)
|
|
274
|
-
|
|
275
|
-
---
|
|
276
|
-
|
|
277
|
-
## Suggested Next Actions
|
|
278
|
-
|
|
279
|
-
- To create a task from this plan: `/task-add "Port <feature name> from <source-path>" --roadmap <if applicable>`
|
|
280
|
-
- To explore the source further: use Read on `<most important source file>`
|
|
281
|
-
- If a dependency decision is needed: <frame the specific decision>
|
|
282
|
-
```
|
|
283
|
-
|
|
284
|
-
### 4b. Optionally Create a Task File
|
|
285
|
-
|
|
286
|
-
If the user requested a task file (or if the plan is actionable enough to execute), suggest:
|
|
287
|
-
|
|
288
|
-
```
|
|
289
|
-
/task-add "Port <feature name> from <source-project-name>"
|
|
290
|
-
```
|
|
230
|
+
| Elicitation | Answer to supply |
|
|
231
|
+
|---|---|
|
|
232
|
+
| Goal | The one/two-sentence port summary + overall effort verdict from 3b |
|
|
233
|
+
| Phases | Group the ordered Porting Steps from 4a into 2-5 execution-flavored phases (e.g. "Dependencies", "Core port", "Integration", "Tests") — never one phase per step |
|
|
234
|
+
| Owner | Ask the user if not already known |
|
|
235
|
+
| Linked PRD/ADRs | Any `wiki/work/requirements/` or `wiki/work/decisions/` entries found during Phase 2a/2c |
|
|
291
236
|
|
|
292
|
-
|
|
237
|
+
Each Porting Step becomes one roadmap item — an inline placeholder (`- [ ] <step title>`) under its phase, per `/roadmap-create`'s item-format rules. **Do not embed the step's file list / what-to-do / definition-of-done in the roadmap item** — that detail belongs in the task file created for it via `/task-add --roadmap ROADMAP-NNNN <step title>` (or automatically when `/roadmap-next` runs).
|
|
293
238
|
|
|
294
239
|
---
|
|
295
240
|
|
|
296
241
|
## Phase 5: Report to User
|
|
297
242
|
|
|
298
|
-
After
|
|
243
|
+
After the roadmap (or single task) is created:
|
|
299
244
|
|
|
300
|
-
1. State the path
|
|
245
|
+
1. State what was created: the roadmap path (`wiki/work/roadmaps/ROADMAP-NNNN-slug.md`) or the single task command run
|
|
301
246
|
2. Give a one-line overall effort verdict (e.g., "Medium effort — 4 files to adapt, 1 rewrite, no new dependencies required")
|
|
302
247
|
3. List the top 3 porting steps in brief
|
|
303
248
|
4. Call out the single biggest risk or blocker
|
|
304
|
-
5. Suggest the most useful next action (
|
|
249
|
+
5. Suggest the most useful next action (`/roadmap-next ROADMAP-NNNN`, further exploration, or a specific dependency decision to make)
|
|
305
250
|
|
|
306
251
|
---
|
|
307
252
|
|
|
@@ -51,6 +51,7 @@ If the topic is a single task with several steps, **stop and tell the user** —
|
|
|
51
51
|
- `wiki/work/roadmaps/lifecycle.md` (frontmatter schema, status lifecycle — authoritative)
|
|
52
52
|
- A sample of recent roadmaps in `wiki/work/roadmaps/` to learn local conventions
|
|
53
53
|
- The active-task bullets in `wiki/work/tasks/index.md` so you know what task files already exist and can be linked
|
|
54
|
+
4. **Prior-art scan (optional, cheap — skip silently if nothing plausible turns up):** read `wiki/index.md`'s `### Concepts` and `### Sources` sections for titles/summaries matching the topic, then run `mcp__serena__search_for_pattern` for the topic's key terms across `wiki/knowledge/concepts/` and `wiki/knowledge/sources/`. This is a scan-and-surface check, not a `/research` substitute — don't widen it into a full research pass. Any candidate hit gets confirmed with the user during Step 3's Q&A, never cited unconfirmed. If confirmed, its slug(s) populate the roadmap's `derived_from:` frontmatter field (array of `wiki/knowledge/{concepts,sources}` slugs — see ROADMAP-0013 for a precedent).
|
|
54
55
|
|
|
55
56
|
### Step 2: Locate the roadmap directory and assign a number
|
|
56
57
|
|
|
@@ -82,6 +83,8 @@ Walk through the elicitations below. Batch related questions into a single `AskU
|
|
|
82
83
|
|-------|-------------------|
|
|
83
84
|
| 1 | Goal, Phases, Owner, Linked PRD/ADRs |
|
|
84
85
|
|
|
86
|
+
If Step 1's prior-art scan surfaced candidate concept/source pages, fold a confirmation question into this same batch (or a short follow-up if the batch is already full): name the candidate page(s) and ask whether they're relevant to this roadmap. Confirmed hits become the `derived_from:` frontmatter value written in Step 6; unconfirmed or rejected candidates are dropped silently — never cited without confirmation.
|
|
87
|
+
|
|
85
88
|
Then **per-phase**, in a single follow-up `AskUserQuestion` round (one question per phase, up to 4 — split into multiple rounds only if there are 5 phases):
|
|
86
89
|
|
|
87
90
|
| # | Elicitation | Quality bar |
|
|
@@ -137,6 +140,7 @@ Use `Write` to create `wiki/work/roadmaps/ROADMAP-NNNN-slug.md` following the fi
|
|
|
137
140
|
| `Created` | Today's date (derive at runtime — use the conversation environment's `currentDate`, otherwise `date +%Y-%m-%d`) |
|
|
138
141
|
| `Last updated` | Same as `Created` |
|
|
139
142
|
| `Owner` | From Step 3 #3 |
|
|
143
|
+
| `derived_from` | Array of `wiki/knowledge/{concepts,sources}` slugs confirmed during Step 3's prior-art check, or omit the field entirely if none were confirmed — never invent entries |
|
|
140
144
|
| `Linked PRD` | From Step 3 #4, or `—` |
|
|
141
145
|
| `Linked ADRs` | From Step 3 #4, or `—` |
|
|
142
146
|
| `Tags` | 1-3 short area tags inferred from the topic (e.g. `auth`, `billing`, `infra`). If the user did not name any, propose tags during Step 4's confirmation rather than inventing them silently |
|
|
@@ -211,7 +211,7 @@ Huge inputs (malicious or not) exhaust token budgets, spike rate limits, and inf
|
|
|
211
211
|
|
|
212
212
|
## Reporting
|
|
213
213
|
|
|
214
|
-
**Output**: after compiling findings, write the full report to
|
|
214
|
+
**Output**: after compiling findings, write the full report to `wiki/reports/security-audit/<YYYY-MM-DD>.md` using the **Write** tool (create the directory if it doesn't exist). If a report for today already exists, write `<YYYY-MM-DD>-2.md` (then `-3`, …) rather than overwriting — a persisted history is what makes check B4 ("benchmark results tracked over time") true instead of aspirational. Print the same report in the conversation as well; the file is a durable copy, not a replacement for the reply.
|
|
215
215
|
|
|
216
216
|
**Per-check status:** ✅ PASS (control exists & effective) · ⚠️ WARN (partial / has gaps) · ❌ FAIL (no evidence; vulnerable) · ℹ️ N/A (not applicable) · 🔍 NEEDS-REVIEW (can't determine from code — flag for manual review).
|
|
217
217
|
|
|
@@ -246,4 +246,4 @@ Categories audited: [list]
|
|
|
246
246
|
5. **Do not fix** — audit and report only; hand off fixes to the user or `/task-add`.
|
|
247
247
|
6. **Scope to the repo** — don't speculate about external infra unless config files are present.
|
|
248
248
|
7. **One category at a time** — complete each fully before the next; don't interleave findings.
|
|
249
|
-
8. **Persist the report** — write it to
|
|
249
|
+
8. **Persist the report** — write it to `wiki/reports/security-audit/` (see Reporting) in addition to printing it; a report that only lives in the chat leaves no trail for the next audit to compare against.
|
|
@@ -3,7 +3,7 @@ name: task-add
|
|
|
3
3
|
description: Create a structured, execution-ready task file in wiki/work/tasks/
|
|
4
4
|
category: planning
|
|
5
5
|
model: claude-sonnet-5
|
|
6
|
-
argument-hint: <task description> [--decision DEC-NNNN#DM] [--roadmap ROADMAP-NNNN]
|
|
6
|
+
argument-hint: <task description> [--decision DEC-NNNN#DM] [--roadmap ROADMAP-NNNN] [--knowledge <slug>]
|
|
7
7
|
disable-model-invocation: false
|
|
8
8
|
user-invocable: true
|
|
9
9
|
---
|
|
@@ -55,6 +55,22 @@ Store `(roadmap_file_path, roadmap_number)` for Step 9.
|
|
|
55
55
|
|
|
56
56
|
If no roadmap reference: skip this step entirely.
|
|
57
57
|
|
|
58
|
+
### Step 2b: Parse and validate knowledge reference (only if `$ARGUMENTS` contains `--knowledge` or a recognizable concept/source slug)
|
|
59
|
+
|
|
60
|
+
Detect:
|
|
61
|
+
- `--knowledge <slug>` — flag form (e.g. `--knowledge wiki-skill-boilerplate-duplication`)
|
|
62
|
+
- a bare slug matching an existing page filename (without extension) in `wiki/knowledge/concepts/` or `wiki/knowledge/sources/`
|
|
63
|
+
|
|
64
|
+
Strip the knowledge token and any `--knowledge` flag from `$ARGUMENTS` to get the clean task description.
|
|
65
|
+
|
|
66
|
+
Locate the page: use `mcp__serena__find_file` to search for `<slug>.md` (try the slug as given, and with `.md` appended if not already present) in `wiki/knowledge/concepts/` and `wiki/knowledge/sources/`.
|
|
67
|
+
|
|
68
|
+
**If found**: store `(knowledge_file_path, knowledge_slug)` for Step 8.
|
|
69
|
+
|
|
70
|
+
**If not found**: warn the user (e.g. "Knowledge page '<slug>' not found in wiki/knowledge/concepts/ or wiki/knowledge/sources/ — continuing without a knowledge link.") and continue — never block task creation on a missing knowledge page.
|
|
71
|
+
|
|
72
|
+
If no knowledge reference: skip this step entirely.
|
|
73
|
+
|
|
58
74
|
### Step 4: Determine the next task number
|
|
59
75
|
|
|
60
76
|
Scan **all** task locations to find the next available number:
|
|
@@ -120,6 +136,7 @@ Populate `depends_on`, `blocks`, and `parallel_safe_with` from Step 5 as lists o
|
|
|
120
136
|
# TASK-NNNN — Task Title
|
|
121
137
|
|
|
122
138
|
implements::[[DEC-NNNN#DM]] ← only when a decision reference was provided
|
|
139
|
+
relates_to::[[<slug>]] ← only when Step 2b resolved a knowledge reference
|
|
123
140
|
depends_on::[[TASK-NNNN]] ← one line per dependency from Step 5; omit entirely if none
|
|
124
141
|
blocks::[[TASK-NNNN]] ← one line per blocked task from Step 5; omit entirely if none
|
|
125
142
|
|
|
@@ -149,6 +166,8 @@ Agent type annotations: valid types are `general-purpose`, `Explore`, `Plan`.
|
|
|
149
166
|
|
|
150
167
|
**Decision link** (only when Step 2 found an accepted decision reference): Insert `implements::[[DEC-NNNN#DM]]` as a typed link on the line immediately after the H1, before `## Objective`.
|
|
151
168
|
|
|
169
|
+
**Knowledge link** (only when Step 2b resolved a knowledge reference): Insert `relates_to::[[<slug>]]` as a typed link in the same position — immediately after `implements::` when it's present, or immediately after the H1 when it isn't.
|
|
170
|
+
|
|
152
171
|
**Dependency links** (from the Step 5 data, no re-derivation needed): insert one `depends_on::[[TASK-NNNN]]` line per dependency and one `blocks::[[TASK-NNNN]]` line per blocked task, in the same position — immediately after `implements::` when it's present, or immediately after the H1 when it isn't. *Aside: these typed-link lines are additive to the existing `> **Depends on**:`/`> **Blocks**:` blockquote format, not a replacement, and creating them here does not backfill any pre-existing task file.*
|
|
153
172
|
|
|
154
173
|
### Step 9: Update the family index
|
|
@@ -55,6 +55,7 @@ Unit-backed:
|
|
|
55
55
|
• UAT-EDGE-002: Rate Limit Window — `node --test test/rate-limit.test.js` (7 tests, 0 fail)
|
|
56
56
|
Failed:
|
|
57
57
|
• UAT-API-003: Delete Position — "auto-judge: HTTP 500 expected 204"
|
|
58
|
+
→ /bug-file "UAT-API-003: HTTP 500 received, expected 204"
|
|
58
59
|
• UAT-EDGE-001: Empty Positions — "auto-judge: manual test requires human verification"
|
|
59
60
|
Next action: /uat-walk wiki/work/uat/UAT-005-positions.md
|
|
60
61
|
```
|
|
@@ -65,7 +66,7 @@ On all-pass, replace `Next action` with the task/UAT IDs and their new `done`/`p
|
|
|
65
66
|
|
|
66
67
|
## Rules
|
|
67
68
|
|
|
68
|
-
- **No user interaction, ever** — no `AskUserQuestion`, no inline prompts, no clarifying questions. Ambiguity → record fail / exit with a diagnostic summary.
|
|
69
|
+
- **No user interaction, ever** — no `AskUserQuestion`, no inline prompts, no clarifying questions. Ambiguity → record fail / exit with a diagnostic summary. Bug-file suggestions in the summary are informational text only — never call `/bug-file` itself.
|
|
69
70
|
- **Verdict discipline** — `[x] Pass` only on concrete machine-verified evidence: a matching live command, or a unit-backed run meeting all 7 criteria. `[FAIL: auto-judge: <reason>]` for everything else (uncertainty, missing command with no unit test, non-verifiable Expected, UI, bare manual); **never** `[SKIP]`.
|
|
70
71
|
- **A green exit code is not a pass** — for unit-backed tests, always confirm the run actually executed tests from the recorded file (UAT-CORE Step 4 criterion 3). Exit 0 with 0 tests collected is the one failure mode that looks exactly like success.
|
|
71
72
|
- **No browser automation** — UI tests always fail-closed to human verification, unit test or not.
|
|
@@ -122,7 +122,7 @@ Batch verdict input formats: `all pass` / `all p` (same to all) · `p p f fix s`
|
|
|
122
122
|
|
|
123
123
|
### Verdict actions (per test)
|
|
124
124
|
- **Pass** → `- [x] Pass <!-- YYYY-MM-DD -->`
|
|
125
|
-
- **Fail** → ask inline "What went wrong? (optional)"; mark `- [FAIL: <note or "No details provided">] <!-- YYYY-MM-DD
|
|
125
|
+
- **Fail** → ask inline "What went wrong? (optional)"; mark `- [FAIL: <note or "No details provided">] <!-- YYYY-MM-DD -->`. Once recorded, ask inline "File a bug for this? (y/n)" — default no if the user doesn't answer explicitly. On yes: invoke `Skill` `bug-file` with a pre-filled description assembled from the test's `Description`/`Steps`/`EXPECTED` fields and the fail note as `Actual Behavior` (pass this as the skill's `$ARGUMENTS` parameter). After `/bug-file` completes (or the user says no), continue to the next test without delay.
|
|
126
126
|
- **Skip** → ask inline "Reason for skipping? (optional)"; mark `- [SKIP: <reason or "User skipped">] <!-- YYYY-MM-DD -->`
|
|
127
127
|
- **Fix now** → see Fix workflow. Process all non-fix verdicts in the batch first, then handle fix-now tests one at a time.
|
|
128
128
|
|
|
@@ -107,6 +107,33 @@ Report format:
|
|
|
107
107
|
|
|
108
108
|
Report-only — provenance is a human judgment (whether a page is genuinely `inferred`), so these are never auto-fixed (see Step 4).
|
|
109
109
|
|
|
110
|
+
### 2.11 Typed-link target resolution (MEDIUM)
|
|
111
|
+
|
|
112
|
+
Scan all wiki pages for `keyword::[[target]]` patterns (vocabulary defined in `wiki/conventions.md` §3: `derived_from`, `supersedes`, `superseded_by`, `implements`, `uses`, `depends_on`, `contradicts`, `relates_to`, `caused`, `fixed`). For each match, resolve the target to confirm it exists:
|
|
113
|
+
|
|
114
|
+
**Resolution logic:**
|
|
115
|
+
- **Decision targets** (`DEC-NNNN` or `DEC-NNNN#DM`): Confirm the file exists in `wiki/work/decisions/` or `wiki/work/decisions/archive/`. If `#DM` anchor is present, confirm that decision block (`## <Title>` + `Status: <status>` pattern) exists in the file.
|
|
116
|
+
- **Work-family targets** (`TASK-NNNN`, `BUG-NNNN`, `UAT-NNNN`, `REQ-NNNN`, `ROADMAP-NNNN`): Confirm the file exists in the respective family directory (`wiki/work/<family>/`) or `wiki/work/<family>/archive/`.
|
|
117
|
+
- **Knowledge page targets** (bare slugs, e.g. `[[typed-wiki-links]]`): Confirm a page with a matching `id:` or entry in `aliases:` frontmatter exists under `wiki/knowledge/`.
|
|
118
|
+
|
|
119
|
+
**Reporting:**
|
|
120
|
+
- **Unresolved targets** — report as `[MEDIUM] dangling typed link — <file>:<line> — <keyword>::[[<target>]] does not resolve to any existing page or work item`.
|
|
121
|
+
- **Superseded decision targets** — if a target resolves to a decision block with `Status: superseded by DEC-N#DX`, report separately as `[LOW] typed link to superseded decision — <file>:<line> — consider updating to DEC-N#DX` (informational, not broken; the link still resolves).
|
|
122
|
+
|
|
123
|
+
### 2.12 Task-less accepted decisions (MEDIUM)
|
|
124
|
+
|
|
125
|
+
For each decision file in `wiki/work/decisions/` (excluding `lifecycle.md`; include `archive/`), parse every `## D*` decision block — each H2 matching `## D\d+\.` is a decision block, collected in document order. For each block:
|
|
126
|
+
|
|
127
|
+
- Skip unless `Status: accepted` — only accepted decisions need a follow-up task; skip `proposed`, `deprecated`, `superseded by …`.
|
|
128
|
+
- A decision is task-less if its `### Links` section is absent, or has no `Source task(s):` line, or the `Source task(s):` line is blank / contains only a placeholder (e.g. "none yet").
|
|
129
|
+
|
|
130
|
+
Unlike `/decision-next` (which stops at the first gap), report **every** task-less accepted decision found across all decision files — matching this skill's "report all, fix none without approval" contract.
|
|
131
|
+
|
|
132
|
+
Report format:
|
|
133
|
+
```
|
|
134
|
+
[MEDIUM] task-less accepted decision — DEC-NNNN#DM (<title>) has no Source task(s) link
|
|
135
|
+
```
|
|
136
|
+
|
|
110
137
|
## Step 3: Report findings
|
|
111
138
|
|
|
112
139
|
Group by severity (HIGH / MEDIUM / LOW). For each finding:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@codewizard-dt/bootstrap",
|
|
3
|
-
"version": "5.
|
|
3
|
+
"version": "5.3.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": {
|