opcrew 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# Opcrew
+
+Opcrew provides a crew of structured agents and an OpenCode plugin that registers them automatically.
+
+## Setup
+
+Install dependencies:
+
+```bash
+bun install
+```
+
+Run the CLI locally:
+
+```bash
+bun run src/cli/index.ts install --opencode
+```
+
+## OpenCode Plugin
+
+This project ships an OpenCode plugin that registers the crew agents via `config.agent`.
+
+### Build
+
+```bash
+bun run build
+bun run build:types
+```
+
+### Install as plugin
+
+Publish the package and add it to your OpenCode config:
+
+```json
+{
+  "plugin": ["opcrew@0.1.0"]
+}
+```
+
+The plugin entrypoint is `src/opencode-plugin.ts` and the published bundle is `dist/opencode-plugin.js`.
+
+## Knowledge Base
+
+Project context lives under `docs/knowledge/`:
+
+- `decisions/` for ADRs
+- `runbooks/` for operational procedures
+- `project-map.md` for module map
+- `glossary.md` for definitions

package/dist/core/Agent.d.ts

@@ -0,0 +1,14 @@
+export interface AgentConfig {
+    name: string;
+    role: 'Orchestrator' | 'Planner' | 'Executor' | 'Reviewer';
+    mode: 'primary' | 'subagent';
+    instructions: string[];
+    tools: string[];
+}
+export declare class OpCrewAgent {
+    readonly config: AgentConfig;
+    constructor(config: AgentConfig);
+    compileToMarkdown(): string;
+    compileToOpenCodeMarkdown(): string;
+    private buildMarkdownBody;
+}

package/dist/crew/Boatswain.d.ts

@@ -0,0 +1,2 @@
+import { OpCrewAgent } from "../core/Agent";
+export declare const Boatswain: OpCrewAgent;

package/dist/crew/Captain.d.ts

@@ -0,0 +1,2 @@
+import { OpCrewAgent } from "../core/Agent";
+export declare const Captain: OpCrewAgent;

package/dist/crew/Navigator.d.ts

@@ -0,0 +1,2 @@
+import { OpCrewAgent } from "../core/Agent";
+export declare const Navigator: OpCrewAgent;

package/dist/crew/Quartermaster.d.ts

@@ -0,0 +1,2 @@
+import { OpCrewAgent } from "../core/Agent";
+export declare const Quartermaster: OpCrewAgent;

package/dist/crew/index.d.ts

@@ -0,0 +1,6 @@
+import { Captain } from "./Captain";
+import { Navigator } from "./Navigator";
+import { Boatswain } from "./Boatswain";
+import { Quartermaster } from "./Quartermaster";
+export declare const crew: readonly [import("../core/Agent").OpCrewAgent, import("../core/Agent").OpCrewAgent, import("../core/Agent").OpCrewAgent, import("../core/Agent").OpCrewAgent];
+export { Captain, Navigator, Boatswain, Quartermaster };

package/dist/opencode-plugin.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const OpCrewPlugin: Plugin;
+export default OpCrewPlugin;

package/dist/opencode-plugin.js

@@ -0,0 +1,193 @@
+// @bun
+// src/core/Agent.ts
+class OpCrewAgent {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  compileToMarkdown() {
+    const frontmatter = `---
+name: ${this.config.name}
+role: ${this.config.role}
+tools: [${this.config.tools.join(", ")}]
+---`;
+    return `${frontmatter}
+${this.buildMarkdownBody()}`;
+  }
+  compileToOpenCodeMarkdown() {
+    const permissionByRole = {
+      Orchestrator: { edit: "deny", bash: "ask", webfetch: "deny" },
+      Planner: { edit: "deny", bash: "ask", webfetch: "allow" },
+      Executor: { edit: "allow", bash: "allow", webfetch: "ask" },
+      Reviewer: { edit: "deny", bash: "ask", webfetch: "deny" }
+    };
+    const permission = permissionByRole[this.config.role];
+    const frontmatter = `---
+description: ${this.config.name}
+mode: ${this.config.mode}
+permission:
+  edit: ${permission.edit}
+  bash: ${permission.bash}
+  webfetch: ${permission.webfetch}
+---`;
+    return `${frontmatter}
+${this.buildMarkdownBody()}`;
+  }
+  buildMarkdownBody() {
+    const instructionsList = this.config.instructions.map((instruction) => `- ${instruction}`).join(`
+`);
+    return `
+# ${this.config.name}
+${instructionsList}
+
+## Shared Context
+Refer to \`.opcrew/logbook.json\` for the current voyage status.
+`;
+  }
+}
+
+// src/crew/Captain.ts
+var Captain = new OpCrewAgent({
+  name: "Captain",
+  role: "Orchestrator",
+  mode: "primary",
+  instructions: [
+    "Define mission intent with explicit scope, constraints, and success criteria before any execution.",
+    "Assign roles in order: Navigator plans, Boatswain executes, Quartermaster reviews; resolve conflicts quickly.",
+    "Require a logbook entry that captures decisions, risks, and acceptance checks for every mission.",
+    "Escalate blockers immediately and re-sequence work to unblock the critical path.",
+    "Enforce conventions: small, reviewable diffs; no scope creep; verification required before declaring done.",
+    "Intent gate: restate user intent, classify task type (trivial/explicit/exploratory/open-ended/ambiguous), and choose the workflow before action.",
+    "Delegation bias: default to delegation when specialists are available; only solo if trivial and single-step.",
+    "Delegation protocol: require task/outcome/tools/must-do/must-not/context in every order; reject vague asks.",
+    "Parallel exploration: launch explore/librarian tasks concurrently for non-trivial discovery, and avoid duplicate searches.",
+    "Verification gate: ensure diagnostics/tests run and evidence is logged before marking complete.",
+    "Knowledge discipline: require crew to read/update docs/knowledge (project map, glossary, relevant ADRs) for any decision or scope change.",
+    "Ensure every material decision is captured as an ADR in docs/knowledge/decisions."
+  ],
+  tools: ["read_fs", "write_logbook", "dispatch_orders"]
+});
+
+// src/crew/Navigator.ts
+var Navigator = new OpCrewAgent({
+  name: "Navigator",
+  role: "Planner",
+  mode: "subagent",
+  instructions: [
+    "Chart the implementation path based on the Captain's intent and constraints.",
+    "Decompose work into atomic, ordered tasks with clear inputs, outputs, and ownership.",
+    "Record the plan in the logbook with file targets, dependencies, and acceptance checks.",
+    "Maintain a current project map (key files, modules, and ownership boundaries).",
+    "Flag ambiguity early, propose alternatives, and surface risks before execution starts.",
+    "Apply the intent gate: classify the request and select the correct workflow (explore vs. implement vs. clarify).",
+    "Create todo/task lists for any multi-step plan; enforce one in-progress item at a time.",
+    "Mandate parallel discovery for unknowns: launch multiple explore/librarian threads and consolidate findings.",
+    "Define verification steps explicitly (diagnostics/tests/build) and include success evidence in the plan.",
+    "Consult docs/knowledge before planning; update project-map/glossary/ADRs when scope or definitions change."
+  ],
+  tools: ["read_fs", "web_search", "edit_logbook"]
+});
+
+// src/crew/Boatswain.ts
+var Boatswain = new OpCrewAgent({
+  name: "Boatswain",
+  role: "Executor",
+  mode: "subagent",
+  instructions: [
+    "Turn approved Navigator steps into precise edits without scope creep.",
+    "Follow existing patterns, naming, and formatting; avoid speculative changes.",
+    "Keep diffs lean and standards-compliant; update only what the plan calls for.",
+    "Run required sanity tests and record results in the logbook.",
+    "Log completion status, assumptions, and blockers immediately for the Captain.",
+    "Do not re-run delegated exploration; wait for Navigator findings before implementing dependent changes.",
+    "Use verification gates: lsp diagnostics on touched files plus relevant tests/builds before completion.",
+    "Update docs/knowledge when execution changes assumptions, definitions, or operational steps."
+  ],
+  tools: ["read_fs", "edit_code", "run_tests"]
+});
+
+// src/crew/Quartermaster.ts
+var Quartermaster = new OpCrewAgent({
+  name: "Quartermaster",
+  role: "Reviewer",
+  mode: "subagent",
+  instructions: [
+    "Inspect each diff for regression risks, scope drift, and missing context.",
+    "Confirm tests, docs, and logbook entries prove the change is complete.",
+    "Verify acceptance checks and ensure the plan-to-implementation trace is intact.",
+    "Escalate unresolved quality gaps to the Captain before approval.",
+    "Require rework when verification is missing or conventions are violated.",
+    "Reject approvals lacking evidence (diagnostics/tests/build logs) or missing todo/task tracking.",
+    "Verify delegation protocol compliance when specialists were involved (task/outcome/tools/must-do/must-not/context).",
+    "Reject approval if docs/knowledge changes are missing for material decisions or scope shifts."
+  ],
+  tools: ["read_fs", "review_diffs", "check_tests"]
+});
+
+// src/crew/index.ts
+var crew = [
+  Captain,
+  Navigator,
+  Boatswain,
+  Quartermaster
+];
+
+// src/opencode-plugin.ts
+var permissionByRole = {
+  Orchestrator: { edit: "deny", bash: "ask", webfetch: "deny" },
+  Planner: { edit: "deny", bash: "ask", webfetch: "allow" },
+  Executor: { edit: "allow", bash: "allow", webfetch: "ask" },
+  Reviewer: { edit: "deny", bash: "ask", webfetch: "deny" }
+};
+function toAgentId(agent) {
+  return agent.config.name.toLowerCase().replace(/\s+/g, "-");
+}
+function buildPrompt(agent) {
+  const instructionsList = agent.config.instructions.map((instruction) => `- ${instruction}`).join(`
+`);
+  return `# ${agent.config.name}
+${instructionsList}
+
+## Shared Context
+Refer to \`.opcrew/logbook.json\` for the current voyage status.
+`;
+}
+function toOpenCodeAgentConfig(agent) {
+  return {
+    description: agent.config.name,
+    mode: agent.config.mode,
+    prompt: buildPrompt(agent),
+    permission: permissionByRole[agent.config.role]
+  };
+}
+var OpCrewPlugin = async ({ client }) => {
+  await client.app.log({
+    body: {
+      service: "opcrew",
+      level: "info",
+      message: "OpenCode plugin initialized"
+    }
+  });
+  return {
+    config: async (config) => {
+      const agents = config.agent ?? {};
+      for (const agent of crew) {
+        agents[toAgentId(agent)] = toOpenCodeAgentConfig(agent);
+      }
+      config.agent = agents;
+      await client.app.log({
+        body: {
+          service: "opcrew",
+          level: "info",
+          message: "Crew agents registered",
+          extra: { agents: Object.keys(agents) }
+        }
+      });
+    }
+  };
+};
+var opencode_plugin_default = OpCrewPlugin;
+export {
+  opencode_plugin_default as default,
+  OpCrewPlugin
+};

package/docs/knowledge/README.md

@@ -0,0 +1,67 @@
+# Knowledge Base Conventions
+
+This folder is the **canonical, human-readable source of truth** for project context. Agents must read relevant files before acting and update them when decisions or constraints change.
+
+## Structure
+
+- `decisions/` — Architecture Decision Records (ADRs)
+- `runbooks/` — Operational procedures and recurring workflows
+- `glossary.md` — Terms, abbreviations, and canonical definitions
+- `project-map.md` — High-level module map, ownership boundaries, and key entry points
+
+## Rules of Engagement
+
+1. **Read first:** Check `project-map.md`, `glossary.md`, and any related ADRs before planning or execution.
+2. **Write when you decide:** Any non-trivial decision that changes direction, constraints, or approach must be captured as an ADR.
+3. **Keep it small and explicit:** Prefer concise entries with clear rationale and consequences.
+4. **No hidden knowledge:** If it matters for future work, it belongs here.
+5. **Git is the source of truth:** Do not store canonical decisions in databases; this folder is the canonical record.
+
+## ADR Template
+
+Create a new file in `decisions/` using the next sequence number:
+
+```text
+YYYYMMDD-###-short-title.md
+```
+
+Include the following sections:
+
+```markdown
+# Title
+
+## Status
+Accepted | Superseded | Deprecated
+
+## Context
+What problem are we solving? What constraints apply?
+
+## Decision
+What did we decide?
+
+## Consequences
+What tradeoffs or follow-up work does this create?
+```
+
+## Runbook Template
+
+Create a new file in `runbooks/` using:
+
+```text
+topic-short-title.md
+```
+
+```markdown
+# Title
+
+## Purpose
+
+## Preconditions
+
+## Steps
+1.
+
+## Verification
+
+## Rollback
+```

package/docs/knowledge/decisions/20260328-001-knowledge-base-source-of-truth.md

@@ -0,0 +1,15 @@
+# Knowledge Base Source of Truth
+
+## Status
+Accepted
+
+## Context
+We need a maintainable way to preserve project decisions, conventions, and operational guidance for agents and humans.
+
+## Decision
+Use the filesystem as the canonical knowledge base in `docs/knowledge/`. Keep decisions as ADRs, project map and glossary as living docs, and runbooks for operational procedures.
+
+## Consequences
+- Decisions become reviewable and diffable in Git.
+- Agents must read/update these docs as part of workflow conventions.
+- A database can be added later only as a derived index, not as the source of truth.

package/docs/knowledge/glossary.md

@@ -0,0 +1,10 @@
+# Glossary
+
+## ADR (Architecture Decision Record)
+A short, structured document that records a significant architectural or process decision, its context, and its consequences.
+
+## Logbook
+The mission log that captures decisions, risks, task status, and verification evidence for each mission.
+
+## Mission
+A unit of work defined by the Captain, typically decomposed into tasks by the Navigator and executed by the Boatswain.

package/docs/knowledge/project-map.md

@@ -0,0 +1,18 @@
+# Project Map
+
+## Purpose
+High-level map of key modules, entry points, and ownership boundaries. Keep this updated when new modules are added or responsibilities shift.
+
+## Modules
+
+- `src/crew/` — Crew agent definitions and instruction sets.
+- `src/core/` — Core agent framework, orchestration primitives, and shared utilities.
+
+## Entry Points
+
+- `index.ts` — Application entry point.
+
+## Conventions
+
+- Follow crew instruction conventions in `src/crew/` for workflow discipline.
+- Keep diffs small and verification evidence attached to changes.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "opcrew",
+  "description": "OpenCrew agents and OpenCode plugin",
+  "version": "0.1.0",
+  "main": "./dist/opencode-plugin.js",
+  "module": "./dist/opencode-plugin.js",
+  "type": "module",
+  "private": false,
+  "license": "UNLICENSED",
+  "keywords": [
+    "opencode",
+    "plugin",
+    "agents",
+    "crew"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "docs/knowledge"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/opencode-plugin.js",
+      "types": "./dist/opencode-plugin.d.ts"
+    }
+  },
+  "types": "./dist/opencode-plugin.d.ts",
+  "bin": {
+    "opcrew": "src/cli/index.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "bun build src/opencode-plugin.ts --outdir dist --target bun",
+    "build:types": "bunx tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5",
+    "undici-types": "^6.11.1"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "latest"
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+
+import process from "node:process";
+
+import { installToTool } from "./install";
+
+const usage = `Usage:
+  bunx opcrew install [--claude] [--opencode] [--codex]
+
+At least one flag is required.
+`;
+
+const FLAG_TO_TOOL = {
+  "--claude": "claude",
+  "--opencode": "opencode",
+  "--codex": "codex",
+} as const;
+
+type SupportedFlag = keyof typeof FLAG_TO_TOOL;
+
+function showUsage(message?: string): never {
+  if (message) {
+    console.error(message);
+  }
+  console.error(usage.trimEnd());
+  process.exit(1);
+}
+
+async function main() {
+  const [subcommand, ...flags] = process.argv.slice(2);
+
+  if (subcommand !== "install") {
+    showUsage("Missing or invalid subcommand. Use 'install'.");
+  }
+
+  if (flags.length === 0) {
+    showUsage("No install target provided.");
+  }
+
+  const selectedTools: string[] = [];
+  const seen = new Set<string>();
+
+  for (const flag of flags) {
+    const tool = FLAG_TO_TOOL[flag as SupportedFlag];
+
+    if (!tool) {
+      showUsage(`Unknown flag: ${flag}`);
+    }
+
+    if (seen.has(tool)) {
+      continue;
+    }
+
+    seen.add(tool);
+    selectedTools.push(tool);
+  }
+
+  if (selectedTools.length === 0) {
+    showUsage("No valid flags provided.");
+  }
+
+  for (const tool of selectedTools) {
+    await installToTool(tool as "claude" | "opencode" | "codex");
+  }
+}
+
+await main().catch((error) => {
+  console.error("Installation failed:", error);
+  process.exit(1);
+});