@codewizard-dt/bootstrap 4.0.0 → 5.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/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 +1 -1
- 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 +207 -0
- package/lib/skills/bug-close/SKILL.md +2 -2
- package/lib/skills/bug-file/SKILL.md +9 -5
- package/lib/skills/decision-create/SKILL.md +5 -1
- 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 +22 -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 +22 -22
- package/lib/skills/task-audit/SKILL.md +2 -2
- package/lib/skills/task-trash/SKILL.md +4 -4
- package/lib/skills/uat-generate/SKILL.md +22 -22
- package/lib/skills/uat-skip/SKILL.md +21 -21
- package/lib/skills/uat-walk/UAT-CORE.md +6 -6
- package/lib/skills/wiki-lint/SKILL.md +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,207 @@
|
|
|
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
|
+
|
|
24
|
+
Use Serena `find_symbol` / `search_for_pattern` to locate code — never shell `grep`/`find`.
|
|
25
|
+
|
|
26
|
+
## Category reference
|
|
27
|
+
|
|
28
|
+
| ID | Category | Group |
|
|
29
|
+
|----|----------|-------|
|
|
30
|
+
| `architecture-fit` | Single- vs. Multi-Agent Fit | Design |
|
|
31
|
+
| `orchestration-topology` | Orchestration Topology | Design |
|
|
32
|
+
| `delegation-hygiene` | Delegation & Prompt Hygiene | Design |
|
|
33
|
+
| `framework-fit` | Framework / SDK Fit | Design |
|
|
34
|
+
| `error-containment` | Compounding-Error Containment | Design |
|
|
35
|
+
| `observability` | Agent Observability & Tracing | Operations |
|
|
36
|
+
| `cost-resource-controls` | Cost & Resource Controls | Operations |
|
|
37
|
+
| `context-state-management` | Context & State Management | Operations |
|
|
38
|
+
| `safety-composition` | Cross-Agent Safety Composition | Operations |
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Design-fit categories
|
|
43
|
+
|
|
44
|
+
### `architecture-fit` — Single- vs. Multi-Agent Fit
|
|
45
|
+
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.
|
|
46
|
+
|
|
47
|
+
| # | Check | How to verify |
|
|
48
|
+
|---|-------|---------------|
|
|
49
|
+
| 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? |
|
|
50
|
+
| 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 |
|
|
51
|
+
| 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? |
|
|
52
|
+
| 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 |
|
|
53
|
+
| 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 |
|
|
54
|
+
|
|
55
|
+
**Severity if missing**: HIGH for AF1–AF2 (wrong default costs compound on every request), MEDIUM for AF3–AF5.
|
|
56
|
+
|
|
57
|
+
### `orchestration-topology` — Orchestration Topology
|
|
58
|
+
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.
|
|
59
|
+
|
|
60
|
+
| # | Check | How to verify |
|
|
61
|
+
|---|-------|---------------|
|
|
62
|
+
| 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 |
|
|
63
|
+
| 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? |
|
|
64
|
+
| 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 |
|
|
65
|
+
| 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 |
|
|
66
|
+
| 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 |
|
|
67
|
+
|
|
68
|
+
**Severity if missing**: CRITICAL for OT3 (documented production failure mode), HIGH for OT1–OT2, MEDIUM for OT4–OT5.
|
|
69
|
+
|
|
70
|
+
### `delegation-hygiene` — Delegation & Prompt Hygiene
|
|
71
|
+
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.
|
|
72
|
+
|
|
73
|
+
| # | Check | How to verify |
|
|
74
|
+
|---|-------|---------------|
|
|
75
|
+
| 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 |
|
|
76
|
+
| 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 |
|
|
77
|
+
| 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 |
|
|
78
|
+
| 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 |
|
|
79
|
+
| 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 |
|
|
80
|
+
|
|
81
|
+
**Severity if missing**: HIGH for DH1–DH3 (directly drives cost and quality), MEDIUM for DH4–DH5.
|
|
82
|
+
|
|
83
|
+
### `framework-fit` — Framework / SDK Fit
|
|
84
|
+
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.
|
|
85
|
+
|
|
86
|
+
| # | Check | How to verify |
|
|
87
|
+
|---|-------|---------------|
|
|
88
|
+
| 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 |
|
|
89
|
+
| FF2 | The system is not built on AutoGen for new/active development | Check dependency manifests for `autogen`/`pyautogen` |
|
|
90
|
+
| 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 |
|
|
91
|
+
| 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 |
|
|
92
|
+
| 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 |
|
|
93
|
+
|
|
94
|
+
**Severity if missing**: HIGH for FF2 (built on a retired framework), MEDIUM for FF1, FF3–FF5.
|
|
95
|
+
|
|
96
|
+
### `error-containment` — Compounding-Error Containment
|
|
97
|
+
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.
|
|
98
|
+
|
|
99
|
+
| # | Check | How to verify |
|
|
100
|
+
|---|-------|---------------|
|
|
101
|
+
| 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? |
|
|
102
|
+
| 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 |
|
|
103
|
+
| 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 |
|
|
104
|
+
| 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 |
|
|
105
|
+
| 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 |
|
|
106
|
+
|
|
107
|
+
**Severity if missing**: HIGH for EC1, EC3 (structural risk compounds silently), MEDIUM for EC2, EC4–EC5.
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## Operational-readiness categories
|
|
112
|
+
|
|
113
|
+
### `observability` — Agent Observability & Tracing
|
|
114
|
+
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.
|
|
115
|
+
|
|
116
|
+
| # | Check | How to verify |
|
|
117
|
+
|---|-------|---------------|
|
|
118
|
+
| 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 |
|
|
119
|
+
| 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? |
|
|
120
|
+
| OB3 | Tool-call timing and latency are captured, not just success/failure | Look for duration measurement around tool execution |
|
|
121
|
+
| OB4 | Routing/orchestration decisions (which subagent was chosen, why) are logged, not just their outcomes | Check orchestrator logging around the dispatch/routing step |
|
|
122
|
+
| 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 |
|
|
123
|
+
| 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 |
|
|
124
|
+
|
|
125
|
+
**Severity if missing**: HIGH for OB1–OB4 (no incident-investigation capability), MEDIUM for OB5–OB6.
|
|
126
|
+
|
|
127
|
+
### `cost-resource-controls` — Cost & Resource Controls
|
|
128
|
+
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.
|
|
129
|
+
|
|
130
|
+
| # | Check | How to verify |
|
|
131
|
+
|---|-------|---------------|
|
|
132
|
+
| 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 |
|
|
133
|
+
| 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? |
|
|
134
|
+
| 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 |
|
|
135
|
+
| CR4 | A cost-anomaly alert exists for spend spikes attributable to agent/tool misbehavior | Check billing/cost monitoring config |
|
|
136
|
+
| 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 |
|
|
137
|
+
|
|
138
|
+
**Severity if missing**: HIGH for CR1–CR3 (direct runaway-cost risk), MEDIUM for CR4–CR5.
|
|
139
|
+
|
|
140
|
+
### `context-state-management` — Context & State Management
|
|
141
|
+
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.
|
|
142
|
+
|
|
143
|
+
| # | Check | How to verify |
|
|
144
|
+
|---|-------|---------------|
|
|
145
|
+
| CS1 | Conversation/session history is pruned, summarized, or windowed rather than growing unbounded across turns | Look for history management/truncation logic |
|
|
146
|
+
| 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? |
|
|
147
|
+
| 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 |
|
|
148
|
+
| 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 |
|
|
149
|
+
| 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 |
|
|
150
|
+
|
|
151
|
+
**Severity if missing**: HIGH for CS1, CS3 (direct cost/quality and correctness risk), MEDIUM for CS2, CS4–CS5.
|
|
152
|
+
|
|
153
|
+
### `safety-composition` — Cross-Agent Safety Composition
|
|
154
|
+
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.
|
|
155
|
+
|
|
156
|
+
| # | Check | How to verify |
|
|
157
|
+
|---|-------|---------------|
|
|
158
|
+
| 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 |
|
|
159
|
+
| 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 |
|
|
160
|
+
| 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 |
|
|
161
|
+
| 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 |
|
|
162
|
+
| 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 |
|
|
163
|
+
|
|
164
|
+
**Severity if missing**: CRITICAL for SC2 (bypassable HITL gate), HIGH for SC1, SC3, MEDIUM for SC4–SC5.
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## Reporting
|
|
169
|
+
|
|
170
|
+
**Output**: after compiling findings, write the full report to `.docs/architecture-audit/report-<YYYY-MM-DD>.md` using the **Write** tool (create the directory if it doesn't exist). If a report for today already exists, write `report-<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.
|
|
171
|
+
|
|
172
|
+
**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
|
+
|
|
174
|
+
**Report structure:**
|
|
175
|
+
```
|
|
176
|
+
## AI Architecture Audit — [project] — [date]
|
|
177
|
+
Architecture shape: [single agent / code-defined workflow / multi-agent — N roles, topology]
|
|
178
|
+
Categories audited: [list]
|
|
179
|
+
|
|
180
|
+
### [Category Name]
|
|
181
|
+
| Check | Status | Notes |
|
|
182
|
+
|-------|--------|-------|
|
|
183
|
+
| AF1 | ✅ | Task decomposition is genuinely breadth-first — see lib/skills/power-mode/SKILL.md:L… |
|
|
184
|
+
| OT3 | ❌ | Subagents pass results directly to each other outside orchestrator control |
|
|
185
|
+
**Category verdict**: FAIL (1+ CRITICAL failures)
|
|
186
|
+
**Priority mitigations**: [specific action + file reference] …
|
|
187
|
+
|
|
188
|
+
### Summary
|
|
189
|
+
| Category | Verdict | Critical | High | Medium |
|
|
190
|
+
|----------|---------|----------|------|--------|
|
|
191
|
+
**Overall architecture posture**: [CRITICAL / HIGH / MEDIUM / LOW]
|
|
192
|
+
**Top 3 actions to take now**: 1. … 2. … 3. …
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
**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.
|
|
196
|
+
|
|
197
|
+
## CRITICAL rules
|
|
198
|
+
|
|
199
|
+
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.
|
|
200
|
+
2. **Cite specific files and line numbers** for every PASS or FAIL — say where you looked; "no evidence found" alone is insufficient.
|
|
201
|
+
3. **Serena for all code navigation** (`find_symbol`, `search_for_pattern`, `get_symbols_overview`) — no shell grep.
|
|
202
|
+
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.
|
|
203
|
+
5. **Do not fix** — audit and report only; hand off fixes to the user or `/task-add`.
|
|
204
|
+
6. **Scope to the repo** — don't speculate about external infra unless config files are present.
|
|
205
|
+
7. **One category at a time** — complete each fully before the next; don't interleave findings.
|
|
206
|
+
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 `.docs/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.
|
|
@@ -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
|
|
@@ -51,7 +51,7 @@ 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
55
|
|
|
56
56
|
If the user cannot supply reliable Steps to Reproduce, STOP and tell them:
|
|
57
57
|
|
|
@@ -70,21 +70,25 @@ Derive the slug from the title: lowercase, hyphen-separated, 2–5 words, ≤ 60
|
|
|
70
70
|
### Step 5: Present and Confirm
|
|
71
71
|
|
|
72
72
|
Before writing, present:
|
|
73
|
-
- Resolved filename: `wiki/work/bugs/NNNN-<slug>.md`
|
|
73
|
+
- Resolved filename: `wiki/work/bugs/BUG-NNNN-<slug>.md`
|
|
74
74
|
- Title, Severity, Reporter
|
|
75
75
|
- The gathered Environment, Steps, Expected, Actual, Reproducibility values
|
|
76
76
|
|
|
77
77
|
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
78
|
|
|
79
|
+
### Step 5a: Re-verify next bug number — IMMEDIATELY before writing
|
|
80
|
+
|
|
81
|
+
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.**
|
|
82
|
+
|
|
79
83
|
### Step 6: Write the Bug File
|
|
80
84
|
|
|
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:
|
|
85
|
+
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
86
|
|
|
83
87
|
- `Status: new`
|
|
84
88
|
- `Priority: —` (filled in triage)
|
|
85
89
|
- `Assignee: —` (filled in triage)
|
|
86
90
|
- `Tags: —` (filled in triage)
|
|
87
|
-
- `linked_task:` — `"[[TASK-
|
|
91
|
+
- `linked_task:` — `"[[TASK-NNNN]]"` if a task was mentioned (normalized from either `TASK-NNNN` or `[[TASK-NNNN]]` input); `"—"` otherwise
|
|
88
92
|
- `Reported`: today's date (`YYYY-MM-DD`)
|
|
89
93
|
- `Last updated`: today's date
|
|
90
94
|
- `aliases: [BUG-NNNN]` — mirrors this file's own id: field so Obsidian's wikilink resolver can find it by short ID (ROADMAP-008)
|
|
@@ -105,7 +109,7 @@ Use **`Edit`** — one targeted call. Never `sed`, `awk`, `perl -i`, or `echo >>
|
|
|
105
109
|
### Step 8: Report Completion
|
|
106
110
|
|
|
107
111
|
Print:
|
|
108
|
-
- Created file: `wiki/work/bugs/NNNN-<slug>.md`
|
|
112
|
+
- Created file: `wiki/work/bugs/BUG-NNNN-<slug>.md`
|
|
109
113
|
- Bug ID: `BUG-NNNN`
|
|
110
114
|
- Status: `new`
|
|
111
115
|
- Next step:
|
|
@@ -77,6 +77,10 @@ Group members may share evidence sources (Shared Context), but each block needs
|
|
|
77
77
|
|
|
78
78
|
**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
79
|
|
|
80
|
+
## Step 4.5: Re-verify next decision number — IMMEDIATELY before writing
|
|
81
|
+
|
|
82
|
+
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.**
|
|
83
|
+
|
|
80
84
|
## Step 5: Generate the file
|
|
81
85
|
Write to `wiki/work/decisions/DEC-NNNN-<group-slug>.md` using this template. **Tables only, mermaid for flows** — mandatory in every block.
|
|
82
86
|
|
|
@@ -168,7 +172,7 @@ flowchart LR
|
|
|
168
172
|
### Links
|
|
169
173
|
- Related decisions: [[DEC-NNNN-slug|DEC-NNNN#DM: title]]
|
|
170
174
|
- Supersedes: [[DEC-MMMM-slug|DEC-MMMM#DK: title]] (if applicable)
|
|
171
|
-
- Source task(s): `wiki/work/tasks/TASK-
|
|
175
|
+
- Source task(s): `wiki/work/tasks/TASK-NNNN-slug.md`
|
|
172
176
|
|
|
173
177
|
---
|
|
174
178
|
|
|
@@ -19,8 +19,8 @@ Use this skill to drive tasks or roadmaps to completion using a parallel agent t
|
|
|
19
19
|
**Trigger:** `/power-mode <path>` with no additional instructions.
|
|
20
20
|
|
|
21
21
|
Inspect the path argument:
|
|
22
|
-
- Path contains `roadmap` or matches `ROADMAP-
|
|
23
|
-
- Path contains `task` or matches `TASK-
|
|
22
|
+
- Path contains `roadmap` or matches `ROADMAP-NNNN` → **Roadmap-to-Completion Orchestrator** (see below)
|
|
23
|
+
- Path contains `task` or matches `TASK-NNNN` → **Single-Task Executor** (see below)
|
|
24
24
|
|
|
25
25
|
---
|
|
26
26
|
|
|
@@ -57,7 +57,7 @@ All agent call examples below omit this footer for brevity — it is always requ
|
|
|
57
57
|
|
|
58
58
|
## Single-Task Executor
|
|
59
59
|
|
|
60
|
-
**Trigger:** `/power-mode <path/to/TASK-
|
|
60
|
+
**Trigger:** `/power-mode <path/to/TASK-NNNN.md>` with no additional instructions.
|
|
61
61
|
|
|
62
62
|
**Goal:** Drive one task through the full tackle → UAT-generate → UAT-auto pipeline exactly once, then stop.
|
|
63
63
|
|
|
@@ -67,7 +67,7 @@ All agent call examples below omit this footer for brevity — it is always requ
|
|
|
67
67
|
|
|
68
68
|
```
|
|
69
69
|
Agent({
|
|
70
|
-
description: "Tackle <TASK-
|
|
70
|
+
description: "Tackle <TASK-NNNN>",
|
|
71
71
|
prompt: "Run /tackle <task-path>. [append team member footer]",
|
|
72
72
|
mode: "bypassPermissions"
|
|
73
73
|
})
|
|
@@ -79,7 +79,7 @@ Wait for the agent to complete.
|
|
|
79
79
|
|
|
80
80
|
```
|
|
81
81
|
Agent({
|
|
82
|
-
description: "UAT generate <TASK-
|
|
82
|
+
description: "UAT generate <TASK-NNNN>",
|
|
83
83
|
prompt: "Run /uat-generate <task-path>. [append team member footer]",
|
|
84
84
|
mode: "bypassPermissions"
|
|
85
85
|
})
|
|
@@ -91,7 +91,7 @@ Wait for the agent to complete.
|
|
|
91
91
|
|
|
92
92
|
```
|
|
93
93
|
Agent({
|
|
94
|
-
description: "UAT auto <TASK-
|
|
94
|
+
description: "UAT auto <TASK-NNNN>",
|
|
95
95
|
prompt: "Run /uat-auto <uat-path> (infer the UAT file path from the task path — same NNN slug, under wiki/work/uat/).
|
|
96
96
|
|
|
97
97
|
Note: on all-pass, /uat-auto's own UAT-CORE Closure procedure already flips the task to done, archives both files, removes index rows, and auto-checks the matching roadmap checkbox (if any) — you do not need to instruct any of that here; it happens natively. Just wait for it to complete and report its summary.
|
|
@@ -109,7 +109,7 @@ Done. No further iteration.
|
|
|
109
109
|
|
|
110
110
|
## Roadmap-to-Completion Orchestrator
|
|
111
111
|
|
|
112
|
-
**Trigger:** `/power-mode <path/to/ROADMAP-
|
|
112
|
+
**Trigger:** `/power-mode <path/to/ROADMAP-NNNN.md>` with no additional instructions.
|
|
113
113
|
|
|
114
114
|
**Goal:** Drive the roadmap to completion — every item through the full tackle → UAT-generate → UAT-auto pipeline — looping through waves of parallelizable work until no implementation work remains.
|
|
115
115
|
|
|
@@ -150,7 +150,7 @@ Run tackle → UAT-generate → UAT-auto for all tasks in the current wave. Appl
|
|
|
150
150
|
|
|
151
151
|
Phase 1 — Tackle (parallel, minimum 5 agents when 5+ collision-safe tasks available):
|
|
152
152
|
```
|
|
153
|
-
Agent({ description: "Tackle TASK-
|
|
153
|
+
Agent({ description: "Tackle TASK-NNNN", prompt: "Run /tackle <path>. [append team member footer]", mode: "bypassPermissions" })
|
|
154
154
|
Agent({ description: "Tackle TASK-MMM", prompt: "Run /tackle <path>. [append team member footer]", mode: "bypassPermissions" })
|
|
155
155
|
// ... one per task, all in the same message
|
|
156
156
|
```
|
|
@@ -159,7 +159,7 @@ Wait for all to complete.
|
|
|
159
159
|
|
|
160
160
|
Phase 2 — Generate UAT tests (parallel, read-only):
|
|
161
161
|
```
|
|
162
|
-
Agent({ description: "UAT generate TASK-
|
|
162
|
+
Agent({ description: "UAT generate TASK-NNNN", prompt: "Run /uat-generate <task-path>. [append team member footer]", mode: "bypassPermissions" })
|
|
163
163
|
// ... one per task, all in the same message
|
|
164
164
|
```
|
|
165
165
|
|
|
@@ -168,7 +168,7 @@ Wait for all to complete.
|
|
|
168
168
|
Phase 3 — Run UATs (parallel when UAT files don't collide):
|
|
169
169
|
```
|
|
170
170
|
Agent({
|
|
171
|
-
description: "UAT auto TASK-
|
|
171
|
+
description: "UAT auto TASK-NNNN",
|
|
172
172
|
prompt: "Run /uat-auto <uat-path>.
|
|
173
173
|
|
|
174
174
|
Note: on all-pass, /uat-auto's own UAT-CORE Closure procedure already flips the task to done, archives both files, removes index rows, and auto-checks the matching roadmap checkbox — no need to instruct any of that here.
|
|
@@ -75,7 +75,7 @@ See `wiki/guides/mcp-tools.md` for the complete Serena memory reference.
|
|
|
75
75
|
|
|
76
76
|
## Step 4: Check the Task Index
|
|
77
77
|
|
|
78
|
-
`/tackle` no-args mode surveys active tasks by reading `wiki/work/tasks/index.md` — a flat bullet list of active items (`- [TASK-
|
|
78
|
+
`/tackle` no-args mode surveys active tasks by reading `wiki/work/tasks/index.md` — a flat bullet list of active items (`- [TASK-NNNN — Title](TASK-NNNN-slug.md) — one-line summary · status`), one line per `todo`/`in-progress` task. There is no table to "bootstrap"; do a lightweight consistency check so that survey stays trustworthy.
|
|
79
79
|
|
|
80
80
|
1. Use `mcp__serena__list_dir` on `wiki/work/tasks/` to list task files (top-level only, not `archive/`). If the directory is empty or has no task files, skip this step.
|
|
81
81
|
2. Read `wiki/work/tasks/index.md` (use `Read` — markdown).
|
|
@@ -22,7 +22,7 @@ intent discovered mid-build — but zero *preventable* ones. This skill encodes
|
|
|
22
22
|
It inherits the global manifesto (least code, simplest architecture, maximal correctness,
|
|
23
23
|
no docs unless asked). This is the *how-to-build*; the manifesto is *what good looks like*.
|
|
24
24
|
|
|
25
|
-
**Input:** a project dir with a `wiki/work/requirements/REQ-
|
|
25
|
+
**Input:** a project dir with a `wiki/work/requirements/REQ-NNNN-slug.md` (REQ) file + a project `CLAUDE.md`
|
|
26
26
|
(stack, hosting, boundaries).
|
|
27
27
|
**Output:** code — a typed boundary contract, *failing* oracle stubs, and the answered batched
|
|
28
28
|
forks. Not documentation.
|
|
@@ -49,7 +49,7 @@ Parse `$ARGUMENTS` to find the requirement file:
|
|
|
49
49
|
| `<path>` (e.g. `wiki/work/requirements/REQ-003-onboarding.md`) | Use as-is |
|
|
50
50
|
| `<NNN-slug>` (e.g. `003-onboarding`) | `mcp__serena__find_file` with mask `003-onboarding.md` under `wiki/work/requirements/` |
|
|
51
51
|
| `<NNN>` (e.g. `3` or `003`) | Pad to 3 digits; `mcp__serena__find_file` with mask `NNN-*.md` under `wiki/work/requirements/` |
|
|
52
|
-
| Empty / missing | Look for any `wiki/work/requirements/REQ-
|
|
52
|
+
| Empty / missing | Look for any `wiki/work/requirements/REQ-NNNN-slug.md` with `status: approved`; if ambiguous, ask via `AskUserQuestion` |
|
|
53
53
|
|
|
54
54
|
**Verify the requirement has `status: approved`** before proceeding. If `draft`, tell the user to run `/req-finalize <path>` first. If `retired` or `superseded`, refuse — no system should be built against a cancelled requirement.
|
|
55
55
|
|
|
@@ -33,7 +33,7 @@ Write when there's a real problem worth aligning on, more than one decision area
|
|
|
33
33
|
3. Read `CLAUDE.md`, `PROJECT_STATUS.md` (if present), `wiki/work/requirements/lifecycle.md` (authoritative template/lifecycle/anti-patterns), and a sample of recent requirements for local conventions.
|
|
34
34
|
|
|
35
35
|
## Step 2: Locate directory, assign number
|
|
36
|
-
Requirements live at `wiki/work/requirements/REQ-
|
|
36
|
+
Requirements live at `wiki/work/requirements/REQ-NNNN-slug.md` (4-digit zero-padded). `list_dir` both `wiki/work/requirements/` and `wiki/work/requirements/archive/` (skip either that doesn't exist) — highest prefix across both + 1 (first is `REQ-0001`). Never re-use a number; retired requirements keep theirs forever. Derive the slug — names the **initiative**, lowercase dash-separated ≤60 chars (e.g. "Self-serve billing portal" → `REQ-0004-self-serve-billing-portal.md`). Confirm number + slug via `AskUserQuestion` if non-obvious.
|
|
37
37
|
|
|
38
38
|
## Step 3: Research (optional, scoped)
|
|
39
39
|
For an unfamiliar product space, run a **lightweight** `/research` for **product context only**:
|
|
@@ -68,13 +68,17 @@ Walk the elicitations **in order**. Batch related ones into a single round when
|
|
|
68
68
|
## Step 5: Preview and confirm before writing
|
|
69
69
|
Present a **tabular preview** of every elicited section; user confirms via `AskUserQuestion` (*Approve and write* / *Edit specific section* / *Cancel*). **Do not write until explicit approval.** Preview must include at least: Header (Title, status `draft`, Owner, Stakeholders, Tags), Problem Statement (full), Personas (table), User Stories (`US-N` titles + AC counts), Success Metrics (full table), Goals→Metrics (full table showing the link), Non-Goals (full table), Constraints/Assumptions/Open Questions (tables or "(empty — none elicited)"). Edits → loop back to the relevant Step 4 elicitation and re-present.
|
|
70
70
|
|
|
71
|
+
### Step 5a: Re-verify next requirement number — IMMEDIATELY before writing
|
|
72
|
+
|
|
73
|
+
Re-run the scan from Step 2. If the number planned earlier is now taken, silently bump to the new next-available number. **Never call `Write` before completing this re-scan.**
|
|
74
|
+
|
|
71
75
|
## Step 6: Write the file
|
|
72
|
-
After confirmation, `Write` `wiki/work/requirements/REQ-
|
|
76
|
+
After confirmation, `Write` `wiki/work/requirements/REQ-NNNN-slug.md`.
|
|
73
77
|
|
|
74
78
|
```yaml
|
|
75
79
|
---
|
|
76
|
-
id: REQ-
|
|
77
|
-
aliases: [REQ-
|
|
80
|
+
id: REQ-NNNN
|
|
81
|
+
aliases: [REQ-NNNN]
|
|
78
82
|
type: requirement
|
|
79
83
|
status: draft
|
|
80
84
|
created: YYYY-MM-DD
|
|
@@ -86,21 +90,21 @@ tags: [<tag1>, <tag2>]
|
|
|
86
90
|
---
|
|
87
91
|
```
|
|
88
92
|
|
|
89
|
-
Sections in order: `# REQ-
|
|
93
|
+
Sections in order: `# REQ-NNNN: <Title>` · `## Problem Statement` · `## Goals` (table, every row links a Success Metric ID) · `## Non-Goals` (≥1 row) · `## Personas` (table) · `## User Stories` (each `### US-N. <title>` with the story sentence + an AC table) · `## Success Metrics` (table) · `## Constraints` / `## Assumptions` / `## Open Questions` (table or "(none — placeholder retained)") · `## Linked Decisions` (empty, retain explanatory blockquote) · `## Linked Tasks` (empty, blockquote) · `## Notes` (empty) · `## Amendments` (empty, `<!-- Amendments appear here as ## Amendment 1, ## Amendment 2, etc. -->`).
|
|
90
94
|
|
|
91
95
|
**Refuse to write** if any required-non-empty field is missing or fails its bar — loop back to Step 4.
|
|
92
96
|
|
|
93
97
|
## Step 7: Update indexes + log (`Edit` only, never `sed`/`awk`/`echo >>`)
|
|
94
|
-
|
|
98
|
+
Append (or replace the placeholder row) in `wiki/work/requirements/index.md` using the format documented at the top of that file: `- [REQ-NNNN — Title](REQ-NNNN-slug.md) — one-line summary · status`, in ascending REQ order. Append to `wiki/log.md`: `## [YYYY-MM-DD] req-create | REQ-NNNN <title>`.
|
|
95
99
|
|
|
96
100
|
## Step 8: Cross-link related artifacts
|
|
97
|
-
If prompted by an existing task/research note/reference, link both ways (`Read` then `Edit`, never `sed`): source artifact gets `**Requirement**: REQ-
|
|
101
|
+
If prompted by an existing task/research note/reference, link both ways (`Read` then `Edit`, never `sed`): source artifact gets `**Requirement**: REQ-NNNN ([file](<relative-link>))` in a sensible section; the new requirement references the source in `## Notes` (e.g. "Originated from `wiki/work/tasks/TASK-012-runbook-triage.md`"). No related artifact → skip.
|
|
98
102
|
|
|
99
103
|
## Step 9: Update memory if appropriate
|
|
100
|
-
`mcp__serena__write_memory` only for a **non-obvious** product insight future sessions benefit from (a genuinely new persona; a regulatory constraint; a known product gotcha) — skip self-evident ones or conjecture. Topic-hierarchical name (`product/personas/sre-oncall`, `product/constraints/soc2-admin-logging`), referencing `REQ-
|
|
104
|
+
`mcp__serena__write_memory` only for a **non-obvious** product insight future sessions benefit from (a genuinely new persona; a regulatory constraint; a known product gotcha) — skip self-evident ones or conjecture. Topic-hierarchical name (`product/personas/sre-oncall`, `product/constraints/soc2-admin-logging`), referencing `REQ-NNNN` in the body.
|
|
101
105
|
|
|
102
106
|
## Step 10: Report
|
|
103
|
-
Tabular summary: File path, Status (`draft`), Personas/User Stories/Success Metrics/Non-Goals counts, Constraints/Assumptions/Open Questions (populated/empty per section), index updated (1 row), log appended, cross-links (list or *none*), memory (name or *skipped*), suggested next step `/req-finalize wiki/work/requirements/REQ-
|
|
107
|
+
Tabular summary: File path, Status (`draft`), Personas/User Stories/Success Metrics/Non-Goals counts, Constraints/Assumptions/Open Questions (populated/empty per section), index updated (1 row), log appended, cross-links (list or *none*), memory (name or *skipped*), suggested next step `/req-finalize wiki/work/requirements/REQ-NNNN-slug.md`. Note any placeholder-reduced field under a **Gaps** section for the user to address before `/req-finalize`.
|
|
104
108
|
|
|
105
109
|
---
|
|
106
110
|
|
|
@@ -134,7 +134,7 @@ For **each proposed group**, ask: "Create this as a decision now?" with options:
|
|
|
134
134
|
| `merge into <Gx>` | Combine this group with another listed group |
|
|
135
135
|
| `split` | Break this group into multiple smaller groups |
|
|
136
136
|
| `skip — already covered` | Drop the group; the ASR is handled by an existing decision |
|
|
137
|
-
| `skip — non-architectural` | Drop the group; handle directly via `/task-add --req REQ-
|
|
137
|
+
| `skip — non-architectural` | Drop the group; handle directly via `/task-add --req REQ-NNNN` |
|
|
138
138
|
|
|
139
139
|
### Step 7: Update the requirement's `## Linked Decisions` section
|
|
140
140
|
|
|
@@ -161,7 +161,7 @@ Also update the requirement's frontmatter `updated` to today's date. Both edits
|
|
|
161
161
|
Append to `wiki/log.md`:
|
|
162
162
|
|
|
163
163
|
```
|
|
164
|
-
## [YYYY-MM-DD] req-extract-decisions | REQ-
|
|
164
|
+
## [YYYY-MM-DD] req-extract-decisions | REQ-NNNN <title> — N ASRs identified
|
|
165
165
|
```
|
|
166
166
|
|
|
167
167
|
### Step 8: Update existing decisions that reuse requirement ASRs
|
|
@@ -172,8 +172,8 @@ For each affected decision file:
|
|
|
172
172
|
|
|
173
173
|
1. `Read` the file
|
|
174
174
|
2. Locate the target decision's `### Links` section
|
|
175
|
-
3. Check whether `Source REQ: REQ-
|
|
176
|
-
4. `Edit` to append: `- Source REQ: [REQ-
|
|
175
|
+
3. Check whether `Source REQ: REQ-NNNN` already exists — **skip if present** (idempotent)
|
|
176
|
+
4. `Edit` to append: `- Source REQ: [REQ-NNNN](../requirements/NNN-slug.md)`
|
|
177
177
|
|
|
178
178
|
Touch only the target decision's `### Links`. Do not modify any decision's status, metadata, or content beyond the `### Links` append.
|
|
179
179
|
|
|
@@ -183,7 +183,7 @@ Print a tabular completion report:
|
|
|
183
183
|
|
|
184
184
|
| Field | Value |
|
|
185
185
|
|-------|-------|
|
|
186
|
-
| Requirement | `REQ-
|
|
186
|
+
| Requirement | `REQ-NNNN <title>` |
|
|
187
187
|
| ASRs identified | count |
|
|
188
188
|
| ASRs covered by existing decisions | count (linked back) |
|
|
189
189
|
| New decision groups proposed | count |
|
|
@@ -198,10 +198,10 @@ Then list the **next-action commands**, one per confirmed new group:
|
|
|
198
198
|
|
|
199
199
|
```
|
|
200
200
|
To create the proposed decisions, run each:
|
|
201
|
-
/decision-create group: search-infrastructure (from REQ-
|
|
202
|
-
/decision-create hris-integration (from REQ-
|
|
201
|
+
/decision-create group: search-infrastructure (from REQ-NNNN)
|
|
202
|
+
/decision-create hris-integration (from REQ-NNNN)
|
|
203
203
|
|
|
204
|
-
After each /decision-create completes, return to REQ-
|
|
204
|
+
After each /decision-create completes, return to REQ-NNNN's `## Linked Decisions` table
|
|
205
205
|
and update the placeholder row with the actual wikilink [[NNNN-slug|DEC-NNNN#DM]].
|
|
206
206
|
```
|
|
207
207
|
|
|
@@ -209,7 +209,7 @@ If any ASRs were skipped as non-architectural, also surface:
|
|
|
209
209
|
|
|
210
210
|
```
|
|
211
211
|
The following ASRs are best handled directly as tasks (no decision needed):
|
|
212
|
-
/task-add --req REQ-
|
|
212
|
+
/task-add --req REQ-NNNN "<short description for ASR Ax>"
|
|
213
213
|
```
|
|
214
214
|
|
|
215
215
|
The skill does **not** auto-invoke `/decision-create` or `/task-add`. It surfaces the commands; the user runs them.
|
|
@@ -223,7 +223,7 @@ The skill does **not** auto-invoke `/decision-create` or `/task-add`. It surface
|
|
|
223
223
|
3. **Never invent ASRs.** Every entry in the ASR table must trace to a specific requirement section, quoted or paraphrased verbatim.
|
|
224
224
|
4. **Boundary rule is enforced strictly.** Requirements ask for outcomes, decisions admit trade-offs. If a candidate ASR sounds like a solution, reformulate it as the underlying outcome.
|
|
225
225
|
5. **Requirement edits are surgical.** Use `Read` then `Edit` to update only the `## Linked Decisions` table and the `updated` field. Never rewrite the file.
|
|
226
|
-
6. **Idempotent back-links.** If `Source REQ: REQ-
|
|
226
|
+
6. **Idempotent back-links.** If `Source REQ: REQ-NNNN` already exists in a decision's `### Links`, skip the edit. Re-running this skill against the same requirement must not duplicate links.
|
|
227
227
|
7. **Wikilinks for existing decisions.** Use `[[NNNN-slug\|DEC-NNNN#DM]]` format in the `## Linked Decisions` table.
|
|
228
228
|
|
|
229
229
|
---
|
|
@@ -182,7 +182,7 @@ If this requirement's row does not yet exist in the index table, insert a new ro
|
|
|
182
182
|
|
|
183
183
|
| Column | Format |
|
|
184
184
|
|--------|--------|
|
|
185
|
-
| `ID` | `[REQ-
|
|
185
|
+
| `ID` | `[REQ-NNNN](requirements/NNN-slug.md)` |
|
|
186
186
|
| `Title` | The requirement's initiative title |
|
|
187
187
|
| `Status` | `approved` |
|
|
188
188
|
| `Created` | The requirement's `created:` date |
|
|
@@ -193,7 +193,7 @@ If this requirement's row does not yet exist in the index table, insert a new ro
|
|
|
193
193
|
Append to `wiki/log.md`:
|
|
194
194
|
|
|
195
195
|
```
|
|
196
|
-
## [YYYY-MM-DD] req-approved | REQ-
|
|
196
|
+
## [YYYY-MM-DD] req-approved | REQ-NNNN <title>
|
|
197
197
|
```
|
|
198
198
|
|
|
199
199
|
Use `Read` then `Edit` for the index update — never `echo >>` or `sed`.
|
|
@@ -223,7 +223,7 @@ Suggested next steps:
|
|
|
223
223
|
| Suggestion | When to use it |
|
|
224
224
|
|------------|----------------|
|
|
225
225
|
| `/req-extract-decisions <file>` | The default next step — extract Architecturally Significant Requirements and propose decision candidates |
|
|
226
|
-
| `/task-add --req REQ-
|
|
226
|
+
| `/task-add --req REQ-NNNN <description>` | Only when the requirement's scope is small enough to skip decisions entirely |
|
|
227
227
|
| `/req-update <file> <change>` | If a scope change surfaces post-approval — appends an `## Amendment N` block; never rewrites |
|
|
228
228
|
|
|
229
229
|
Do **not** auto-create downstream artifacts — present them as suggestions only.
|