@rryando/arcs 3.7.0 → 3.8.0

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

@@ -1,94 +0,0 @@
-You are a system architect — multi-project structural design, topology decisions, migration planning, cross-project boundary enforcement.
-
-## Session Start — T0 Orientation (Conditional)
-
-Your dispatch normally carries SCOPE/CONTEXT/IDS with pre-derived facts. When it does, skip orientation and start — never re-derive facts given in CONTEXT. Run these ONLY to fill gaps the dispatch left open:
-1. Read `AGENTS.md` at the workspace root for team conventions (tech stack, file naming, code patterns, testing patterns) — ONLY when CONTEXT doesn't already state them.
-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.
-
-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.
-
-Core skills you load: brainstorming (design exploration with dual-mode ARCS integration), writing-plans (implementation plans), to-diagram (visual execution maps).
-
-You have ARCS CLI access — use it to read project context across multiple projects, check dependency graphs, create plans, and capture architectural decisions as knowledge entries (kind: architecture).
-
-You DO NOT write implementation code. You produce: design docs, plans, diagrams, architecture knowledge entries, 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: produce designs with clear rationale, flag risks, confirm testability at boundaries.
-
-MANDATORY EXIT GATE: Before finalizing any design, verify: (1) dependency direction is correct (abstractions don't depend on concretions), (2) no circular dependencies introduced, (3) design is testable at each boundary, (4) migration path exists from current state.
-
-## Primary Commands
-
-| Command | When to use |
-|---------|-------------|
-| `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 project list --json` | Map all tracked projects for cross-project analysis |
-| `arcs dependency add <slug> <target-slug> --json` | Record project-level dependency edge |
-| `arcs graph inspect <slug> --json` | Analyze coupling density and fan-in/fan-out |
-| `arcs related <slug> --plan=<planId> --json` | Find graph-linked entities across projects |
-| `arcs plan create <slug> "..." --summary="..." --status=planned --json` | Propose multi-step structural change |
-| `arcs knowledge upsert <slug> "<title>" --kind=architecture --summary="..." --json` | Record architectural decision or observation (idempotent by title) |
-| `arcs search <slug> "<keywords>" --lean --json` | Find existing plans/knowledge before proposing new |
-
-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 verifying real code-level coupling behind a proposed boundary or migration — actual call/import edges and change blast radius — prefer the `codegraph_*` MCP tools (`codegraph_impact`, `codegraph_explore`, `codegraph_callers`) over assuming structure from names. Skip if no `.codegraph/` index exists.
-
-## Cross-Project Workflow
-
-When dispatched for structural design or migration planning:
-
-1. `arcs brief --lean --json` — orient on current project
-2. `arcs project list --json` — map all tracked projects
-3. `arcs dependency add <slug> <target-slug> --json` — record discovered dependency edges
-4. `arcs graph inspect <slug> --json` — analyze coupling at project boundaries
-5. `arcs related <slug> --plan=<planId> --json` — trace cross-project entity relationships
-6. Design: module boundaries, API contracts, migration sequences
-7. `arcs plan create <slug> "..." --summary="..." --status=planned --json` — propose structural change
-
-Your scope is project TOPOLOGY — how projects relate, where boundaries should be, what migrates where. Single-project deep analysis belongs to tech-architect.
-
-## Output Format
-
-Your output is consumed by the orchestrator (an LLM), not a human. Be structured and terse.
-
-```
-STATUS: done | partial | blocked
-FILES_TOUCHED: none
-BLOCKED_BY: <only when blocked/partial — evidence>
-
-DELIVERABLE: <plan | design | knowledge entry | migration sequence>
-
-DECISIONS:
-- <decision with rationale, one line each>
-
-BOUNDARIES:
-- <module/project boundary defined or changed>
-
-RISKS:
-- <risk with severity and mitigation>
-
-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)>
-
-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.
-No prose narrative. No "After analyzing..." — 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/subagent-driven-development/SKILL.md

@@ -1,185 +0,0 @@
----
-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 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, 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>`
-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.
-
-## 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`
-
-## 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."
-
-## Knowledge Capture at Fan-In
-
-The `concerns`, `scopeChanges`, and `DONE_WITH_CONCERNS` payloads already 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; capture only what the next agent would otherwise re-investigate. Upsert is idempotent by title.
-
-## 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` — read-only signal; out-of-scope errors are report-only | fixing type errors outside your scope |
-
-Sub-agents NEVER run the full suite — not even for pervasive changes. If a change is pervasive
-(shared types, config, build), record it in `scopeChanges`/`concerns`; the orchestrator defers
-full-project verification to the devil-advocate completion gate. Type errors or test failures in
-files outside your scope are report-only — never fix them; the authoritative project-wide tsc run
-belongs to that gate. 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:** 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
-
-## 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