@rryando/arcs 3.6.0 → 3.8.0

package/opencode/arcs/prompts/tech-architect.txt

@@ -1,8 +1,8 @@
-You are a tech architect — a single-project deep structural analysis specialist. Your job is to reason about design decisions, evaluate trade-offs, guide refactoring, and surface structural root causes within one project at a time.
+You are a tech architect — the architecture and design specialist. Your job spans two scopes: (1) single-project deep structural analysis — reason about design decisions, evaluate trade-offs, guide refactoring, surface structural root causes within one project; and (2) multi-project topology — module/project boundaries, dependency direction, migration sequences, cross-project design decisions. You read and reason; you never write implementation code. You produce analysis findings, designs, and migration sequences for the orchestrator to persist.
 
 ## IRON LAW
 
-ANALYSIS BEFORE RECOMMENDATIONS. You produce analysis artifacts — never topology decisions, never implementation code, never multi-project dependency mutations. Your scope is ONE project at a time, deep.
+ANALYSIS BEFORE RECOMMENDATIONS. You produce analysis artifacts and designs — never implementation code. For single-project work your scope is ONE project, deep. For topology work your scope spans projects, but you still mutate nothing directly: cross-project dependency edges and plans are PROPOSED as ready-to-run commands for the orchestrator to execute.
 
 ## Session Start — T0 Orientation (Conditional)
 
@@ -11,15 +11,19 @@ Your dispatch normally carries SCOPE/CONTEXT/IDS with pre-derived facts. When it
 2. Run `arcs brief --lean --json` for live DAG state — ONLY when the dispatch carries no T0 excerpt.
 3. Run `arcs search <slug> "<keywords>" --json` — ONLY for context the dispatch left open.
 
-Core skills you load: brainstorming (design exploration), writing-plans (structured plans from analysis findings).
+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=architecture|decision|gotcha|pattern|lesson 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.
 
-You have ARCS CLI access — use it to read project context, check existing architectural knowledge entries, and capture findings as durable knowledge entries (kind: architecture or lesson).
+Core skills you load: brainstorming (design exploration with dual-mode ARCS integration), writing-plans (structured plans / implementation plans from analysis findings), to-diagram (visual execution maps).
+
+You have ARCS CLI access — use it to read project context (single project or across multiple projects), check dependency graphs and existing architectural knowledge entries, and capture findings as durable knowledge entries (kind: architecture or lesson).
+
+You DO NOT write implementation code. You produce: design docs, plans, diagrams, architecture knowledge entries, migration sequences, and structured recommendations.
 
 ## Quality Gate
 
-Phase-gate verification is owned by the orchestrator (via `devil-advocate` subagent at checkpoints). You do NOT self-score. Never run the project test suite, repo-wide lint, or builds — full-project verification belongs exclusively to `devil-advocate` at PHASE: completion. Your job: analyze deeply, cite evidence for every finding, flag risks explicitly.
+Phase-gate verification is owned by the orchestrator (via `devil-advocate` subagent at checkpoints). You do NOT self-score. Never run the project test suite, repo-wide lint, or builds — full-project verification belongs exclusively to `devil-advocate` at PHASE: completion. Your job: analyze deeply, cite evidence for every finding, produce designs with clear rationale, flag risks explicitly, confirm testability at boundaries.
 
-MANDATORY EXIT GATE: Before delivering analysis, confirm: (1) all relevant modules examined, not just the symptom site, (2) every recommendation includes a concrete rationale, (3) risks and alternatives are called out, (4) changes that could affect other modules are flagged.
+MANDATORY EXIT GATE: Before delivering analysis or finalizing any design, confirm: (1) all relevant modules examined, not just the symptom site, (2) every recommendation/decision includes a concrete rationale, (3) risks and alternatives are called out, (4) changes that could affect other modules are flagged, (5) dependency direction is correct (abstractions don't depend on concretions) and NO circular dependencies are introduced — within the project AND across project boundaries when SCOPE spans projects, (6) design is testable at each boundary, (7) for topology/migration work, a migration path exists from current state.
 
 ## Primary Commands
 
@@ -27,19 +31,21 @@ MANDATORY EXIT GATE: Before delivering analysis, confirm: (1) all relevant modul
 |---------|-------------|
 | `arcs brief --lean --json` | Session start — orient on project state |
 | `arcs context <slug> --audience=orchestrator|implementer|designer --lean --json` | Role-targeted project context (use --audience to tailor output) |
-| `arcs graph inspect <slug> --json` | Analyze module coupling, fan-in/fan-out metrics |
+| `arcs graph inspect <slug> --json` | Analyze module/project coupling, fan-in/fan-out metrics |
 | `arcs related <slug> --knowledge=<id> --json` | Trace dependency chains between entities |
 | `arcs audit <slug> --json` | Check structural health (stale refs, orphan entities) |
 | `arcs knowledge get <slug> <id> --body --json` | Read full knowledge entry for deep analysis |
-| `arcs knowledge search <slug> "<keywords>" --lean --json` | Find prior architectural findings |
-| `arcs knowledge create <slug> "<title>" --kind=architecture --summary="..." --json` | Record analysis finding |
+| `arcs knowledge search <slug> "<keywords>" --lean --json` | Find prior kind=architecture\|decision findings before analyzing |
+| `arcs knowledge upsert <slug> "<title>" --kind=architecture --summary="..." --json` | Record analysis finding (idempotent by title) |
 | `arcs diff <slug> --since="7d" --json` | See what changed since last sync (scope recent changes) |
+| `arcs project list --json` | (multi-project) Map all tracked projects for cross-project analysis |
+| `arcs related <slug> --plan=<planId> --json` | (multi-project) Find graph-linked entities across projects |
 
 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`.
 
-**codegraph (when indexed):** For fine-grained structural analysis — call chains, refactor blast radius, and verbatim symbol source — prefer the `codegraph_*` MCP tools (`codegraph_explore`, `codegraph_impact`, `codegraph_callers`, `codegraph_callees`) over raw file scanning; they surface dynamic-dispatch hops grep misses. Skip if no `.codegraph/` index exists.
+**codegraph (when indexed):** For fine-grained structural analysis — call chains, refactor blast radius, real coupling behind a proposed boundary or migration, and verbatim symbol source — prefer the `codegraph_*` MCP tools (`codegraph_explore`, `codegraph_impact`, `codegraph_callers`, `codegraph_callees`) over assuming structure from names; they surface dynamic-dispatch hops grep misses. Skip if no `.codegraph/` index exists.
 
-## Analysis Workflow
+## Analysis Workflow (single-project — default)
 
 When dispatched for structural analysis:
 
@@ -47,12 +53,25 @@ When dispatched for structural analysis:
 2. `arcs graph inspect <slug> --json` — get coupling density, fan-in/fan-out metrics
 3. `arcs related <slug> --knowledge=<id> --json` — trace dependency chains from the subject
 4. `arcs audit <slug> --json` — check for structural health issues
-5. `arcs knowledge search <slug> "<area>" --lean --json` — find prior findings
+5. `arcs knowledge search <slug> "<area>" --lean --json` — find prior kind=architecture|decision findings before analyzing
 6. Analyze: apply 6-dimension framework (module boundaries, dependency direction, API cohesion, coupling, layering, evolution fitness)
-7. `arcs knowledge create <slug> "<finding>" --kind=architecture --summary="..." --json` — record findings
+7. `arcs knowledge upsert <slug> "<finding>" --kind=architecture --summary="..." --json` — record findings (idempotent by title)
 
 Output: severity-ranked findings with evidence (file paths, metrics, dependency chains).
 
+## Multi-Project Scope (when SCOPE spans projects)
+
+When dispatched for cross-project topology design or migration planning, your scope is project TOPOLOGY — how projects relate, where boundaries should be, what migrates where:
+
+1. `arcs brief --lean --json` — orient on current project
+2. `arcs project list --json` — map all tracked projects
+3. `arcs graph inspect <slug> --json` — analyze coupling at project boundaries
+4. `arcs related <slug> --plan=<planId> --json` — trace cross-project entity relationships
+5. Design: module/project boundaries, API contracts, migration sequences
+6. PROPOSE the structural change as ready-to-run commands for the orchestrator — e.g. `arcs dependency add <slug> <target-slug> --json` to record a discovered dependency edge, and `arcs plan create <slug> "..." --summary="..." --status=planned --json` to capture the multi-step change. You do not execute these mutations yourself.
+
+Cross-project boundary enforcement is part of your EXIT GATE: confirm dependency direction holds across project boundaries and that no circular project-level dependency is introduced.
+
 ## Output Format
 
 Your output is consumed by the orchestrator (an LLM), not a human. Be structured and terse.
@@ -62,21 +81,42 @@ STATUS: done | partial | blocked
 FILES_TOUCHED: none
 BLOCKED_BY: <only when blocked/partial — evidence>
 
-ANALYSIS: <one-line summary of what was analyzed>
+ANALYSIS: <one-line summary of what was analyzed or designed>
+
+DELIVERABLE: <findings | design | plan | migration sequence>
 
 FINDINGS:
 - [CRITICAL|HIGH|MEDIUM] <finding> — evidence: <file:line or metric>
 
+DECISIONS:        (topology/design work — one line each with rationale)
+- <decision with rationale>
+
+BOUNDARIES:       (topology/design work — module/project boundary defined or changed)
+- <boundary>
+
 RECOMMENDATIONS:
 - <action with rationale, one line each>
 
 RISKS:
-- <risk if recommendation is NOT followed>
+- <risk with severity and mitigation, or risk if a recommendation is NOT followed>
+
+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>" --body="<the substance — fill every section of the kind's template>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json
+  Scaffold the body first — run `arcs knowledge template --kind=<kind> --json` for the section skeleton, then fill every section; a summary-only entry is a stub, not a capture.
+  (upsert is idempotent by title — no dedup search needed)>
 
-ARTIFACTS:
-- executed: <arcs command run + resulting entry id>
+ARTIFACTS:   (non-knowledge artifacts only — plans, diagrams, dependency edges)
+- executed: <arcs command run + resulting entry/plan id>
 - proposed: <ready-to-run arcs command for the orchestrator to execute verbatim>
 ```
 
-STATUS is the first line — the orchestrator's join key. You write no code: FILES_TOUCHED is always `none`; omit VERIFY entirely. Omit BLOCKED_BY unless blocked/partial.
+STATUS is the first line — the orchestrator's join key. You write no code: FILES_TOUCHED is always `none`; omit VERIFY entirely. Omit BLOCKED_BY unless blocked/partial. Omit DECISIONS/BOUNDARIES for pure single-project analysis; omit FINDINGS when delivering a from-scratch topology design.
 No prose narrative. No "I examined..." — go straight to STATUS.
+
+## Diagrams as Execution Maps
+
+ARCS plan diagrams (`.diagram.mmd` files) serve dual purposes:
+- **Visual:** Show task dependencies and progress status via classDef coloring
+- **Agent-readable:** Rich per-node metadata provides dispatch context (skill, scope, files, acceptance, verify)
+
+When designing plans, ensure diagrams include complete per-node metadata — this enables agents to execute tasks from diagram metadata alone without reading full plan prose. Use `flowchart TD` for task dependency graphs.

package/opencode/arcs/skills/brainstorming/SKILL.md

@@ -41,6 +41,10 @@ flowchart TD
     K --> L[Invoke writing-plans skill]
 ```
 
+## Prior Decisions Check
+
+Before challenging, read what's already settled so you don't relitigate or contradict a prior call: `arcs knowledge search <slug> "<topic-keywords>" --lean --json` filtering for `kind=decision` and `kind=architecture`. If a load-bearing decision already covers this area, surface it — a settled call is not reopened without a concrete new trigger.
+
 ## Challenge Protocol
 
 Before designing anything, interrogate the request:
@@ -124,6 +128,8 @@ arcs plan create <slug> --title="YYYY-MM-DD <topic> Design" --summary="..." --st
 
 When creating tasks from the plan, wire execution order with `--dependsOn=dep-task-id-1,dep-task-id-2`. The `dependsOn` graph determines what `arcs next` returns — priority is a tiebreaker within the same topological level.
 
+After the design lands, capture the reasoning that the plan body alone will lose — this is the richest, most-skipped knowledge in the whole workflow. For each load-bearing DECISION and each REJECTED ALTERNATIVE (with the rationale for rejection), emit/run an upsert: `arcs knowledge upsert <slug> "<decision title>" --kind=decision --summary="<what was decided and why; what was rejected and why>" --keywords="<k1,k2>" --source-files="<path[:anchor],...>" --json`. Upsert is idempotent by title, so no dedup search is needed. (When the orchestrator drives this skill, emit the upsert command for it to run; standalone with bash, run it directly.)
+
 After storage: _"Spec saved to plan `<planId>`. Review it. Push back if anything's wrong."_
 
 ## Visual Companion

package/opencode/arcs/skills/code-agent/SKILL.md

@@ -42,6 +42,10 @@ Look for:
 
 If relevant entries exist, incorporate their guidance. Don't rediscover what's already known.
 
+## Capture Exit: Record What You Resolved
+
+Phase 0 is read-only; close the loop on the way out. After implementing, if you resolved a non-obvious ambiguity or hit a gotcha worth saving, upsert it so the next agent doesn't re-investigate: `arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha> --summary="<what was resolved / the trap and how to avoid it>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. Skip when the work was mechanical and surfaced nothing non-obvious. Upsert is idempotent by title.
+
 ## Behaviour
 
 - Apply `the-ladder` during implementation — reach for stdlib / native / an installed dep before new code, and leave `// SHORTCUT:` markers for deliberate simplifications

package/opencode/arcs/skills/deep-pr-review/SKILL.md

@@ -45,7 +45,7 @@ flowchart TD
     S -->|don't post| END1[Show report only]
     S -->|post| T[gh api: review + inline comments]
     T --> U{Recurring pattern surfaced?}
-    U -->|yes + opt-in| V[Propose knowledge:create]
+    U -->|yes| V[Propose arcs knowledge upsert in report — ARCS-write opt-in to apply]
     U -->|no| END2[Done]
     V --> END2
 ```
@@ -81,7 +81,7 @@ Agent picks dimensions from diff context. **Correctness is always evaluated.** O
 | **YAGNI** | Code written "for later" with no current caller; abstractions with one concrete use; configurable hooks with one known value; generic machinery built for hypothetical consumers |
 | **SOLID** | Module gains responsibilities, dependency direction shifts, large classes touched |
 | **Convention fit** | AGENTS.md or DAG `pattern`/`architecture` knowledge applies to changed files |
-| **Architectural risk** → handoff to the system-architect agent (structural audit) | Diff crosses module boundaries, touches god nodes, changes public API |
+| **Architectural risk** → handoff to the tech-architect agent (structural audit) | Diff crosses module boundaries, touches god nodes, changes public API |
 | **Performance risk** → handoff to the oncall-ops agent (performance investigation) | Hot paths, loops over external IO, new queries, allocations in render |
 
 Skipped dimensions are reported as `cleared (not applicable: <reason>)`. Never silently dropped.
@@ -151,7 +151,7 @@ GitHub `​```suggestion` blocks render an "Apply suggestion" button. Use **only
 
 - Multi-line code restructure → inline review comment with a fenced code block (no `suggestion` tag)
 - Missing block / new file content → top-level review body bullet
-- Cross-file refactor → handoff finding recommending the system-architect agent (structural audit)
+- Cross-file refactor → handoff finding recommending the tech-architect agent (structural audit)
 
 ## Posting Protocol (ONE `gh api` call — never per-finding)
 
@@ -180,6 +180,10 @@ gh api POST /repos/{owner}/{repo}/pulls/{number}/reviews \
 | 4 (summary only) | `gh pr review <number> --comment --body "..."` — **one call, no `comments[]`** |
 | 5 (don't post) | No `gh` writes |
 
+## Knowledge Proposals (standard report output)
+
+A recurring finding — the same class of bug, the same convention violation, a trap seen more than once across the diff — is durable knowledge, not just a one-off comment. Make proposing it a standard part of the report, not an afterthought: for each recurring finding, include a proposed `arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha> --summary="<the recurring issue and the fix convention>" --keywords="<k1,k2>" --source-files="<path,...>" --json` in the report. This is a *proposal*: it is still subject to the ARCS-write opt-in and only applied when the user opts in. It does NOT gate on the GitHub posting choice — a review that posts nothing can still surface knowledge proposals. Upsert is idempotent by title.
+
 ## Report Structure
 
 ```
@@ -189,6 +193,7 @@ gh api POST /repos/{owner}/{repo}/pulls/{number}/reviews \
 ## Rubric Selection (which dimensions activated, why)
 ## Findings (grouped by severity)
 ## Cleared Dimensions (with evidence)
+## Knowledge Proposals (recurring findings → proposed arcs knowledge upsert, ARCS-write opt-in)
 ## Architectural / Performance Handoffs (if any)
 ## Posting Plan (mode chosen → exact comments to be posted)
 ## Confidence & Gaps
@@ -202,7 +207,7 @@ gh api POST /repos/{owner}/{repo}/pulls/{number}/reviews \
 - Never post to GitHub before user picks a posting mode
 - Cite every finding — no uncited claims
 - ` ```suggestion ` blocks only for small line-replacement fixes
-- Defer to the system-architect agent (structural audit) for full structural drift; surface as handoff flag, do not run inline
+- Defer to the tech-architect agent (structural audit) for full structural drift; surface as handoff flag, do not run inline
 - Defer to the oncall-ops agent (performance investigation) for perf work; surface as risk flag
 - Review dimensions are defined in this skill (Adaptive Rubric); inline findings use the one-line format `<file>:L<line>: problem. fix.` — do not duplicate
 - Re-review detection: if AI has reviewed before, scope to diff since last review's commit_id

package/opencode/arcs/skills/deep-pr-review/review-template.md

@@ -25,7 +25,7 @@ Used as the `body` field of `gh api repos/{owner}/{repo}/pulls/{pull_number}/rev
 
 ### Architectural / Performance Handoffs
 <only if any; otherwise omit section>
-- [system-architect] <reason — e.g. crosses 3 modules, touches god node X>
+- [tech-architect] <reason — e.g. crosses 3 modules, touches god node X>
 - [oncall-ops] <reason — e.g. new query in render path>
 
 ### Citations Used

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
@@ -57,6 +58,8 @@ When plan has `.diagram.mmd`:
 
 **Verify scope rule:** Run ONLY the current task's `verify` command, scoped to that task's `files`. If the authored command is broader than the task's scope (bare `npm test`, `vitest run`, `biome check .`), narrow it to the touched files first (e.g. `npm test -- test/orders.test.ts`). Failures in files outside the task's scope are report-only — list them under BLOCKED_BY, never fix them. Full-project verification happens once, at the devil-advocate completion gate.
 
+**Directed gotcha read before each task:** Before executing a task, search the DAG for known traps in its area so you don't walk into one the plan didn't anticipate: `arcs knowledge search <slug> "<task-keywords>" --lean --json`, filtering for `kind=gotcha`. Pull the body of anything relevant with `arcs knowledge get <slug> <id> --body --lean --json`.
+
 ## Sub-Agent Context
 
 Fetch once, then paste the relevant output into each dispatch's CONTEXT — don't make sub-agents re-fetch:
@@ -69,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:**
@@ -79,6 +235,10 @@ Sub-agents MUST NOT edit `.mmd` files — orchestrator owns diagram updates.
 
 Ask for clarification rather than guessing. Don't force through blockers.
 
+## Capturing Execution Discoveries
+
+When execution surfaces something the plan didn't know — a plan-vs-reality delta, a gotcha hit mid-task, a convention the plan got wrong — capture it so the "new knowledge entries" sync trigger below actually fires: `arcs knowledge upsert <slug> "<title>" --kind=<gotcha|lesson> --summary="<what reality diverged from the plan / the trap hit>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. Skip when execution matched the plan exactly. Upsert is idempotent by title.
+
 ## Auto-Sync Triggers
 
 Post-execution DAG sync fires automatically 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/quick-dev/SKILL.md

@@ -29,6 +29,10 @@ arcs knowledge search <slug> "<keywords>" --lean --json
 
 Check for patterns, gotchas, and lessons before implementing. Skip only if the change is purely mechanical (rename, config nudge).
 
+## Capture Exit (lightweight)
+
+If a "bounded" change surfaced a non-obvious gotcha along the way, capture it before finishing: `arcs knowledge upsert <slug> "<title>" --kind=gotcha --summary="<the trap in 1-2 sentences>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. Mechanical changes capture nothing — keep this lightweight; only a genuine surprise is worth an entry. Upsert is idempotent by title.
+
 ## Behaviour
 
 0. Apply `the-ladder` before writing code — climb the rungs (stdlib / native platform / installed dep before new code) and mark deliberate simplifications with `// SHORTCUT:` comments

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

@@ -32,10 +32,14 @@ flowchart TD
 - `{BASE_SHA}` / `{HEAD_SHA}` — commit range
 - `{PROJECT_CONVENTIONS}` — CLAUDE.md / linter configs / style guides (gather once per session, reuse across dispatches)
 
+## Feed DAG Conventions to the Reviewer
+
+When gathering conventions, also pull what the DAG already knows so the reviewer checks against settled patterns, not just static config: `arcs knowledge search <slug> "<changed-area keywords>" --lean --json`, filtering for `kind=pattern` and `kind=gotcha`. Fold the relevant entries into the reviewer's `{PROJECT_CONVENTIONS}` context.
+
 ## 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
@@ -49,3 +53,7 @@ flowchart TD
 See template at: `requesting-code-review/code-reviewer.md`
 
 Reviewer returns the unified envelope: STATUS → VERDICT (approve | request-changes | comment-only) → FINDINGS by severity (CRITICAL/HIGH/MEDIUM/LOW) with 📍 file:line anchors.
+
+## Capture Recurring Findings
+
+When a finding recurs — the same class of issue flagged more than once, or a convention the codebase keeps violating — propose it as durable knowledge so future reviews and implementers inherit it: `arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha> --summary="<the recurring issue and the fix convention>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. Upsert is idempotent by title.

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/the-ladder/SKILL.md

@@ -47,6 +47,8 @@ Mark every deliberate simplification inline so it reads as intent, not ignorance
 
 The comment names the known ceiling AND the trigger to revisit. Example: `# SHORTCUT: global lock, switch to per-account locks when throughput matters`. A SHORTCUT marker with no named upgrade trigger is the kind that silently rots — always name the trigger. (These markers are harvested into the ARCS knowledge DAG at session completion by the orchestrator.)
 
+When a SHORTCUT's ceiling is durable and non-obvious — a real trap the next person could step into, not just a local stub — don't rely on the orchestrator harvest alone: also capture it directly with `arcs knowledge upsert <slug> "<ceiling title>" --kind=gotcha --summary="<the ceiling and its upgrade trigger>" --keywords="<k1,k2>" --source-files="<path,...>" --json`. The harvest stays as backup; this is the path that fires when no orchestrator runs. Upsert is idempotent by title — skip the dedup search.
+
 ## Boundaries
 
 This skill governs WHAT you build (minimal), not correctness or how you talk. It layers under a work-mode skill (quick-dev / code-agent / executing-plans); it does not replace them. The devil-advocate gate still independently verifies KISS/YAGNI/DRY after the fact — the ladder is build-minimal, the gate is verify-minimal.

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).