opencode-teammate 0.1.0

package/src/assets/command/specify.md

@@ -0,0 +1,135 @@
+---
+name: specify
+agent: plan
+model: github-copilot/claude-sonnet-4.5
+description: "Transform a thought into a specification document and implementation plan."
+---
+
+# Specification Workflow
+
+Transform brainstorm thoughts into well-defined specifications through collaborative dialogue.
+
+**Input:** A set of thought file paths from the `specs/thoughts/` folder.
+
+<thought_file>
+$ARGUMENTS
+</thought_file>
+
+---
+
+## Phase 1: Context Gathering
+
+- 1. **Load the Thought**: Read the thought files from `specs/thoughts/` folder
+- 2. **Gather Related Context**: Delegate exploration tasks to subagents
+  - Spawn parallel exploration tasks
+    ```
+    Task(subagent_type="explore", description="Explore specifications", prompt="Explore specification related to...")
+    # Any relevant exploration tasks...
+    ```
+  - Identify potential conflicts or overlaps with existing specifications
+- 3. **Present Initial Understanding**: Summarize what you understand from the thought (100-150 words)
+  - ```
+    Based on the thought document, here's my understanding:
+
+    **Core Idea**: [What the thought is about]
+    **Key Goals**: [What it aims to achieve]
+    **Open Questions**: [What needs clarification]
+
+    Is this understanding correct?
+    ```
+
+---
+
+## Phase 2: Clarification Dialogue
+
+### 2.1 Clarify with User
+
+Ask questions **one at a time** to fully understand:
+
+- **Purpose**: What problem does this solve?
+- **Scope**: What's in vs. out?
+- **Constraints**: Technical, time, or resource limitations?
+- **Success**: How do we know it's done?
+- **Users**: Who benefits from this?
+
+**Guidelines:**
+
+- Prefer multiple choice questions when possible
+- React to answers by spawning @codebase-analyser when relevant
+- Stop clarifying when you have enough to write the specification
+- Keep the dialogue bidirectional - answer user questions too
+- Maximum 5-7 clarifying questions before moving forward
+
+### 2.2 Confirm Readiness
+
+Before proceeding, confirm with the user:
+
+```
+I believe I have enough information to write the specification. Here's the scope:
+
+**What we're building**: [Summary]
+**Key requirements**: [List 3-5 main requirements]
+**Out of scope**: [What we're NOT doing]
+
+Ready to proceed with the specification?
+```
+
+**IMPORTANT**: Before continuing to Phase 3, ensure the user switched to Build mode. If not, ask the user to do so.
+
+---
+
+## Phase 3: Write Specification
+
+### 3.1 Delegate Writing
+
+Ask @general to write the specification file for you:
+
+- Provide the feature name (2-4 words, action-noun format)
+- The subagent should use the `writing-specification` skill to create the document
+- Write the specification to `specs/<feature-name>.md`
+
+### 3.2 Present for Validation
+
+Present the specification in sections (200-300 words each):
+
+1. **Overview & User Scenarios** - Present first, get approval
+2. **Functional Requirements** - Present second, get approval
+3. **Success Criteria & Edge Cases** - Present last, get approval
+
+After each section:
+
+- Ask: "Does this capture [section topic] correctly? Should I adjust?"
+- If adjustments are needed, similarly to 3.1 Delegate Writing, ask @general to make them. Once adjustments are made, revalidate the section.
+
+---
+
+## Phase 4: Implementation Plan Reconciliation
+
+Once the specification is validated and written, reconcile the implementation plan with the new or updated specification.
+
+### 4.1 Delegate to Planner
+
+Ask @mate.planner to reconcile the implementation plan with the specification:
+
+- Provide context on the specification changes.
+- Provide the Beads Epic ID and the specification file path.
+
+### 4.2 Strategic Alignment (The "Ask")
+
+Present the planner report to the user and review it with the user:
+
+- Are the tasks appropriately sized?
+- Are dependencies correct?
+- Does the plan cover all requirements?
+- If the user requests for changes, ask @mate.planner to make them.
+
+---
+
+## Key Principles
+
+- **One question at a time**: Don't overwhelm with multiple questions
+- **Bidirectional dialogue**: Answer user questions, don't just ask
+- **Validate incrementally**: Present sections, get approval, then write
+- **No open questions in final spec**: Research or ask immediately, don't defer
+- **Be skeptical**: Question vague requirements, identify issues early
+- **YAGNI ruthlessly**: Remove unnecessary features from all specifications

package/src/assets/command/work.md

@@ -0,0 +1,247 @@
+---
+name: work
+agent: build
+model: github-copilot/claude-sonnet-4.5
+description: "Claim a ready task from beads and get it done."
+---
+
+# Work
+
+You are tasked with implementing an approved technical plan from beads issues. Your goal is to execute the task autonomously from start to finish, only pausing when you encounter significant mismatches between the plan and reality.
+
+<user_prompt>
+$ARGUMENTS
+</user_prompt>
+
+## Workflow Overview
+
+---
+
+## Phase 1: Select Task
+
+Run `bd ready` to find tasks with no blockers.
+
+**Selection Logic:**
+
+- **User provided task ID:** Use it directly, validate with `bd show <task_id>`
+- **Multiple tasks available:** Present list with priority/title, ask user to select
+- **Single task available:** Auto-select and inform user
+- **No tasks available:** Inform user: "No tasks, run `bd blocked` to see what's waiting" and exit.
+
+---
+
+## Phase 2: Claim Task
+
+Before updating the task, make sure you have claimed the related epic if any.
+Run `bd update <task_id> --claim` to atomically claim the task.
+
+**If claim fails:** Task is already claimed. Inform user and return to Phase 1.
+
+---
+
+## [When claimed task is an epic] Phase 3: View Task Details
+
+Run `bd show <task_id>` and parse for:
+
+- Files to create/modify
+- Dependencies and blockers
+- Acceptance criteria
+
+**If task is an epic:**
+
+- Verify that all child tasks are closed and jump to Phase 7: Validate Acceptance Criteria.
+- If any child tasks are open, inform user and return to Phase 1.
+
+---
+
+## [When claimed task is a task] Phase 3: View Task Details
+
+Run `bd show <task_id>` and parse for:
+
+- Files to create/modify
+- Dependencies and blockers
+- Acceptance criteria
+
+**If task is an epic:**
+
+- Verify that all child tasks are closed and jump to Phase 7: Validate Acceptance Criteria.
+- If any child tasks are open, inform user and return to Phase 1.
+
+---
+
+## Phase 4: Setup Environment
+
+- **Create Feature Branch**
+  - Branch naming: Use task ID prefix + 3-5 words from title in kebab-case.
+- Run environment setup commands
+
+---
+
+## Phase 5: Retrieve Context
+
+### Deep Analysis
+
+Use @explore to understand:
+
+- Current architecture and patterns
+- Where new code should fit
+- Existing implementations that might conflict
+- Testing patterns to follow
+
+### Read Mentioned Files
+
+**CRITICAL:** Read files COMPLETELY - never use limit/offset parameters.
+
+Read every file mentioned in the task to understand its purpose, structure, and integration points.
+
+### Create Todo List
+
+Create an internal checklist tracking:
+
+- Implementation items (files, functions, integrations)
+- Verification items (tests, acceptance criteria)
+- Cleanup items (logging, docs, debug code removal)
+
+Update this list as you work - check off completed items, add discovered items.
+
+---
+
+## Phase 6: Implement the Plan
+
+### Implementation Philosophy
+
+**Your job:**
+
+- Follow the task's intent while adapting to reality
+- Make atomic, logical commits as you progress
+- Verify continuously (test as you go)
+- Be autonomous - implement fully before asking questions
+
+**You should NOT:**
+
+- Simplify code just to avoid diagnostics
+- Skip verification steps
+- Wait until the end to commit
+
+### Handle Mismatches
+
+**Only pause and ask when:**
+
+- The mismatch significantly impacts the implementation approach
+- You cannot make a reasonable decision autonomously
+- Following the task literally would break existing code
+
+**Present clearly:**
+
+```
+🛑 Mismatch Detected
+
+**Task Expected:** [what task says]
+**Actual Situation:** [what you found]
+**Why This Matters:** [impact analysis]
+
+**Options:**
+1. [Option A with trade-offs]
+2. [Option B with trade-offs]
+
+How should I proceed?
+```
+
+**Do NOT ask about:**
+
+- Minor naming differences
+- Import statement order
+- Formatting preferences (use project style)
+
+---
+
+## Phase 7: Validate Acceptance Criteria
+
+Before marking complete, verify ALL acceptance criteria from the task.
+
+Run quality gates (see AGENTS.md for standard commands):
+
+- Tests pass
+- Linting clean
+- Formatting correct
+- Type checking passes (if applicable)
+
+If any fail, fix and re-verify until all pass.
+
+---
+
+## Phase 8: Complete the Session
+
+```bash
+bd close <task_id> --reason "Completed" # Close task
+bd sync                                 # Sync beads database
+git status                              # Verify clean
+git commit -m "chore: sync beads"       # Commit beads issues changes (if relevant)
+git push -u origin <branch-name>        # Push branch
+git status                              # Verify push succeeded
+gh pr create --title "<Task Title>" \   # Submit the pull request
+  --body "<Why? and How? Changes Description>" \
+  --assignee @me \
+  --base main
+```
+
+### Summary
+
+Present completion summary:
+
+```
+✅ Task Completed: [task_id] - [Task Title]
+
+**Branch:** <branch-name>
+**Commits:** [N commits]
+
+**Files Changed:**
+- Created: [list]
+- Modified: [list]
+
+**Next Steps:**
+- Create PR from <branch-name> → main
+- Run `bd ready` for next task
+```
+
+---
+
+## Key Principles
+
+- **Autonomy First:** Only pause for significant mismatches
+- **Atomic Commits:** Commit at logical checkpoints throughout implementation
+- **Verify Continuously:** Test as you go, not just at end
+- **Read Completely:** Never use limit/offset when reading files
+- **Follow Intent:** Adapt plan to reality while honoring its purpose
+- **Branch per Task:** One task = one branch = one focused change
+
+---
+
+## Troubleshooting
+
+**Task is blocked:** Check `bd show <task_id>` for blockers. Work on blocker first or select different task.
+
+**Branch already exists:** Check `git status`. If clean, delete with `git branch -D <branch>`. If dirty, stash or commit first.
+
+**Tests failing:** Review failure output carefully. Fix root cause, don't simplify implementation.
+
+**Files not found:** If create task, that's expected. If modify task, verify paths with find/grep or ask if paths changed.
+
+**Acceptance criteria unclear:** Use best judgment based on task goal. Document assumptions in commit messages.
+
+---
+
+## Session Close Protocol
+
+**MANDATORY before saying "done":**
+
+```
+[ ] All tests passing (see AGENTS.md)
+[ ] All linting passing (see AGENTS.md)
+[ ] All changes committed (git status clean)
+[ ] Task closed in beads (bd close <task_id>)
+[ ] Branch pushed to remote (git push)
+[ ] Summary provided to user
+```
+
+**Never skip these steps.** Work is not done until pushed and closed.

package/src/assets/index.ts

@@ -0,0 +1,37 @@
+import { Glob, $ } from "bun";
+import * as path from "path";
+import { all, objectify, toResult } from "radashi";
+
+const MARKDOWNS = new Glob("**/*.md");
+
+export async function install(destination: string) {
+  const $$ = $.cwd(destination);
+
+  await $$`mkdir -p .opencode/command && mkdir -p .opencode/agent`;
+
+  const assets = await all(
+    objectify(
+      Array.from(MARKDOWNS.scanSync({ cwd: import.meta.dir })),
+      (fileName) => fileName,
+      async (fileName) => {
+        const parsed = path.parse(fileName);
+        const output = path.format({
+          ...parsed,
+          base: `mate.${parsed.base}`,
+          name: `mate.${parsed.name}`,
+        });
+
+        const [error] = await toResult(
+          $$`cp ${import.meta.dir}/${fileName} ${destination}/.opencode/${output}`.quiet(),
+        );
+
+        if (error)
+          console.error(`[opencode-teammate] Failed to install markdown '${fileName}'`, error);
+
+        return error === undefined;
+      },
+    ),
+  );
+
+  return assets;
+}

package/src/cli/commands/manifest.ts

@@ -0,0 +1,6 @@
+export default {
+  work: () => import("./work"),
+  spec: {
+    sync: () => import("./spec/sync"),
+  },
+};

package/src/cli/commands/spec/sync.ts

@@ -0,0 +1,47 @@
+import { defineCommand, option } from "@bunli/core";
+import { z } from "zod";
+import * as path from "node:path";
+
+import * as use from "../../../use-cases";
+import * as assets from "../../../adapters/assets";
+
+export default defineCommand({
+  name: "sync",
+  description: "Syncs the specifications with beads epics",
+  options: {
+    target: option(
+      z
+        .string()
+        .transform((t) => path.resolve(t))
+        .optional(),
+      {
+        description: "Specification file or directory to sync",
+        short: "t",
+      },
+    ),
+    watch: option(z.boolean().default(false), {
+      description: "Watch target for changes",
+      short: "w",
+    }),
+  },
+  handler: async ({ flags, cwd, colors, spinner }) => {
+    const project = "/Users/hugo/arion/d-gram";
+
+    const syncs = use.syncSpecifications({
+      project,
+      source: assets.specifications.use({
+        target: flags.target ?? cwd,
+        ignore: new Bun.Glob("thoughts/**/*.md"),
+        watch: flags.watch,
+      }),
+    });
+
+    if (flags.watch) spinner("Watching for changes...").start();
+
+    for await (const sync of syncs) {
+      const { asset, issue } = sync;
+      const filepath = path.relative(project, path.format(asset.filepath));
+      process.stdout.write(`\r\x1b[K${colors.bold(filepath)}: ${issue.id}\n`);
+    }
+  },
+});

package/src/cli/commands/work.ts

@@ -0,0 +1,110 @@
+import { defineCommand, option } from "@bunli/core";
+import { colors, type ColorFunction } from "@bunli/utils";
+import { z } from "zod";
+import { chain, counting, listify, Semaphore } from "radashi";
+
+import { poll, waitFor } from "../../utils/polling";
+import { createClient } from "../../utils/opencode";
+import * as projects from "../../utils/projects";
+import * as beads from "../../adapters/beads";
+import * as use from "../../use-cases";
+
+// - through a tool `i_am_stuck(boolean)`, integrate agent.status = "stuck" with beads
+//   - when the task is stuck, the RALPH loop should:
+//     - not close
+//     - not resolve
+//     - request for human jump in the session
+export default defineCommand({
+  name: "work",
+  alias: ["ralph"],
+  description: "Starts RALPH loop on opened tasks",
+  options: {
+    concurrency: option(z.coerce.number().min(1).default(1), {
+      description: "How many workers can be spawned at the same time",
+      short: "c",
+    }),
+    task: option(z.string().optional(), {
+      description:
+        "Task (including subtasks) to work on. When not provided, workers can be spawned for any ready tasks.",
+      short: "t",
+    }),
+    "wait-on-idle": option(z.boolean().default(false), {
+      description: "If no task is available, wait for one to become available.",
+    }),
+    "max-dispatches": option(z.coerce.number().min(1).default(Infinity), {
+      description: "Limit the number of tasks that can be dispatched to workers.",
+      short: "n",
+    }),
+    project: option(z.string().optional(), {
+      description:
+        "Project to work on. When not provided, workers can be spawned for any ready tasks.",
+      short: "p",
+    }),
+  },
+  handler: async ({ flags, colors }) => {
+    const client = await createClient({
+      loopUpForDesktopServer: true,
+    });
+    const directory = await projects.use(client, flags.project);
+    const shell = Bun.$.cwd(directory);
+    const dispatched = new Set<string>();
+
+    const { "wait-on-idle": waitOnIdle, "max-dispatches": maxDispatches } = flags;
+
+    const tasks = poll(
+      () =>
+        beads.issues.list.ready(shell, {
+          parent: flags.task,
+        }),
+      { interval: "1 second", exitOnEmpty: !waitOnIdle },
+    );
+
+    const semaphore = new Semaphore(flags.concurrency);
+
+    for await (const task of tasks) {
+      const permit = await semaphore.acquire();
+
+      dispatched.add(task.id);
+      use
+        .workOnIssue({
+          client,
+          directory,
+          issue: task,
+        })
+        .catch((error) => console.error(error))
+        .finally(() => permit.release());
+
+      if (dispatched.size >= maxDispatches) break;
+    }
+
+    // wait for all works to complete
+    await waitFor(
+      async () => semaphore.queueLength === 0 && semaphore.maxCapacity === semaphore.capacity,
+      { interval: "1 second" },
+    );
+
+    const issues = await beads.issues.list(shell, {
+      all: true,
+      ids: Array.from(dispatched.values()),
+    });
+
+    const counts = counting(issues, (issue) => issue.status);
+    const recap = listify(counts, (status, count) => {
+      const style = recapStyles[status] ?? colors.reset;
+      return style(`${count} ${status}`);
+    });
+
+    console.log(
+      colors.gray(`Dispatched: ${colors.italic(Array.from(dispatched.values()).join(", "))}`),
+    );
+    console.log(`Tasks: ${recap.join(", ")}`);
+  },
+});
+
+const recapStyles = {
+  open: chain(colors.yellow, colors.italic),
+  in_progress: chain(colors.yellow, colors.italic),
+  blocked: chain(colors.red, colors.bold, colors.underline),
+  deferred: colors.red,
+  closed: chain(colors.green, colors.bold),
+} as Record<string, ColorFunction>;

package/src/cli/index.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env bun
+
+import { createCLI } from "@bunli/core";
+
+import manifest from "./commands/manifest";
+
+const cli = await createCLI();
+
+await cli.load(manifest);
+
+await cli.run();

package/src/plugin.ts

@@ -0,0 +1,45 @@
+import type { Plugin } from "@opencode-ai/plugin";
+
+import * as assets from "./assets";
+import { register } from "./utils/opencode";
+import { chain } from "./utils/chain";
+import * as use from "./use-cases";
+import * as tools from "./tools";
+
+export const TeammatePlugin: Plugin = async (options) => {
+  const { directory } = options;
+
+  const client = await register(options);
+  await assets.install(directory);
+
+  return {
+    // event: async ({ event }) => {
+    //   const [error] = await toResult(use.trackSpecs(options, event));
+    //   if (error)
+    //     await client.app.log({
+    //       service: "opencode-teammate",
+    //       level: "error",
+    //       message:
+    //         error instanceof ShellError
+    //           ? error.stderr.toString()
+    //           : error.message,
+    //     });
+    // },
+    "command.execute.before": async (input, output) => {
+      await chain({ stopOnFatal: true }, () =>
+        use.injectBeadsIssue({
+          client,
+          directory,
+          input,
+          output,
+        }),
+      );
+    },
+    tool: {
+      i_am_stuck: tools.createIAmStuck(client),
+      i_am_done: tools.createIAmDone(client),
+    },
+  };
+};
+
+export default TeammatePlugin;

package/src/tools/i-am-done.ts

@@ -0,0 +1,44 @@
+import { tool } from "@opencode-ai/plugin";
+import type { OpencodeClient } from "@opencode-ai/sdk/v2/client";
+import { assert, dedent } from "radashi";
+
+import * as beads from "../adapters/beads";
+
+export const createIAmDone = (client: OpencodeClient) =>
+  tool({
+    description: dedent`
+    Inform your manager that you are done with the task. The manager will then review your work and handle the rest.
+    Use this tool when:
+    - All acceptance criteria are met and you have completed the task.
+    - Right before returning
+  `,
+    args: {},
+    execute: async (_args, ctx) => {
+      const session = await client.session.get({
+        sessionID: ctx.sessionID,
+        directory: ctx.directory,
+      });
+      assert(session.data, `Failed to fetch session: ${JSON.stringify(session.error)}`);
+
+      const message = await client.session.message({
+        sessionID: ctx.sessionID,
+        messageID: ctx.messageID,
+        directory: ctx.directory,
+      });
+      assert(message.data, `Failed to fetch session message: ${JSON.stringify(session.error)}`);
+
+      const { info } = message.data;
+
+      await beads.agents.done(Bun.$.cwd(session.data.directory), session.data.slug, {
+        context: {
+          agent: ctx.agent,
+          model: info.role === "user" ? info.model.modelID : info.modelID,
+          provider: info.role === "user" ? info.model.providerID : info.providerID,
+        },
+      });
+
+      return dedent`
+        You are marked as done. Your manager will review your work and come back to you if needed.
+      `;
+    },
+  });