@rryando/arcs 3.10.0 → 3.11.0

package/scripts/deploy-opencode-bundle.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+
 // Deploy opencode ARCS bundle bundle from repo to user config.
 //
 // Direction: repo → config ONLY. Never writes config → repo.
@@ -11,6 +12,7 @@
 // Outputs JSON to stdout: DeployResult
 // Exit code: 0 on success, 1 on error.
 
+import { createHash } from "node:crypto";
 import {
   copyFileSync,
   existsSync,
@@ -27,6 +29,9 @@ import { fileURLToPath } from "node:url";
 import {
   assertNoReservedPathSegments,
   assertPathWithinCategoryRoot,
+  isActiveAgentForMode,
+  isRetiredAgentForMode,
+  validateRetirementReplacements,
   wireCodegraphMcp,
   wireRtk,
 } from "./lib/bundle-helpers.mjs";
@@ -59,6 +64,42 @@ function ensureParentDir(filePath) {
   mkdirSync(dirname(filePath), { recursive: true });
 }
 
+function sha256(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function readInstalledManifest() {
+  const path = resolve(configRoot, ".arcs-bundle.json");
+  if (!existsSync(path)) return null;
+  try {
+    const value = JSON.parse(readFileSync(path, "utf-8"));
+    return value?.bundleId === "arcs-opencode-bundle" ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function configOwnershipHash(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return sha256(JSON.stringify(value));
+  }
+  const withoutModel = { ...value };
+  delete withoutModel.model;
+  return sha256(JSON.stringify(withoutModel));
+}
+
+function agentDefaultModel(manifest, id) {
+  const merge = (manifest.config?.requiredMerges ?? []).find(
+    (candidate) =>
+      candidate.path?.length === 2 &&
+      candidate.path[0] === "agent" &&
+      candidate.path[1] === id &&
+      candidate.value &&
+      typeof candidate.value === "object",
+  );
+  return merge?.value?.model;
+}
+
 function validateManifestPaths(manifest) {
   assertPathWithinCategoryRoot(manifest.skills.source, "skills");
   assertPathWithinCategoryRoot(manifest.skills.destination, "skills");
@@ -78,6 +119,43 @@ function validateManifestPaths(manifest) {
   }
 }
 
+function validateAgentRegistry(agents) {
+  if (!Array.isArray(agents)) throw new Error("Invalid agent registry: agents must be an array");
+  const byId = new Map();
+  const sources = new Set();
+  const destinations = new Set();
+  for (const agent of agents ?? []) {
+    if (!agent || typeof agent.id !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(agent.id)) {
+      throw new Error("Invalid agent registry: every agent requires a valid id");
+    }
+    if (agent.status !== "active" && agent.status !== "retired") {
+      throw new Error(`Invalid agent registry status for ${agent.id}`);
+    }
+    if (agent.kind !== "primary" && agent.kind !== "subagent") {
+      throw new Error(`Invalid agent registry kind for ${agent.id}`);
+    }
+    if (
+      !Array.isArray(agent.modes) ||
+      agent.modes.length === 0 ||
+      agent.modes.some((mode) => mode !== "opencode" && mode !== "claudecode")
+    ) {
+      throw new Error(`Invalid agent registry modes for ${agent.id}`);
+    }
+    if (byId.has(agent.id)) throw new Error(`Invalid agent registry: duplicate id ${agent.id}`);
+    if (sources.has(agent.source)) {
+      throw new Error(`Invalid agent registry: duplicate source ${agent.source}`);
+    }
+    if (destinations.has(agent.destination)) {
+      throw new Error(`Invalid agent registry: duplicate destination ${agent.destination}`);
+    }
+    byId.set(agent.id, agent);
+    sources.add(agent.source);
+    destinations.add(agent.destination);
+  }
+
+  validateRetirementReplacements(agents);
+}
+
 async function main() {
   const manifestPath = resolve(bundleRoot, "manifest.json");
   if (!existsSync(manifestPath)) {
@@ -86,6 +164,8 @@ async function main() {
 
   const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
   validateManifestPaths(manifest);
+  validateAgentRegistry(manifest.agents);
+  const previousManifest = readInstalledManifest();
 
   // Build mapping: config-relative path → bundle-absolute path
   const deployMap = new Map();
@@ -102,7 +182,7 @@ async function main() {
   }
 
   // Plugin
-  if (manifest.plugin && manifest.plugin.source) {
+  if (manifest.plugin?.source) {
     const pluginSource = resolve(bundleRoot, manifest.plugin.source);
     if (existsSync(pluginSource)) {
       deployMap.set(manifest.plugin.destination, pluginSource);
@@ -110,7 +190,9 @@ async function main() {
   }
 
   // Agents (sub-agent prompts) — bundle prompts/<file> → config prompts/<file>
-  for (const agent of manifest.agents ?? []) {
+  for (const agent of (manifest.agents ?? []).filter((record) =>
+    isActiveAgentForMode(record, "opencode"),
+  )) {
     const agentSource = resolve(bundleRoot, agent.source);
     if (existsSync(agentSource)) {
       deployMap.set(agent.destination, agentSource);
@@ -128,8 +210,7 @@ async function main() {
     const sourceContent = readFileSync(bundleAbsolute, "utf-8");
 
     const isNew = !existsSync(configAbsolute);
-    const isChanged =
-      !isNew && readFileSync(configAbsolute, "utf-8") !== sourceContent;
+    const isChanged = !isNew && readFileSync(configAbsolute, "utf-8") !== sourceContent;
 
     if (isNew) {
       filesAdded.push(configRelative);
@@ -168,6 +249,54 @@ async function main() {
     }
   }
 
+  const retiredById = new Map(
+    (manifest.agents ?? [])
+      .filter((agent) => isRetiredAgentForMode(agent, "opencode"))
+      .map((agent) => [agent.id, agent]),
+  );
+  let config = null;
+  let configChanged = false;
+  const configPath = resolve(configRoot, "opencode.json");
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf-8"));
+    } catch {
+      config = null;
+    }
+  }
+  const configAgents =
+    config?.agent && typeof config.agent === "object" && !Array.isArray(config.agent)
+      ? config.agent
+      : null;
+
+  for (const ownership of previousManifest?.agents ?? []) {
+    const retired = retiredById.get(ownership.id);
+    if (!retired || retired.destination !== ownership.promptDestination) continue;
+    const promptPath = resolve(configRoot, ownership.promptDestination);
+    if (existsSync(promptPath) && sha256(readFileSync(promptPath)) === ownership.sourceHash) {
+      filesRemoved.push(ownership.promptDestination);
+    }
+
+    if (!configAgents || !ownership.configKey || !ownership.configHash) continue;
+    const current = configAgents[ownership.configKey];
+    if (current === undefined || configOwnershipHash(current) !== ownership.configHash) continue;
+    const replacement = retired.replacementId ? configAgents[retired.replacementId] : null;
+    const retiredDefault = agentDefaultModel(manifest, ownership.id);
+    if (
+      replacement &&
+      typeof replacement === "object" &&
+      current?.model !== undefined &&
+      current.model !== retiredDefault
+    ) {
+      const replacementDefault = agentDefaultModel(manifest, retired.replacementId);
+      if (replacement.model === undefined || replacement.model === replacementDefault) {
+        replacement.model = current.model;
+      }
+    }
+    delete configAgents[ownership.configKey];
+    configChanged = true;
+  }
+
   // Pass 2: Apply writes (only when not dry-run)
   if (!dryRun) {
     // Clean-delete the skills directory before copying to guarantee a fresh install.
@@ -189,6 +318,53 @@ async function main() {
     for (const fileToRemove of filesRemoved) {
       rmSync(resolve(configRoot, fileToRemove), { force: true });
     }
+
+    if (configChanged) {
+      writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+    }
+
+    const activeAgents = (manifest.agents ?? []).filter((agent) =>
+      isActiveAgentForMode(agent, "opencode"),
+    );
+    const previousAgents = new Map(
+      (previousManifest?.agents ?? []).map((ownership) => [ownership.id, ownership]),
+    );
+    const installedAgents = activeAgents
+      .filter((agent) => deployMap.has(agent.destination))
+      .map((agent) => {
+        const previous = previousAgents.get(agent.id);
+        const currentConfig = configAgents?.[agent.id];
+        const configStillOwned =
+          previous?.configKey &&
+          previous?.configHash &&
+          currentConfig !== undefined &&
+          configOwnershipHash(currentConfig) === previous.configHash;
+        return {
+          id: agent.id,
+          promptDestination: agent.destination,
+          sourceHash: sha256(readFileSync(resolve(configRoot, agent.destination))),
+          ...(configStillOwned
+            ? { configKey: previous.configKey, configHash: previous.configHash }
+            : {}),
+        };
+      });
+    writeFileSync(
+      resolve(configRoot, ".arcs-bundle.json"),
+      `${JSON.stringify(
+        {
+          bundleId: manifest.bundleId,
+          installMode: manifest.installMode,
+          sourceBundleVersion: "deploy-script",
+          sourceBundleHash: sha256(readFileSync(manifestPath)),
+          installedAt: new Date().toISOString(),
+          ownedPaths: manifest.ownedPaths ?? [],
+          agents: installedAgents,
+        },
+        null,
+        2,
+      )}\n`,
+      "utf-8",
+    );
   }
 
   // After successful deploy, ensure arcs CLI is globally registered
@@ -227,7 +403,7 @@ async function main() {
     }),
   };
 
-  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 }
 
 try {

package/scripts/lib/bundle-helpers.mjs

@@ -1,6 +1,32 @@
 import { spawnSync } from "node:child_process";
 import { isAbsolute, relative, resolve } from "node:path";
 
+export function isActiveAgentForMode(agent, mode) {
+  return agent.status === "active" && agent.modes.includes(mode);
+}
+
+export function isRetiredAgentForMode(agent, mode) {
+  return agent.status === "retired" && agent.modes.includes(mode);
+}
+
+export function validateRetirementReplacements(agents) {
+  const byId = new Map(agents.map((agent) => [agent.id, agent]));
+  for (const agent of agents) {
+    if (agent.status !== "retired") continue;
+    const replacement = agent.replacementId ? byId.get(agent.replacementId) : undefined;
+    if (
+      !replacement ||
+      replacement.status !== "active" ||
+      replacement.kind !== agent.kind ||
+      agent.modes.some((mode) => !replacement.modes.includes(mode))
+    ) {
+      throw new Error(
+        `Retired agent ${agent.id} must name an active compatible replacement covering kind and modes`,
+      );
+    }
+  }
+}
+
 export function normalizeRelativePath(filePath) {
   return filePath.replace(/\\/g, "/");
 }

package/scripts/lint-bundle.mjs

@@ -21,7 +21,8 @@ const bundleRoot = process.env.BUNDLE_LINT_BUNDLE_ROOT
   ? resolve(repoRoot, process.env.BUNDLE_LINT_BUNDLE_ROOT)
   : defaultBundleRoot;
 
-/** @type {Array<{severity: 'error'|'warning', kind: string, message: string, file?: string, repair?: string}>} */const issues = [];
+/** @type {Array<{severity: 'error'|'warning', kind: string, message: string, file?: string, repair?: string}>} */ const issues =
+  [];
 
 function addIssue(severity, kind, message, file, repair) {
   const issue = { severity, kind, message };
@@ -55,6 +56,114 @@ if (!existsSync(sourceManifestPath)) {
 }
 const sourceManifest = JSON.parse(readFileSync(sourceManifestPath, "utf-8"));
 
+function isPromptPath(value) {
+  if (typeof value !== "string" || value.includes("\\")) return false;
+  const segments = value.split("/");
+  return (
+    segments.length >= 2 &&
+    segments[0] === "prompts" &&
+    segments.slice(1).every((segment) => segment !== "" && segment !== "." && segment !== "..") &&
+    segments.at(-1).endsWith(".txt")
+  );
+}
+
+function isAgentRegistryRecord(agent) {
+  return (
+    agent &&
+    typeof agent.id === "string" &&
+    /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(agent.id) &&
+    ["active", "retired"].includes(agent.status) &&
+    ["primary", "subagent"].includes(agent.kind) &&
+    ["heavy", "standard", "light"].includes(agent.tier) &&
+    Array.isArray(agent.modes) &&
+    agent.modes.length > 0 &&
+    agent.modes.every((mode) => ["opencode", "claudecode"].includes(mode)) &&
+    isPromptPath(agent.source) &&
+    isPromptPath(agent.destination) &&
+    typeof agent.description === "string" &&
+    agent.description.length > 0 &&
+    agent.permissions &&
+    ["edit", "bash", "webfetch", "mcp", "task"].every((permission) =>
+      ["allow", "deny"].includes(agent.permissions[permission]),
+    )
+  );
+}
+
+if (!Array.isArray(sourceManifest.agents)) {
+  addIssue(
+    "error",
+    "invalid-agent-registry",
+    `Source manifest agents must be an array`,
+    "manifest.json",
+  );
+}
+const registryAgents = Array.isArray(sourceManifest.agents) ? sourceManifest.agents : [];
+const registryIds = new Set();
+const registrySources = new Set();
+const registryDestinations = new Set();
+for (const agent of registryAgents) {
+  if (!isAgentRegistryRecord(agent)) {
+    addIssue(
+      "error",
+      "invalid-agent-registry",
+      `Source manifest contains an invalid agent registry record`,
+      "manifest.json",
+    );
+    continue;
+  }
+  if (registryIds.has(agent.id)) {
+    addIssue(
+      "error",
+      "invalid-agent-registry",
+      `Source manifest contains duplicate agent id ${agent.id}`,
+      "manifest.json",
+    );
+  }
+  registryIds.add(agent.id);
+  if (registrySources.has(agent.source)) {
+    addIssue(
+      "error",
+      "invalid-agent-registry",
+      `Source manifest contains duplicate agent source ${agent.source}`,
+      "manifest.json",
+    );
+  }
+  registrySources.add(agent.source);
+  if (registryDestinations.has(agent.destination)) {
+    addIssue(
+      "error",
+      "invalid-agent-registry",
+      `Source manifest contains duplicate agent destination ${agent.destination}`,
+      "manifest.json",
+    );
+  }
+  registryDestinations.add(agent.destination);
+
+  if (agent.status === "active" && agent.kind === "subagent" && agent.modes.includes("opencode")) {
+    const merge = sourceManifest.config?.requiredMerges?.find(
+      (entry) =>
+        entry.path?.length === 2 && entry.path[0] === "agent" && entry.path[1] === agent.id,
+    );
+    const value = merge?.value;
+    if (
+      !value ||
+      value.description !== agent.description ||
+      value.mode !== agent.kind ||
+      value.prompt !== `{file:./${agent.destination}}` ||
+      ["edit", "bash", "webfetch", "mcp"].some(
+        (permission) => value.permission?.[permission] !== agent.permissions[permission],
+      )
+    ) {
+      addIssue(
+        "error",
+        "agent-config-drift",
+        `OpenCode config for ${agent.id} does not match its registry record`,
+        "manifest.json",
+      );
+    }
+  }
+}
+
 // --- Check 1: Every manifest-declared bundled file exists ---
 const declaredFiles = new Set();
 
@@ -77,18 +186,29 @@ for (const [skillName, skillFiles] of Object.entries(manifest.skills ?? {})) {
 for (const agentFile of manifest.agents ?? []) {
   declaredFiles.add(agentFile);
   if (!existsSync(resolve(bundleRoot, agentFile))) {
-    addIssue("error", "missing-declared-file", `Manifest declares ${agentFile} but file is missing`, agentFile);
+    addIssue(
+      "error",
+      "missing-declared-file",
+      `Manifest declares ${agentFile} but file is missing`,
+      agentFile,
+    );
   }
 }
 
 for (const pluginFile of manifest.plugin ?? []) {
   declaredFiles.add(pluginFile);
   if (!existsSync(resolve(bundleRoot, pluginFile))) {
-    addIssue("error", "missing-declared-file", `Manifest declares ${pluginFile} but file is missing`, pluginFile);
+    addIssue(
+      "error",
+      "missing-declared-file",
+      `Manifest declares ${pluginFile} but file is missing`,
+      pluginFile,
+    );
   }
 }
 
 for (const agent of sourceManifest.agents ?? []) {
+  if (agent.status !== "active" || !isPromptPath(agent.source)) continue;
   declaredFiles.add(agent.source);
   if (!existsSync(resolve(bundleRoot, agent.source))) {
     addIssue(

package/skills/explore-dag.md

@@ -17,9 +17,9 @@ flowchart TD
 
     A[arcs project list → big picture] --> B{Question answered by DAG?}
     B -->|yes| C[Report from DAG data]
-    B -->|no| D[Dispatch graph-explorer sub-agent]:::sub
-    D --> E{Durable discovery?}
-    E -->|yes| F[arcs knowledge upsert]
+    B -->|no| D[Dispatch graph-explorer: codegraph then bounded source fallback]:::sub
+    D --> E{Durable discovery proposed?}
+    E -->|yes| F[Gate proposal before orchestrator persistence]
     E -->|no| C
     F --> C
 ```
@@ -49,6 +49,8 @@ Discovery: `arcs --commands --json`
 3. `arcs project get <slug> --json` per dependency for meta/docs
 4. Build dependency chain
 
+For repository questions, use DAG-first search (`arcs search`, `arcs related`, and indexed bodies). When DAG evidence is insufficient, `graph-explorer` uses codegraph if available, then bounded source fallback. Exploration remains read-only; durable findings are proposals until their owning phase passes.
+
 ## Tips
 
 - Start with `arcs project list` for the big picture

package/skills/init-project.md

@@ -15,18 +15,16 @@ User wants to track a new project, bootstrap documentation, or connect a repo to
 flowchart TD
     classDef sub fill:#8b5cf6,color:#fff
 
-    A[Gather: name, description, repoUrl?, dependsOn?] --> B[arcs project list → conflict check]
-    B --> C[Present summary to user]
-    C -->|confirmed| 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[codegraph MCP explore / impact for enrichment]:::sub
-    H & G3 --> I[Fan out: tech-architect + docs-researcher]:::sub
-    I --> J[Collect proposals → dedup → arcs knowledge create × N]
-    J --> K[Done]
+    A[Gather identity and exact requested artifacts] --> B[Read-only analyses, max four per round]:::sub
+    B --> C[Present exact project and docs artifact set]
+    C --> D[devil-advocate INIT gate]
+    D -->|PASS| E[Request current-turn exact authorization]
+    E -->|authorized| F[Orchestrator: arcs project init + approved docs]
+    F --> G{pending_enrichment?}
+    G -->|yes| H[Read-only enrichment proposals]:::sub
+    H --> I[Gate proposals, then orchestrator persists]
+    G -->|no| J[Validate and report]
+    I --> J
 ```
 
 ## CLI Primer
@@ -38,14 +36,17 @@ Discovery: `arcs --commands --json`
 
 ## Constraints
 
-- Do NOT read repo to infer name/description — gather from user
+- Gather project identity and requested artifact scope from the user; repository analysis supplies evidence, not authority
 - Verify `dependsOn` targets exist via `arcs project list --json`
 - Init creates empty plans/ and knowledge/ indexes
-- Repo analysis is **fan-out across typed agents**, not a generic "analysis sub-agent" (see Agent Dispatch table below)
+- Repo analysis is read-only fan-out across typed agents, with at most four disjoint analyses per round
+- No durable write occurs before the INIT gate passes and the user authorizes the exact artifact set in the current turn
+- Plans, tasks, and diagrams use the separate HITL design pipeline: `brainstorming` design approval, then `writing-plans` as sole author, gate, and exact-revision authorization
+- No automatic git actions; add, commit, and push require an explicit current-turn user request
 
 ## 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 land on the proposal-store ledger (`pending_enrichment: true`); agents enrich them into knowledge entries via the `enriching-codegraph-proposals` skill.
+`arcs project init` uses codegraph when available and degrades cleanly when it is absent. Ingestion creates structural **proposals**, not accepted knowledge. If init reports `pending_enrichment: true`, the orchestrator dispatches the read-only `enriching-codegraph-proposals` skill and persists only proposals that pass their owning gate.
 
 1. **Detect:** `detectCodegraph()` from `src/utils/codegraph.ts`. If unavailable, skip cleanly — never block INIT on codegraph.
 2. **Trust the gitignore guarantee:** `runIndex()` already auto-appends `.codegraph/` to `.gitignore` (`ensureGitignoreEntry`). Don't redundantly check or modify `.gitignore` from agents — running the index is sufficient.
@@ -58,14 +59,14 @@ The orchestrator runs codegraph directly during INIT to produce structural **pro
    - 8 god nodes (`kind=module`, ranked by callers+callees / impact)
    - 8 architecture clusters (`kind=architecture`, synthesized pseudo-communities by directory prefix)
    - 5 cross-module couplings (`kind=gotcha`, high-degree links across top-level dirs)
-5. **Enrich** with the `enriching-codegraph-proposals` skill — read `arcs proposal list <slug> --json`, decide per-proposal verdicts (keep / merge / drop), persist via `arcs proposal promote` and `arcs proposal drop`. Sub-agents may run read-only codegraph MCP queries for evidence (the MCP server auto-syncs via its own file watcher):
+5. **Enrich read-only** with the `enriching-codegraph-proposals` skill — read `arcs proposal list <slug> --json` and return exact keep / merge / drop proposed mutations. Sub-agents may run read-only codegraph MCP queries for evidence:
    - `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
-6. **Hand to typed agents:** the proposals + query results go to the sub-agents listed in **Agent Dispatch** below; they merge graph evidence with code reading and return finalized knowledge entries.
-7. **Write** the entries directly via `arcs batch --file=ops.json` (one batch invocation for all knowledge entries) or `arcs knowledge create` per entry.
+6. **Gate:** `devil-advocate` reviews the exact enrichment proposal.
+7. **Persist after PASS:** the orchestrator applies only the gated proposal operations. Workers never write knowledge directly.
 
 If codegraph is missing, log "codegraph not on PATH; proceeding without graph signal" and skip steps 3–5. Sub-agents still run; they just lack the graph priors.
 
@@ -82,23 +83,23 @@ If codegraph is missing, log "codegraph not on PATH; proceeding without graph si
 
 | Sub-agent | Owns | Knowledge kinds it produces |
 |-----------|------|----------------------------|
-| `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` (`AGENT_MODE: architecture`) | 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. Each agent receives the relevant `KnowledgeProposal` records from `ingestGraph` plus targeted codegraph MCP queries for evidence. Each agent returns finalized proposals (title, kind, summary, keywords, sourceFiles, body) for the orchestrator to write directly via `arcs knowledge create` (or `arcs batch`).
+Dispatch only disjoint read-only analyses in parallel, with a maximum of four agents per round. Each agent receives relevant graph evidence and returns proposals; persistence remains with the orchestrator after the owning gate passes.
 
 ## Knowledge Categories for Analysis Sub-Agents
 
 | Category | Kind | What to discover | Primary agent |
 |----------|------|------------------|---------------|
-| tech stack | `architecture` | Languages, frameworks, runtimes, build tools, versions | `docs-researcher` |
-| key files | `reference` | Entry points, config files, main modules, purposes | `docs-researcher` (codegraph_search "entry points") |
+| 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`; 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 | `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` |
+| 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`) |

package/skills/orchestrate.md

@@ -8,7 +8,7 @@ description: Classify intent and route work across all ARCS workflows
 
 ## When
 
-User request maps to multiple workflows, needs routing, or chains INIT → BRAINSTORM → EXECUTE.
+User request needs routing through INIT, DESIGN, EXECUTE, SYNC, EXPLORE, REVIEW, or MULTI.
 
 ## Flow
 
@@ -17,12 +17,13 @@ flowchart TD
     A[User Request] --> B[T0: arcs brief --lean --json]
     B --> C[Classify Intent]
     C -->|new project| INIT[INIT]
-    C -->|plan/decompose| BRAINSTORM[BRAINSTORM]
+    C -->|design/plan| DESIGN[DESIGN]
     C -->|do work| EXECUTE[EXECUTE]
     C -->|reconcile| SYNC[SYNC]
-    C -->|discover/report| EXPLORE[EXPLORE]
+    C -->|discover| EXPLORE[EXPLORE]
+    C -->|review/audit| REVIEW[REVIEW]
     C -->|compound| MULTI[MULTI]
-    INIT & BRAINSTORM & EXECUTE & SYNC & EXPLORE & MULTI --> DONE[Completion: what done + state + next steps]
+    INIT & DESIGN & EXECUTE & SYNC & EXPLORE & REVIEW & MULTI --> DONE[Completion gate and terminal state]
 ```
 
 ## Context Tiers
@@ -58,7 +59,7 @@ flowchart TD
 
 Use `recommendedSurface` to pick the routing branch:
 - `QUEUE` → execute the active task (EXECUTE workflow)
-- `PLAN`  → decompose or plan work (BRAINSTORM workflow)
+- `PLAN`  → design or plan work (DESIGN workflow)
 - `MEMORY` → no active work; review knowledge or propose a new plan
 
 ## CLI Primer
@@ -69,14 +70,29 @@ arcs <command> --json
 ```
 Discovery: `arcs --commands --json`
 
-## Skill Selection (EXECUTE)
+## Agent and Skill Routes
 
-| Task shape | Skill |
-|-----------|-------|
-| Fully bounded | `quick-dev` |
-| Mostly clear, 1-2 open questions | `code-agent` |
-| Non-trivial, test-first | `test-driven-development` |
-| Design open | reclassify → BRAINSTORM |
+| Agent | AGENT_MODE | Route |
+|-------|------------|-------|
+| `software-engineer` | `default` | Implementation with orchestrator-selected `WORK_MODE: bounded` or `inspect`; load `implementation` |
+| `software-engineer` | `incident` | Diagnosis-first work; add mandatory `systematic-debugging` |
+| `tech-architect` | `architecture` | Read-only design with `brainstorming`, then `writing-plans` only after design approval |
+| `tech-architect` | `research` | DAG-first cited research; use `writing-knowledge` for substantive proposals |
+| `graph-explorer` | `default` | DAG-first repository facts, dependencies, and bounded source questions |
+| `code-reviewer` | `review` / `audit` | Reactive diff/PR review or proactive scope/architecture audit |
+| `devil-advocate` | phase name | Mandatory phase and completion gates |
+| `arcs-docs` | `audit` / `apply` | Two-pass SYNC only |
+
+The twelve skills are `implementation`, `test-driven-development`, `executing-plans`, `systematic-debugging`, `brainstorming`, `writing-plans`, `to-diagram`, `writing-knowledge`, `init-project`, `enriching-codegraph-proposals`, `deep-pr-review`, and `caveman-commit`.
+
+`WORK_MODE: bounded` means no repository exploration or user questions. `WORK_MODE: inspect` permits limited inspection to resolve at most one material decision. Add `test-driven-development` for new behavior or bug fixes, and add `executing-plans` only for one approved plan node.
+
+## Workflow Contracts
+
+- **DESIGN:** `brainstorming` produces a read-only design. After the user approves it, `writing-plans` is the sole author of the complete exact plan, task, dependency, verification, and diagram draft. `devil-advocate` gates that draft before exact current-turn authorization and persistence.
+- **SYNC:** exactly two-pass — `arcs-docs` `audit` returns exact proposed mutations; `devil-advocate` gates them; only then may `arcs-docs` `apply` the approved mutations and validate the DAG.
+- **EXPLORE:** use DAG-first retrieval. If the DAG cannot answer, dispatch `graph-explorer` for codegraph or bounded source fallback.
+- **Git:** no automatic git actions. Run add, commit, or push only after an explicit current-turn user request naming the action.
 
 ## Loop Tools
 
@@ -90,7 +106,7 @@ Use these `arcs loop` session commands only when iterative execution is explicit
 
 - Sub-agents run ONLY the scoped VERIFY command from their dispatch (tests/lint on files they touched) — never the full suite.
 - The orchestrator never verifies: no tests, lint, builds, or `tsc`.
-- `devil-advocate` PHASE: completion is the session's single full-project pass (full suite + `tsc --noEmit`); on BLOCK, re-dispatch scoped fixes from its FAILURES attribution and re-gate. Two consecutive BLOCKs → stop, report.
+- `devil-advocate` PHASE: completion is the session's single full-project pass (`npm test`, `npm run typecheck`, and `npm run lint`); on BLOCK, re-dispatch scoped fixes from its FAILURES attribution and re-gate. Two consecutive BLOCKs → stop, report.
 
 ## Completion