opencode-multiagent 0.2.0

package/skills/verification-gates/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: verification-gates
+description: Creates explicit validation checkpoints (verification gates) between project phases to catch errors early and ensure quality before proceeding. Use when the user asks about quality gates, milestone checks, phase transitions, approval steps, go/no-go decision points, or preventing cascading errors across a multi-step workflow. Produces acceptance criteria checklists, automated CI gate configurations, manual sign-off requirements, and conditional review rules for scenarios such as security changes, API changes, or database migrations.
+version: 1.0.0
+triggers:
+  - verify before
+  - checkpoint
+  - quality gate
+  - make sure before
+  - validation
+tags:
+  - planning
+  - verification
+  - quality
+  - gates
+difficulty: beginner
+estimatedTime: 10
+relatedSkills:
+  - planning/design-first
+  - planning/task-decomposition
+  - testing/red-green-refactor
+---
+
+# Verification Gates
+
+You are implementing verification gates - explicit checkpoints where work is validated before proceeding. This prevents cascading errors and ensures quality at each phase.
+
+## Core Principle
+
+**Never proceed to the next phase with unverified assumptions from the previous phase.**
+
+A verification gate is a deliberate pause to confirm that prerequisites are met before continuing.
+
+## Standard Verification Gates
+
+### Gate 1: Requirements Verification
+
+Before starting design:
+
+- [ ] All requirements are documented and clear
+- [ ] Ambiguities have been resolved with stakeholders
+- [ ] Non-requirements are explicitly stated
+- [ ] Acceptance criteria are defined
+- [ ] Edge cases are identified
+
+**Actions:**
+1. Review requirements document
+2. Identify any unclear items
+3. Get explicit confirmation on ambiguous points
+4. Document answers
+
+### Gate 2: Design Verification
+
+Before starting implementation:
+
+- [ ] Design addresses all requirements
+- [ ] Technical approach is validated
+- [ ] Interfaces are defined
+- [ ] Data model is complete
+- [ ] Error handling is planned
+- [ ] Design has been reviewed (self or peer)
+
+**Actions:**
+1. Walk through design against requirements
+2. Review with rubber duck or teammate
+3. Check for missing pieces
+4. Get approval to proceed
+
+### Gate 3: Implementation Verification
+
+Before calling task complete:
+
+- [ ] Code compiles/runs without errors
+- [ ] All tests pass
+- [ ] New code has test coverage
+- [ ] Code follows project conventions
+- [ ] No obvious bugs or issues
+- [ ] Dependencies are appropriate
+
+**Actions:**
+1. Run full test suite
+2. Self-review the diff
+3. Check for code smells
+4. Verify against acceptance criteria
+
+### Gate 4: Integration Verification
+
+Before merging:
+
+- [ ] Feature works end-to-end
+- [ ] Integration tests pass
+- [ ] No regression in existing functionality
+- [ ] Performance is acceptable
+- [ ] Documentation is updated
+
+**Actions:**
+1. Test the full user flow
+2. Run integration test suite
+3. Compare performance metrics
+4. Review documentation changes
+
+### Gate 5: Deployment Verification
+
+Before marking complete:
+
+- [ ] Feature works in target environment
+- [ ] Monitoring shows no errors
+- [ ] Feature flags are properly configured
+- [ ] Rollback plan exists
+- [ ] Stakeholders can verify
+
+**Actions:**
+1. Smoke test in environment
+2. Check error logs and metrics
+3. Get stakeholder sign-off
+4. Document deployment
+
+## Gate Types
+
+### Automated Gates
+
+Gates that can be enforced automatically:
+
+```yaml
+# CI Pipeline Gates
+gates:
+  - name: lint
+    command: npm run lint
+    required: true
+
+  - name: type-check
+    command: npm run typecheck
+    required: true
+
+  - name: unit-tests
+    command: npm run test
+    required: true
+    coverage: 80%
+
+  - name: build
+    command: npm run build
+    required: true
+```
+
+### Manual Gates
+
+Gates requiring human judgment:
+
+```markdown
+## Manual Verification Checklist
+
+Before Code Review:
+- [ ] I've tested my changes locally
+- [ ] I've written/updated tests
+- [ ] I've read my own diff
+- [ ] I've checked for security issues
+- [ ] I've updated documentation
+
+Before Deployment:
+- [ ] Code review approved
+- [ ] QA verified (if applicable)
+- [ ] Stakeholder approved (if required)
+- [ ] Deployment plan reviewed
+```
+
+### Conditional Gates
+
+Gates that apply in specific situations:
+
+| Condition | Required Gates |
+|-----------|---------------|
+| Security-related | Security review |
+| Public API change | API review + migration plan |
+| Database change | DBA review + backup plan |
+| Performance-sensitive | Performance test |
+| Breaking change | Deprecation notice + migration |
+
+## Implementing Gates
+
+### In Your Workflow
+
+```
+Task Start
+    │
+    ▼
+┌─────────────────┐
+│ Gate: Prereqs   │ ← Verify before starting
+│ - Requirements  │
+│ - Dependencies  │
+└────────┬────────┘
+         │
+         ▼
+    Do the work
+         │
+         ▼
+┌─────────────────┐
+│ Gate: Completion│ ← Verify before proceeding
+│ - Tests pass    │
+│ - Code reviewed │
+└────────┬────────┘
+         │
+         ▼
+Task Complete
+```
+
+### Gate Documentation Template
+
+```markdown
+## Gate: [Name]
+
+**When:** [Before what action]
+
+**Purpose:** [What this gate ensures]
+
+**Checklist:**
+- [ ] Item 1
+- [ ] Item 2
+- [ ] Item 3
+
+**Verification Method:**
+- [How to verify each item]
+
+**Failure Actions:**
+- [What to do if gate fails]
+
+**Approver:** [Who can approve passage]
+```
+
+## Gate Metrics
+
+Good gates have high effectiveness (catch most issues), low overhead (quick to pass), and high value (prevent expensive downstream fixes). Track which gate caught an issue and how much time was spent at each gate to tune your process over time.
+
+## Integration with CI/CD
+
+```yaml
+# GitHub Actions example
+jobs:
+  gate-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: npm ci
+      - run: npm run lint
+
+  gate-test:
+    needs: gate-lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: npm ci
+      - run: npm run test
+
+  gate-build:
+    needs: gate-test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: npm ci
+      - run: npm run build
+
+  deploy:
+    needs: gate-build
+    # Only deploys if all gates pass
+```
+
+## Quick Reference
+
+| Phase | Gate Before | Key Checks |
+|-------|-------------|------------|
+| Design | Requirements | Clear, complete, approved |
+| Implementation | Design | Reviewed, feasible |
+| Review | Implementation | Tests, conventions, working |
+| Merge | Review | Approved, conflicts resolved |
+| Deploy | Merge | Environment ready, plan exists |
+
+## Integration with Other Skills
+
+- **design-first**: Gates validate design before implementation
+- **task-decomposition**: Gates between task phases
+- **testing/red-green-refactor**: Tests are key gate criteria
+- **collaboration/structured-review**: Review is a gate

package/skills/verification-gates/manifest.json

@@ -0,0 +1,19 @@
+{
+  "name": "verification-gates",
+  "version": "1.0.0",
+  "description": "Verification gates and acceptance checkpoints between risky phases",
+  "triggers": [
+    "verification gate",
+    "quality gate",
+    "milestone check",
+    "approval step",
+    "go no go"
+  ],
+  "applicable_agents": [
+    "planner",
+    "auditor",
+    "strategist"
+  ],
+  "max_context_tokens": 1800,
+  "entry_file": "SKILL.md"
+}

package/src/control-plane.ts

@@ -0,0 +1,21 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+
+import { createPluginHooks } from "./opencode-multiagent/hooks.ts";
+import { loadRuntimeSettings } from "./opencode-multiagent/runtime.ts";
+
+export const OpenCodeMultiAgentPlugin = async (context: PluginInput) => {
+  const client = context.client;
+  const projectRoot = context.worktree || context.directory;
+  const { flags, modelTiers, agentSettings } = await loadRuntimeSettings();
+
+  return createPluginHooks({
+    client,
+    flags,
+    modelTiers,
+    agentSettings,
+    projectRoot,
+  });
+};
+
+export const ControlPlanePlugin = OpenCodeMultiAgentPlugin;
+export default OpenCodeMultiAgentPlugin;

package/src/index.ts

@@ -0,0 +1,8 @@
+import type { Plugin } from "@opencode-ai/plugin";
+
+import OpenCodeMultiAgentPlugin from "./control-plane.ts";
+
+const plugin: Plugin = OpenCodeMultiAgentPlugin;
+
+export default plugin;
+export { plugin as OpenCodeMultiAgentPlugin };

package/src/opencode-multiagent/compiler.ts

@@ -0,0 +1,168 @@
+import { disabledNativeAgents } from "./constants.ts";
+import { note } from "./log.ts";
+import { loadMarkdownDefs } from "./markdown.ts";
+import { resolveTier } from "./runtime.ts";
+import { clone, compact, merge, own } from "./utils.ts";
+
+type GenericRecord = Record<string, unknown>;
+type MergedConfig = GenericRecord & {
+  agent?: Record<string, GenericRecord>;
+  command?: Record<string, GenericRecord>;
+  default_agent?: string;
+  permission?: Record<string, unknown>;
+  _mcpPermissionRegistry?: Map<string, MpcPermissionRegistry>;
+};
+
+type MpcPermissionRegistry = {
+  allowed: string[];
+  denied: string[];
+  fallback: "allow" | "deny";
+};
+
+export const normalizeDefinitionData = (data: GenericRecord, modelTiers: Record<string, string>): GenericRecord => {
+  const result = clone(data) ?? {};
+  delete result.variant;
+  if (typeof result.model === "string") result.model = resolveTier(result.model, modelTiers);
+  return result;
+};
+
+const mcpPrefixes = ["exa_", "context7_", "gh_grep_", "github_", "code_index_", "repo_git_"];
+
+export const isMcpPermissionKey = (key: string): boolean =>
+  mcpPrefixes.some((prefix) => key === prefix || key.startsWith(prefix));
+
+export const buildMcpPermissionRegistry = (permission: GenericRecord = {}): MpcPermissionRegistry => {
+  const allowed: string[] = [];
+  const denied: string[] = [];
+  for (const [key, value] of Object.entries(permission)) {
+    if (!isMcpPermissionKey(key)) continue;
+    if (value === "allow") allowed.push(key);
+    if (value === "deny") denied.push(key);
+  }
+  return { allowed, denied, fallback: permission["*"] === "allow" ? "allow" : "deny" };
+};
+
+export async function compileAgents(
+  cfg: MergedConfig,
+  dirs: Array<string | undefined>,
+  modelTiers: Record<string, string>,
+  agentSettings: GenericRecord = {},
+): Promise<Map<string, MpcPermissionRegistry>> {
+  const defs = await loadMarkdownDefs(dirs);
+  if (!cfg.agent || typeof cfg.agent !== "object") cfg.agent = {};
+  const mcpRegistry = new Map<string, MpcPermissionRegistry>();
+
+  for (const [name, raw] of defs.entries()) {
+    const data = normalizeDefinitionData(raw.data, modelTiers);
+    if (!own(cfg.agent, name)) {
+      cfg.agent[name] = {};
+    } else if (!cfg.agent[name] || typeof cfg.agent[name] !== "object") {
+      continue;
+    }
+
+    const target = cfg.agent[name] as GenericRecord;
+    const explicitFields = new Set(Object.keys(target));
+    for (const [field, value] of Object.entries(data)) {
+      if (own(target, field)) continue;
+      target[field] = clone(value);
+    }
+
+    const overrides = agentSettings?.[name];
+    if (overrides && typeof overrides === "object") {
+      for (const [field, value] of Object.entries(overrides as GenericRecord)) {
+        if (["model", "temperature", "steps"].includes(field) && !explicitFields.has(field)) {
+          target[field] = clone(value);
+        }
+      }
+    }
+
+    if (!own(target, "prompt") && typeof raw.body === "string") {
+      target.prompt = raw.body.trim();
+    }
+
+    mcpRegistry.set(name, buildMcpPermissionRegistry((target.permission as GenericRecord | undefined) ?? {}));
+  }
+
+  cfg._mcpPermissionRegistry = mcpRegistry;
+  return mcpRegistry;
+}
+
+export async function compileCommands(
+  cfg: MergedConfig,
+  dirs: Array<string | undefined>,
+  modelTiers: Record<string, string>,
+): Promise<void> {
+  const defs = await loadMarkdownDefs(dirs);
+  if (!cfg.command || typeof cfg.command !== "object") cfg.command = {};
+
+  for (const [name, raw] of defs.entries()) {
+    const data = normalizeDefinitionData(raw.data, modelTiers);
+    if (!own(cfg.command, name)) {
+      cfg.command[name] = {};
+    } else if (!cfg.command[name] || typeof cfg.command[name] !== "object") {
+      continue;
+    }
+
+    const target = cfg.command[name] as GenericRecord;
+    for (const [field, value] of Object.entries(data)) {
+      if (own(target, field)) continue;
+      target[field] = clone(value);
+    }
+
+    if (!own(target, "template") && typeof raw.body === "string") {
+      target.template = raw.body.trim();
+    }
+  }
+}
+
+export const applyBuiltInAgentPolicy = async (cfg: MergedConfig): Promise<void> => {
+  if (!cfg.agent || typeof cfg.agent !== "object") cfg.agent = {};
+  for (const name of disabledNativeAgents) {
+    cfg.agent[name] = merge(cfg.agent[name], { disable: true });
+  }
+
+  const current = typeof cfg.default_agent === "string" ? cfg.default_agent : undefined;
+  const currentAgent = current ? cfg.agent?.[current] : undefined;
+  const preferred = cfg.agent.lead && cfg.agent.lead.disable !== true ? "lead" : cfg.agent.critic && cfg.agent.critic.disable !== true ? "critic" : undefined;
+  const invalidCurrent =
+    !current ||
+    disabledNativeAgents.includes(current) ||
+    !currentAgent ||
+    currentAgent.disable === true ||
+    currentAgent.hidden === true ||
+    currentAgent.mode === "subagent" ||
+    currentAgent.mode === "sub" ||
+    (preferred === "lead" && current !== "lead");
+
+  if (invalidCurrent && preferred) {
+    const previous = current;
+    cfg.default_agent = preferred;
+    await note(
+      "config_warning",
+      compact({
+        observation: true,
+        warning: "default_agent_reset",
+        previous,
+        next: preferred,
+      }),
+    );
+  }
+};
+
+export const applyPermissionDefaults = (cfg: MergedConfig): void => {
+  if (!cfg.permission || typeof cfg.permission !== "object") cfg.permission = {};
+  for (const [key, value] of Object.entries({
+    bash: "allow",
+    read: "allow",
+    edit: "allow",
+    glob: "allow",
+    grep: "allow",
+    list: "allow",
+  })) {
+    if (!own(cfg.permission, key)) {
+      (cfg.permission as GenericRecord)[key] = value;
+    }
+  }
+};
+
+export type { MergedConfig, MpcPermissionRegistry };

package/src/opencode-multiagent/constants.ts

@@ -0,0 +1,178 @@
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const pluginName = "opencode-multiagent";
+export const pluginMode = "stable";
+
+export const opencodeDir = join(homedir(), ".config", "opencode");
+export const pluginDir = join(opencodeDir, "plugins");
+export const globalAgentsDir = join(opencodeDir, "agents");
+export const globalCommandsDir = join(opencodeDir, "commands");
+export const logDirPath = join(opencodeDir, "logs");
+export const logFilePath = join(logDirPath, `${pluginName}.jsonl`);
+export const flagsPath = join(pluginDir, `${pluginName}.flags.json`);
+export const agentSettingsPath = join(pluginDir, `${pluginName}.agent-settings.json`);
+export const profilesPath = join(pluginDir, `${pluginName}.profiles.json`);
+
+export const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+export const bundledAgentSettingsPath = join(packageRoot, "defaults", "agent-settings.json");
+export const bundledAgentsDir = join(packageRoot, "agents");
+export const bundledCommandsDir = join(packageRoot, "commands");
+export const bundledSkillsDir = join(packageRoot, "skills");
+
+export const trackedEventTypes = new Set([
+  "permission.updated",
+  "permission.replied",
+  "session.created",
+  "session.status",
+  "session.diff",
+  "file.edited",
+  "session.deleted",
+  "session.idle",
+  "message.updated",
+  "message.part.updated",
+  "message.part.delta",
+  "command.executed",
+]);
+
+export const supervisionEventTypes = new Set([
+  "session.created",
+  "message.updated",
+  "message.part.updated",
+  "message.part.delta",
+  "session.idle",
+  "session.deleted",
+]);
+
+export const qualityEventTypes = new Set(["file.edited", "session.idle", "session.deleted"]);
+export const telemetryEventTypes = new Set(["session.created", "message.updated", "session.deleted"]);
+export const suspiciousTerms = ["blocked", "failed", "error", "permission", "refused"];
+export const qualitySignalRegex =
+  /\b(test|tests|lint|typecheck|tsc|build|pytest|vitest|jest|cargo test|go test|ruff|mypy|eslint|biome|prettier)\b/i;
+
+export const mcpToolPrefixes = ["exa_", "context7_", "gh_grep_", "github_", "code_index_", "repo_git_"];
+
+export const defaultProfiles = {
+  minimal: {
+    enforcement: true,
+    observation: false,
+    prompt_controls: false,
+    agent_compilation: true,
+    command_compilation: true,
+    mcp_compilation: true,
+    telemetry: false,
+    supervision: false,
+    quality_gate: false,
+    experimental: {
+      chat_system_transform: false,
+      chat_messages_transform: false,
+      session_compacting: false,
+      text_complete: false,
+    },
+  },
+  standard: {
+    enforcement: true,
+    observation: true,
+    prompt_controls: true,
+    agent_compilation: true,
+    command_compilation: true,
+    mcp_compilation: true,
+    telemetry: true,
+    supervision: true,
+    quality_gate: true,
+    skill_sources: [bundledSkillsDir, join(homedir(), ".agents", "skills"), join(homedir(), "skills")],
+    skill_injection: false,
+    experimental: {
+      chat_system_transform: false,
+      chat_messages_transform: false,
+      session_compacting: false,
+      text_complete: false,
+    },
+  },
+  strict: {
+    enforcement: true,
+    observation: true,
+    prompt_controls: true,
+    agent_compilation: true,
+    command_compilation: true,
+    mcp_compilation: true,
+    telemetry: true,
+    supervision: true,
+    quality_gate: true,
+    experimental: {
+      chat_system_transform: true,
+      chat_messages_transform: true,
+      session_compacting: true,
+      text_complete: true,
+    },
+  },
+};
+
+export const defaultFlags = {
+  profile: "standard",
+  enforcement: true,
+  observation: true,
+  prompt_controls: true,
+  agent_compilation: true,
+  command_compilation: true,
+  mcp_compilation: true,
+  telemetry: true,
+  supervision: true,
+  quality_gate: true,
+  skill_sources: [bundledSkillsDir, join(homedir(), ".agents", "skills"), join(homedir(), "skills")],
+  skill_injection: false,
+  compiler: {
+    permission_compilation: true,
+  },
+  experimental: {
+    chat_system_transform: false,
+    chat_messages_transform: false,
+    session_compacting: false,
+    text_complete: false,
+  },
+  supervision_config: {
+    idle_timeout_ms: 180000,
+    cooldown_ms: 300000,
+  },
+  quality_config: {
+    reminder_idle_ms: 120000,
+    reminder_cooldown_ms: 300000,
+  },
+};
+
+export const disabledNativeAgents = ["build", "plan", "general", "explore"];
+
+export const blockedPathPrefixRegex = /^(\/etc|\/root|\/boot|\/proc|\/sys|\/dev)(?:\/|$)/;
+export const blockedPathFragments = ["/.ssh/", "/credentials", "/secrets", "/.aws/", "/.gcloud/", "/.kube/"];
+export const blockedPathSuffixes = ["/.ssh", "/credentials"];
+export const destructiveBashFragments = [
+  "git reset --" + "hard",
+  "git che" + "ckout --",
+  "r" + "m -rf /",
+  "r" + "m -rf ~",
+  "su" + "do ",
+  "shut" + "down",
+  "re" + "boot",
+  "mk" + "fs",
+  "dd i" + "f=",
+  "cu" + "rl | ba" + "sh",
+  "cu" + "rl | sh",
+  "wg" + "et | ba" + "sh",
+  "wg" + "et | sh",
+  "ev" + "al $(",
+  "> /de" + "v/",
+  ":" + "(){",
+  "ch" + "mod 777",
+  "ki" + "ll -9 -1",
+  "no" + "hup ",
+];
+export const sensitiveMentions = ["/etc", "/root", "/boot", "/proc", "/sys", "/dev", "/.ssh", "~/.ssh"];
+
+export const noteText =
+  "[opencode-multiagent note] Sensitive system paths and destructive shell fragments are blocked by local runtime policy.";
+export const experimentalText =
+  "[opencode-multiagent experimental] Experimental control-plane transforms are active for this session.";
+
+export type DefaultFlags = typeof defaultFlags;
+export type DefaultProfiles = typeof defaultProfiles;