@rryando/arcs 4.1.0 → 4.2.0

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

@@ -1,61 +1,35 @@
 ---
 name: implementation
-description: Use for orchestrator-selected bounded or inspect implementation work. Bounded executes a fully specified change directly; inspect resolves limited uncertainty from the repo and DAG before coding.
+description: Inspect, edit, verify, or execute a ready plan node
 ---
 
-# Skill: implementation
+# Implementation
 
-## Work Mode Is Dispatch Authority
+## Work Modes
 
-The orchestrator selects exactly one work mode in the dispatch: `bounded` or `inspect`. Do not re-route yourself or silently expand scope.
+`bounded`, `inspect`, and `plan-node` are hints, not lifecycle gates:
 
-### `bounded`
+- **bounded:** the requested files and behavior are already clear; start directly.
+- **inspect:** inspect the smallest repository surface needed to resolve implementation details.
+- **plan-node:** check declared dependencies, execute the current ready node within its scope, run relevant verification, and align task and diagram state through the ARCS CLI. Never edit DAG files or diagrams directly, execute a blocked node, or absorb an adjacent outcome.
 
-Use when the task, files, acceptance criteria, and VERIFY command are fully specified.
+In any mode, ask only when evidence cannot resolve a change to the goal, material scope, dependency strategy, or risk.
 
-- Execute directly with no repo exploration and no user questions.
-- Read only the dispatched files and context needed to make the change.
-- If a material decision or hidden scope appears, stop and return `STATUS: blocked`; do not guess or switch modes.
+## Method
 
-### `inspect`
+1. Inspect relevant code and tests.
+2. Reuse existing patterns and dependencies.
+3. Edit the minimum code needed for a complete result.
+4. Add proportionate tests for changed behavior.
+5. Verify with targeted checks; use broader checks for broad or high-risk work.
+6. If verification fails, fix failures caused by the change and rerun the relevant check.
 
-Use when the goal is clear but limited implementation details remain.
+For `plan-node`, read the current node metadata, confirm every predecessor is done, and use ARCS CLI task and diagram commands to keep completion state aligned. If dependencies are unmet or the node conflicts with its scope, stop with the concrete blocker instead of selecting other work.
 
-1. Inspect the repository and DAG first: search relevant knowledge, then inspect the smallest set of patterns, types, callers, and tests that can resolve the decision.
-2. Infer the answer when tools or established conventions make it clear.
-3. Ask at most one targeted user question, and only for a material decision that is not tool-resolvable.
-4. If uncertainty is design-shaping or scope expands, stop and return `STATUS: blocked` rather than improvising.
+Prefer necessity → standard library → platform capability → installed dependency → minimum custom code. Do not simplify away security, accessibility, validation, error handling, or data-loss protection.
 
-## Construction Discipline
+Do not commit, push, deploy, or modify unrelated files without an explicit request.
 
-Before adding code, stop at the first rung that satisfies the requirement:
+## Return
 
-1. **Necessity** — omit speculative or unrequested work.
-2. **Standard library** — use it when it correctly covers the need.
-3. **Native platform** — prefer a built-in platform capability.
-4. **Installed dependency** — reuse one before adding code or a dependency.
-5. **Minimum code** — write only the smallest correct implementation.
-
-Do not introduce abstractions, configuration, scaffolding, or dependencies for hypothetical consumers. Minimal does not mean flimsy: never simplify away security controls, accessibility basics, trust-boundary validation, or error handling that prevents data loss.
-
-Mark every deliberate simplification with its known ceiling and concrete revisit trigger:
-
-```
-// SHORTCUT: <ceiling>, upgrade when <trigger>
-```
-
-## Implementation And Verification
-
-- Follow existing repository conventions and the dispatch SCOPE.
-- Use test-driven-development when the dispatch requires it or when adding non-trivial behavior; structural changes may rely on existing focused contracts.
-- Run exactly the dispatch VERIFY command, scoped to touched files. NEVER the full suite, project-wide lint, or full build.
-- Fix failures in touched files and re-run VERIFY. Report failures originating outside SCOPE under `BLOCKED_BY`; do not edit those files.
-- Never commit unless explicitly asked.
-
-## Knowledge Exit
-
-Knowledge is proposal-only. For a durable, non-obvious pattern or gotcha, return a substantive ready-to-run proposal for orchestrator persistence at fan-in; do not execute `arcs knowledge upsert` yourself. Skip mechanical or easily re-derived observations.
-
-`arcs knowledge template --kind=<kind> --json`; `arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha|lesson|architecture|decision> --summary="<summary>" --body="<substantive filled template>" --keywords="<keywords>" --source-files="<path[:anchor]>" --json`
-
-Upsert is idempotent by title.
+Report changed files, verification actually run, remaining risk, and blockers.

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

@@ -1,160 +1,22 @@
 ---
 name: init-project
-description: Use when initializing a new ARCS project — bootstrapping a repo into the DAG with metadata, docs, and structural knowledge entries. Covers gather → present summary → init → codegraph ingestion → fan-out analysis across typed sub-agents.
+description: Initialize a repository as an ARCS project with useful minimal metadata
 ---
 
-# Skill: init-project
+# Initialize Project
 
-## When
+## Method
 
-User wants to track a new project, bootstrap documentation, or connect a repo to the ARCS DAG. Triggers: "new project", "track this repo", "add project X", "init <repo>".
+An explicit request to init or track a project authorizes the local ARCS initialization. Ask only for missing user-owned identity such as name, description, workspace path, or dependency choice.
 
-> **Canonical orchestrator workflow:** `src/cli/arcs-orchestrate.ts` under `### INIT Workflow` — this skill mirrors that flow with full operational detail. If the two diverge, the orchestrator prompt wins.
+1. Check slug conflicts with `arcs project list`.
+2. Verify named dependency projects exist.
+3. Run `arcs project init` with the requested metadata.
+4. Add only requested or clearly useful overview/dependency documentation.
+5. Validate the new project and report its slug and paths.
 
-## Flow
+Codegraph is optional. When available, initialization may index the workspace and emit structural proposals. When absent, continue without it. If `pending_enrichment` is true, process useful proposals with `enriching-codegraph-proposals`; do not require a broad agent fan-out.
 
-```mermaid
-flowchart TD
-    classDef sub fill:#8b5cf6,color:#fff
+Raw proposals are not knowledge. Inspect them before keep, merge, drop, or promote decisions. Never infer destructive cleanup, deployment, publication, or Git permission from initialization.
 
-    A[Gather: name, description, repoUrl?, dependsOn?] --> B[arcs project list → conflict check]
-    B --> C[Present summary to user]
-    C -->|user confirms| D[arcs project init]
-    D --> E[arcs project update-doc × 4]
-    E --> F{codegraph on PATH?}
-    F -->|yes| G[codegraph index --force --quiet]
-    F -->|no| H[Skip graph step, log gap]
-    G --> G2[ingestGraph → ≤20 proposals]
-    G2 --> G3[Enrich queue: list → keep/merge/drop → promote/drop]
-    G3 --> I[Fan out: tech-architect analysis + research modes]:::sub
-    H --> I
-    I --> K[Done]
-```
-
-## CLI Primer
-
-```bash
-arcs project init "Foo" --description="..." --path="$(pwd)" --json
-```
-Discovery: `arcs --commands --json`. Mutating commands run directly — no token.
-
-## Constraints
-
-- Do NOT read repo to infer name/description — gather from user
-- Verify `dependsOn` targets exist via `arcs project list --json`
-- `arcs project init` creates empty `plans/`, `knowledge/`, `tasks/` indexes — don't pre-populate
-- Repo analysis is **fan-out across typed agents**, never a generic "analysis sub-agent" (see Agent Dispatch below)
-- Never block INIT on codegraph — it's optional. Skip cleanly if missing.
-
-## Codegraph Sub-Flow (DEFAULT: ON when binary present)
-
-The orchestrator runs codegraph directly during INIT to produce structural **proposals** before any sub-agent reads code. Proposals are durable on the proposal-store ledger; agents enrich them into knowledge entries via the `enriching-codegraph-proposals` skill. This is the default path when `codegraph` is on PATH; skip cleanly otherwise.
-
-1. **Detect:** call `detectCodegraph()` from `src/utils/codegraph.ts`. If unavailable, log "codegraph not on PATH; proceeding without graph signal" and skip steps 3–6.
-2. **Trust the gitignore guarantee:** `runIndex()` already auto-appends `.codegraph/` to `.gitignore` via `ensureGitignoreEntry`. Do NOT redundantly check or modify `.gitignore` from agents — running the index is sufficient.
-3. **Index** (project-based; CLI drives the bundled runtime — no LLM API key required):
-   ```bash
-   codegraph index <workspacePath> --force --quiet
-   ```
-   Builds a per-project codegraph index under `<workspacePath>/.codegraph/`.
-4. **Ingest as proposals:** `arcs project init` internally calls `ingestGraph(slug)`, which parses codegraph CLI `--json` output and writes up to 20 structural proposals to `proposals/graphify.json` (filename retained for compatibility; rename pending; test files filtered):
-   - 8 god nodes (`kind=module`, ranked by callers+callees / impact as a proxy for degree)
-   - 8 architecture clusters (`kind=architecture`, synthesized pseudo-communities by directory prefix — codegraph has no community/cluster export)
-   - 5 cross-module couplings (`kind=gotcha`, high-degree links across top-level dirs; relations hard-coded as `["calls"]`)
-
-   Codegraph never writes directly to the knowledge surface. The init envelope returns `data.codegraph.pending_enrichment: true` to signal that proposals are waiting.
-5. **Enrich** with the `enriching-codegraph-proposals` skill — read `arcs proposal list <slug> --json`, decide per-proposal verdicts (keep / merge / drop), and return exact proposed promote/drop commands for orchestrator application. Pending codegraph proposals never bypass this lifecycle into knowledge.
-6. **Optional graph queries** for evidence during enrichment (sub-agents may run these via the codegraph MCP server, which auto-syncs through its own file watcher):
-   - `codegraph_search "entry points and main commands"` → seeds for "key files" reference entries
-   - `codegraph_explore` on core modules → seeds for "core modules" entries
-   - `codegraph_node "<godNodeLabel>"` → structural summary for module entry bodies
-   - `codegraph_impact "<critical-symbol>"` → reverse-impact map for high-risk modules
-   - `codegraph_callers` / `codegraph_callees "<symbol>"` → dependency paths for architecture entries
-7. **Hand to typed agents** (in parallel) for independently authored, code-grounded follow-up entries beyond the proposal queue — see **Agent Dispatch** below.
-
-## Content Guidelines
-
-| Doc | Format |
-|-----|--------|
-| `overview.md` | 2-3 sentence summary + goals |
-| `tasks.md` | `[ ]` backlog / `[/]` in-progress / `[x]` done |
-| `dependencies.md` | Upstream + downstream sections |
-| `knowledge.md` | High-level context + pointers to structured entries |
-
-Update via `arcs project update-doc <slug> <doc> --content="..."`.
-
-## Agent Dispatch (named typed agents — DO NOT default to a generic analysis agent)
-
-| Sub-agent | Owns | Knowledge kinds it produces |
-|-----------|------|----------------------------|
-| `tech-architect` (analysis mode) | Module boundaries, clusters, dependency direction, cross-module couplings, structural gotchas, lessons | `architecture`, `module`, `gotcha`, `lesson` |
-| `tech-architect` (`AGENT_MODE: research`) | Tech stack, third-party libraries, key files, features | `reference`, `feature` |
-| `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)
-- Targeted codegraph queries for evidence (e.g., `codegraph_node` / `codegraph_impact` output for the modules they own)
-- Explicit scope (which files / which kinds to produce)
-
-Raw `KnowledgeProposal` records stay in the proposal lifecycle above. Each typed agent may instead return an independently authored finding: `{title, kind, summary, keywords, sourceFiles, body}`. Workers do not execute `arcs knowledge upsert`; after deduplication they return substantive ready-to-run commands for orchestrator fan-in persistence.
-
-## Knowledge Categories for Analysis Sub-Agents
-
-| Category | Kind | What to discover | Primary agent |
-|----------|------|------------------|---------------|
-| tech stack | `architecture` | Languages, frameworks, runtimes, build tools, versions | `tech-architect` (`AGENT_MODE: research`) |
-| key files | `reference` | Entry points, config files, main modules, purposes | `tech-architect` (`AGENT_MODE: research`; use `codegraph_search "entry points"`) |
-| 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 | `tech-architect` (`AGENT_MODE: research`) |
-| third-party libraries | `reference` | Key dependencies and why they are used | `tech-architect` (`AGENT_MODE: research`) |
-| features | `feature` | Major user-facing or system-facing features | `tech-architect` (`AGENT_MODE: research`) |
-| 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 | `tech-architect` (auto from `ingestGraph`) |
-
-## Worked Example
-
-```bash
-# 1. Conflict check
-arcs project list --json
-
-# 2. Present summary to user; on confirmation, init
-arcs project init "Foo" --description="Foo CLI tool" --path="$(pwd)" --json
-
-# 3. Update docs
-arcs project update-doc foo overview --content="..." --json
-# ... repeat for tasks, dependencies, knowledge
-
-# 4. Codegraph (if available) — runs inside `arcs project init`
-codegraph index . --force --quiet
-# ingestGraph parses codegraph CLI --json → proposals/graphify.json (filename retained; rename pending)
-# init envelope: data.codegraph.pending_enrichment === true → load
-# `enriching-codegraph-proposals` and run the verdict loop:
-arcs proposal list foo --json
-# keep: promote only after authoring the required title, summary, body, and source files
-arcs proposal promote foo <id> --title="..." --summary="..." --body-file=... --kind=module --source-files=... --json
-# merge: promote with --merge-with=<existing-knowledge-id> and append graph evidence
-arcs proposal promote foo <id> --merge-with=<existing-knowledge-id> --body-file=... --source-files=... --json
-arcs proposal drop foo <id> --reason="..." --json
-
-# 5. Fan out typed agents (parallel) for entries beyond proposal scope
-#    tech-architect (analysis mode)          → architecture/module/gotcha/lesson entries
-#    tech-architect (AGENT_MODE: research)   → reference/feature entries
-
-# 6. Propose only independently authored, non-proposal-derived findings.
-# Obtain the kind-specific body anatomy before authoring the ready-to-run command:
-arcs knowledge template --kind=architecture --json
-arcs knowledge upsert foo "Tech stack: TypeScript + Node 20" --kind=architecture --summary="..." --body-file=... --source-files=package.json --json
-# Return the upsert; do not execute it. The orchestrator persists it at fan-in.
-```
-
-## Exit Conditions
-
-| Condition | Action |
-|-----------|--------|
-| Project already in DAG (slug collision) | Stop. Surface conflict; ask user to rename or use existing |
-| User declines summary | Stop. No mutations performed |
-| `codegraph` missing | Continue without graph signal; sub-agents run with code reading only |
-| `dependsOn` target missing | Stop. Ask user to init dependencies first or remove the link |
-| Init succeeds but knowledge fan-out fails | Project exists in DAG; rerun knowledge phase later via SYNC |
+If a write fails, stop and report partial state instead of layering more mutations on an uncertain project.

package/opencode/arcs/skills/install-claude-code-hook/SKILL.md

@@ -1,143 +1,23 @@
 ---
 name: install-claude-code-hook
-description: Use when retrofitting the Claude Code session-bridge hook onto an already-inited ARCS project — triggers "install the claude code hook", "enable session bridge", "set up hook for this project", "hook up claude code to arcs", "the arcs web UI can't see my session". Claude Code only; detects existing state, then installs after explicit confirmation.
+description: Install the ARCS session-bridge hook into an existing Claude Code workspace
 ---
 
-# Skill: install-claude-code-hook
+# Install Claude Code Hook
 
-## When
+## Boundary
 
-The project is already in the DAG but its workspace never got the session-bridge hook — usually because `arcs project init` predated the offer, or the offer was declined. Triggers: "install the claude code hook", "enable session bridge", "set up hook for this project", "hook up claude code to arcs", "the arcs web UI can't see my session".
+Claude Code only. If the current harness is not Claude Code, stop. The hook changes `.claude/settings.local.json`, so obtain explicit confirmation before using `--write`.
 
-> **Claude-Code-only skill.** Step 0 is self-knowledge, not detection: if you are not running as Claude Code, say so and stop. The hook registers into Claude Code's own settings file; installing it from another harness configures a client that will never run it. There is no environment-variable heuristic here by design — you know your own harness.
+## Method
 
-> **Executes, unlike the proposal skills.** After explicit user confirmation this skill runs `arcs hooks install-claude-code <slug> --write` itself. That is not a `writing-knowledge`-style "propose, don't execute" case: the write is local machine config (`.claude/settings.local.json`), not a durable ARCS DAG mutation. It mirrors `promptAndInstallClaudeCodeHook`, which already executes directly inside `arcs project init` behind the same confirm.
+1. Run `arcs hooks status <slug> --json`.
+2. If already installed for this slug, report a no-op.
+3. Explain the file written, registered events, local token, and that a new Claude Code session is required.
+4. If the hook points at another slug, warn that installation will repoint it and confirm that effect.
+5. After explicit confirmation, run `arcs hooks install-claude-code <slug> --write --json` once.
+6. Report `settingsPath`, events, and next-session requirement.
 
-## Flow
+Do not hand-edit Claude settings. A malformed settings file is a stop condition: surface the CLI error and do not repair, reformat, or delete it. Do not rerun installation for reassurance because it may rotate the token.
 
-```mermaid
-flowchart TD
-    classDef decision fill:#f59e0b,color:#fff
-    classDef terminal fill:#22c55e,color:#fff
-
-    A{Running as Claude Code?}:::decision -->|no| Stop[State Claude-Code-only, stop]:::terminal
-    A -->|yes| B[arcs hooks status slug --json]
-    B --> C{installed?}:::decision
-    C -->|false| D[Explain the bridge, ask to install]
-    C -->|true| E{matchesCurrentSlug?}:::decision
-    E -->|true| F[Report found, no-op]:::terminal
-    E -->|false| G[Warn: installing repoints matchedSlugs, re-confirm]
-    D -->|declines| H[Print manual fallback, no mutation]:::terminal
-    G -->|declines| H
-    D -->|explicit yes| I[arcs hooks install-claude-code slug --write]
-    G -->|explicit yes| I
-    I --> J{ok?}:::decision
-    J -->|true| K[Report settingsPath + events + new-session note]:::terminal
-    J -->|false| L[Surface the CLI error verbatim, no repair]:::terminal
-```
-
-## CLI Primer
-
-```bash
-arcs hooks status <slug> --json
-arcs hooks install-claude-code <slug> --write --json
-```
-Discovery: `arcs --commands --json`. Mutating commands run directly — no token.
-
-`hooks status` is read-only and rotates nothing, so it is safe to call as many times as you like. Its envelope:
-
-| Field | Meaning |
-|---|---|
-| `installed` | `true` only when ALL THREE events (`SessionStart`, `UserPromptSubmit`, `SessionEnd`) are registered. A partial registration is a broken bridge and reports `false`. |
-| `matchesCurrentSlug` | The registered hook carries `ARCS_HOOK_SLUG=<slug>` for the project you asked about. |
-| `matchedSlugs` | Every slug found on a matching hook command — how you see a hook wired to a *different* project. |
-| `hookScriptPath` | Absolute path of the script the hook entry runs; the key both status and install match on. |
-
-`hooks install-claude-code <slug> --write` performs the write via the same consent-gated merge `arcs project init` uses, and returns `settingsPath` and `events` alongside the pre-existing `token` / `hookScriptPath` / `serverUrl` / `settingsSnippet` fields. Omitting `--write` keeps the old snippet-only behavior — no file is touched — which is the manual fallback.
-
-## Constraints
-
-- Step 0 first: not Claude Code → state that this skill is Claude-Code-only and stop. No install, no status call.
-- Never write without EXPLICIT user confirmation. Default posture is do nothing; silence, ambiguity, or "sure, whatever you think" is not consent.
-- `matchesCurrentSlug: false` with a non-empty `matchedSlugs` demands a SECOND, explicit re-confirmation — the merge is keyed on `hookScriptPath`, so one workspace holds one hook and installing silently repoints it away from the other slug.
-- Never edit `.claude/settings.local.json`, `.claude/settings.json`, or `~/.claude/settings.json` yourself. `--write` is the only sanctioned mutation path.
-- Install failure (malformed existing settings file) → surface the CLI's own error message verbatim. Do NOT repair, reformat, or delete the settings file from this skill; the CLI aborted precisely so a hand-edited file is not clobbered.
-- Do not rerun `--write` "to be safe" — every run rotates the token and invalidates the previously installed entry.
-- Pass `--url` only when the user runs `arcs web` on a non-default port; the hook posts to `http://127.0.0.1:4173` otherwise.
-
-## Opt-In Copy (what the user must be told before confirming)
-
-State all four, plainly, before asking:
-
-1. **What it buys them** — the ARCS web UI can see this Claude Code session, and messages queued from the UI are delivered to the next prompt.
-2. **What is written** — `<workspacePath>/.claude/settings.local.json` and nothing else. Never the global config, never a committed file; `settings.local.json` is the git-ignored variant and the token in it is a secret.
-3. **What is registered** — one script under three events: `SessionStart`, `UserPromptSubmit`, `SessionEnd`.
-4. **When it takes effect** — a NEW Claude Code session. The session asking for the install will not pick it up.
-
-## Worked Example
-
-```bash
-# 0. Self-check: you are Claude Code. If not → "This skill is Claude-Code-only." Stop here.
-
-# 1. Read-only detection (rotates nothing; safe to repeat)
-arcs hooks status arcs --json
-# → {"installed":false,"matchesCurrentSlug":false,"matchedSlugs":[],
-#    "hookScriptPath":"/…/scripts/claude-code-session-hook.mjs"}
-
-# 2. Not installed → present the opt-in copy above, then ask:
-#    "Install the Claude Code session-bridge hook for `arcs` now?"
-#    Wait for an explicit yes. Anything else → step 4.
-
-# 3. Explicit yes → install and report
-arcs hooks install-claude-code arcs --write --json
-# → {"settingsPath":"/home/u/Work/arcs/.claude/settings.local.json",
-#    "events":["SessionStart","UserPromptSubmit","SessionEnd"], …}
-# Report: settingsPath, the three events, and "start a NEW Claude Code session to pick it up".
-
-# 4. Declined → no mutation. Print the manual fallback (snippet only, writes nothing):
-arcs hooks install-claude-code arcs --json
-# Paste `settingsSnippet` into .claude/settings.local.json by hand.
-```
-
-Already-installed branch:
-
-```bash
-arcs hooks status arcs --json
-# → {"installed":true,"matchesCurrentSlug":true,"matchedSlugs":["arcs"], …}
-# Report "session-bridge hook already installed for `arcs`". No-op. Done.
-```
-
-Different-slug branch:
-
-```bash
-arcs hooks status arcs --json
-# → {"installed":true,"matchesCurrentSlug":false,"matchedSlugs":["legacy-app"], …}
-# Warn: "This workspace's hook is registered for `legacy-app`. One workspace holds
-#        one hook by design — installing for `arcs` will silently repoint it and
-#        `legacy-app` will stop reporting sessions."
-# Require a SECOND explicit confirmation, then:
-arcs hooks install-claude-code arcs --write --json
-```
-
-Failure branch:
-
-```bash
-arcs hooks install-claude-code arcs --write --json
-# → {"ok":false,"code":"hook_install_error","message":"/…/.claude/settings.local.json exists
-#     but is not valid JSON — fix it manually or delete it, then re-run
-#     `arcs hooks install-claude-code arcs`. Nothing was written."}
-# Relay that message verbatim. Do not touch the file.
-```
-
-## Exit Conditions
-
-| Condition | Action |
-|-----------|--------|
-| Not running as Claude Code | Stop. State the skill is Claude-Code-only; run nothing |
-| `installed: true` and `matchesCurrentSlug: true` | Stop. Report already installed; no-op |
-| `installed: true` and `matchesCurrentSlug: false` | Warn that installing repoints the hook away from `matchedSlugs`; require a second explicit confirmation before `--write` |
-| `installed: false` | Present the opt-in copy; install only on explicit confirmation |
-| User declines at any confirmation | Stop. No mutation. Print the manual fallback: `arcs hooks install-claude-code <slug> --json` (snippet only, no `--write`) |
-| `--write` succeeds | Report `settingsPath` and `events`; tell the user a NEW Claude Code session is required |
-| `--write` fails (e.g. malformed settings file) | Surface the CLI's error message verbatim. Attempt no repair; nothing was written |
-| Project has no workspace path (`no_workspace_paths`) | Stop. Relay the error and offer the snippet-only fallback |
+Without confirmation, offer the snippet-only command without `--write`.

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

@@ -1,162 +1,23 @@
 ---
 name: systematic-debugging
-description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+description: Diagnose bugs and failing tests from evidence before changing code
 ---
 
-# Skill: systematic-debugging
+# Systematic Debugging
 
-## When
+## Method
 
-Any bug, test failure, or unexpected behavior — before proposing fixes.
+Observe → reproduce → isolate → regression test → fix → verify.
 
-> Follows ARCS CLI Primer: `arcs --commands --json` for discovery, `--json --lean` on all calls.
+1. **Observe:** read the full error, logs, inputs, and recent relevant changes.
+2. **Reproduce:** find the smallest reliable reproduction. Add instrumentation when needed.
+3. **Isolate:** trace backward, compare a working path, and test one hypothesis at a time.
+4. **Regression test:** encode the failure when practical.
+5. **Fix:** change the root cause with the smallest targeted patch.
+6. **Verify:** show the reproduction and relevant checks pass.
 
-## Flow
+If three failed fixes do not improve the evidence, stop and question the architecture or assumptions instead of stacking another guess.
 
-```mermaid
-flowchart TD
-    classDef decision fill:#f59e0b,color:#fff
-    classDef stop fill:#ef4444,color:#fff
+Use ARCS knowledge only when a prior gotcha may save time. Capturing a durable discovery is optional, not part of the success condition.
 
-    Bug[Bug observed] --> ARCS[Check ARCS knowledge]
-    ARCS --> Found{Match found?}
-    Found -->|Yes| Verify[Verify it applies]
-    Found -->|No| Observe
-
-    Verify -->|Applies| Isolate
-    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{Root cause isolated?}
-    Test -->|Yes| WriteFail[Write failing regression test]
-    Test -->|No| FailCount{3+ failures?}
-    FailCount -->|No| Theory
-    FailCount -->|Yes| Arch[Question architecture]
-
-    WriteFail --> Implement[Single targeted fix]
-    Implement --> Green{Scoped verification passes?}
-    Green -->|Yes| Capture[Propose resolution 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: Root Cause Isolation
-
-- Test the hypothesis with the smallest possible diagnostic change
-- One variable at a time — never stack fixes
-- If hypothesis fails, form a new one from evidence
-- Do not proceed until the evidence isolates the root cause
-- **Escalation:** 3+ failed fixes → question the architecture, not the symptom
-
-## Phase 4: Fix
-
-- Write a failing regression test FIRST (proves the bug exists and prevents a fix-before-test path)
-- Implement a single targeted fix
-- Run scoped verification for the files you changed (your dispatch VERIFY command — never the full suite; the devil-advocate completion gate owns that)
-- Prepare the resolution as an ARCS knowledge proposal after verification passes; do not execute `arcs knowledge upsert`
-- If your fix introduces new failures in YOUR scoped tests, revert and return to Phase 2. Failures in files outside your scope are report-only (BLOCKED_BY) — likely a sibling agent's in-flight work; never fix or revert it
-
-## 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 identification, propose durable knowledge for orchestrator fan-in persistence:
-- **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.
-
-### Propose Resolution as Knowledge
-
-After resolving the issue, choose the kind and obtain its required anatomy before authoring a complete entry:
-
-```bash
-arcs knowledge template --kind=gotcha --json
-# Fill every returned section with observed evidence, affected files, and the fix approach.
-arcs knowledge upsert <slug> "<specific debugging discovery>" \
-  --kind=gotcha --summary="<durable takeaway>" --body-file=<complete-body.md> \
-  --keywords="<error,component,root-cause>" --source-files=<affected-paths> --json
-```
-
-Return that command as a ready-to-run proposal. Do not execute `arcs knowledge upsert`; the orchestrator owns fan-in persistence. Use the same template-first flow for `lesson` and `pattern`; do not copy a body-shaped example that omits the selected kind's required sections.
-
-**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?"
+Optional references provide concise techniques for tracing, waiting, and defense in depth. Do not run destructive Git operations unless the user requests them.