opcrew 0.1.0 → 0.1.2

package/README.md

@@ -2,6 +2,75 @@
 
 Opcrew provides a crew of structured agents and an OpenCode plugin that registers them automatically.
 
+## Crew Roles
+
+| Agent | Role | Responsibility |
+|-------|------|----------------|
+| **Captain** | Orchestrator | Coordinates, delegates, verifies - never executes directly |
+| **Navigator** | Planner | Charts implementation path, decomposes work, creates todo lists |
+| **Boatswain** | Executor | Executes tasks, writes code, makes file changes |
+| **Quartermaster** | Reviewer | Verifies work, runs tests, ensures quality |
+| **Scout** | Researcher | Gathers external information - libraries, APIs, best practices |
+
+## Workflow
+
+```
+┌─────────────┐                    ┌───────────┐
+│    User     │ ──── intent ─────► │  Captain  │
+└─────────────┘                    └─────┬─────┘
+                                         │
+          ┌──────────────────────────────┼──────────────────────────────┐
+          │                              │                              │
+          │ delegates via task tool      │ may summon for research      │
+          ▼                              │                              ▼
+   ┌───────────┐                         │                       ┌───────────┐
+   │ Navigator │ ◄───────────────────────┘                       │   Scout   │
+   └─────┬─────┘         may summon for research                 └───────────┘
+         │                                                        ▲
+         │ creates plan + todo list                               │
+         │                                                        │
+         ▼                                                        │
+   ┌───────────┐                                                  │
+   │  Captain  │ ◄── reviews plan ───                             │
+   └─────┬─────┘                                                  │
+         │                                                        │
+         │ delegates via task tool                                │
+         ▼                                                        │
+   ┌───────────┐       may need research ─────────────────────────┘
+   │ Boatswain │
+   └─────┬─────┘
+         │
+         │ executes tasks
+         ▼
+   ┌──────────────┐
+   │ Quartermaster│
+   └──────┬───────┘
+          │
+          │ verifies & reports
+          ▼
+   ┌───────────┐
+   │  Captain  │
+   └───────────┘
+```
+
+### Flow Description
+
+1. **Intent** → Captain receives user intent, classifies task type
+2. **Planning** → Captain delegates to Navigator, who creates plan and todo list
+   - Navigator may summon Scout for external research (libraries, APIs, docs)
+3. **Review** → Captain reviews Navigator's plan
+4. **Execution** → Captain delegates to Boatswain to execute tasks
+   - Boatswain may trigger Scout if implementation requires external info
+5. **Verification** → Captain delegates to Quartermaster for testing/review
+6. **Completion** → Quartermaster reports to Captain
+
+### Scout Activation
+
+Scout can be summoned by:
+- **Navigator** - During planning to research libraries, frameworks, best practices
+- **Captain** - When external information is needed for decision-making
+- **Boatswain** - During execution if implementation requires API docs or examples
+
 ## Setup
 
 Install dependencies:
@@ -33,12 +102,26 @@ Publish the package and add it to your OpenCode config:
 
 ```json
 {
-  "plugin": ["opcrew@0.1.0"]
+  "plugin": ["opcrew@0.1.2"]
 }
 ```
 
 The plugin entrypoint is `src/opencode-plugin.ts` and the published bundle is `dist/opencode-plugin.js`.
 
+## Logbook
+
+The crew tracks progress in `.opcrew/logbook.json`:
+
+| Section | Purpose |
+|---------|---------|
+| `voyage` | Current session status (idle/active/blocked/completed) |
+| `missions` | Tasks with intent, status, and outcome |
+| `decisions` | Key decisions with rationale |
+| `blockers` | Impediments blocking progress |
+| `notes` | General observations |
+
+Use the `edit_logbook` tool to update the logbook.
+
 ## Knowledge Base
 
 Project context lives under `docs/knowledge/`:

package/dist/cli.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/cli/index.ts
+import process from "process";
+
+// src/cli/install.ts
+import { mkdir, writeFile } from "fs/promises";
+import path from "path";
+
+// 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" },
+      Researcher: { edit: "deny", bash: "deny", webfetch: "allow" }
+    };
+    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: [
+    "You are the orchestrator - you NEVER execute work directly. Your role is to coordinate, delegate, and verify.",
+    "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 mandate: ALWAYS delegate work to specialists using the task tool. Never perform file edits, code changes, or direct execution yourself.",
+    "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: delegate verification to Quartermaster; 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", "edit_logbook", "task"]
+});
+
+// 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 and manage 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.",
+    "Delegate external research to Scout when you need information from outside the project: libraries, APIs, best practices, or documentation.",
+    "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", "todowrite"]
+});
+
+// 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", "grep", "bash", "write"]
+});
+
+// src/crew/Scout.ts
+var Scout = new OpCrewAgent({
+  name: "Scout",
+  role: "Researcher",
+  mode: "subagent",
+  instructions: [
+    "You are the crew's eyes to the outside world - research and gather information when summoned by Captain or Navigator.",
+    "Focus exclusively on external research: web searches, documentation lookup, API references, and best practices.",
+    "Never modify project files - your job is to gather intelligence, not execute changes.",
+    "Provide concise, actionable findings with clear sources and citations.",
+    "When researching libraries or frameworks, include: version info, installation methods, key APIs, and gotchas.",
+    "Compare alternatives when relevant: pros/cons, trade-offs, and recommendations with rationale.",
+    "Flag deprecated or outdated information; always verify against official sources when possible.",
+    "Summarize findings in a structured format: problem, findings, recommendations, sources.",
+    "If research reveals the task is more complex than expected, escalate to Navigator for replanning.",
+    "Cache useful references in docs/knowledge for future crew reference."
+  ],
+  tools: ["web_search", "web_fetch", "read_fs"]
+});
+
+// src/crew/index.ts
+var crew = [
+  Captain,
+  Navigator,
+  Boatswain,
+  Quartermaster,
+  Scout
+];
+
+// src/cli/install.ts
+var CLAUDE_DIR = path.join(".claudecode", "agents");
+var OPENCODE_DIR = path.join(".opencode", "agents");
+var CODEX_FILE = path.join(".codex", "instructions.md");
+async function ensureDir(targetDir) {
+  await mkdir(targetDir, { recursive: true });
+}
+async function installToTool(tool) {
+  if (tool === "codex") {
+    await installForCodex();
+    return;
+  }
+  const targetDir = tool === "claude" ? CLAUDE_DIR : OPENCODE_DIR;
+  await ensureDir(targetDir);
+  for (const agent of crew) {
+    const filename = `${agent.config.name.toLowerCase()}.md`;
+    const filePath = path.join(targetDir, filename);
+    const content = tool === "opencode" ? agent.compileToOpenCodeMarkdown() : agent.compileToMarkdown();
+    await writeFile(filePath, content);
+    console.log(`Synced ${agent.config.name} to ${targetDir}`);
+  }
+}
+async function installForCodex() {
+  const codexDir = path.dirname(CODEX_FILE);
+  await ensureDir(codexDir);
+  const compiled = crew.map((agent) => agent.compileToMarkdown()).join(`
+
+---
+
+`);
+  await writeFile(CODEX_FILE, compiled);
+  console.log(`Synced Codex instructions to ${CODEX_FILE}`);
+}
+
+// src/cli/index.ts
+var usage = `Usage:
+  bunx opcrew install [--claude] [--opencode] [--codex]
+
+At least one flag is required.
+`;
+var FLAG_TO_TOOL = {
+  "--claude": "claude",
+  "--opencode": "opencode",
+  "--codex": "codex"
+};
+function showUsage(message) {
+  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 = [];
+  const seen = new Set;
+  for (const flag of flags) {
+    const tool = FLAG_TO_TOOL[flag];
+    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);
+  }
+}
+await main().catch((error) => {
+  console.error("Installation failed:", error);
+  process.exit(1);
+});

package/dist/core/Agent.d.ts

@@ -1,6 +1,6 @@
 export interface AgentConfig {
     name: string;
-    role: 'Orchestrator' | 'Planner' | 'Executor' | 'Reviewer';
+    role: 'Orchestrator' | 'Planner' | 'Executor' | 'Reviewer' | 'Researcher';
     mode: 'primary' | 'subagent';
     instructions: string[];
     tools: string[];

package/dist/crew/Scout.d.ts

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

package/dist/crew/index.d.ts

@@ -2,5 +2,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 };
+import { Scout } from "./Scout";
+export declare const crew: readonly [import("../core/Agent").OpCrewAgent, import("../core/Agent").OpCrewAgent, import("../core/Agent").OpCrewAgent, import("../core/Agent").OpCrewAgent, import("../core/Agent").OpCrewAgent];
+export { Captain, Navigator, Boatswain, Quartermaster, Scout };