@codewizard-dt/bootstrap 4.0.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/README.md +18 -60
- package/lib/prompts/README.md +0 -1
- package/lib/scripts/README.md +1 -2
- package/lib/scripts/migrate-project.sh +1 -1
- package/lib/scripts/setup-project.sh +0 -1
- package/lib/scripts/sync-wiki-scaffold.sh +3 -15
- package/lib/scripts/templates/CLAUDE-wiki.md +4 -4
- package/lib/scripts/templates/bootstrap-prefs-schema.json +1 -1
- package/lib/scripts/templates/wiki/conventions.md +4 -2
- package/lib/scripts/templates/wiki/dashboard.html +2 -2
- package/lib/scripts/templates/wiki/index.md +4 -4
- package/lib/scripts/templates/wiki/work/requirements/index.md +1 -1
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +2 -2
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +1 -1
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +4 -4
- package/lib/scripts/templates/wiki/work/tasks/index.md +1 -1
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +6 -6
- package/lib/scripts/templates/wiki/work/uat/index.md +1 -1
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +4 -4
- package/lib/scripts/wiki-dashboard-server.js +1 -1
- package/lib/skills/README.md +2 -1
- package/lib/skills/architecture-audit/SKILL.md +228 -0
- package/lib/skills/bug-close/SKILL.md +5 -2
- package/lib/skills/bug-file/SKILL.md +24 -6
- package/lib/skills/decision-create/SKILL.md +7 -2
- 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/power-mode/SKILL.md +10 -10
- package/lib/skills/primer/SKILL.md +1 -1
- package/lib/skills/req-compile/SKILL.md +2 -2
- package/lib/skills/req-create/SKILL.md +13 -9
- package/lib/skills/req-extract-decisions/SKILL.md +10 -10
- package/lib/skills/req-finalize/SKILL.md +3 -3
- package/lib/skills/req-retire/SKILL.md +10 -10
- package/lib/skills/req-update/SKILL.md +4 -4
- package/lib/skills/roadmap-assess/SKILL.md +7 -7
- package/lib/skills/roadmap-create/SKILL.md +26 -22
- package/lib/skills/roadmap-next/SKILL.md +10 -10
- package/lib/skills/security-audit/SKILL.md +3 -0
- package/lib/skills/tackle/SKILL.md +3 -3
- package/lib/skills/task-add/SKILL.md +41 -22
- package/lib/skills/task-audit/SKILL.md +2 -2
- package/lib/skills/task-trash/SKILL.md +4 -4
- package/lib/skills/uat-auto/SKILL.md +2 -1
- package/lib/skills/uat-generate/SKILL.md +22 -22
- package/lib/skills/uat-skip/SKILL.md +21 -21
- package/lib/skills/uat-walk/SKILL.md +1 -1
- package/lib/skills/uat-walk/UAT-CORE.md +6 -6
- package/lib/skills/wiki-lint/SKILL.md +28 -1
- package/package.json +1 -1
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: architecture-audit
|
|
3
|
+
description: Audit an AI agent/application's architecture across 9 categories — design fit (single- vs. multi-agent justification, orchestration topology, delegation hygiene, framework/SDK fit, compounding-error containment) and operational readiness (observability, cost/resource controls, context/state management, cross-agent safety composition). Run a full audit or a single named category.
|
|
4
|
+
category: researching
|
|
5
|
+
model: claude-opus-5
|
|
6
|
+
argument-hint: "[category-name | full]"
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# AI Architecture Audit
|
|
12
|
+
|
|
13
|
+
Structured architecture audit of this project's agentic/LLM system design. **Audits and reports only — does not fix.**
|
|
14
|
+
|
|
15
|
+
**Invocation** `$ARGUMENTS`: empty/`full` → all 9 categories · named category (e.g. `orchestration-topology`) → that one · `design` → the 5 design-fit categories · `operations` → the 4 operational-readiness categories.
|
|
16
|
+
|
|
17
|
+
## Setup (before any category)
|
|
18
|
+
|
|
19
|
+
1. **Read project context** — `mcp__serena__list_dir` on root + key dirs (src, app, api, lib, server, agents, orchestrator, workflows, tools, skills).
|
|
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
|
+
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
|
+
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).
|
|
24
|
+
|
|
25
|
+
Use Serena `find_symbol` / `search_for_pattern` to locate code — never shell `grep`/`find`.
|
|
26
|
+
|
|
27
|
+
## Category reference
|
|
28
|
+
|
|
29
|
+
| ID | Category | Group |
|
|
30
|
+
|----|----------|-------|
|
|
31
|
+
| `architecture-fit` | Single- vs. Multi-Agent Fit | Design |
|
|
32
|
+
| `orchestration-topology` | Orchestration Topology | Design |
|
|
33
|
+
| `delegation-hygiene` | Delegation & Prompt Hygiene | Design |
|
|
34
|
+
| `framework-fit` | Framework / SDK Fit | Design |
|
|
35
|
+
| `error-containment` | Compounding-Error Containment | Design |
|
|
36
|
+
| `observability` | Agent Observability & Tracing | Operations |
|
|
37
|
+
| `cost-resource-controls` | Cost & Resource Controls | Operations |
|
|
38
|
+
| `context-state-management` | Context & State Management | Operations |
|
|
39
|
+
| `safety-composition` | Cross-Agent Safety Composition | Operations |
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Design-fit categories
|
|
44
|
+
|
|
45
|
+
### `architecture-fit` — Single- vs. Multi-Agent Fit
|
|
46
|
+
Multi-agent systems cost roughly 4-15x a single-chat interaction in tokens; the gain only shows up on genuinely breadth-first, parallelizable work. Teams that skip this check routinely build elaborate multi-agent systems that a better-prompted single agent would have matched.
|
|
47
|
+
|
|
48
|
+
| # | Check | How to verify |
|
|
49
|
+
|---|-------|---------------|
|
|
50
|
+
| AF1 | The task class this system targets is actually breadth-first/parallelizable (independent facets, independent files/records) rather than a single linear reasoning chain | Read the orchestrator's task-decomposition logic or prompt; does it fan out over genuinely independent units? |
|
|
51
|
+
| AF2 | A single-agent or code-defined-workflow baseline was tried/considered before multi-agent was adopted, or there's a documented reason it wasn't | Check ADRs/decision docs, comments, or commit history for the design rationale |
|
|
52
|
+
| AF3 | Subagent/team count scales with query complexity rather than being a fixed high number for every request | Find team-size logic — is there a simple/complex branch, or is it always N agents? |
|
|
53
|
+
| AF4 | The system doesn't spawn a new agent for tasks a single tool call or direct response could handle | Sample a few entry points — trace what triggers agent spawning vs. direct execution |
|
|
54
|
+
| AF5 | Token/cost multiplier of the multi-agent path vs. a single-agent equivalent has been measured or estimated, not assumed | Look for benchmarking, eval comparisons, or cost analysis docs |
|
|
55
|
+
|
|
56
|
+
**Severity if missing**: HIGH for AF1–AF2 (wrong default costs compound on every request), MEDIUM for AF3–AF5.
|
|
57
|
+
|
|
58
|
+
### `orchestration-topology` — Orchestration Topology
|
|
59
|
+
The pattern that survives production is hierarchical orchestrator + isolated subagents; peer-to-peer "group chat" topologies have a documented failure mode where a single false premise cascades to 100% of agents.
|
|
60
|
+
|
|
61
|
+
| # | Check | How to verify |
|
|
62
|
+
|---|-------|---------------|
|
|
63
|
+
| OT1 | A single orchestrator/lead agent assigns work and owns final synthesis — subagents don't coordinate directly with each other | Trace message/control flow between agents |
|
|
64
|
+
| OT2 | Subagents are stateless or locally-scoped, not sharing a mutable global state that any agent can write | Check subagent context construction — do they receive isolated inputs? |
|
|
65
|
+
| OT3 | No peer-to-peer "group chat" / mesh topology where agents debate or negotiate directly without orchestrator mediation | Look for direct agent-to-agent message passing outside the orchestrator |
|
|
66
|
+
| OT4 | If a router/supervisor pattern is used instead of full orchestration, routing decisions are logged and deterministic where possible (not silently LLM-guessed) | Find the routing/classification step and its output handling |
|
|
67
|
+
| OT5 | Subagent results return to the orchestrator for verification/synthesis rather than being trusted and passed straight downstream | Trace what happens to a subagent's raw output after it returns |
|
|
68
|
+
|
|
69
|
+
**Severity if missing**: CRITICAL for OT3 (documented production failure mode), HIGH for OT1–OT2, MEDIUM for OT4–OT5.
|
|
70
|
+
|
|
71
|
+
### `delegation-hygiene` — Delegation & Prompt Hygiene
|
|
72
|
+
Every subagent needs an explicit objective, output format, tool/source guidance, and task boundary; subagents should return distilled summaries, not full transcripts, back to the lead — raw transcripts pollute the lead's context and burn tokens at the multi-agent cost multiplier.
|
|
73
|
+
|
|
74
|
+
| # | Check | How to verify |
|
|
75
|
+
|---|-------|---------------|
|
|
76
|
+
| DH1 | Each subagent invocation carries an explicit objective and expected output format, not just a raw forwarded user request | Read subagent prompt-construction code/skill text |
|
|
77
|
+
| DH2 | Subagents are given explicit tool/source guidance and a task boundary (what's in scope, what's out) | Same — check for scope-limiting language |
|
|
78
|
+
| DH3 | Subagents return a distilled summary/result to the lead agent, not their full tool-call transcript | Check what's captured from a subagent call and passed back up |
|
|
79
|
+
| DH4 | Effort-scaling rules exist so a simple query can't accidentally spawn a large team | Find team-size/effort selection logic and its default |
|
|
80
|
+
| DH5 | Fresh (non-forked) subagents receive full necessary context in the prompt itself — the delegator doesn't assume shared memory the subagent doesn't have | Read a sample delegation prompt for self-containment |
|
|
81
|
+
|
|
82
|
+
**Severity if missing**: HIGH for DH1–DH3 (directly drives cost and quality), MEDIUM for DH4–DH5.
|
|
83
|
+
|
|
84
|
+
### `framework-fit` — Framework / SDK Fit
|
|
85
|
+
Vendor-native SDKs win when committed to one provider; LangGraph earns its complexity only when graph/checkpointing durability is actually needed; CrewAI trades production maturity for prototyping speed; AutoGen is maintenance-only and shouldn't anchor new work.
|
|
86
|
+
|
|
87
|
+
| # | Check | How to verify |
|
|
88
|
+
|---|-------|---------------|
|
|
89
|
+
| FF1 | The chosen framework/SDK matches actual needs (durable checkpointing → LangGraph; single-provider → vendor-native SDK; fast prototyping → CrewAI; TS product backend → Mastra; TS UI+streaming → Vercel AI SDK) rather than being inherited by default | Check framework imports against what the system actually does with them |
|
|
90
|
+
| FF2 | The system is not built on AutoGen for new/active development | Check dependency manifests for `autogen`/`pyautogen` |
|
|
91
|
+
| FF3 | If a provider-neutral framework was chosen while only ever calling one model provider, there's a specific reason (multi-provider roadmap, need for the framework's graph/state machinery) | Check model client config vs. framework choice |
|
|
92
|
+
| FF4 | Framework version is pinned, and any framework-specific abstraction (state graph, crew config) is not duplicating functionality the vendor SDK already provides for free | Check lockfile/manifest pinning; look for redundant home-grown orchestration next to an already-capable framework |
|
|
93
|
+
| FF5 | If using the Claude Agent SDK, it's clearly distinguished in code/docs from the Messages API Tool Runner (`client.beta.messages.tool_runner`) — the former ships the full Claude Code harness (filesystem/bash tools included), the latter only loops over developer-defined tools | Check which package is imported and whether docs/comments describe its actual scope correctly |
|
|
94
|
+
|
|
95
|
+
**Severity if missing**: HIGH for FF2 (built on a retired framework), MEDIUM for FF1, FF3–FF5.
|
|
96
|
+
|
|
97
|
+
### `error-containment` — Compounding-Error Containment
|
|
98
|
+
At 85% per-step accuracy, a 10-step chain succeeds only ~20% of the time; a wrong output at step N poisons every downstream agent's context, and summarization adds its own lossy error on top. The fix is architectural: decompose into small, independently verifiable units rather than one monolithic chain.
|
|
99
|
+
|
|
100
|
+
| # | Check | How to verify |
|
|
101
|
+
|---|-------|---------------|
|
|
102
|
+
| EC1 | Multi-step/multi-agent workflows are decomposed into atomic subtasks whose outputs can be independently verified before entering downstream context | Trace a workflow's step boundaries — is there a check between steps, or a blind pass-through? |
|
|
103
|
+
| EC2 | Long agent chains have an explicit accuracy/success expectation, not an assumption that each step is reliable | Look for retry logic, validation steps, or documented error budgets |
|
|
104
|
+
| EC3 | A verification or review step exists before a subagent's output is treated as ground truth by later steps (mirrors the code-review "verify" pattern already used elsewhere in this repo's own skills) | Check for a distinct verify/critique phase vs. single-pass execution |
|
|
105
|
+
| EC4 | Summarization steps (context compression, subagent-result distillation) are checked for information loss on critical facts, not applied uniformly with no spot-check | Find summarization logic and any safeguards around it |
|
|
106
|
+
| EC5 | Failure in one subtask degrades gracefully (partial result, flagged gap) rather than silently propagating a wrong answer through the rest of the pipeline | Trace error-handling paths from a subagent/tool failure |
|
|
107
|
+
|
|
108
|
+
**Severity if missing**: HIGH for EC1, EC3 (structural risk compounds silently), MEDIUM for EC2, EC4–EC5.
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## Operational-readiness categories
|
|
113
|
+
|
|
114
|
+
### `observability` — Agent Observability & Tracing
|
|
115
|
+
Without tracing of routing decisions, tool-call timing, and token/cost by agent, incidents in a multi-step system are nearly impossible to diagnose after the fact — and for a Claude Code–based system specifically, this may already be available for free via the harness's built-in OpenTelemetry export.
|
|
116
|
+
|
|
117
|
+
| # | Check | How to verify |
|
|
118
|
+
|---|-------|---------------|
|
|
119
|
+
| OB1 | Agent/tool-call spans are instrumented (ideally OTel GenAI semantic conventions: `gen_ai.*`, `invoke_agent`/`execute_tool` spans) so a request's full delegation chain is reconstructable | Search for tracing SDK usage, span creation around LLM/tool calls |
|
|
120
|
+
| OB2 | Token usage and cost are attributable per agent/subagent/skill, not just aggregated globally | Check metrics emission — is there a per-agent or per-role dimension? |
|
|
121
|
+
| OB3 | Tool-call timing and latency are captured, not just success/failure | Look for duration measurement around tool execution |
|
|
122
|
+
| OB4 | Routing/orchestration decisions (which subagent was chosen, why) are logged, not just their outcomes | Check orchestrator logging around the dispatch/routing step |
|
|
123
|
+
| OB5 | If this is a Claude Code–based system, `CLAUDE_CODE_ENABLE_TELEMETRY`/`OTEL_*` (built-in metrics, log events, beta distributed traces with nested subagent spans) has been evaluated and a decision made, not left unexamined | Check for any documentation, env config, or explicit decision record about Claude Code's native OTel export |
|
|
124
|
+
| OB6 | Telemetry defaults to structural data only (durations, model names, token counts) — prompt/tool-argument content logging is an explicit, reviewed opt-in, not a default | Check `OTEL_LOG_USER_PROMPTS`/`OTEL_LOG_TOOL_DETAILS`-equivalent flags and their default state |
|
|
125
|
+
|
|
126
|
+
**Severity if missing**: HIGH for OB1–OB4 (no incident-investigation capability), MEDIUM for OB5–OB6.
|
|
127
|
+
|
|
128
|
+
### `cost-resource-controls` — Cost & Resource Controls
|
|
129
|
+
Recursive or looping agent calls and unscaled team sizes turn a benign request into a runaway cost; controls need to exist at the orchestration layer, not just the API layer.
|
|
130
|
+
|
|
131
|
+
| # | Check | How to verify |
|
|
132
|
+
|---|-------|---------------|
|
|
133
|
+
| CR1 | Agent recursion depth or iteration count is capped (circuit breaker on runaway delegation loops) | Search for max_iterations/max_depth guards in orchestration code |
|
|
134
|
+
| CR2 | Per-request or per-session token/cost budgets are enforced, with multi-agent fan-out counted against the same budget | Check budget/limit logic — does it account for subagent token spend, not just the top-level call? |
|
|
135
|
+
| CR3 | Concurrent subagent count is bounded (matches this repo's own convention of hard-coded team-size caps, e.g. min/max concurrency per orchestrator) | Check concurrency limits in the orchestrator |
|
|
136
|
+
| CR4 | A cost-anomaly alert exists for spend spikes attributable to agent/tool misbehavior | Check billing/cost monitoring config |
|
|
137
|
+
| CR5 | Timeouts exist on individual agent/tool calls so one hung step doesn't block or inflate the whole pipeline | Check timeout params on model/tool clients |
|
|
138
|
+
|
|
139
|
+
**Severity if missing**: HIGH for CR1–CR3 (direct runaway-cost risk), MEDIUM for CR4–CR5.
|
|
140
|
+
|
|
141
|
+
### `context-state-management` — Context & State Management
|
|
142
|
+
Context window growth in multi-turn or multi-agent workflows must be bounded; unmanaged growth degrades quality and inflates cost, and naive summarization can silently drop critical facts.
|
|
143
|
+
|
|
144
|
+
| # | Check | How to verify |
|
|
145
|
+
|---|-------|---------------|
|
|
146
|
+
| CS1 | Conversation/session history is pruned, summarized, or windowed rather than growing unbounded across turns | Look for history management/truncation logic |
|
|
147
|
+
| CS2 | Subagent context is constructed explicitly per-call (fresh subagents get what they need in the prompt) rather than relying on implicit shared state | Check subagent invocation — is context assembled deliberately or inherited by default assumption? |
|
|
148
|
+
| CS3 | State that must persist across steps (task state, roadmap/task status, workflow progress) lives in a durable, inspectable store, not only in an LLM's working context | Check where cross-step state is actually written (files, DB, wiki) vs. held only in-context |
|
|
149
|
+
| CS4 | Any automatic context-compression feature (memory summarization, observational memory) has visibility into when it fires and what it costs, rather than running as an invisible background process | Check for logging/telemetry around compression events |
|
|
150
|
+
| CS5 | Long-running or resumable workflows checkpoint state so a crash or interruption doesn't require replaying the entire chain | Check for checkpoint/resume support in the workflow engine |
|
|
151
|
+
|
|
152
|
+
**Severity if missing**: HIGH for CS1, CS3 (direct cost/quality and correctness risk), MEDIUM for CS2, CS4–CS5.
|
|
153
|
+
|
|
154
|
+
### `safety-composition` — Cross-Agent Safety Composition
|
|
155
|
+
Individually-benign behavior in each agent can compound into an unwanted *global* outcome across a multi-agent system — per-agent safety does not automatically compose into system-level safety.
|
|
156
|
+
|
|
157
|
+
| # | Check | How to verify |
|
|
158
|
+
|---|-------|---------------|
|
|
159
|
+
| SC1 | System-level behavior (not just each agent's individual output) is reviewed or tested — e.g. does the combination of subagent outputs ever produce an outcome no single agent would have produced alone? | Check for integration-level tests/evals beyond per-agent unit checks |
|
|
160
|
+
| SC2 | Destructive or irreversible actions require the same HITL gating regardless of which agent in the chain initiates them (a subagent can't bypass a gate the orchestrator enforces) | Trace a destructive action's authorization path when triggered by a subagent vs. the lead agent |
|
|
161
|
+
| SC3 | Shared resources/tools used by multiple agents have consistent permission scoping — one agent's tool grant isn't inherited by another via shared context | Check tool/permission assignment per agent role |
|
|
162
|
+
| SC4 | A quirk or drift in one agent's behavior (e.g. a subagent that over-triggers a tool) is monitored at the aggregate/system level, not just per-agent | Check for system-level monitoring/alerting distinct from per-agent logs |
|
|
163
|
+
| SC5 | Agent role boundaries are enforced structurally (scoped tools/prompts), not only by instruction — an agent shouldn't be able to talk itself into another agent's authority | Check whether role/tool restriction is code-level or prompt-level only |
|
|
164
|
+
|
|
165
|
+
**Severity if missing**: CRITICAL for SC2 (bypassable HITL gate), HIGH for SC1, SC3, MEDIUM for SC4–SC5.
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## Reporting
|
|
170
|
+
|
|
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
|
+
```
|
|
185
|
+
|
|
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).
|
|
187
|
+
|
|
188
|
+
**Report structure:**
|
|
189
|
+
```
|
|
190
|
+
## AI Architecture Audit — [project] — [date]
|
|
191
|
+
Architecture shape: [single agent / code-defined workflow / multi-agent — N roles, topology]
|
|
192
|
+
Categories audited: [list]
|
|
193
|
+
|
|
194
|
+
### Topology
|
|
195
|
+
```mermaid
|
|
196
|
+
flowchart TD
|
|
197
|
+
...
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### [Category Name]
|
|
201
|
+
| Check | Status | Notes |
|
|
202
|
+
|-------|--------|-------|
|
|
203
|
+
| AF1 | ✅ | Task decomposition is genuinely breadth-first — see lib/skills/power-mode/SKILL.md:L… |
|
|
204
|
+
| OT3 | ❌ | Subagents pass results directly to each other outside orchestrator control |
|
|
205
|
+
**Category verdict**: FAIL (1+ CRITICAL failures)
|
|
206
|
+
**Priority mitigations**: [specific action + file reference] …
|
|
207
|
+
|
|
208
|
+
### Summary
|
|
209
|
+
| Category | Verdict | Critical | High | Medium |
|
|
210
|
+
|----------|---------|----------|------|--------|
|
|
211
|
+
**Overall architecture posture**: [CRITICAL / HIGH / MEDIUM / LOW]
|
|
212
|
+
**Top 3 actions to take now**: 1. … 2. … 3. …
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
**Verdict rules:** CRITICAL posture = any CRITICAL finding fails · HIGH = all CRITICAL pass but 2+ HIGH fail · MEDIUM = all CRITICAL & HIGH pass or WARN · LOW = only MEDIUM and below.
|
|
216
|
+
|
|
217
|
+
## CRITICAL rules
|
|
218
|
+
|
|
219
|
+
1. **Read code, don't run it** — verify architecture claims by reading implementation/skill definitions, never by attempting live load tests or real multi-agent runs.
|
|
220
|
+
2. **Cite specific files and line numbers** for every PASS or FAIL — say where you looked; "no evidence found" alone is insufficient.
|
|
221
|
+
3. **Serena for all code navigation** (`find_symbol`, `search_for_pattern`, `get_symbols_overview`) — no shell grep.
|
|
222
|
+
4. **Flag NEEDS-REVIEW honestly** — controls needing runtime observation (e.g. actual token-cost multiplier, live cascade behavior) get flagged with what to verify manually.
|
|
223
|
+
5. **Do not fix** — audit and report only; hand off fixes to the user or `/task-add`.
|
|
224
|
+
6. **Scope to the repo** — don't speculate about external infra unless config files are present.
|
|
225
|
+
7. **One category at a time** — complete each fully before the next; don't interleave findings.
|
|
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."
|
|
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.
|
|
@@ -85,7 +85,7 @@ Use `AskUserQuestion` (batched where the UI permits):
|
|
|
85
85
|
| Fix commit | Short SHA (or "see PR") | **Yes** |
|
|
86
86
|
| Fix version | Release tag or `—` | No |
|
|
87
87
|
| Linked PR | `#NNN` or full URL or `—` | No (recommended) |
|
|
88
|
-
| Linked task | `[[TASK-
|
|
88
|
+
| Linked task | `[[TASK-NNNN]]` or `—` | No |
|
|
89
89
|
| **Regression test** | Path to an automated test that fails-before / passes-after, **or** path to a UAT entry that exercises the fix | **Yes** |
|
|
90
90
|
|
|
91
91
|
For **Verify and close**, both required fields must be supplied. If the user cannot name a regression test, STOP and tell them:
|
|
@@ -123,7 +123,7 @@ Use **`Edit`** — one targeted call. Never `sed`, `awk`, `perl -i`, or `echo >>
|
|
|
123
123
|
|
|
124
124
|
### Step 9: Cross-Linking
|
|
125
125
|
|
|
126
|
-
- If a `Linked task` was provided in `[[TASK-
|
|
126
|
+
- If a `Linked task` was provided in `[[TASK-NNNN]]` format: resolve the task file using `mcp__serena__find_file` with pattern `TASK-NNNN-*` searching `wiki/work/tasks/` (finds active or archived). Then open the task file and append `- Closes BUG-NNNN` to its footer (after the existing UAT link section, or under a new `**Closes**:` line). Use `Edit`.
|
|
127
127
|
- If a `Linked PR` was provided and PR is open: remind the user to add `Closes BUG-NNNN` to the PR description so GitHub auto-references the bug record.
|
|
128
128
|
|
|
129
129
|
### Step 10: Report Completion
|
|
@@ -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
|
---
|
|
@@ -51,7 +51,9 @@ For each missing required-on-report field, use `AskUserQuestion`. Batch related
|
|
|
51
51
|
|
|
52
52
|
**Do not** ask for `Priority`, `Assignee`, `Impact`, `Workaround`, `Tags`, `Linked task`, `Root Cause`, or `Resolution` — those belong to `/bug-triage` or `/bug-close`. Leaving them blank (or with the templated placeholder line) on initial filing is correct.
|
|
53
53
|
|
|
54
|
-
**Exception**: if the user mentions a task in `$ARGUMENTS`, accept it in either `TASK-
|
|
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
|
+
|
|
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).
|
|
55
57
|
|
|
56
58
|
If the user cannot supply reliable Steps to Reproduce, STOP and tell them:
|
|
57
59
|
|
|
@@ -70,26 +72,42 @@ Derive the slug from the title: lowercase, hyphen-separated, 2–5 words, ≤ 60
|
|
|
70
72
|
### Step 5: Present and Confirm
|
|
71
73
|
|
|
72
74
|
Before writing, present:
|
|
73
|
-
- Resolved filename: `wiki/work/bugs/NNNN-<slug>.md`
|
|
75
|
+
- Resolved filename: `wiki/work/bugs/BUG-NNNN-<slug>.md`
|
|
74
76
|
- Title, Severity, Reporter
|
|
75
77
|
- The gathered Environment, Steps, Expected, Actual, Reproducibility values
|
|
76
78
|
|
|
77
79
|
Ask the user to confirm via `AskUserQuestion` ("File this bug? Yes / Edit / Cancel"). If `Cancel`, STOP. If `Edit`, ask which field and re-prompt.
|
|
78
80
|
|
|
81
|
+
### Step 5a: Re-verify next bug number — IMMEDIATELY before writing
|
|
82
|
+
|
|
83
|
+
Re-run the scan from Step 4. If the number planned in Step 4/5 is now taken, silently bump to the new next-available number. **Never call `Write` before completing this re-scan.**
|
|
84
|
+
|
|
79
85
|
### Step 6: Write the Bug File
|
|
80
86
|
|
|
81
|
-
Use `Write` to create `wiki/work/bugs/NNNN-<slug>.md`, following the frontmatter schema in `wiki/work/bugs/lifecycle.md` and the field set gathered in Steps 3–5. Set:
|
|
87
|
+
Use `Write` to create `wiki/work/bugs/BUG-NNNN-<slug>.md`, following the frontmatter schema in `wiki/work/bugs/lifecycle.md` and the field set gathered in Steps 3–5. Set:
|
|
82
88
|
|
|
83
89
|
- `Status: new`
|
|
84
90
|
- `Priority: —` (filled in triage)
|
|
85
91
|
- `Assignee: —` (filled in triage)
|
|
86
92
|
- `Tags: —` (filled in triage)
|
|
87
|
-
- `linked_task:` — `"[[TASK-
|
|
93
|
+
- `linked_task:` — `"[[TASK-NNNN]]"` if a task was mentioned (normalized from either `TASK-NNNN` or `[[TASK-NNNN]]` input); `"—"` otherwise
|
|
88
94
|
- `Reported`: today's date (`YYYY-MM-DD`)
|
|
89
95
|
- `Last updated`: today's date
|
|
90
96
|
- `aliases: [BUG-NNNN]` — mirrors this file's own id: field so Obsidian's wikilink resolver can find it by short ID (ROADMAP-008)
|
|
91
97
|
- Leave `Root Cause Analysis`, `Resolution`, and `Related` sections present but empty (the templated placeholder line under each `>` quote is fine)
|
|
92
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
|
+
|
|
93
111
|
### Step 7: Update the Bug Index
|
|
94
112
|
|
|
95
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`):
|
|
@@ -105,7 +123,7 @@ Use **`Edit`** — one targeted call. Never `sed`, `awk`, `perl -i`, or `echo >>
|
|
|
105
123
|
### Step 8: Report Completion
|
|
106
124
|
|
|
107
125
|
Print:
|
|
108
|
-
- Created file: `wiki/work/bugs/NNNN-<slug>.md`
|
|
126
|
+
- Created file: `wiki/work/bugs/BUG-NNNN-<slug>.md`
|
|
109
127
|
- Bug ID: `BUG-NNNN`
|
|
110
128
|
- Status: `new`
|
|
111
129
|
- Next step:
|
|
@@ -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,10 +74,14 @@ 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
|
|
|
81
|
+
## Step 4.5: Re-verify next decision number — IMMEDIATELY before writing
|
|
82
|
+
|
|
83
|
+
Re-run the scan from Step 2 (`list_dir` on `wiki/work/decisions/` and `archive/`, highest 4-digit prefix + 1). If the number planned earlier is now taken, silently bump to the new next-available number. **Never call `Write` before completing this re-scan.**
|
|
84
|
+
|
|
80
85
|
## Step 5: Generate the file
|
|
81
86
|
Write to `wiki/work/decisions/DEC-NNNN-<group-slug>.md` using this template. **Tables only, mermaid for flows** — mandatory in every block.
|
|
82
87
|
|
|
@@ -168,7 +173,7 @@ flowchart LR
|
|
|
168
173
|
### Links
|
|
169
174
|
- Related decisions: [[DEC-NNNN-slug|DEC-NNNN#DM: title]]
|
|
170
175
|
- Supersedes: [[DEC-MMMM-slug|DEC-MMMM#DK: title]] (if applicable)
|
|
171
|
-
- Source task(s): `wiki/work/tasks/TASK-
|
|
176
|
+
- Source task(s): `wiki/work/tasks/TASK-NNNN-slug.md`
|
|
172
177
|
|
|
173
178
|
---
|
|
174
179
|
|
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)
|