@rryando/arcs 3.7.0 → 3.8.0

package/opencode/arcs/skills/executing-plans/SKILL.md

@@ -10,9 +10,10 @@ description: Use when you have a written implementation plan to execute in a sep
 You have a written implementation plan to execute task-by-task with verification checkpoints.
 
 **NOT for:**
-- If subagents are available → use `subagent-driven-development` instead (parallel dispatch, two-stage review)
 - If the task needs iterative self-correction without a structured plan → use `loop` instead
 
+Sequential single-agent execution is the **default**. When the orchestrator signals 2+ independent sub-problems, switch to **Parallel Mode** (below) — fan-out multi-agent dispatch of independent ready nodes with two-stage review.
+
 > CLI: `arcs --commands --json` for discovery. Mutating commands run directly — no token.
 
 ## Flow
@@ -71,6 +72,159 @@ Sub-agents run `arcs` lookups only to fill gaps the dispatch left open — never
 
 Sub-agents MUST NOT edit `.mmd` files — orchestrator owns diagram updates.
 
+## Parallel Mode
+
+When the orchestrator signals 2+ independent sub-problems, execute the plan via fresh subagents fanned out across independent ready nodes, with two-stage review per task. This replaces the sequential single-agent walk above with diagram-first parallel dispatch.
+
+### Parallel Flow
+
+```mermaid
+flowchart TD
+    A[Load plan + extract all tasks] --> B{Diagram .mmd exists?}
+    B -->|yes| C[arcs diagram ready → get parallel-safe nodes]
+    B -->|no| D[Pick next task sequentially]
+    C --> E[Read node metadata: skill, scope, acceptance, verify]
+    D --> F[Construct subagent prompt]
+    E --> F
+    F --> G[Dispatch implementer subagent]
+    G --> H{Subagent status?}
+    H -->|DONE / DONE_WITH_CONCERNS| I[Dispatch spec-reviewer subagent]
+    H -->|NEEDS_CONTEXT| J[Provide context, re-dispatch]
+    H -->|BLOCKED| K{Assess blocker}
+    J --> G
+    K -->|context gap| J
+    K -->|needs stronger model| L[Re-dispatch with capable model]
+    K -->|task too large| M[Split task, update plan]
+    K -->|plan wrong| N[Escalate to human]
+    L --> G
+    I --> O{Spec compliant?}
+    O -->|no| P[Implementer fixes spec gaps] --> I
+    O -->|yes| Q[Code-quality review — see gate note below]
+    Q --> R{Quality approved?}
+    R -->|no| S[Implementer fixes quality issues] --> Q
+    R -->|yes| T[Mark task done]
+    T --> U{More tasks?}
+    U -->|yes| B
+    U -->|no| V[Dispatch devil-advocate PHASE: completion — the single full-project pass]
+    V -->|PASS| W[Report completion]
+    V -->|BLOCK| X[Re-dispatch scoped fixes per FAILURES] --> V
+```
+
+**Gate cap:** two consecutive completion BLOCKs → stop and escalate to human; never loop the V→X cycle a third time.
+
+**Under the ARCS orchestrator:** the orchestrator's devil-advocate PHASE: execute gate replaces the code-quality reviewer step (the gate runs the scoped VERIFY and the drift check); spec review remains. Running standalone (no orchestrator session), keep both reviewer stages as drawn.
+
+### Retry & Escalation
+
+```mermaid
+flowchart TD
+    A[Subagent fails] --> B{First attempt?}
+    B -->|yes| C[Re-dispatch with more context or stronger model]
+    B -->|no| D{Same failure mode?}
+    D -->|yes| E[Escalate to human — don't loop]
+    D -->|no| C
+    C --> F{Success?}
+    F -->|yes| G[Continue pipeline]
+    F -->|no| D
+```
+
+### Diagram-First Dispatch
+
+When the plan has a `.mmd` file:
+
+1. `arcs diagram ready <slug> <planId>` → all returned nodes are dispatch-safe in parallel
+2. Use per-node `%%` metadata (`skill`, `scope`, `files`, `acceptance`, `verify`) to construct prompts
+3. After completion: `arcs task transition <slug> <taskId> done --diagramNodeId=T001 --planId=<planId>` (standalone only — under the orchestrator, report done and let it transition)
+4. Re-run `diagram ready` to discover newly-unblocked nodes
+5. If node metadata is incomplete, fall back to reading the plan body for that task
+
+**Ownership:** Dispatcher owns `.mmd` updates. Implementer subagents MUST NOT edit diagrams.
+
+### Sub-Agent Prompt Construction
+
+Every implementer subagent prompt MUST include:
+
+| Section | Content |
+|---------|---------|
+| **Goal** | Exact task description from plan (full text, not summary) |
+| **Context** | Where this task fits in the plan; what came before |
+| **Scope** | File boundaries — what to touch, what NOT to touch |
+| **Acceptance** | Done criteria copied verbatim from plan/diagram |
+| **Verify** | Exact command to run before claiming done — scoped to the task's files, never the full suite |
+| **Skill** | Which work-mode skill to load (from diagram metadata or inferred) |
+| **Return** | Structured Return envelope (below) — brief prose findings first, JSON block last |
+
+Do NOT make the subagent read the plan file. Provide full text in the prompt. Prompt templates: `./implementer-prompt.md`, `./spec-reviewer-prompt.md`, `./code-quality-reviewer-prompt.md`.
+
+### Model Selection
+
+| Task complexity | Model tier |
+|----------------|-----------|
+| 1-2 files, clear spec, mechanical | Fast/cheap |
+| Multi-file integration, pattern matching | Standard |
+| Architecture, design, review | Most capable |
+
+### Structured Return
+
+All sub-agents MUST return a JSON block as the LAST thing in their message — brief prose findings first, JSON block last, nothing after it:
+
+```json
+{
+  "status": "DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT",
+  "summary": "<1-2 sentences>",
+  "payload": { "<role-specific fields per prompt template>": "..." }
+}
+```
+
+Role payloads: implementer → `filesChanged`/`filesCreated`/`verification{command,result,scopeReason}`/`concerns`/`scopeChanges`; spec reviewer → `compliant`/`issues`; quality reviewer → `approved`/`issues`.
+Orchestrator parses `status` for routing, `payload` for action.
+Mapping to the orchestrator's Standard Return Envelope: DONE→done, DONE_WITH_CONCERNS→done + concerns surfaced, BLOCKED→blocked, NEEDS_CONTEXT→blocked.
+
+Include in every dispatch prompt:
+> "Return format: brief prose findings first, then the JSON envelope (status + typed payload) from your role's prompt template as the LAST thing in your message — nothing after it."
+
+### Review Gates
+
+- **Spec review** (always): a fresh reviewer verifies the implementer built what was requested — nothing more, nothing less. Reads the actual code, never trusts the report. See `./spec-reviewer-prompt.md`.
+- **Code-quality review** (standalone only): a fresh reviewer verifies the implementation is clean, tested, maintainable. See `./code-quality-reviewer-prompt.md`. **Under the ARCS orchestrator, the devil-advocate PHASE: execute gate replaces this step** (it runs the scoped VERIFY + drift check) — spec review still runs.
+- Spec review BEFORE code quality review (never reverse). Never skip re-review after fixes — if a reviewer finds issues, the implementer fixes and the reviewer re-reviews until approved.
+
+### Parallelism Rules
+
+Parallel implementers are allowed when tasks touch **zero shared files**.
+
+1. **Independence check:** verify no file overlap before dispatch. If overlap → serialize.
+2. **Batch limit:** maximum 4 concurrent subagents per round. Queue remaining.
+3. **Prompt construction:** per the Sub-Agent Prompt Construction table above — all rows required.
+4. **Conflict detection:** after fan-out completes, check for conflicting edits before committing.
+5. **Shared context:** fetch once (e.g., project brief), inject into all subagent prompts — don't make each agent re-fetch.
+
+**When to serialize instead:**
+- Tasks share source files (even different functions in same file)
+- Task B's approach depends on Task A's output
+- Both tasks modify test fixtures or shared mocks
+
+### Knowledge Capture at Fan-In
+
+The `concerns`, `scopeChanges`, and `DONE_WITH_CONCERNS` payloads collected from each subagent are near-free durable signal — don't discard them. At fan-in, route the durable items (a non-obvious trap hit, a convention that had to be discovered, a plan-vs-reality delta) into the DAG: `arcs knowledge upsert <slug> "<title>" --kind=<gotcha|pattern> --summary="<1-2 sentences>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. Skip purely mechanical or task-local notes. Upsert is idempotent by title.
+
+### Git State Discipline (Parallel)
+
+- Sub-agents MUST NOT run `git stash` — ever, under any circumstance
+- Sub-agents MUST NOT run `git checkout` on shared branches
+- Sub-agents commit their changes atomically (scoped to task files) before reporting back
+- Other agents may be working concurrently — do not assume a clean worktree
+- Use `git diff HEAD -- <your-files>` to verify YOUR changes only — bare `git diff` is unreliable in parallel
+- If you see unexpected changes in files outside your scope: **ignore them** — they belong to another agent
+
+### Parallel Mode Constraints
+
+- Fresh subagent per task — never reuse session context
+- Parallel implementers only when zero file overlap (dispatcher verifies)
+- Never ignore BLOCKED/NEEDS_CONTEXT status — something must change
+- DONE_WITH_CONCERNS: read concerns before proceeding; address if correctness/scope related
+- Scope changes discovered by subagents: report in summary, dispatcher handles diagram regeneration
+
 ## Review Checkpoint Criteria
 
 **STOP executing immediately when:**

package/opencode/arcs/skills/init-project/SKILL.md

@@ -26,7 +26,7 @@ flowchart TD
     F -->|no| H[Skip graph step, log gap]
     G --> G2[ingestGraph → ≤20 proposals]
     G2 --> G3[codegraph MCP explore / impact for enrichment]:::sub
-    H & G3 --> I[Fan out: system-architect + docs-researcher + tech-architect]:::sub
+    H & G3 --> I[Fan out: tech-architect + docs-researcher]:::sub
     I --> J[Collect proposals → dedup → arcs knowledge create × N]
     J --> K[Done]
 ```
@@ -87,10 +87,9 @@ Update via `arcs project update-doc <slug> <doc> --content="..."`.
 
 | Sub-agent | Owns | Knowledge kinds it produces |
 |-----------|------|----------------------------|
-| `system-architect` | Module boundaries, clusters, dependency direction | `architecture`, `module` |
+| `tech-architect` | Module boundaries, clusters, dependency direction, cross-module couplings, structural gotchas, lessons | `architecture`, `module`, `gotcha`, `lesson` |
 | `docs-researcher` | Tech stack, third-party libraries, key files, features | `reference`, `feature` |
-| `tech-architect` | Cross-module couplings, structural gotchas, lessons | `gotcha`, `lesson` |
-| `qa-analyst` (optional) | Coding-style + convention scan from existing code | `pattern` |
+| `code-reviewer` (audit mode, optional) | Coding-style + convention scan from existing code | `pattern` |
 
 Dispatch in parallel — all agents in one message, per the orchestrator's Parallelism rules. Each agent receives:
 - The relevant `KnowledgeProposal` records from `ingestGraph` (so they don't rediscover what codegraph already found)
@@ -105,14 +104,14 @@ Each agent returns finalized proposals: `{title, kind, summary, keywords, source
 |----------|------|------------------|---------------|
 | tech stack | `architecture` | Languages, frameworks, runtimes, build tools, versions | `docs-researcher` |
 | key files | `reference` | Entry points, config files, main modules, purposes | `docs-researcher` (use `codegraph_search "entry points"`) |
-| code patterns | `pattern` | Recurring design patterns, abstractions, error handling | `qa-analyst` or `system-architect` |
-| coding style | `pattern` | Formatting, linting, import ordering, file organization | `qa-analyst` |
-| core modules | `module` | Core modules / shared functions — what, where, interconnections | `system-architect` (god nodes from codegraph) |
+| code patterns | `pattern` | Recurring design patterns, abstractions, error handling | `code-reviewer` (audit mode) or `tech-architect` |
+| coding style | `pattern` | Formatting, linting, import ordering, file organization | `code-reviewer` (audit mode) |
+| core modules | `module` | Core modules / shared functions — what, where, interconnections | `tech-architect` (god nodes from codegraph) |
 | external services | `module` | APIs, databases, message queues the project interacts with | `docs-researcher` |
 | third-party libraries | `reference` | Key dependencies and why they are used | `docs-researcher` |
 | features | `feature` | Major user-facing or system-facing features | `docs-researcher` |
 | cross-module couplings | `gotcha` | Hot edges between modules surfaced by codegraph | `tech-architect` (auto from `ingestGraph`) |
-| architecture clusters | `architecture` | Pseudo-community / directory groupings from codegraph | `system-architect` (auto from `ingestGraph`) |
+| architecture clusters | `architecture` | Pseudo-community / directory groupings from codegraph | `tech-architect` (auto from `ingestGraph`) |
 
 ## Worked Example
 
@@ -137,9 +136,8 @@ arcs proposal promote foo <id> --title="..." --summary="..." --body-file=... --k
 arcs proposal drop foo <id> --reason="..." --json
 
 # 5. Fan out typed agents (parallel) for entries beyond proposal scope
-#    system-architect → architecture/module entries
+#    tech-architect   → architecture/module/gotcha/lesson entries
 #    docs-researcher  → reference/feature entries
-#    tech-architect   → gotcha/lesson entries
 
 # 6. Write any non-proposal-derived knowledge entries directly
 arcs knowledge create foo "Tech stack: TypeScript + Node 20" --kind=architecture --summary="..." --body="..." --json

package/opencode/arcs/skills/requesting-code-review/SKILL.md

@@ -39,7 +39,7 @@ When gathering conventions, also pull what the DAG already knows so the reviewer
 ## When to Request
 
 **Mandatory:** after major features, before merge to main.
-**Already scheduled:** when `subagent-driven-development` drives the loop, its pipeline dispatches this review as stage 2 (code-quality-reviewer applies this template's checklist but returns the SDD JSON envelope) — do not schedule it twice for the same task.
+**Already scheduled:** when `executing-plans` parallel mode drives the loop, its pipeline dispatches this review as stage 2 (code-quality-reviewer applies this template's checklist but returns the parallel-mode JSON envelope) — do not schedule it twice for the same task.
 **Optional:** when stuck, before refactoring, after complex bugfix.
 
 ## Red Flags

package/opencode/arcs/skills/requesting-code-review/code-reviewer.md

@@ -75,7 +75,7 @@ git diff {BASE_SHA}..{HEAD_SHA}
 
 No prose narrative. No "Overall this looks..." — open with the Standard Return Envelope, then VERDICT, then FINDINGS grouped by severity.
 
-When dispatched via subagent-driven-development, return its JSON envelope instead (see code-quality-reviewer-prompt.md).
+When dispatched via executing-plans parallel mode, return its JSON envelope instead (see code-quality-reviewer-prompt.md).
 
 ```
 STATUS: done | blocked | partial

package/opencode/arcs/skills/test-driven-development/SKILL.md

@@ -9,7 +9,7 @@ description: Use when implementing any feature or bugfix, before writing impleme
 
 Implementing any feature, bugfix, or behavior change. No production code without a failing test first.
 
-> **Note:** This skill is typically invoked BY `code-agent` when new non-trivial behavior needs test-first implementation. Rarely loaded directly by orchestrators — prefer routing through `code-agent` which will invoke TDD as needed.
+> **Note:** This skill is loaded DIRECTLY by the orchestrator when test-first is a hard requirement (the decision tree's "test-first valuable" trigger). It is also available as a sub-flow within `code-agent`, which invokes TDD when new non-trivial behavior needs test-first implementation.
 
 ## Flow
 

package/opencode/arcs/skills/writing-knowledge/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: writing-knowledge
+description: Use when capturing a knowledge entry, before writing its body — to author a substantive per-kind body, not a summary-only stub
+---
+
+# Skill: writing-knowledge
+
+## When
+
+You are about to persist a durable insight to the DAG (`arcs knowledge upsert` / `create`) and need the entry to be *actionable*, not a stub.
+
+> CLI Primer: `arcs --commands --json` for discovery. Mutating commands run directly — no token.
+
+## The Floor: Every Entry Needs a Body
+
+A knowledge entry is two things: a `--summary` (the headline) and a `--body` (the substance). The single most common KB failure is the **summary-only stub** — an entry whose summary just restates its title and whose body is empty. It is structurally "healthy" and worthless to the next dispatch.
+
+EVERY non-mechanical entry MUST carry a real `--body` (`--body="…"` inline, or `--body-file=<path>` once it's long enough to fight shell-escaping). The value lives in the body, written to the **anatomy of its kind**.
+
+## Scaffold, Don't Freehand
+
+Before writing, scaffold the section skeleton from the command:
+
+```bash
+arcs knowledge template --kind=<kind> --json   # structured sections
+arcs knowledge template --kind=<kind>          # plain markdown skeleton
+```
+
+This emits one `## <heading>` per section with a deletable hint comment. **Fill EVERY section** — a half-filled skeleton is still a stub.
+
+> **DRY / authoritative source:** `arcs knowledge template` is the AUTHORITATIVE skeleton. The anatomy below only *illustrates* the shape. If the table here ever diverges from the command output, **the command wins** — scaffold from it, not from this file.
+
+## The 8 Kinds at a Glance
+
+| Kind | Section anatomy |
+| --- | --- |
+| **gotcha** | Symptom · Root cause · Fix or workaround · Trigger |
+| **lesson** | Expectation · What happened · Why · Next time |
+| **pattern** | When to use · Shape · Example · When not to use |
+| **architecture** | Structure · Invariant or constraint · Failure mode |
+| **decision** | Decision · Rationale and forces · Alternatives rejected · Consequences |
+| **module** | Purpose · Key files and entry points · Responsibilities · Dependencies |
+| **feature** | What it does · How it works · Entry points · Edge cases |
+| **reference** | Summary · Canonical location · Usage notes |
+
+Pick the kind by what the insight *is*: a bug you hit → `gotcha`; a wrong belief corrected → `lesson`; a reusable shape → `pattern`; a structural why → `architecture`; a single settled call → `decision`; an area of the codebase → `module`/`feature`; a pointer to a canonical source → `reference`.
+
+## Write
+
+```bash
+arcs knowledge upsert <slug> "<title>" \
+  --kind=<kind> \
+  --summary="<one-line headline>" \
+  --body="<every section of the kind, filled>" \
+  --keywords="<k1,k2>" \
+  --source-files="<path[:anchor],…>" \
+  --json
+```
+
+`upsert` is idempotent by title — create-or-update, no dedup search dance. `--summary` AND `--body` AND `--source-files` together are the floor for a file-specific entry. Reach for `arcs knowledge create` only when creation MUST fail on an existing title.
+
+## Self-Check Before You Commit
+
+> **"Could someone act on this in six months without re-deriving it?"**
+
+If the insight cost you reasoning, a debug session, or a dead end, capture *that* — not just its one-line conclusion. Inverse (per the-ladder): if anyone could re-derive it in ten seconds, don't write it at all.
+
+## Constraints
+
+- Scaffold from `arcs knowledge template` — never freehand the section headings.
+- Fill every section; a half-filled skeleton is a stub.
+- `--summary` is the headline, `--body` is the value — never ship summary-only.
+- Match kind to the nature of the insight; don't force everything into `gotcha`.
+- Skip capture entirely for purely mechanical work (renames, config nudges, diagram regens).

package/opencode/arcs/skills/writing-plans/SKILL.md

@@ -114,7 +114,7 @@ Expected: PASS
 ```markdown
 # [Feature Name] Implementation Plan
 
-> **For agentic workers:** REQUIRED: Use arcs:subagent-driven-development (if subagents available) or arcs:executing-plans to implement this plan.
+> **For agentic workers:** REQUIRED: Use arcs:executing-plans to implement this plan (sequential single-agent by default, or parallel mode when independent tasks can fan out).
 
 **Goal:** [One sentence]
 
@@ -173,8 +173,7 @@ Then extract the plan's "why this structure" rationale into a durable entry —
 
 > "Plan complete and saved via `arcs plan get <slug> <planId>` in project `<slug>`. Ready to execute?"
 
-- **Subagents available** → REQUIRED: use `arcs:subagent-driven-development`
-- **No subagents** → use `arcs:executing-plans`
+- REQUIRED: use `arcs:executing-plans` — its parallel mode fans out independent tasks to subagents when available, falling back to sequential single-agent execution otherwise
 
 ## Constraints
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rryando/arcs",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "ARCS — DAG-based task orchestration for AI agents. Persistent workflow continuity via graph-structured context.",
   "type": "module",
   "main": "dist/index.js",
@@ -57,5 +57,8 @@
     "vite": "^6.4.1",
     "vitest": "^3.2.4",
     "@types/bun": "latest"
+  },
+  "allowScripts": {
+    "esbuild@0.25.12": true
   }
 }

package/scripts/build-opencode-bundle.mjs

@@ -30,10 +30,8 @@ const preservedOutputFiles = new Set([
   // Agent prompt files (repo-authored, referenced via {file:} in manifest.json)
   "prompts/software-engineer.txt",
   "prompts/tech-architect.txt",
-  "prompts/qa-analyst.txt",
   "prompts/oncall-ops.txt",
   "prompts/arcs-docs.txt",
-  "prompts/system-architect.txt",
   "prompts/code-reviewer.txt",
   "prompts/docs-researcher.txt",
   "prompts/devil-advocate.txt",

package/scripts/deploy-claudecode-bundle.mjs

@@ -87,14 +87,12 @@ const agentTierMap = {
   "docs-researcher": "heavy",
   "arcs-docs": "heavy",
   "oncall-ops": "heavy",
-  "system-architect": "heavy",
   "arcs-orchestrate": "standard",
   "arcs-orchestrate-caveman": "standard",
   "devil-advocate": "standard",
   "graph-explorer": "light",
   "code-reviewer": "light",
   "tech-architect": "light",
-  "qa-analyst": "light",
 };
 
 // Agent descriptions mirror opencode/arcs/manifest.json (canonical) — keep in sync.
@@ -134,20 +132,6 @@ const agentMetadata = {
     tools: "Read, Glob, Grep, Bash",
     model: "inherit",
   },
-  "qa-analyst": {
-    name: "QA Analyst",
-    description:
-      "Quality enforcement specialist. Proactive code audits, review dispatch, convention compliance.",
-    tools: "Read, Glob, Grep, Bash",
-    model: "inherit",
-  },
-  "system-architect": {
-    name: "System Architect",
-    description:
-      "Architecture and design specialist. Module boundaries, dependency graphs, migration strategies, and cross-project design decisions.",
-    tools: "Read, Glob, Grep, Bash",
-    model: "inherit",
-  },
   "arcs-docs": {
     name: "ARCS Docs Specialist",
     description:

package/scripts/lint-bundle.mjs

@@ -34,10 +34,8 @@ const preservedFiles = new Set([
   // requiredMerges, not from bundle-runtime.json's `agents` array).
   "prompts/software-engineer.txt",
   "prompts/tech-architect.txt",
-  "prompts/qa-analyst.txt",
   "prompts/oncall-ops.txt",
   "prompts/arcs-docs.txt",
-  "prompts/system-architect.txt",
   "prompts/code-reviewer.txt",
   "prompts/docs-researcher.txt",
   "prompts/devil-advocate.txt",

package/skills/init-project.md

@@ -24,7 +24,7 @@ flowchart TD
     F -->|no| H[Skip graph step, log gap]
     G --> G2[ingestGraph → ≤20 proposals]
     G2 --> G3[codegraph MCP explore / impact for enrichment]:::sub
-    H & G3 --> I[Fan out: system-architect + docs-researcher + tech-architect]:::sub
+    H & G3 --> I[Fan out: tech-architect + docs-researcher]:::sub
     I --> J[Collect proposals → dedup → arcs knowledge create × N]
     J --> K[Done]
 ```
@@ -82,10 +82,9 @@ If codegraph is missing, log "codegraph not on PATH; proceeding without graph si
 
 | Sub-agent | Owns | Knowledge kinds it produces |
 |-----------|------|----------------------------|
-| `system-architect` | Module boundaries, clusters, dependency direction | `architecture`, `module` |
+| `tech-architect` | Module boundaries, clusters, dependency direction, cross-module couplings, structural gotchas, lessons | `architecture`, `module`, `gotcha`, `lesson` |
 | `docs-researcher` | Tech stack, third-party libraries, key files, features | `reference`, `feature` |
-| `tech-architect` | Cross-module couplings, structural gotchas, lessons | `gotcha`, `lesson` |
-| `qa-analyst` (optional) | Coding-style + convention scan from existing code | `pattern` |
+| `code-reviewer` (audit mode, optional) | Coding-style + convention scan from existing code | `pattern` |
 
 Dispatch in parallel. Each agent receives the relevant `KnowledgeProposal` records from `ingestGraph` plus targeted codegraph MCP queries for evidence. Each agent returns finalized proposals (title, kind, summary, keywords, sourceFiles, body) for the orchestrator to write directly via `arcs knowledge create` (or `arcs batch`).
 
@@ -95,11 +94,11 @@ Dispatch in parallel. Each agent receives the relevant `KnowledgeProposal` recor
 |----------|------|------------------|---------------|
 | tech stack | `architecture` | Languages, frameworks, runtimes, build tools, versions | `docs-researcher` |
 | key files | `reference` | Entry points, config files, main modules, purposes | `docs-researcher` (codegraph_search "entry points") |
-| code patterns | `pattern` | Recurring design patterns, abstractions, error handling | `qa-analyst` or `system-architect` |
-| coding style | `pattern` | Formatting, linting, import ordering, file organization | `qa-analyst` |
-| core modules | `module` | Core modules/shared functions — what, where, interconnections | `system-architect` (god nodes from codegraph) |
+| code patterns | `pattern` | Recurring design patterns, abstractions, error handling | `code-reviewer` (audit mode) or `tech-architect` |
+| coding style | `pattern` | Formatting, linting, import ordering, file organization | `code-reviewer` (audit mode) |
+| core modules | `module` | Core modules/shared functions — what, where, interconnections | `tech-architect` (god nodes from codegraph) |
 | external services | `module` | APIs, databases, message queues the project interacts with | `docs-researcher` |
 | third-party libraries | `reference` | Key dependencies and why they are used | `docs-researcher` |
 | features | `feature` | Major user-facing or system-facing features | `docs-researcher` |
 | cross-module couplings | `gotcha` | Hot edges between modules surfaced by codegraph | `tech-architect` (auto from `ingestGraph`) |
-| architecture clusters | `architecture` | Pseudo-community/directory groupings from codegraph | `system-architect` (auto from `ingestGraph`) |
+| architecture clusters | `architecture` | Pseudo-community/directory groupings from codegraph | `tech-architect` (auto from `ingestGraph`) |

package/opencode/arcs/prompts/qa-analyst.txt

@@ -1,86 +0,0 @@
-You are a QA analyst — a quality enforcement specialist. You perform proactive audits, enforce conventions, and verify work meets standards. You never edit code — you produce findings and recommendations.
-
-## IRON LAW
-
-Audits without evidence are incomplete. Every finding must cite file paths, line ranges, or command output. "It seems wrong" is not a finding.
-
-## Session Start — T0 Orientation (Conditional)
-
-Your dispatch normally carries SCOPE/GOAL/CONTEXT/IDS. When it does, skip orientation and start — run orientation reads ONLY to fill gaps the dispatch left open:
-- Read `AGENTS.md` (team conventions: tech stack, file naming, code patterns, testing patterns) only when CONTEXT doesn't already state the conventions you need.
-- `arcs brief --lean --json` (live DAG state) and `arcs search <slug> "<keywords>" --json` only for context the dispatch omits.
-
-Never re-derive facts given in CONTEXT.
-
-Core skills you load: requesting-code-review (dispatch reviewers).
-
-You have ARCS CLI access — use it to read project context, check knowledge entries for patterns/conventions, and propose audit findings as tasks or knowledge for the orchestrator to create.
-
-READ ONLY: never edit code during quality assessment. Never execute tests, lint, or builds — the only command you may run is a scoped VERIFY command explicitly provided in your dispatch; runtime verification belongs to the devil-advocate completion gate. Produce structured reports with severity and ARCS artifact proposals.
-
-## Quality Gate
-
-Phase-gate verification is owned by the orchestrator (via `devil-advocate` subagent at checkpoints). You do NOT self-score. Your job: produce findings with evidence, cite file:line for every claim.
-
-MANDATORY EXIT GATE: Before finalizing any audit, confirm you checked all required dimensions within the dispatch-declared SCOPE, findings match team conventions (from CONTEXT or AGENTS.md), and redundancy findings carry cross-module grep evidence for symbols defined in your SCOPE.
-
-## Primary Commands
-
-| Command | When to use |
-|---------|-------------|
-| `arcs brief --lean --json` | Session start — orient on project state |
-| `arcs audit <slug> --json` | Run structural health checks (stale sourceFiles, orphan refs) |
-| `arcs validate <slug> --json` | Check DAG invariants (task/plan consistency). Use `--checks=sourcefiles\|status-drift\|diagrams\|agents-md` for targeted checks (default: `all`) |
-| `arcs diff <slug> --since="7d" --json` | Scope what changed since last audit |
-| `arcs knowledge list <slug> --json` | Review knowledge entries for taxonomy compliance |
-| `arcs search <slug> "<keywords>" --lean --json` | Find convention patterns to verify compliance |
-| `arcs related <slug> --task=<id> --json` | Find related tasks/knowledge via graph traversal (also accepts --plan or --knowledge) |
-
-All commands support `--json` for machine-readable output. Reads return `{ok, data}`; failures return `{ok:false, code, message, hint?}`. **Routing:** success → stdout, errors → stderr — always capture both with `2>&1`.
-
-## Proactive Audit Workflow
-
-KNOWLEDGE-FIRST: before producing output, unless your dispatch CONTEXT already carries the relevant prior knowledge, run `arcs knowledge search <slug> "<scope keywords>" --lean --json` and read any kind=gotcha|pattern|lesson|architecture entry covering your SCOPE (`arcs knowledge get <slug> <id> --body --lean --json` for full text). Incorporate it — do not rediscover what the DAG already knows. Skip only for purely mechanical changes. Calibrate against the DAG's prior pattern/gotcha entries, not just grep and AGENTS.md.
-
-You are invoked BEFORE a feature lands — not after. Your job is to find problems before they ship. Stay within the dispatch-declared SCOPE. Steps 1-4 apply only when the dispatch GOAL is a project-level audit — skip them for feature-scoped audits.
-
-1. `arcs brief --lean --json` — orient on project state
-2. `arcs audit <slug> --json` — structural health check
-3. `arcs validate <slug> --json` — DAG invariant check
-4. `arcs knowledge list <slug> --json` — verify taxonomy compliance
-5. `arcs search <slug> "<feature keywords>" --lean --json` — find related context the dispatch didn't carry
-6. Cross-module grep: `rg "<symbol>" --type ts` — trace usage of symbols defined in your SCOPE across boundaries
-7. Report: severity-grouped findings with file:line evidence
-
-## Output Format
-
-Your output is consumed by the orchestrator (an LLM), not a human. Be structured and terse. Open with the Standard Return Envelope, then agent-specific sections:
-
-```
-STATUS: done | blocked | partial
-
-FILES_TOUCHED: none   (read-only — you never edit)
-
-VERIFY: <scoped VERIFY command from dispatch> → pass|fail   (omit when the dispatch provides none)
-
-BLOCKED_BY: <only when blocked/partial — what prevented a complete audit>
-
-AUDIT: <what was audited — scope in one line>
-
-FINDINGS:
-- [CRITICAL] <file:line> — <issue>
-- [HIGH] <file:line> — <issue>
-- [MEDIUM] <file:line> — <issue>
-- [LOW] <file:line> — <issue>
-
-CONVENTIONS:
-- <compliant | violations with file:line>
-
-TASKS: <none | suggested tasks for orchestrator to create>
-
-KNOWLEDGE: <none | one ready-to-run command per durable, reusable insight surfaced this dispatch:
-  arcs knowledge upsert <slug> "<title>" --kind=<lesson|gotcha|pattern|architecture|decision> --summary="<1-2 sentences>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json
-  (upsert is idempotent by title — no dedup search needed)>
-```
-
-No prose narrative. No "I audited..." — go straight to STATUS.