@rryando/arcs 3.4.0 → 3.4.2

package/scripts/deploy-claudecode-bundle.mjs

@@ -32,7 +32,7 @@ import {
 import { homedir } from "node:os";
 import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { wireCodegraphMcp } from "./lib/bundle-helpers.mjs";
+import { wireCodegraphMcp, wireRtk } from "./lib/bundle-helpers.mjs";
 
 const scriptDir = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(scriptDir, "..");
@@ -88,71 +88,84 @@ const agentTierMap = {
   "arcs-docs": "heavy",
   "oncall-ops": "heavy",
   "system-architect": "heavy",
-  general: "heavy",
   "arcs-orchestrate": "standard",
   "arcs-orchestrate-caveman": "standard",
   "devil-advocate": "standard",
+  "graph-explorer": "light",
   "code-reviewer": "light",
   "tech-architect": "light",
   "qa-analyst": "light",
 };
 
+// Agent descriptions mirror opencode/arcs/manifest.json (canonical) — keep in sync.
 const agentMetadata = {
   "software-engineer": {
     name: "Software Engineer",
-    description: "Implementation specialist. Writes code, runs tests, and ships features.",
+    description:
+      "Implementation specialist. Writes code, runs tests, ships features. Loads quick-dev, code-agent, test-driven-development, and executing-plans skills as needed.",
     tools: "Read, Write, Edit, Glob, Grep, Bash",
     model: "inherit",
   },
   "devil-advocate": {
     name: "Devil's Advocate",
-    description: "Adversarial phase-gate agent. Checks work using KISS/YAGNI/DRY principles.",
+    description:
+      "Adversarial phase-gate agent. Checks work at phase boundaries using KISS/YAGNI/DRY principles. Runs tests, reads diffs, delivers pass/block verdicts. Cannot edit code.",
+    tools: "Read, Glob, Grep, Bash",
+    model: "inherit",
+  },
+  "graph-explorer": {
+    name: "Graph Explorer",
+    description:
+      "DAG-first codebase and knowledge exploration specialist. Queries arcs search, related, and context first, then codegraph MCP code-intelligence tools, before falling back to raw file-system tools. Replaces vanilla explore for ARCS projects.",
     tools: "Read, Glob, Grep, Bash",
     model: "inherit",
   },
   "tech-architect": {
     name: "Technical Architect",
     description:
-      "Architecture and analysis specialist. Deep structural reasoning and trade-off evaluation.",
+      "Architecture and analysis specialist. Deep structural reasoning, refactor guidance, trade-off evaluation, and root cause analysis without making hasty edits.",
     tools: "Read, Glob, Grep, Bash",
     model: "inherit",
   },
   "code-reviewer": {
     name: "Code Reviewer",
-    description: "Reviews code changes for correctness, maintainability, and testing issues.",
+    description:
+      "Reviews code changes for production readiness and catches correctness, maintainability, and testing issues.",
     tools: "Read, Glob, Grep, Bash",
     model: "inherit",
   },
   "qa-analyst": {
     name: "QA Analyst",
-    description: "Quality enforcement specialist. Proactive code audits and convention compliance.",
+    description:
+      "Quality enforcement specialist. Proactive code audits, review dispatch, convention compliance.",
     tools: "Read, Glob, Grep, Bash",
     model: "inherit",
   },
   "system-architect": {
     name: "System Architect",
     description:
-      "Architecture and design specialist. Module boundaries, dependency graphs, and design decisions.",
+      "Architecture and design specialist. Module boundaries, dependency graphs, migration strategies, and cross-project design decisions.",
     tools: "Read, Glob, Grep, Bash",
     model: "inherit",
   },
   "arcs-docs": {
     name: "ARCS Docs Specialist",
     description:
-      "Documentation specialist. Manages plans, knowledge entries, diagrams, and DAG health.",
+      "ARCS documentation specialist. Manages plans, knowledge entries, diagrams, and DAG health. Knows ARCS structure intimately.",
     tools: "Read, Write, Edit, Glob, Grep, Bash",
     model: "inherit",
   },
   "docs-researcher": {
     name: "Docs Researcher",
-    description: "Handles documentation writing, research synthesis, and document-heavy analysis.",
+    description:
+      "Handles documentation writing, research synthesis, OCR-adjacent extraction, and document-heavy analysis tasks.",
     tools: "Read, Write, Edit, Glob, Grep, Bash",
     model: "inherit",
   },
   "oncall-ops": {
     name: "On-Call Ops",
     description:
-      "Debugging and diagnosis specialist. Finds root causes through systematic investigation.",
+      "Debugging and diagnosis specialist. Finds root causes through systematic investigation, log triage, bisect, and performance profiling.",
     tools: "Read, Write, Edit, Glob, Grep, Bash",
     model: "inherit",
   },
@@ -224,15 +237,23 @@ function buildAgentSources() {
     const tier = agentTierMap[stem] || "standard";
     const model = tierModels[tier];
 
-    const toolsArray = meta.tools.split(",").map((t) => t.trim());
-    const toolsYaml = `[${toolsArray.map((t) => `"${t}"`).join(", ")}]`;
+    // Claude Code requires `name` to be a kebab-case identifier (lowercase
+    // letters + hyphens). The filename stem already satisfies this and is
+    // unique, so it IS the agent name — the human-readable label lives in
+    // `description`. The default-agent setting (DEFAULT_AGENT) references this
+    // same stem, so it resolves. Display names with spaces/parens/apostrophes
+    // (meta.name) are invalid here and caused intermittent init failures.
+    const toolsCsv = meta.tools
+      .split(",")
+      .map((t) => t.trim())
+      .join(", ");
 
     const compiledContent = [
       "---",
-      `name: ${meta.name}`,
+      `name: ${stem}`,
       `description: ${meta.description}`,
       `model: ${model}`,
-      `tools: ${toolsYaml}`,
+      `tools: ${toolsCsv}`,
       "---",
       "",
       promptContent,
@@ -428,6 +449,11 @@ function main() {
   // Best-effort: wire the codegraph MCP server. Skipped on dry-run; never fatal.
   const codegraphWired = dryRun ? false : wireCodegraphMcp("claude");
 
+  // Best-effort: wire RTK instructions + hook. `rtk init -g` only writes the
+  // user-global config, so project-scoped deploys skip it. Skipped on dry-run;
+  // never fatal.
+  const rtkWired = dryRun || scope === "project" ? false : wireRtk("claude");
+
   const result = {
     dryRun,
     source: bundleRoot,
@@ -438,6 +464,7 @@ function main() {
     filesRemoved,
     filesUnchanged,
     codegraphWired,
+    rtkWired,
   };
 
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/scripts/deploy-opencode-bundle.mjs

@@ -24,7 +24,7 @@ import {
 import { homedir } from "node:os";
 import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { wireCodegraphMcp } from "./lib/bundle-helpers.mjs";
+import { wireCodegraphMcp, wireRtk } from "./lib/bundle-helpers.mjs";
 
 const scriptDir = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(scriptDir, "..");
@@ -182,6 +182,9 @@ async function main() {
   // Best-effort: wire the codegraph MCP server. Skipped on dry-run; never fatal.
   const codegraphWired = dryRun ? false : wireCodegraphMcp("opencode");
 
+  // Best-effort: wire RTK instructions + hook. Skipped on dry-run; never fatal.
+  const rtkWired = dryRun ? false : wireRtk("opencode");
+
   const result = {
     dryRun,
     source: bundleRoot,
@@ -193,6 +196,7 @@ async function main() {
     restartRequired,
     cliRegistered: !dryRun,
     codegraphWired,
+    rtkWired,
     ...(restartRequired && {
       restartGuidance: "Plugin file changed. Restart opencode for changes to take effect.",
     }),

package/scripts/lib/bundle-helpers.mjs

@@ -174,7 +174,10 @@ export function validateDeclaredPath(relativePath, outputRoot, validationRoot) {
 
 export function wireCodegraphMcp(target) {
   // Best-effort: wire the codegraph MCP server for this host. Non-fatal.
-  // Skipped silently if the codegraph binary is absent.
+  // Skipped silently if the codegraph binary is absent, or when
+  // ARCS_SKIP_CODEGRAPH=1 (set by the test suite so deploy-script runs never
+  // mutate the developer's real host config).
+  if (process.env.ARCS_SKIP_CODEGRAPH === "1") return false;
   try {
     const r = spawnSync("codegraph", ["install", `--target=${target}`, "--yes"], {
       encoding: "utf-8",
@@ -187,3 +190,26 @@ export function wireCodegraphMcp(target) {
     return false;
   }
 }
+
+export function wireRtk(target) {
+  // Best-effort: wire RTK (token-optimized command proxy) for this host.
+  // `rtk init -g` always covers Claude Code; `--opencode` additionally
+  // installs the OpenCode plugin. Non-fatal. Skipped silently if the rtk
+  // binary is absent, or when ARCS_SKIP_RTK=1 (set by the test suite so
+  // deploy-script runs never mutate the developer's real host config).
+  if (process.env.ARCS_SKIP_RTK === "1") return false;
+  try {
+    const args = ["init", "-g"];
+    if (target === "opencode") args.push("--opencode");
+    args.push("--auto-patch");
+    const r = spawnSync("rtk", args, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 120_000,
+    });
+    if (r.error || r.status !== 0) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}

package/scripts/lint-bundle.mjs

@@ -28,7 +28,6 @@ const preservedFiles = new Set([
   ".opencode/plugins/arcs.js",
   "skills/loop/SKILL.md",
   "skills/caveman-commit/SKILL.md",
-  "skills/caveman-review/SKILL.md",
   "skills/init-project/SKILL.md",
   // Sub-agent prompt files (repo-authored, referenced from manifest.json
   // requiredMerges, not from bundle-runtime.json's `agents` array).

package/skills/init-project.md

@@ -87,7 +87,7 @@ If codegraph is missing, log "codegraph not on PATH; proceeding without graph si
 | `tech-architect` | Cross-module couplings, structural gotchas, lessons | `gotcha`, `lesson` |
 | `qa-analyst` (optional) | Coding-style + convention scan from existing code | `pattern` |
 
-Dispatch in parallel (load `dispatching-parallel-agents`). 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 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`).
 
 ## Knowledge Categories for Analysis Sub-Agents
 

package/skills/orchestrate.md

@@ -86,9 +86,16 @@ Discovery: `arcs --commands --json`
 
 Pair with `loop` skill for iteration discipline.
 
+## Verification Contract
+
+- 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.
+
 ## Completion
 
 Every session ends with:
-1. What was done
-2. Current project state
-3. Suggested next steps
+1. Gate — if any agent reported FILES_TOUCHED ≠ none, dispatch `devil-advocate` PHASE: completion (the only full-project verification); BLOCK → fix loop; never claim done before PASS. Zero-file-change sessions skip the gate.
+2. What was done
+3. Current project state
+4. Suggested next steps