@rryando/arcs 3.0.0

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

@@ -0,0 +1,162 @@
+---
+name: subagent-driven-development
+description: Use when executing implementation plans with independent tasks in the current session
+---
+
+# Skill: Subagent-Driven Development
+
+## When
+
+You have an implementation plan with mostly-independent tasks and want to execute them in-session via fresh subagents with two-stage review.
+
+**NOT for:**
+- If no subagent dispatch capability is available → use `executing-plans` instead (single-agent sequential)
+- If the work is iterative self-correction without structured plan tasks → use `loop` instead
+
+> CLI Primer: `arcs --commands --json` for discovery. Mutating commands run directly — no token.
+
+## 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[Dispatch code-quality reviewer]
+    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 final cross-task reviewer]
+    V --> W[Load skill: finishing-a-development-branch]
+```
+
+## 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>`
+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 |
+| **Skill** | Which work-mode skill to load (from diagram metadata or inferred) |
+
+Do NOT make the subagent read the plan file. Provide full text in the prompt.
+
+## 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 |
+
+## Prompt Templates
+
+- `./implementer-prompt.md`
+- `./spec-reviewer-prompt.md`
+- `./code-quality-reviewer-prompt.md`
+- `./return-schema.md` — structured output format (inject into every dispatch)
+
+## Structured Return
+
+All sub-agents MUST return a JSON block as the final thing in their message, per `./return-schema.md`.
+Orchestrator parses `status` for routing, `payload` for action. Free-form prose above is fine.
+
+Include in every dispatch prompt:
+> "Return format: JSON envelope with status + typed payload. See return-schema.md for your role's schema."
+
+## Git State Discipline
+
+- 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
+
+## Verification Scoping
+
+Sub-agents lint and test **only files they touched**:
+
+| Scope | Command | NOT this |
+|-------|---------|----------|
+| Lint | `biome check src/changed.ts` | `biome check .` |
+| Test | `vitest run test/changed.test.ts` | `vitest run` / `npm test` |
+| Type check | `tsc --noEmit` (whole-project — exception) | — |
+
+Full suite justified ONLY when change is pervasive (shared types, config, build).
+Sub-agent must state `scopeReason` in return payload.
+
+## Parallelism Rules
+
+Parallel implementers are allowed when tasks touch **zero shared files**.
+
+1. **Independence check:** Orchestrator verifies no file overlap before dispatch. If overlap → serialize.
+2. **Batch limit:** Maximum 4 concurrent subagents per round. Queue remaining.
+3. **Prompt construction:** Each subagent gets: Scope, Goal, Context, Constraints, Output format — all 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
+
+## Constraints
+
+- Fresh subagent per task — never reuse session context
+- Spec review BEFORE code quality review (never reverse)
+- Parallel implementers only when zero file overlap (orchestrator verifies)
+- Never skip re-review after fixes
+- Never ignore BLOCKED/NEEDS_CONTEXT status — something must change
+- Never start on main/master without explicit user consent
+- If reviewer finds issues → implementer fixes → reviewer re-reviews → repeat until approved
+- DONE_WITH_CONCERNS: read concerns before proceeding; address if correctness/scope related
+- Scope changes discovered by subagents: report in summary, dispatcher handles diagram regeneration

package/opencode/arcs/skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -0,0 +1,53 @@
+# Code Quality Reviewer Prompt Template
+
+Use this template when dispatching a code quality reviewer subagent.
+
+**Purpose:** Verify implementation is well-built (clean, tested, maintainable)
+
+**Only dispatch after spec compliance review passes.**
+
+```
+Task tool (arcs:code-reviewer):
+  Use template at requesting-code-review/code-reviewer.md
+
+  WHAT_WAS_IMPLEMENTED: [from implementer's report]
+  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
+  BASE_SHA: [commit before task]
+  HEAD_SHA: [current commit]
+  DESCRIPTION: [task summary]
+```
+
+**In addition to standard code quality concerns, the reviewer should check:**
+- Does each file have one clear responsibility with a well-defined interface?
+- Are units decomposed so they can be understood and tested independently?
+- Is the implementation following the file structure from the plan?
+- Did this implementation create new files that are already large, or significantly grow existing files? (Don't flag pre-existing file sizes — focus on what this change contributed.)
+
+## Report Format (MANDATORY)
+
+Return prose explanation followed by this EXACT JSON block as the LAST thing in your message:
+
+```json
+{
+  "status": "DONE | DONE_WITH_CONCERNS",
+  "summary": "<1-2 sentences: quality verdict>",
+  "payload": {
+    "approved": true,
+    "issues": [
+      {
+        "severity": "critical | important | minor",
+        "file": "src/foo.ts",
+        "line": 15,
+        "finding": "Variable name unclear",
+        "suggestion": "Rename `d` to `duration`"
+      }
+    ]
+  }
+}
+```
+
+- `approved: true` = quality acceptable (minor issues OK)
+- `approved: false` = must fix before proceeding (has critical/important issues)
+- Severity: `critical` (must fix), `important` (should fix), `minor` (nice to fix)
+
+**No prose after the JSON block.**

package/opencode/arcs/skills/subagent-driven-development/implementer-prompt.md

@@ -0,0 +1,148 @@
+# Implementer Subagent Prompt Template
+
+Use this template when dispatching an implementer subagent.
+
+```
+Task tool (general-purpose):
+  description: "Implement Task N: [task name]"
+  prompt: |
+    You are implementing Task N: [task name]
+
+    ## Task Description
+
+    [FULL TEXT of task from plan - paste it here, don't make subagent read file]
+
+    ## Context
+
+    [Scene-setting: where this fits, dependencies, architectural context]
+
+    ## Before You Begin
+
+    If you have questions about:
+    - The requirements or acceptance criteria
+    - The approach or implementation strategy
+    - Dependencies or assumptions
+    - Anything unclear in the task description
+
+    **Ask them now.** Raise any concerns before starting work.
+
+    ## Your Job
+
+    Once you're clear on requirements:
+    1. Implement exactly what the task specifies
+    2. Write tests (following TDD if task says to)
+    3. Verify implementation works (scoped — see below)
+    4. Commit your work (scoped to your task files only: `git add <your-files>`)
+    5. Self-review (see below)
+    6. Report back with structured JSON
+
+    Work from: [directory]
+
+    **While you work:** If you encounter something unexpected or unclear, **ask questions**.
+    It's always OK to pause and clarify. Don't guess or make assumptions.
+
+    ## Git Rules
+
+    - NEVER run `git stash` — under any circumstance
+    - NEVER run `git checkout` on shared branches
+    - Commit your changes before reporting (scoped to your task files only: `git add <your-files>`)
+    - If you see changes to files outside your scope, IGNORE them — another agent owns those
+    - Use `git diff HEAD -- <files-you-changed>` to verify YOUR changes only
+    - Do NOT use bare `git diff` — it's unreliable when multiple agents share a worktree
+
+    ## Verification (Scoped)
+
+    Lint and test ONLY the files you touched:
+    - Lint: `biome check src/your-file.ts` (NOT `biome check .`)
+    - Test: `vitest run test/your-file.test.ts` (NOT `vitest run` or `npm test`)
+    - Type check: `tsc --noEmit` (this one is whole-project — exception)
+
+    Full suite only when your change is pervasive (shared types, config, build).
+    You MUST state why your verification scope is sufficient in your report.
+
+    ## Code Organization
+
+    You reason best about code you can hold in context at once, and your edits are more
+    reliable when files are focused. Keep this in mind:
+    - Follow the file structure defined in the plan
+    - Each file should have one clear responsibility with a well-defined interface
+    - If a file you're creating is growing beyond the plan's intent, stop and report
+      it as DONE_WITH_CONCERNS — don't split files on your own without plan guidance
+    - If an existing file you're modifying is already large or tangled, work carefully
+      and note it as a concern in your report
+    - In existing codebases, follow established patterns. Improve code you're touching
+      the way a good developer would, but don't restructure things outside your task.
+
+    ## When You're in Over Your Head
+
+    It is always OK to stop and say "this is too hard for me." Bad work is worse than
+    no work. You will not be penalized for escalating.
+
+    **STOP and escalate when:**
+    - The task requires architectural decisions with multiple valid approaches
+    - You need to understand code beyond what was provided and can't find clarity
+    - You feel uncertain about whether your approach is correct
+    - The task involves restructuring existing code in ways the plan didn't anticipate
+    - You've been reading file after file trying to understand the system without progress
+
+    **How to escalate:** Report back with status BLOCKED or NEEDS_CONTEXT. Describe
+    specifically what you're stuck on, what you've tried, and what kind of help you need.
+    The controller can provide more context, re-dispatch with a more capable model,
+    or break the task into smaller pieces.
+
+    ## Before Reporting Back: Self-Review
+
+    Review your work with fresh eyes. Ask yourself:
+
+    **Completeness:**
+    - Did I fully implement everything in the spec?
+    - Did I miss any requirements?
+    - Are there edge cases I didn't handle?
+
+    **Quality:**
+    - Is this my best work?
+    - Are names clear and accurate (match what things do, not how they work)?
+    - Is the code clean and maintainable?
+
+    **Discipline:**
+    - Did I avoid overbuilding (YAGNI)?
+    - Did I only build what was requested?
+    - Did I follow existing patterns in the codebase?
+
+    **Testing:**
+    - Do tests actually verify behavior (not just mock behavior)?
+    - Did I follow TDD if required?
+    - Are tests comprehensive?
+
+    If you find issues during self-review, fix them now before reporting.
+
+    ## Report Format (MANDATORY)
+
+    When done, return prose explanation followed by this EXACT JSON block as the LAST thing in your message:
+
+    ```json
+    {
+      "status": "DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT",
+      "summary": "<1-2 sentences: what was accomplished>",
+      "payload": {
+        "filesChanged": ["src/foo.ts", "test/foo.test.ts"],
+        "filesCreated": ["src/bar.ts"],
+        "verification": {
+          "command": "<exact command you ran>",
+          "result": "pass | fail",
+          "scopeReason": "<why this scope is sufficient>"
+        },
+        "concerns": [],
+        "scopeChanges": []
+      }
+    }
+    ```
+
+    - `concerns`: doubts about correctness (use with DONE_WITH_CONCERNS)
+    - `scopeChanges`: discovered work outside task boundaries (orchestrator handles)
+    - Use BLOCKED if you cannot complete the task
+    - Use NEEDS_CONTEXT if you need information that wasn't provided
+    - Never silently produce work you're unsure about
+
+    **No prose after the JSON block.**
+```

package/opencode/arcs/skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -0,0 +1,85 @@
+# Spec Compliance Reviewer Prompt Template
+
+Use this template when dispatching a spec compliance reviewer subagent.
+
+**Purpose:** Verify implementer built what was requested (nothing more, nothing less)
+
+```
+Task tool (general-purpose):
+  description: "Review spec compliance for Task N"
+  prompt: |
+    You are reviewing whether an implementation matches its specification.
+
+    ## What Was Requested
+
+    [FULL TEXT of task requirements]
+
+    ## What Implementer Claims They Built
+
+    [From implementer's report]
+
+    ## CRITICAL: Do Not Trust the Report
+
+    The implementer finished suspiciously quickly. Their report may be incomplete,
+    inaccurate, or optimistic. You MUST verify everything independently.
+
+    **DO NOT:**
+    - Take their word for what they implemented
+    - Trust their claims about completeness
+    - Accept their interpretation of requirements
+
+    **DO:**
+    - Read the actual code they wrote
+    - Compare actual implementation to requirements line by line
+    - Check for missing pieces they claimed to implement
+    - Look for extra features they didn't mention
+
+    ## Your Job
+
+    Read the implementation code and verify:
+
+    **Missing requirements:**
+    - Did they implement everything that was requested?
+    - Are there requirements they skipped or missed?
+    - Did they claim something works but didn't actually implement it?
+
+    **Extra/unneeded work:**
+    - Did they build things that weren't requested?
+    - Did they over-engineer or add unnecessary features?
+    - Did they add "nice to haves" that weren't in spec?
+
+    **Misunderstandings:**
+    - Did they interpret requirements differently than intended?
+    - Did they solve the wrong problem?
+    - Did they implement the right feature but wrong way?
+
+    **Verify by reading code, not by trusting report.**
+
+    ## Report Format (MANDATORY)
+
+    Return prose explanation followed by this EXACT JSON block as the LAST thing in your message:
+
+    ```json
+    {
+      "status": "DONE | DONE_WITH_CONCERNS",
+      "summary": "<1-2 sentences: compliance verdict>",
+      "payload": {
+        "compliant": true,
+        "issues": [
+          {
+            "file": "src/foo.ts",
+            "line": 42,
+            "requirement": "Must validate input length",
+            "finding": "No length check present"
+          }
+        ]
+      }
+    }
+    ```
+
+    - `compliant: true` + empty `issues` = spec met
+    - `compliant: false` + populated `issues` = gaps found (use DONE_WITH_CONCERNS)
+    - Each issue must reference the specific requirement and what's missing/extra
+
+    **No prose after the JSON block.**
+```

package/opencode/arcs/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+---
+
+# Skill: systematic-debugging
+
+## When
+
+Any bug, test failure, or unexpected behavior — before proposing fixes.
+
+> Follows ARCS CLI Primer: `arcs --commands --json` for discovery, `--json --lean` on all calls.
+
+## Flow
+
+```mermaid
+flowchart TD
+    classDef decision fill:#f59e0b,color:#fff
+    classDef stop fill:#ef4444,color:#fff
+
+    Bug[Bug observed] --> ARCS[Check ARCS knowledge]
+    ARCS --> Found{Match found?}
+    Found -->|Yes| Verify[Verify it applies]
+    Found -->|No| Observe
+
+    Verify -->|Applies| Fix
+    Verify -->|Doesn't apply| Observe
+
+    Observe[Phase 1: Observe] --> Repro{Reproducible?}
+    Repro -->|No| Instrument[Add logging/tracing]
+    Instrument --> Observe
+    Repro -->|Yes| Hypothesize[Phase 2: Hypothesize]
+
+    Hypothesize --> Compare[Find working example, list differences]
+    Compare --> Theory[Form single specific hypothesis]
+
+    Theory --> Isolate[Phase 3: Isolate]
+    Isolate --> Test{Smallest change confirms?}
+    Test -->|Yes| Fix[Phase 4: Fix]
+    Test -->|No| FailCount{3+ failures?}
+    FailCount -->|No| Theory
+    FailCount -->|Yes| Arch[Question architecture]
+
+    Fix --> WriteFail[Write failing test]
+    WriteFail --> Implement[Single targeted fix]
+    Implement --> Green{Tests pass?}
+    Green -->|Yes| Capture[Capture as ARCS knowledge]
+    Green -->|No| FailCount
+
+    class Found,Repro,Test,FailCount,Green decision
+    class Arch stop
+```
+
+## Phase 1: Observe (Root Cause Investigation)
+
+- Read the actual error message completely
+- Reproduce consistently before proceeding
+- Check recent changes (`git log`, `git diff`)
+- Trace data flow backward from failure point
+- Instrument component boundaries if cause unclear
+- **Pre-step:** `arcs knowledge search <slug> "<error>" --json` for gotcha/lesson/pattern entries
+
+## Phase 2: Hypothesize (Pattern Analysis)
+
+- Find a working example in the same codebase
+- Compare working vs broken — list every difference
+- Understand the dependency chain
+- Form ONE specific hypothesis (not multiple)
+
+## Phase 3: Isolate
+
+- Test with the smallest possible change
+- One variable at a time — never stack fixes
+- If hypothesis fails, form a new one from evidence
+- **Escalation:** 3+ failed fixes → question the architecture, not the symptom
+
+## Phase 4: Fix
+
+- Write a failing test FIRST (proves the bug exists)
+- Implement a single targeted fix
+- Verify all tests pass
+- If fix introduces new failures, revert and return to Phase 2
+
+## Log Triage Protocol
+
+**Scan order:** failure point → errors → warnings → timing anomalies
+
+```bash
+rg -n "ERROR|FATAL|panic|exception" <logfile>   # Error grep
+jq 'select(.level == "error")' <json-log>       # Structured logs
+```
+
+**Output:** Timeline of events leading to failure (T-5m, T-3m, T-0).
+
+## Git Bisect (Regressions)
+
+```bash
+git bisect start
+git bisect bad HEAD
+git bisect good <last-known-good>
+git bisect run <test-command>
+```
+
+After finding the commit: read the diff, isolate specific lines, feed into Phase 2.
+
+## Dependency Conflict Diagnosis
+
+| Symptom | Likely Cause |
+|---------|-------------|
+| `instanceof` fails across modules | Duplicate package copies |
+| Type mismatch on same interface | Different versions loaded |
+| "Cannot find module" intermittent | Hoisting conflict |
+| Works with `--legacy-peer-deps` | Peer dep unsatisfied |
+
+Diagnose: `npm ls <pkg>`, `npm explain <pkg>`, check for multiple copies.
+
+## ARCS Knowledge Capture
+
+After root cause identified, persist as knowledge:
+- **gotcha** — environmental/config traps
+- **lesson** — architectural insights from this session
+- **pattern** — reusable solution to recurring problem
+
+Include: root cause summary, evidence, affected files, fix approach.
+
+### Capture Resolution as Knowledge
+
+After resolving the issue, persist the learning:
+
+```bash
+# For a surprising behavior or trap
+arcs knowledge create <slug> "Redis connection pool exhaustion under load" \
+  --kind=gotcha \
+  --summary="Pool size defaults to 10; under concurrent requests >50, connections time out silently" \
+  --body="Root cause: default pool size. Fix: set poolSize to max(50, expectedConcurrency). Symptoms: intermittent 503s with no error logs." \
+  --json
+
+# For a reusable debugging technique or resolution pattern
+arcs knowledge create <slug> "Diagnosing silent connection failures" \
+  --kind=lesson \
+  --summary="Enable connection-level event logging before load testing" \
+  --body="Attach listeners to pool 'error' and 'timeout' events. Default Node.js behavior swallows these." \
+  --json
+
+# For a pattern that should be followed going forward
+arcs knowledge create <slug> "Connection pool sizing formula" \
+  --kind=pattern \
+  --summary="Pool size = max(50, 2x expected peak concurrency)" \
+  --body="Applies to Redis, Postgres, and HTTP agent pools. Validated under load test 2026-05-26." \
+  --json
+```
+
+**Kind selection guide:**
+- `gotcha` — surprising behavior, trap, or non-obvious failure mode
+- `lesson` — learned technique, debugging approach, resolution method
+- `pattern` — reusable solution that should be applied going forward
+
+## Constraints
+
+- **NO FIXES WITHOUT ROOT CAUSE INVESTIGATION.** If Phase 1 incomplete, you cannot propose fixes.
+- **One variable at a time.** Never apply multiple changes simultaneously.
+- **3+ failures = architectural problem.** Stop fixing symptoms, question the pattern.
+- **Test before fix.** Failing test proves the bug; green test proves the fix.
+- **Defense in depth:** After fixing root cause, add validation at multiple layers to prevent recurrence.
+- **Systematic is faster than thrashing.** 15-30min systematic vs 2-3h random fixes.
+
+## Red Flags (Return to Phase 1)
+
+- "Quick fix for now, investigate later"
+- "Just try changing X and see"
+- Proposing solutions before tracing data flow
+- Each fix reveals a new problem in a different place
+- "I don't fully understand but this might work"
+- Human says "stop guessing" or "is that not happening?"