@gobing-ai/spur 0.3.41 → 0.3.43

package/plugins/sp/skills/parallel-execution/references/dispatch-surface.md

@@ -0,0 +1,109 @@
+---
+name: dispatch-surface
+description: "Decision rule for choosing the native subagent versus `spur agent run` when dispatching work to another agent. Trigger-keyed, not preference-stated."
+see_also:
+  - parallel-execution
+  - fan-out-patterns
+  - result-synthesis
+---
+
+# Dispatch Surface: Native Subagent vs `spur agent run`
+
+This is the SSOT for **which execution surface carries a dispatch** to another agent. It owns
+*one axis only* - in-session native subagent versus out-of-process `spur agent run`. It does not
+own which model tier runs the work; that is ADR-033's `model_policy` (see [Composition with
+ADR-033](#composition-with-adr-033)).
+
+The `parallel-execution` skill already owns the dispatch *disciplines* (file-handoffs over pasted
+context, per-role model selection, durable ledgers, never pre-judge the reviewer). Choosing the
+surface a dispatch travels over is the same competency, so the rule lives here alongside them.
+
+## The default
+
+**Use the native subagent when the host platform provides one.**
+
+Native subagents (Claude Code `Skill()`/`Task`, Codex, OpenCode, etc.) are cheaper to spawn, share
+the session's tooling and working directory, and compose with the orchestrating agent's context.
+On a platform that provides them, `spur agent run` is the exception, not the default.
+
+## Escalation triggers to `spur agent run`
+
+Escalate off the native subagent **only** when one of these observable conditions holds. Each is
+checkable without operator judgment - if you cannot point to concrete evidence of one, stay on the
+native subagent.
+
+| # | Trigger | What it means | Example evidence |
+| --- | --------- | --------------- | ------------------ |
+| 1 | **Different model or coding agent required** | The step needs a model or a coding agent the host session cannot provide (`--model`, `--agent`). | "verify on o3" where the host is Claude Code; "run this through omp" from a non-omp host. |
+| 2 | **Headless or unattended step** | The step must run without a live session - scheduled, detached, or driven by a non-interactive caller. | A batch launched by `spur workflow run --async` with no operator attached. |
+| 3 | **Durable auditable run record required** | The dispatch must produce a persisted run record (cost ledger, trace, exit code) for after-the-fact audit. | `spur agent run` writes `.spur/run/` artifacts; a native subagent does not. |
+| 4 | **Workspace or credential isolation required** | The step must run in a separate workspace, worktree, or credential scope from the orchestrating session. | A destructive step isolated to a throwaway worktree; a step that must not inherit the session's `cwd` secrets. |
+
+## The naming requirement
+
+**When you escalate to `spur agent run`, name which trigger applied - in the dispatch, in the
+report, or in the batch ledger.** "Used `spur agent run` because trigger 3 (durable auditable
+record)" is a complete statement; "used `spur agent run`" is not.
+
+This is what makes the choice auditable after the fact. A blanket "prefer subagents when possible"
+is unfalsifiable - an agent can rationalize either surface under it, which is how
+`parallel-execution/SKILL.md` drifted to telling Claude Code to fan out through `spur agent run`
+on the one platform that ships native subagents. Naming one of four checkable conditions makes a
+wrong choice visible in the transcript.
+
+## Composition with ADR-033
+
+[ADR-033](../../../../../docs/00_ADR.md) owns **model-tier selection** through the stage registry's
+`model_policy` (`min_tier` + ordered `fallback` chain, keyed on the canonical `stage_id`). This
+reference owns **execution-surface selection**. The two axes are orthogonal and vary independently:
+
+- A `cheap`-tier step can run in-session on a native subagent.
+- A `capable-3`-tier step can run headless through `spur agent run`.
+
+Do not fold surface choice into `model_policy` - that would couple two axes that vary independently
+and put prompt-layer routing policy into a domain-layer registry. This reference decides *which
+surface carries the work*; ADR-033 decides *which tier runs on it*. Read both; apply each to its
+own axis.
+
+## The sandbox reliability tax on `spur agent run`
+
+`spur agent run` runs the target agent as an external process. Under a sandboxed Bash session it
+can fail outright when the external agent writes its own storage outside the sandbox's allowlist.
+
+**Reproduced during H6 intake:**
+
+```text
+$ spur agent run "..." --agent omp
+SQLiteError: attempt to write a readonly database (SQLITE_READONLY)
+  at .../pi-coding-agent/dist/cli.js:2825
+```
+
+The cause: omp writes its `AgentStorage` SQLite DB under `$HOME/node_modules/`, a path the
+sandboxed Bash session holds read-only. The same failure took down the idea-pipeline's `discovery`
+step (exit code 3, ~1.5s) - the step never reached the agent's logic; it died on storage init.
+
+This is **not** a reason to abandon `spur agent run` - triggers 1-4 still justify it. It is a
+reason to (a) prefer the native subagent when no trigger applies, and (b) when a trigger does
+apply, ensure the run executes in a context that can write the target agent's storage (a
+non-sandboxed shell, or a workspace that owns the storage path). The upstream fix lives in
+pi-coding-agent's storage-path resolution; it is out of scope here and recorded as motivating
+evidence only.
+
+## Composition with the inline pipeline driver (task 0508)
+
+The interactive inline driver (`cross-cutting.md` § Inline-default execution surface) applies this
+reference's default — native subagent first — to sequential `task-pipeline.yaml` `agent.run`
+stages. Eligibility there is the same observable test (pure-slash action, non-interactive state,
+native subagent with shared-worktree capability); the inline driver remains the authority for
+provenance, artifact validation, and no-replay guarantees. This reference stays the authority for
+the native-subagent versus `spur agent run` choice everywhere else.
+
+## See also
+
+- **`parallel-execution`** SKILL.md - the dispatch disciplines this rule sits beside.
+- **[fan-out-patterns.md](fan-out-patterns.md)** - the four fan-out shapes; surface choice is
+  orthogonal to pattern choice.
+- **[result-synthesis.md](result-synthesis.md)** - merging parallel outputs; applies regardless of
+  which surface carried each dispatch.
+- **ADR-033** - model-tier routing via the stage registry; this rule composes with it, never
+  duplicates it.

package/plugins/sp/skills/parallel-execution/references/fan-out-patterns.md

@@ -0,0 +1,101 @@
+---
+name: fan-out-patterns
+description: "Catalog of proven fan-out shapes with per-pattern token-cost estimates, when-to-use decision tables, and anti-patterns."
+see_also:
+  - parallel-execution
+  - result-synthesis
+---
+
+# Fan-Out Patterns
+
+Four proven patterns for parallel subagent execution. Each pattern has a distinct work shape, cost profile, and result expectation. **Match the work shape to the pattern** — don't force a pattern onto mismatched work.
+
+## Pattern catalog
+
+### 1. N-way Investigation
+
+**Use when:** One question, N independent search angles. Each subagent searches a different dimension — by file, by pattern, by subsystem, by time range. The angles are blind to each other by design (multi-modal sweep).
+
+**Token cost:** ~N × 3k tokens per subagent + ~2k synthesis.
+
+**Decision criteria:**
+
+- Single question with multiple search strategies
+- No dependency between search angles
+- Results must be deduped (different angles may find the same thing)
+
+**Example:** "Find all hardcoded secrets in this codebase" → subagent 1 scans by regex, subagent 2 scans by entropy, subagent 3 scans config files, subagent 4 scans CI/CD.
+
+**Anti-pattern:** Using N-way investigation when one angle would find everything. If `rg "API_KEY"` covers 90%, don't fan out 4 ways to find the last 10% — the marginal gain doesn't justify the cost.
+
+### 2. Competency-Lens Review
+
+**Use when:** One artifact (PR, diff, design doc), N review dimensions. Each subagent reviews through a single lens (correctness, security, performance, maintainability, usability). This is the pattern behind adversarial verification.
+
+**Token cost:** ~N × 5k tokens per subagent + ~3k synthesis.
+
+**Decision criteria:**
+
+- Single artifact with multiple quality dimensions
+- Dimensions are independent (security findings don't depend on perf findings)
+- Synthesis must surface conflicts (e.g., perf improvement that weakens security)
+
+**Example:** Code review of a PR → correctness lens, security lens, efficiency lens, maintainability lens. Each subagent produces per-lens findings; synthesis merges into a unified P1–P4 table.
+
+**Anti-pattern:** Using competency-lens review when a single reviewer would catch everything. For a 20-line change, one thorough review beats 3 shallow ones.
+
+### 3. Independent-Task Batch
+
+**Use when:** M tasks with zero dependency edges between them. Each task runs through its pipeline independently. This is the `sp:super-planner` parallel mode.
+
+**Token cost:** ~M × 8k tokens per task + ~3k batch synthesis.
+
+**Decision criteria:**
+
+- Multiple tasks from the same batch
+- Topo-sort confirms zero dependency edges between the selected subset
+- No file-overlap conflicts (different tasks touch different files)
+- Token budget supports M parallel runs
+
+**Example:** Feature A1 decomposes into 5 tasks. Topo-sort shows tasks 2, 3, and 4 have no dependencies on each other → fan out 3-way. Tasks 1 and 5 are sequential (5 depends on 1).
+
+**Anti-pattern:** Fanning out tasks that touch the same files. Two tasks both editing `src/auth/login.ts` WILL produce a merge conflict. Serialize or assign to one subagent.
+
+### 4. Adversarial Verification Panel
+
+**Use when:** One claim needs N independent skeptics. Each subagent tries to REFUTE the claim. A claim survives if ≥2/3 affirm. This is the highest-confidence verification pattern.
+
+**Token cost:** ~N × 4k tokens per subagent + ~2k synthesis.
+
+**Decision criteria:**
+
+- Single factual or testable claim
+- Subagents are prompted to REFUTE (adversarial stance)
+- Vote threshold: ≥ majority must affirm for the claim to survive
+- Use odd N (3, 5) to avoid ties
+
+**Example:** "This refactoring preserves all existing behavior" → 3 subagents independently try to find counterexamples. 2/3 find none → claim survives. 1/3 finds a break → claim is refuted, finding logged.
+
+**Anti-pattern:** Using adversarial panel for subjective questions. "Is this code readable?" has no objective refutation criteria — use competency-lens review instead.
+
+## When-to-use decision table
+
+| Work shape | Pattern | N recommended |
+| ------------ | --------- | --------------- |
+| One question, multiple search angles | N-way investigation | 3–5 |
+| One artifact, multiple quality dimensions | Competency-lens review | 3–4 |
+| M independent tasks | Independent-task batch | 2–8 (budget-limited) |
+| One claim, need high confidence | Adversarial panel | 3–5 (odd) |
+| Sequential dependency chain | **Do not fan out** | — |
+| Single file touched by multiple tasks | **Do not fan out** | — |
+| Token budget < 20k remaining | **Do not fan out** | — |
+
+## Token-budget guard
+
+Before fanning out N subagents, check:
+
+```
+remaining_budget >= (N × per_subagent_estimate) + synthesis_estimate
+```
+
+If not: reduce N, or serialize. A fan-out that exhausts the budget mid-run leaves partial results that are worse than sequential. The driver is responsible for this check — the skill provides the estimates; the orchestrator applies them.

package/plugins/sp/skills/parallel-execution/references/result-synthesis.md

@@ -0,0 +1,94 @@
+---
+name: result-synthesis
+description: "Merge/dedup/conflict-resolution strategies for parallel subagent outputs, anti-patterns, and the unified-report template."
+see_also:
+  - parallel-execution
+  - fan-out-patterns
+---
+
+# Result Synthesis
+
+Parallel subagent outputs must be **synthesized**, not concatenated. Raw dumps from N subagents are noise; a synthesized report is signal. This reference defines the synthesis contract — the rules every fan-out pattern's merge step follows.
+
+## The synthesis contract
+
+### 1. Dedup
+
+Merge findings that share the same `file:line` anchor. Keep the **highest-severity** version.
+
+```
+Subagent A: src/auth.ts:42 — P2 — missing null check
+Subagent B: src/auth.ts:42 — P3 — variable naming unclear
+
+Merged:    src/auth.ts:42 — P2 — missing null check (P3 naming note appended)
+```
+
+**Rule:** same file + same line → one finding. Different lines in the same file are distinct findings.
+
+### 2. Resolve conflicts
+
+When two subagents disagree on the same claim, **surface the disagreement explicitly**. Don't silently pick one.
+
+```
+Subagent A: "The Redis migration is safe — all writes are idempotent"
+Subagent B: "The Redis migration is unsafe — key TTL change breaks cache warming"
+
+Synthesis:  ⚠ CONFLICT — Redis migration safety
+            A: safe (writes idempotent)
+            B: unsafe (TTL breaks cache warming)
+            → Escalate to operator for resolution
+```
+
+**Rule:** conflicts are findings, not failures. Surface them with both positions stated; let the operator resolve.
+
+### 3. Rank by confidence
+
+Sort synthesized results:
+1. HIGH confidence (empirically verified, source-cited)
+2. MEDIUM confidence (reasoned, but not empirically verified)
+3. LOW confidence (heuristic, pattern-match, or uncertain)
+4. Unresolved conflicts (both sides stated)
+
+Within each tier, sort by severity (P1 → P2 → P3 → P4).
+
+### 4. Unified format
+
+Emit one coherent output. The unified report has:
+
+```
+## Synthesized Results
+
+### HIGH Confidence
+| # | Finding | Source | Severity | File:Line |
+|---|---------|--------|----------|-----------|
+
+### MEDIUM Confidence
+...
+
+### Conflicts (unresolved)
+...
+
+### Dropped (deduped into higher-severity)
+...
+
+**Synthesis stats:** N subagents, M raw findings, K after dedup, J conflicts
+```
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Fix |
+|-------------|-------------|-----|
+| **Silent truncation** | "10 items found" but only 8 reported — 2 silently dropped | Always report total → after-dedup counts; document what was dropped and why |
+| **Raw concatenation** | Pasting N subagent outputs end-to-end without merging | Apply the synthesis contract: dedup → resolve → rank → format |
+| **Majority-wins on facts** | "3 subagents say X, 1 says Y → X is correct" — but Y has the evidence | Weight by evidence, not count. One subagent with a repro wins over three without |
+| **Synthesis without audit** | Merged report with no trace of which subagent found what | Every synthesized finding carries a `Source` column naming the originating subagent |
+| **Conflicts resolved silently** | Two opposing findings merged into one without surfacing the disagreement | Conflicts are an explicit section in the unified report |
+
+## Synthesis cost
+
+Budget ~2k tokens for synthesis per pattern. The synthesis step is:
+1. Read all subagent outputs (cached from their runs)
+2. Apply dedup + conflict detection
+3. Emit unified report
+
+Don't re-run subagents during synthesis — their outputs are the input. If a subagent output is malformed or empty, log it as a **dropped subagent** in the synthesis stats.

package/plugins/sp/skills/reverse-engineering/SKILL.md

@@ -0,0 +1,375 @@
+---
+name: reverse-engineering
+description: "Depth-driven codebase reverse engineering with orthogonal mode, focus, and output format controls. Use for unfamiliar codebases, architecture/design reconstruction, onboarding docs, technical debt assessment, and evidence-backed audit reports."
+license: Apache-2.0
+version: 1.1.0
+created_at: 2026-03-28
+updated_at: 2026-07-09
+tags: [analysis-core, reverse-engineering, hld, audit, codebase-analysis, architecture, design]
+metadata:
+  author: cc-agents
+  platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
+  category: analysis-core
+  interactions:
+    - pipeline
+    - reviewer
+  severity_levels:
+    - critical
+    - high
+    - medium
+  pipeline_steps:
+    - orient
+    - index
+    - classify
+    - trace
+    - synthesize
+    - audit
+  openclaw:
+    emoji: "🔍"
+see_also:
+  - sp:source-driven-development
+---
+
+# sp:reverse-engineering — Codebase Reverse Engineering
+
+Analyze unfamiliar or under-documented codebases and reconstruct their current state with evidence. The skill separates three controls:
+
+1. **Mode**: analysis depth.
+2. **Focus**: analysis lens.
+3. **Format**: output encoding.
+
+Mode must not mix action verbs, subject areas, or serialization formats. For example, `json` is a format, not a mode; `data` is a focus, not a mode; `scan` is an internal action, not a user-facing depth.
+
+## When to Use
+
+**Use PROACTIVELY when:**
+
+- User shares an unfamiliar codebase or repo URL.
+- User asks what a project does, how it is structured, or how it runs.
+- User requests HLD, architecture docs, system design docs, ER diagrams, sequence diagrams, or onboarding docs.
+- User needs a technical debt, security, maintainability, performance, or architecture audit.
+- User wants to understand current state before refactoring.
+
+**Do NOT use for:**
+
+- Implementing code changes. Use `sp:code-implementation`.
+- Debugging a specific runtime failure. Use `sp:sys-debugging`.
+- Writing tests. Use `sp:test-driven-development`.
+- Quick structural code search. Use grep/glob tools directly.
+- Creating indexed context files. This skill may read `.spur/context/` context, but it must not create or mutate it.
+
+## Control Model
+
+### Mode: Analysis Depth
+
+| Mode | Complexity | Purpose | Required Outputs | Optional Outputs |
+|---|---:|---|---|---|
+| `briefing` | 1 | Fast executive reconnaissance for "what is this repo?" | purpose hypothesis, tech stack, repo archetype, entry points, key manifests, top 3 risks/unknowns | dependency highlights |
+| `structure` | 2 | Static repository and component map | repository tree summary, module/component table, ownership/boundary notes, dependency map, entry point map | simple component diagram |
+| `architecture` | 3 | Runtime and system architecture documentation | architecture pattern, system context diagram, runtime topology, major flows, cross-cutting concerns, integration map | deployment view, sequence diagrams for main flows |
+| `design` | 4 | Detailed design reconstruction for implementation understanding | architecture summary, data model, API/command/interface contracts, domain model, important sequence diagrams, ER diagram when data evidence exists | class/UML-style diagram, failure modes |
+| `full` | 5 | Comprehensive reverse-engineering package | all `design` outputs plus quality/security audit, modernization roadmap, open questions, evidence index, machine-readable summary | per-module deep dives |
+
+### Focus: Analysis Lens
+
+Focus changes emphasis, not depth.
+
+| Focus | Effect |
+|---|---|
+| `all` | Balanced coverage for the selected mode. Default. |
+| `stack` | Emphasize languages, frameworks, package managers, runtimes, build tooling, and deploy tooling. |
+| `dependencies` | Emphasize internal and external dependency graph, integration points, and coupling. |
+| `data` | Emphasize persistence, schemas, models, repositories, migrations, and ER diagram evidence. |
+| `flows` | Emphasize request, command, job, event, or business process traces and sequence diagrams. |
+| `api` | Emphasize HTTP routes, RPC surfaces, CLI commands, events, SDKs, and public contracts. |
+| `security` | Emphasize auth, authorization, secrets, validation, injection risk, and exposure boundaries. |
+| `quality` | Emphasize maintainability, complexity, dead code, duplication, testability, and refactoring seams. |
+| `performance` | Emphasize hot paths, blocking I/O, caching, query patterns, and scalability risks. |
+
+### Format: Output Encoding
+
+| Format | Purpose |
+|---|---|
+| `markdown` | Human-readable report. Default. |
+| `json` | Machine-readable summary for downstream skills or automation. |
+| `both` | Markdown report plus JSON summary block or output file. |
+
+## Mode Selection Algorithm
+
+1. Parse explicit arguments if provided:
+   - `--mode briefing|structure|architecture|design|full`
+   - `--focus all|stack|dependencies|data|flows|api|security|quality|performance`
+   - `--format markdown|json|both`
+2. If mode is missing, infer it from user intent:
+   - "what is this", "quick overview", "what stack" -> `briefing`
+   - "repo structure", "module map", "component map" -> `structure`
+   - "architecture", "HLD", "system design" -> `architecture`
+   - "ER diagram", "data model", "sequence diagram", "API contract", "detailed design" -> `design`
+   - "reverse engineer everything", "full audit", "complete docs" -> `full`
+3. If focus is missing, infer it from user intent:
+   - stack/runtime/tooling -> `stack`
+   - dependencies/integrations/coupling -> `dependencies`
+   - database/schema/model/repository -> `data`
+   - workflow/request lifecycle/business process -> `flows`
+   - routes/endpoints/commands/events/contracts -> `api`
+   - security/auth/secrets/validation -> `security`
+   - tech debt/maintainability/refactor -> `quality`
+   - latency/scalability/caching/queries -> `performance`
+   - otherwise -> `all`
+4. If format is missing:
+   - Use `json` only when the user explicitly asks for machine-readable output.
+   - Use `both` when the user asks for a report and reusable structured data.
+   - Otherwise use `markdown`.
+5. If ambiguity remains, choose the lowest depth that can satisfy the request. Prefer `architecture` for generic "analyze this codebase".
+
+## Analysis Workflow
+
+Execute phases in order. Stop at the phase boundary required by the selected mode unless focus or evidence requires a deeper targeted read.
+
+### Phase 1: Orient
+
+1. Identify project root and target path.
+2. Check whether `.spur/context/anatomy.md` exists.
+3. Locate manifests and config files: `package.json`, `bun.lockb`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `requirements.txt`, `pom.xml`, `build.gradle`, Docker/Kubernetes files, CI files.
+4. Identify likely language, framework, package manager, runtime, and deploy model.
+5. Record uncertainty when inferred from naming or layout rather than manifest evidence.
+
+### Phase 2: Index
+
+1. If `.spur/context/anatomy.md` exists, use it to prioritize reads and reduce token usage.
+2. Otherwise use file search to build a bounded map of source, config, tests, scripts, docs, migrations, and generated/vendor directories.
+3. Exclude or de-prioritize generated, vendored, build output, dependency cache, lockfile-only, binary-heavy, and snapshot-heavy paths unless they are directly relevant.
+4. For monorepos, identify packages/apps and either ask for scope or analyze each package at the requested depth if feasible.
+
+### Phase 3: Classify
+
+Classify the codebase as one or more archetypes:
+
+- frontend SPA / SSR / static site
+- backend API / worker / service
+- fullstack app
+- CLI tool
+- library / framework
+- plugin system
+- infrastructure repo
+- monorepo
+- mixed or unclear
+
+Include evidence for classification, such as manifest scripts, entry files, route definitions, command declarations, exports, Docker entrypoints, or package layout.
+
+### Phase 4: Trace
+
+Trace only as deeply as the selected mode requires:
+
+- `briefing`: entry points and obvious high-level modules.
+- `structure`: module boundaries, package graph, and dependency direction.
+- `architecture`: runtime topology, integrations, main flows, cross-cutting concerns.
+- `design`: data model, interfaces/contracts, sequence flows, domain model, failure modes.
+- `full`: design-level tracing plus audit, roadmap, open questions, and evidence index.
+
+### Phase 5: Synthesize
+
+Generate the selected format. Every factual claim about stack, entry points, modules, data, flows, APIs, integrations, and risks must include evidence when source files are available.
+
+### Phase 6: Audit
+
+Run audit analysis when:
+
+- mode is `full`
+- focus is `security`, `quality`, `performance`, or `all` at `architecture` depth or deeper
+- user explicitly requests audit, risk, technical debt, or review
+
+Audit categories:
+
+| Category | What to Find | Evidence Required |
+|---|---|---|
+| Security | hardcoded secrets, unsafe auth, missing authorization, injection risks, unsanitized external input, exposed endpoints | `file/path:line` |
+| Correctness | broken control flow, invalid assumptions, race conditions, missing error handling, data loss paths | `file/path:line` |
+| Performance | N+1 queries, blocking I/O, unbounded loops, missing caching, inefficient hot paths | `file/path:line` or measured metric |
+| Maintainability | oversized modules, circular dependencies, dead code, duplication, fragile abstractions | `file/path:line` or file metrics |
+| Architecture | tight coupling, unclear boundaries, leaky layers, missing abstractions, inconsistent module ownership | multiple file references |
+
+## Output Contracts
+
+### `briefing`
+
+```markdown
+# Codebase Briefing: [Project]
+
+| Field | Value |
+|---|---|
+| Analysis Date | YYYY-MM-DD |
+| Target | `path` |
+| Mode / Focus / Format | `briefing` / `[focus]` / `markdown` |
+| Confidence | High / Medium / Low |
+
+## Purpose Hypothesis
+
+[1-3 sentences with evidence]
+
+## Tech Stack
+
+| Layer | Technology | Evidence | Confidence |
+|---|---|---|---|
+
+## Entry Points
+
+| Entry | Purpose | Evidence |
+|---|---|---|
+
+## Top Risks / Unknowns
+
+| Risk | Why It Matters | Evidence / Gap |
+|---|---|---|
+```
+
+### `structure`
+
+Required sections:
+
+- Briefing summary
+- Repository map
+- Module/component table
+- Entry point map
+- Dependency map
+- Boundary notes
+- Optional component diagram
+
+### `architecture`
+
+Required sections:
+
+- Executive summary
+- Architecture pattern
+- System context diagram
+- Runtime topology
+- Component responsibilities
+- Integration map
+- Main flows
+- Cross-cutting concerns
+- Architecture risks
+
+### `design`
+
+Required sections:
+
+- Architecture summary
+- Domain model
+- Data model and ER diagram when evidence exists
+- API/command/event/interface contracts
+- Sequence diagrams for important flows
+- Class/module relationship diagram when source structure supports it
+- Failure modes and operational assumptions
+
+### `full`
+
+Required sections:
+
+- All `design` sections
+- Security, correctness, performance, maintainability, and architecture audit
+- Prioritized remediation roadmap
+- Open questions and unknowns
+- Evidence index
+- Machine-readable summary if requested or useful for downstream skills
+
+### JSON Summary Schema
+
+Use this shape for `--format json` or `--format both`. Omit fields only when the evidence is unavailable and include an `unknowns` entry explaining why.
+
+```json
+{
+  "target": "path",
+  "analysisDate": "YYYY-MM-DD",
+  "mode": "architecture",
+  "focus": "all",
+  "confidence": "high|medium|low",
+  "stack": [],
+  "entryPoints": [],
+  "components": [],
+  "dependencies": [],
+  "dataModel": [],
+  "interfaces": [],
+  "flows": [],
+  "risks": [],
+  "unknowns": [],
+  "evidence": []
+}
+```
+
+## Evidence Rules
+
+- Cite `file/path:line` for claims derived from source files.
+- Cite manifest paths for stack and package manager claims.
+- Cite multiple files for architectural boundary claims when possible.
+- Mark inferred claims with `Confidence: Medium` or `Confidence: Low`.
+- Never invent services, databases, tables, endpoints, actors, diagrams, or business flows that are not supported by evidence.
+- If line numbers are unavailable from a tool, cite the file path and state that line numbers were not available.
+
+## Diagram Rules
+
+Use Mermaid only. Every diagram must be syntactically valid and must reflect evidence.
+
+| Diagram | Mermaid Type | When to Use |
+|---|---|---|
+| System context / component topology | `flowchart LR` or `graph TD` | `structure`, `architecture`, `design`, `full` |
+| Runtime or business flow | `sequenceDiagram` | `architecture`, `design`, `full`, or focus `flows` |
+| Data model | `erDiagram` | focus `data`, `design`, `full` when schema/model evidence exists |
+| Class/module relationship | `classDiagram` | `design` or `full` when source types/classes support it |
+
+Fallback behavior:
+
+- If data evidence is missing, write "No reliable ER diagram can be produced from available evidence."
+- If a sequence cannot be traced end-to-end, diagram only the observed partial flow and mark missing links.
+- If class-level structure is too dynamic or not class-based, use a component graph instead of forcing `classDiagram`.
+
+## Indexed Context Integration
+
+The indexed-context layer is optional and opportunistic.
+
+1. If `.spur/context/anatomy.md` exists, read it before raw file reads to prioritize high-value files.
+2. If `.spur/context/learnings.md` exists, use it only for project preferences and known context.
+3. If `.spur/context/buglog.md` exists, use it only as supporting evidence for known bug history.
+4. Do not create, update, or require `.spur/context/` files.
+5. Verify final claims against source files whenever source files are available.
+6. If `.spur/context/` is absent, proceed normally without warning unless the user explicitly requested indexed context.
+
+## Edge Cases
+
+| Scenario | Handling |
+|---|---|
+| Empty/minimal codebase | Return `briefing` with "insufficient evidence", list missing artifacts, suggest next files needed. |
+| Monorepo | Identify packages/apps; ask for scope unless `--auto` or requested mode can safely summarize all packages. |
+| No clear entry point | List candidates with confidence and evidence; do not choose one as definitive. |
+| Binary-heavy repo | Focus on manifests, scripts, config, docs, and visible source. |
+| Generated/vendor-heavy repo | Exclude generated/vendor paths from architecture conclusions unless directly relevant. |
+| Framework convention over configuration | State inferred convention and cite framework-specific file patterns. |
+| Multiple languages/stacks | Report each stack separately and identify integration boundaries. |
+| Missing data/schema evidence | Skip ER diagram or mark as partial. |
+| Huge codebase | Produce staged output: briefing first, then deeper sections by package or focus. |
+
+## Severity Definitions
+
+| Severity | Criteria | Examples |
+|---|---|---|
+| Critical | Security risk, data loss potential, exploitable vulnerability, blocking correctness bug | SQL injection, hardcoded credentials, destructive race condition |
+| High | Significant reliability, performance, maintainability, or architecture risk | N+1 query in hot path, missing auth boundary, unbounded queue growth |
+| Medium | Meaningful improvement with bounded blast radius | duplication, unclear ownership, weak typing at boundary |
+| Low | Cosmetic or local maintainability issue | naming inconsistency, minor docs gap |
+
+## Platform Notes
+
+### Claude Code
+
+- Use available Read/Glob/Grep/LSP tools for evidence.
+- For large codebases, analyze orientation and audit concerns in parallel when platform delegation is available.
+- Keep final claims evidence-backed; do not rely on memory alone.
+
+### Codex / OpenClaw / OpenCode / Antigravity / Pi
+
+- Prefer `rg` and `rg --files` for scanning.
+- Use structural tools such as `ast-grep` when available for route, class, function, and import discovery.
+- Do not advertise direct analyzer scripts unless such scripts exist in this skill directory.
+
+## Additional Resources
+
+- **Claim verification**: `sp:source-driven-development`