@rryando/arcs 3.0.0

package/opencode/arcs/.opencode/plugins/arcs.js

@@ -0,0 +1,348 @@
+/**
+ * ARCS plugin for OpenCode.ai
+ *
+ * Injects ARCS bootstrap context via system prompt transform.
+ * Drives loop continuation via CLI delegation (no direct file I/O on DAG).
+ * Skills are discovered via OpenCode's native skill tool from symlinked directory.
+ */
+
+import path from "path";
+import fs from "fs";
+import os from "os";
+import { execFile } from "child_process";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Simple frontmatter extraction (avoid dependency on skills-core for bootstrap)
+const extractAndStripFrontmatter = (content) => {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, content };
+
+  const frontmatterStr = match[1];
+  const body = match[2];
+  const frontmatter = {};
+
+  for (const line of frontmatterStr.split("\n")) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx > 0) {
+      const key = line.slice(0, colonIdx).trim();
+      const value = line
+        .slice(colonIdx + 1)
+        .trim()
+        .replace(/^["']|["']$/g, "");
+      frontmatter[key] = value;
+    }
+  }
+
+  return { frontmatter, content: body };
+};
+
+// Normalize a path: trim whitespace, expand ~, resolve to absolute
+const normalizePath = (p, homeDir) => {
+  if (!p || typeof p !== "string") return null;
+  let normalized = p.trim();
+  if (!normalized) return null;
+  if (normalized.startsWith("~/")) {
+    normalized = path.join(homeDir, normalized.slice(2));
+  } else if (normalized === "~") {
+    normalized = homeDir;
+  }
+  return path.resolve(normalized);
+};
+
+// ---------------------------------------------------------------------------
+// CLI delegation — single writer pattern (no direct DAG file I/O)
+// ---------------------------------------------------------------------------
+
+const arcsExec = (args) =>
+  new Promise((resolve) => {
+    execFile("arcs", args, { timeout: 5000 }, (err, stdout) => {
+      if (err) return resolve(null);
+      try {
+        const result = JSON.parse(stdout);
+        return resolve(result?.ok ? result.data : null);
+      } catch {
+        return resolve(null);
+      }
+    });
+  });
+
+const loopStatus = () => arcsExec(["loop", "status", "--json"]);
+const loopTick = (slug, session) =>
+  arcsExec(["loop", "tick", slug, `--session=${session}`, "--json"]);
+const loopCancel = (slug, session) =>
+  arcsExec(["loop", "cancel", slug, `--session=${session}`, "--json"]);
+
+// ---------------------------------------------------------------------------
+// Continuation prompt builder
+// ---------------------------------------------------------------------------
+
+const buildContinuationPrompt = (state) => {
+  const maxLabel =
+    typeof state.maxIterations === "number" ? String(state.maxIterations) : "unbounded";
+
+  if (state.strategy === "reset") {
+    return `[SYSTEM DIRECTIVE - ARCS LOOP ITERATION ${state.iteration}/${maxLabel}]
+
+Start fresh on the following task. Previous attempts did not complete successfully.
+
+IMPORTANT:
+- Do NOT rely on previous context or partial work
+- Approach the task from scratch with a clean perspective
+- When FULLY complete, output: <promise>${state.completionPromise}</promise>
+- Do not stop until the task is truly done
+
+Task:
+${state.prompt}`;
+  }
+
+  return `[SYSTEM DIRECTIVE - ARCS LOOP ITERATION ${state.iteration}/${maxLabel}]
+
+Your previous attempt did not output the completion promise. Continue working on the task.
+
+IMPORTANT:
+- Review your progress so far
+- Continue from where you left off
+- When FULLY complete, output: <promise>${state.completionPromise}</promise>
+- Do not stop until the task is truly done
+
+Original task:
+${state.prompt}`;
+};
+
+// ---------------------------------------------------------------------------
+// Plugin entry
+// ---------------------------------------------------------------------------
+
+export const ArcsPlugin = async ({ client, directory }) => {
+  const inFlightSessions = new Set();
+  const homeDir = os.homedir();
+  const arcsSkillsDir = path.resolve(__dirname, "../skills/arcs");
+  const envConfigDir = normalizePath(process.env.OPENCODE_CONFIG_DIR, homeDir);
+  const configDir = envConfigDir || path.join(homeDir, ".config/opencode");
+
+  // Cache bootstrap content at plugin load (file doesn't change during session)
+  const cachedBootstrap = (() => {
+    const skillPath = path.join(arcsSkillsDir, "using-superpowers", "SKILL.md");
+    if (!fs.existsSync(skillPath)) return null;
+
+    const fullContent = fs.readFileSync(skillPath, "utf8");
+    const { content } = extractAndStripFrontmatter(fullContent);
+
+    const toolMapping = `**Tool Mapping for OpenCode:**
+When skills reference tools you don't have, substitute OpenCode equivalents:
+- \`TodoWrite\` → \`todowrite\`
+- \`Task\` tool with subagents → Use OpenCode's subagent system (@mention)
+- \`Skill\` tool → OpenCode's native \`skill\` tool
+- \`Read\`, \`Write\`, \`Edit\`, \`Bash\` → Your native tools
+
+**Skills location:**
+ARCS skills are in \`${configDir}/skills/arcs/\`
+Use OpenCode's native \`skill\` tool to list and load skills.`;
+
+    return `<EXTREMELY_IMPORTANT>
+You have ARCS skills loaded.
+
+**IMPORTANT: The using-superpowers skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the skill tool to load "using-superpowers" again - that would be redundant.**
+
+${content}
+
+${toolMapping}
+</EXTREMELY_IMPORTANT>`;
+  })();
+
+  // Cache T0 brief at plugin load — gives every session the operating context
+  // without requiring agents to run `arcs brief` manually.
+  // NOTE: Stale after long sessions (hours). Agents can call `arcs brief --lean --json`
+  // for fresh data when needed. Stale T0 > no T0 for session start orientation.
+  const cachedBrief = await (async () => {
+    const data = await arcsExec(["brief", "--lean", "--json"]);
+    if (!data) return null;
+    return `<arcs_context>\n${JSON.stringify(data, null, 2)}\n</arcs_context>`;
+  })();
+
+  return {
+    // Use system prompt transform to inject bootstrap (fixes #226 agent reset bug)
+    "experimental.chat.system.transform": async (_input, output) => {
+      if (cachedBootstrap) {
+        (output.system ||= []).push(cachedBootstrap);
+      }
+
+      // Inject T0 operating context so agents start with current focus + next action
+      if (cachedBrief) {
+        (output.system ||= []).push(cachedBrief);
+      }
+
+      // Inject the workspace directory so ARCS and other agents always know
+      // which project directory OpenCode was opened in. This is the reliable
+      // source of truth — process.cwd() of MCP servers may differ.
+      if (directory) {
+        (output.system ||= []).push(`<env>\n  Working directory: ${directory}\n</env>`);
+      }
+    },
+
+    event: async ({ event, client }) => {
+      const props = event.properties;
+
+      if (event.type === "session.idle") {
+        const sessionID = props?.sessionID;
+        if (!sessionID) return;
+        if (inFlightSessions.has(sessionID)) return;
+
+        inFlightSessions.add(sessionID);
+        try {
+          const status = await loopStatus();
+          if (!status?.state?.active) return;
+
+          const { state } = status;
+          const slug = status.slug;
+
+          // Only handle the loop's session
+          if (state.sessionId && state.sessionId !== sessionID) return;
+
+          // Detect completion in session messages
+          let completionDetected = false;
+          try {
+            const response = await client.session.messages({
+              path: { id: sessionID },
+              query: { directory },
+            });
+
+            const messages = Array.isArray(response)
+              ? response
+              : response?.data && Array.isArray(response.data)
+                ? response.data
+                : [];
+
+            const scopedMessages =
+              typeof state.messageCountAtStart === "number"
+                ? messages.slice(state.messageCountAtStart)
+                : messages;
+
+            const assistantMsgs = scopedMessages.filter((m) => m.info?.role === "assistant");
+            const pattern = new RegExp(
+              `<promise>\\s*${state.completionPromise.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*</promise>`,
+              "is",
+            );
+
+            for (let i = assistantMsgs.length - 1; i >= 0; i--) {
+              const parts = assistantMsgs[i].parts || [];
+              for (const part of parts) {
+                if (part.type === "text" && part.text && pattern.test(part.text)) {
+                  completionDetected = true;
+                  break;
+                }
+              }
+              if (completionDetected) break;
+            }
+          } catch {}
+
+          if (completionDetected) {
+            await loopCancel(slug, sessionID);
+            await client.tui
+              ?.showToast?.({
+                body: {
+                  title: "ARCS Loop Complete!",
+                  message: `Task completed after ${state.iteration} iteration(s)`,
+                  variant: "success",
+                  duration: 5000,
+                },
+              })
+              .catch(() => {});
+            return;
+          }
+
+          // Tick — CLI handles max-iteration check and state mutation atomically
+          const tickResult = await loopTick(slug, sessionID);
+          if (!tickResult) return; // CLI unreachable or session mismatch
+
+          if (tickResult.maxReached) {
+            await client.tui
+              ?.showToast?.({
+                body: {
+                  title: "ARCS Loop Stopped",
+                  message: `Max iterations (${state.maxIterations}) reached without completion`,
+                  variant: "warning",
+                  duration: 5000,
+                },
+              })
+              .catch(() => {});
+            return;
+          }
+
+          const updatedState = tickResult.state;
+
+          // Show toast
+          await client.tui
+            ?.showToast?.({
+              body: {
+                title: "ARCS Loop",
+                message: `Iteration ${updatedState.iteration}/${typeof updatedState.maxIterations === "number" ? updatedState.maxIterations : "unbounded"}`,
+                variant: "info",
+                duration: 2000,
+              },
+            })
+            .catch(() => {});
+
+          // Inject continuation prompt
+          const continuationPrompt = buildContinuationPrompt(updatedState);
+
+          // Inherit agent/model from last message
+          let agent, model, tools;
+          try {
+            const msgs = await client.session.messages({ path: { id: sessionID } });
+            const messageList = Array.isArray(msgs) ? msgs : msgs?.data || [];
+            for (let i = messageList.length - 1; i >= 0; i--) {
+              const info = messageList[i]?.info;
+              if (info?.agent || info?.model || (info?.modelID && info?.providerID)) {
+                agent = info.agent;
+                model =
+                  info.model ??
+                  (info.providerID && info.modelID
+                    ? { providerID: info.providerID, modelID: info.modelID }
+                    : undefined);
+                tools = info.tools;
+                break;
+              }
+            }
+          } catch {}
+
+          await client.session.promptAsync({
+            path: { id: sessionID },
+            body: {
+              ...(agent !== undefined ? { agent } : {}),
+              ...(model ? { model: { providerID: model.providerID, modelID: model.modelID } } : {}),
+              ...(model?.variant ? { variant: model.variant } : {}),
+              ...(tools ? { tools } : {}),
+              parts: [{ type: "text", text: continuationPrompt }],
+            },
+            query: { directory },
+          });
+        } finally {
+          inFlightSessions.delete(sessionID);
+        }
+      }
+
+      // Handle session deletion — clear loop if it's the loop session
+      if (event.type === "session.deleted") {
+        const sessionID = props?.sessionID;
+        if (!sessionID) return;
+        const status = await loopStatus();
+        if (status?.state?.active && status.state.sessionId === sessionID) {
+          await loopCancel(status.slug, sessionID);
+        }
+      }
+
+      // Handle session error — clear loop
+      if (event.type === "session.error") {
+        const sessionID = props?.sessionID;
+        if (!sessionID) return;
+        const status = await loopStatus();
+        if (status?.state?.active && status.state.sessionId === sessionID) {
+          await loopCancel(status.slug, sessionID);
+        }
+      }
+    },
+  };
+};

package/opencode/arcs/bundle-runtime.json

@@ -0,0 +1,68 @@
+{
+  "skills": {
+    "brainstorming": [
+      "SKILL.md",
+      "spec-document-reviewer-prompt.md",
+      "visual-companion.md",
+      "scripts/frame-template.html",
+      "scripts/helper.js",
+      "scripts/server.js",
+      "scripts/start-server.sh",
+      "scripts/stop-server.sh"
+    ],
+    "code-agent": [
+      "SKILL.md"
+    ],
+    "deep-pr-review": [
+      "SKILL.md",
+      "review-template.md",
+      "graphify-diff.md"
+    ],
+    "executing-plans": [
+      "SKILL.md"
+    ],
+    "quick-dev": [
+      "SKILL.md"
+    ],
+    "requesting-code-review": [
+      "SKILL.md",
+      "code-reviewer.md"
+    ],
+    "subagent-driven-development": [
+      "SKILL.md",
+      "code-quality-reviewer-prompt.md",
+      "implementer-prompt.md",
+      "spec-reviewer-prompt.md"
+    ],
+    "systematic-debugging": [
+      "SKILL.md",
+      "condition-based-waiting.md",
+      "condition-based-waiting-example.ts",
+      "defense-in-depth.md",
+      "find-polluter.sh",
+      "phases-reference.md",
+      "root-cause-tracing.md"
+    ],
+    "test-driven-development": [
+      "SKILL.md",
+      "tdd-rationalizations-and-examples.md",
+      "testing-anti-patterns.md"
+    ],
+    "to-diagram": [
+      "SKILL.md",
+      "scripts/manage-diagram.mjs"
+    ],
+    "writing-plans": [
+      "SKILL.md",
+      "plan-document-reviewer-prompt.md"
+    ]
+  },
+  "agents": [],
+  "plugin": [],
+  "excludePatterns": [
+    "**/references/**",
+    "**/examples/**",
+    "**/CREATION-LOG.md",
+    "**/test-pressure-*.md"
+  ]
+}

package/opencode/arcs/manifest.json

@@ -0,0 +1,279 @@
+{
+  "bundleId": "arcs-opencode-bundle",
+  "installMode": "opencode-arcs",
+  "bundleVersionSource": "package.json",
+  "sourceRoot": "opencode/arcs",
+  "skills": {
+    "source": "skills",
+    "destination": "skills/arcs"
+  },
+  "agents": [
+    { "source": "prompts/software-engineer.txt", "destination": "prompts/software-engineer.txt" },
+    { "source": "prompts/tech-architect.txt", "destination": "prompts/tech-architect.txt" },
+    { "source": "prompts/qa-analyst.txt", "destination": "prompts/qa-analyst.txt" },
+    { "source": "prompts/oncall-ops.txt", "destination": "prompts/oncall-ops.txt" },
+    { "source": "prompts/arcs-docs.txt", "destination": "prompts/arcs-docs.txt" },
+    { "source": "prompts/system-architect.txt", "destination": "prompts/system-architect.txt" },
+    { "source": "prompts/code-reviewer.txt", "destination": "prompts/code-reviewer.txt" },
+    { "source": "prompts/docs-researcher.txt", "destination": "prompts/docs-researcher.txt" },
+    { "source": "prompts/devil-advocate.txt", "destination": "prompts/devil-advocate.txt" }
+  ],
+  "ownedPaths": [
+    "skills/arcs",
+    "plugins/arcs.js"
+  ],
+  "plugin": {
+    "required": true,
+    "source": ".opencode/plugins/arcs.js",
+    "destination": "plugins/arcs.js"
+  },
+  "config": {
+    "requiredMerges": [
+      {
+        "path": [
+          "permission"
+        ],
+        "value": {
+          "external_directory": {
+            "/tmp": "allow",
+            "~/.arcs": "allow",
+            "~/.config/opencode": "allow"
+          }
+        }
+      },
+      {
+        "path": [
+          "model"
+        ],
+        "value": "github-copilot/claude-sonnet-4.6"
+      },
+      {
+        "path": [
+          "agent",
+          "build",
+          "model"
+        ],
+        "value": "github-copilot/claude-sonnet-4.6"
+      },
+      {
+        "path": [
+          "agent",
+          "plan",
+          "model"
+        ],
+        "value": "github-copilot/claude-opus-4.6"
+      },
+      {
+        "path": [
+          "agent",
+          "general",
+          "model"
+        ],
+        "value": "github-copilot/claude-opus-4.6"
+      },
+      {
+        "path": [
+          "agent",
+          "explore",
+          "model"
+        ],
+        "value": "github-copilot/claude-haiku-4.5"
+      },
+      {
+        "path": [
+          "agent",
+          "code-reviewer"
+        ],
+        "value": {
+          "description": "Reviews code changes for production readiness and catches correctness, maintainability, and testing issues.",
+          "mode": "subagent",
+          "model": "github-copilot/claude-haiku-4.5",
+          "prompt": "{file:./prompts/code-reviewer.txt}",
+          "permission": {
+            "edit": "deny",
+            "bash": "allow",
+            "webfetch": "deny"
+          }
+        }
+      },
+      {
+        "path": [
+          "agent",
+          "docs-researcher"
+        ],
+        "value": {
+          "description": "Handles documentation writing, research synthesis, OCR-adjacent extraction, and document-heavy analysis tasks.",
+          "mode": "subagent",
+          "model": "github-copilot/claude-opus-4.6",
+          "permission": {
+            "edit": "ask",
+            "bash": "ask",
+            "webfetch": "allow",
+            "external_directory": {
+              "/tmp": "allow",
+              "~/.arcs": "allow"
+            }
+          },
+          "prompt": "{file:./prompts/docs-researcher.txt}"
+        }
+      },
+      {
+        "path": [
+          "agent",
+          "tech-architect"
+        ],
+        "value": {
+          "description": "Architecture and analysis specialist. Deep structural reasoning, refactor guidance, trade-off evaluation, and root cause analysis without making hasty edits.",
+          "mode": "subagent",
+          "model": "github-copilot/claude-haiku-4.5",
+          "permission": {
+            "edit": "ask",
+            "bash": "ask",
+            "webfetch": "deny",
+            "external_directory": {
+              "~/.arcs": "allow"
+            }
+          },
+          "prompt": "{file:./prompts/tech-architect.txt}"
+        }
+      },
+      {
+        "path": [
+          "agent",
+          "software-engineer"
+        ],
+        "value": {
+          "description": "Implementation specialist. Writes code, runs tests, ships features. Loads quick-dev, code-agent, test-driven-development, executing-plans, finishing-a-development-branch, and aesthetic skills as needed.",
+          "mode": "subagent",
+          "model": "github-copilot/claude-opus-4.6",
+          "permission": {
+            "edit": "allow",
+            "bash": "allow",
+            "webfetch": "deny",
+            "mcp": "allow",
+            "external_directory": {
+              "/tmp": "allow",
+              "~/.arcs": "allow"
+            }
+          },
+          "prompt": "{file:./prompts/software-engineer.txt}"
+        }
+      },
+      {
+        "path": [
+          "agent",
+          "arcs-docs"
+        ],
+        "value": {
+          "description": "ARCS documentation specialist. Manages plans, knowledge entries, diagrams, and DAG health. Knows ARCS structure intimately.",
+          "mode": "subagent",
+          "model": "github-copilot/claude-opus-4.6",
+          "permission": {
+            "edit": "allow",
+            "bash": "allow",
+            "webfetch": "deny",
+            "mcp": "allow",
+            "external_directory": {
+              "/tmp": "allow",
+              "~/.arcs": "allow",
+              "~/.config/opencode": "allow"
+            }
+          },
+          "prompt": "{file:./prompts/arcs-docs.txt}"
+        }
+      },
+      {
+        "path": [
+          "agent",
+          "qa-analyst"
+        ],
+        "value": {
+          "description": "Quality enforcement specialist. Proactive code audits, review dispatch, convention compliance.",
+          "mode": "subagent",
+          "model": "github-copilot/claude-haiku-4.5",
+          "permission": {
+            "edit": "deny",
+            "bash": "allow",
+            "webfetch": "deny",
+            "mcp": "allow",
+            "external_directory": {
+              "~/.arcs": "allow"
+            }
+          },
+          "prompt": "{file:./prompts/qa-analyst.txt}"
+        }
+      },
+      {
+        "path": [
+          "agent",
+          "devil-advocate"
+        ],
+        "value": {
+          "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.",
+          "mode": "subagent",
+          "model": "github-copilot/claude-sonnet-4.6",
+          "permission": {
+            "edit": "deny",
+            "bash": "allow",
+            "webfetch": "deny",
+            "mcp": "allow",
+            "external_directory": {
+              "/tmp": "allow",
+              "~/.arcs": "allow"
+            }
+          },
+          "prompt": "{file:./prompts/devil-advocate.txt}"
+        }
+      },
+      {
+        "path": [
+          "agent",
+          "oncall-ops"
+        ],
+        "value": {
+          "description": "Debugging and diagnosis specialist. Finds root causes through systematic investigation, log triage, bisect, and performance profiling.",
+          "mode": "subagent",
+          "model": "github-copilot/claude-opus-4.6",
+          "permission": {
+            "edit": "ask",
+            "bash": "allow",
+            "webfetch": "deny",
+            "mcp": "allow",
+            "external_directory": {
+              "/tmp": "allow",
+              "~/.arcs": "allow"
+            }
+          },
+          "prompt": "{file:./prompts/oncall-ops.txt}"
+        }
+      },
+      {
+        "path": [
+          "agent",
+          "system-architect"
+        ],
+        "value": {
+          "description": "Architecture and design specialist. Module boundaries, dependency graphs, migration strategies, and cross-project design decisions.",
+          "mode": "subagent",
+          "model": "github-copilot/claude-opus-4.6",
+          "permission": {
+            "edit": "deny",
+            "bash": "allow",
+            "webfetch": "allow",
+            "mcp": "allow",
+            "external_directory": {
+              "~/.arcs": "allow"
+            }
+          },
+          "prompt": "{file:./prompts/system-architect.txt}"
+        }
+      },
+      {
+        "path": [
+          "small_model"
+        ],
+        "value": "github-copilot/claude-haiku-4.5"
+      }
+    ]
+  }
+}