opencode-teammate 0.1.0

package/src/adapters/beads/issues.ts

@@ -0,0 +1,156 @@
+import { assert, first, isEmpty } from "radashi";
+
+// import * as shell from "#utils/shell/index.js";
+import * as shell from "../../utils/shell/index.js";
+
+export type Issue = {
+  id: string;
+  title: string;
+  status: string;
+  created_at: string;
+  external_ref?: string;
+  assignee?: string;
+};
+
+export interface ListOptions {
+  all?: boolean;
+  ids?: string[];
+  type?: string;
+  assignee?: string;
+  status?: "open" | "in_progress" | "blocked" | "deferred" | "closed";
+  sort?:
+    | "priority"
+    | "created"
+    | "updated"
+    | "closed"
+    | "status"
+    | "id"
+    | "title"
+    | "type"
+    | "assignee";
+}
+
+export interface ListReadyOptions {
+  parent?: string;
+  type?: string;
+  unassigned?: boolean;
+  assignee?: string;
+  sort?: "hybrid" | "priority" | "oldest";
+}
+
+export const list = Object.assign(
+  async (client: shell.client.ClientInput, options: ListOptions = {}) => {
+    if (isEmpty(options.ids)) return [];
+
+    const $ = shell.client.use(client);
+
+    const issues = await $<Issue[]>`bd list ${options} --json`.json();
+
+    return issues;
+  },
+  {
+    ready: async (client: shell.client.ClientInput, options: ListReadyOptions = {}) => {
+      const $ = shell.client.use(client);
+
+      const issues = await $<Issue[]>`bd ready ${options} --json`.json();
+
+      return issues;
+    },
+  },
+);
+
+export interface UseOptions {
+  /** Force re-fetching the issue */
+  force?: boolean;
+}
+
+export async function use(
+  client: shell.client.ClientInput,
+  input: { id: string } | Issue,
+  options?: UseOptions,
+) {
+  if ("status" in input && !options?.force) return input;
+
+  return first(
+    await list(client, {
+      ...options,
+      ids: [input.id],
+    }),
+  );
+}
+
+export interface UpdateOptions {
+  "add-label"?: string[] | string;
+  description?: string;
+}
+
+export async function update(
+  client: shell.client.ClientInput,
+  input: { id: string },
+  options: UpdateOptions = {},
+) {
+  const $ = shell.client.use(client);
+
+  const issues = await $<Issue[]>`bd update ${input.id} ${options} --json`.json();
+
+  const [issue] = issues;
+  assert(issue, `Issue '${input.id}' not found`);
+
+  return issue;
+}
+
+export interface ClaimOptions {
+  /** Assignee of the issue */
+  actor?: string;
+}
+
+export async function claim(
+  client: shell.client.ClientInput,
+  input: { id: string },
+  options: ClaimOptions = {},
+) {
+  const $ = shell.client.use(client);
+
+  const issues = await $<Issue[]>`bd update ${input.id} ${options} --claim --json`.json();
+
+  const [issue] = issues;
+  assert(issue, `Issue '${input.id}' not found`);
+
+  return issue;
+}
+
+export interface CloseOptions {
+  /** Reason for closing the issue */
+  reason?: string;
+}
+
+export async function close(
+  client: shell.client.ClientInput,
+  input: { id: string },
+  options: CloseOptions = {},
+) {
+  const $ = shell.client.use(client);
+
+  const issues = await $<Issue[]>`bd close ${input.id} ${options} --json`.json();
+
+  const [issue] = issues;
+  assert(issue, `Issue '${input.id}' not found`);
+
+  return issue;
+}
+
+export async function show(client: shell.client.ClientInput, input: { id: string }) {
+  const $ = shell.client.use(client);
+  return $`bd show ${input.id}`.text();
+}
+
+export namespace find {
+  export async function byExternalRef(
+    client: shell.client.ClientInput,
+    ref: string,
+    options?: ListOptions,
+  ) {
+    const _issues = await list(client, options);
+    return _issues.find((data) => data.external_ref === ref);
+  }
+}

package/src/adapters/beads/specifications.ts

@@ -0,0 +1,55 @@
+import { assert } from "radashi";
+
+// import * as shell from "#utils/shell/index.js";
+import * as shell from "../../utils/shell/index.js";
+
+import * as issues from "./issues";
+
+export type SpecificationInput = {
+  file: string;
+  title: string;
+  description: string;
+};
+
+export async function create(client: shell.client.ClientInput, data: SpecificationInput) {
+  const $ = shell.client.use(client);
+
+  const options = {
+    title: data.title,
+    description: data.description,
+    "external-ref": data.file,
+  };
+
+  const issue = await $<issues.Issue>`bd create --type epic ${options} --json`.json();
+
+  return issue;
+}
+
+export async function update(
+  client: shell.client.ClientInput,
+  input: { id: string },
+  data: SpecificationInput,
+) {
+  const $ = shell.client.use(client);
+
+  const options = {
+    title: data.title,
+    description: data.description,
+    "external-ref": data.file,
+  };
+
+  const _issues = await $<
+    issues.Issue[]
+  >`bd update ${input.id} --type epic ${options} --json`.json();
+
+  const [issue] = _issues;
+  assert(issue, `Issue '${input.id}' not found`);
+
+  return issue;
+}
+
+export namespace find {
+  export function byExternalRef(client: shell.client.ClientInput, ref: string) {
+    return issues.find.byExternalRef(client, ref, { type: "epic" });
+  }
+}

package/src/adapters/environments/index.ts

@@ -0,0 +1,43 @@
+import { $ } from "bun";
+import type { OpencodeClient, Worktree } from "@opencode-ai/sdk/v2/client";
+
+import * as polling from "../../utils/polling";
+
+import * as worktrees from "./worktrees";
+
+export class WorkerEnvironment {
+  public readonly ready: Promise<boolean>;
+
+  constructor(
+    private readonly client: OpencodeClient,
+    private readonly directory: string,
+    public readonly worktree: Worktree,
+  ) {
+    this.ready = polling.waitFor(() => worktrees.isReady(worktree), {
+      interval: "100ms",
+    });
+  }
+
+  public get $() {
+    return $.cwd(this.worktree.directory);
+  }
+
+  static async init(options: worktrees.InitOptions) {
+    const worktree = await worktrees.init(options);
+
+    const env = new WorkerEnvironment(options.client, options.directory, worktree);
+    await env.ready;
+
+    return env;
+  }
+
+  async [Symbol.asyncDispose]() {
+    await worktrees
+      .remove({
+        client: this.client,
+        directory: this.directory,
+        worktreeDirectory: this.worktree.directory,
+      })
+      .catch((error) => console.error(error));
+  }
+}

package/src/adapters/environments/worktrees.ts

@@ -0,0 +1,78 @@
+import type { OpencodeClient } from "@opencode-ai/sdk/v2/client";
+import { prompt } from "@bunli/utils";
+import { assert, Semaphore } from "radashi";
+import * as fs from "node:fs/promises";
+
+import * as projects from "../../utils/projects";
+
+const semaphore = new Semaphore(1);
+
+export interface InitOptions {
+  client: OpencodeClient;
+  directory: string;
+  name: string;
+}
+
+export async function init(options: InitOptions) {
+  const { client, directory } = options;
+
+  const permit = await semaphore.acquire();
+
+  try {
+    const project = await client.project.current({ directory });
+    assert(project.data, `Failed to initialize environment: ${project.error}`);
+
+    const projectLabel = projects.getProjectLabel(project.data);
+
+    if (!project.data.commands?.start) {
+      const shouldContinue = await prompt.confirm(
+        `Opencode project ${projectLabel} does not have a start command. Do you want to continue?`,
+        { default: false },
+      );
+      assert(shouldContinue, `Failed to initialize environment: user asked to stop`);
+    }
+
+    const worktree = await client.worktree.create({
+      directory,
+      worktreeCreateInput: {
+        name: options.name,
+      },
+    });
+    assert(worktree.data, `Failed to initialize worktree: ${JSON.stringify(worktree.error)}`);
+
+    return worktree.data;
+  } finally {
+    permit.release();
+  }
+}
+
+export interface RemoveOptions {
+  client: OpencodeClient;
+  directory: string;
+  worktreeDirectory: string;
+}
+
+export async function remove(options: RemoveOptions) {
+  const { client, directory } = options;
+
+  const worktree = await client.worktree.remove({
+    directory,
+    worktreeRemoveInput: {
+      directory: options.worktreeDirectory,
+    },
+  });
+  assert(worktree.data, `Failed to remove worktree: ${JSON.stringify(worktree.error)}`);
+
+  console.log("Worktree removed");
+
+  return worktree.data;
+}
+
+export async function isReady(options: { directory: string }) {
+  const existings = await Promise.all([
+    fs.exists(`${options.directory}/.opencode`),
+    fs.exists(`${options.directory}/.git`),
+  ]);
+
+  return existings.every((exists) => exists);
+}

package/src/adapters/teammates/index.ts

@@ -0,0 +1,15 @@
+import type { Session } from "@opencode-ai/sdk";
+
+const ID_TO_TEAMMATE = new Map<string, string>();
+
+export function get(sessionId: string) {
+  return ID_TO_TEAMMATE.get(sessionId);
+}
+
+export function createFromSession(session: Session) {
+  const teammate = "slug" in session ? (session.slug as string) : session.id;
+
+  ID_TO_TEAMMATE.set(session.id, teammate);
+
+  return teammate;
+}

package/src/assets/agent/planner.md

@@ -0,0 +1,196 @@
+---
+description: Bridge between human specs and the codebase through an implementation plan stored in Beads.
+mode: subagent
+model: github-copilot/claude-sonnet-4.5
+temperature: 0
+tools:
+  write: false
+  edit: false
+  patch: false
+  question: false
+permissions:
+  bash:
+    "*": deny
+    "bd *": allow
+---
+
+# Planner
+
+You are a non-interactive subagent responsible for reconciling the Beads implementation plan with the current state of a specification. You receive a Beads Epic ID as input and ensure the implementation tasks are synchronized with the related specification.
+
+<user_prompt>
+$ARGUMENTS
+</user_prompt>
+
+---
+
+## Phase 1: Context Acquisition
+
+### 1.1 Load Epic Details
+
+Retrieve the Epic and its current children:
+
+```bash
+bd show <epic-id> --json
+bd list --parent=<epic-id> --json
+```
+
+Extract from the Epic description:
+
+- **Spec Reference**: The path to the related specification file (e.g., `specs/<filename>.md`)
+
+### 1.2 Read Current Specification
+
+Read the specification file referenced in the Epic to understand the current requirements.
+
+### 1.3 Identify Changes
+
+Compare the current specification against existing tasks:
+
+- New requirements not covered by existing tasks
+- Removed requirements with orphaned tasks
+- Modified requirements requiring task updates
+
+---
+
+## Phase 2: Design Implementation Tasks
+
+Break down specifications into **atomic implementation tasks** suitable for single agent sessions.
+
+### 2.1 Task Design Criteria
+
+Each task MUST satisfy ALL of the following:
+
+- **Small Scope**: Completable in a single agent session (1-3 hours of focused work)
+- **Clear I/O**: Explicit inputs (files to read, dependencies) and outputs (files created/modified, tests passing)
+- **Testable**: Clear verification path (unit tests, integration tests, or manual verification steps)
+- **File-Aware**: Include specific file paths when known (e.g., "Create `src/core/event_emitter.py`")
+- **Self-Contained**: Understandable without reading other tasks
+
+### 2.2 Task Description Structure
+
+Each task description should follow this format:
+
+```
+**Goal**: [1-2 sentence summary of what this accomplishes]
+
+**Files to Create/Modify**:
+- path/to/file1.py
+- path/to/file2.py
+
+**Implementation**:
+[Detailed breakdown including:]
+- Key functions/classes to create
+- Important algorithms or logic flows
+- Integration points with existing code
+
+**Acceptance**:
+[Clear verification criteria:]
+- Unit tests pass: [specific test names or scenarios]
+- Manual verification: [specific steps if needed]
+```
+
+### 2.3 Task Breakdown Strategy
+
+When analyzing a specification, break it down following this hierarchy:
+
+1. **Infrastructure First**: Test mocks, configuration, base classes
+2. **Core Logic**: Main algorithms, data structures, business logic
+3. **Integration**: Connect components together
+4. **Validation**: Tests, error handling, edge cases
+5. **Polish**: Documentation, logging, refinements
+
+---
+
+## Phase 3: Execute Reconciliation
+
+**🚨 CRITICAL**: ALL tasks MUST be created with `--parent <epic-id>` flag to establish Epic hierarchy.
+
+### 3.1 Create New Tasks
+
+For each new requirement identified:
+
+```bash
+bd create --title "<Task Title>" --type task --parent <epic-id> --description "<description>"
+```
+
+### 3.2 Update Modified Tasks
+
+For tasks requiring updates:
+
+```bash
+bd update <task-id> --description "<updated-description>"
+```
+
+### 3.3 Close Deprecated Tasks
+
+For requirements that have been removed:
+
+```bash
+bd close <task-id> --reason "Requirement removed from specification"
+```
+
+### 3.4 Manage Dependencies
+
+Link task dependencies:
+
+```bash
+bd dep add <blocked-task> <blocker-task>
+```
+
+---
+
+## Phase 4: Report Changes
+
+Output a clear summary of all changes made:
+
+```
+## Reconciliation Summary for Epic: <epic-id>
+
+**Specification**: specs/<filename>.md
+
+### Tasks:
+
+#### 1. [Task Title] (Priority: P1)
+   - **Goal**: [What this accomplishes]
+   - **Dependencies**: [None | Blocked by: Task X]
+
+#### 2. [Task Title] (Priority: P2)
+   - **Goal**: [What this accomplishes]
+   - **Dependencies**: [Blocked by: Task 1]
+
+[Continue for all tasks...]
+
+### Tasks Closed:
+- `<task-id>`: <task-title> — <reason for closure>
+
+### Task Dependency Graph:
+```
+
+Task 1 (Infrastructure)
+↓
+Task 2 (Core Logic) → Task 3 (Core Logic)
+↓ ↓
+Task 4 (Integration) ←---┘
+↓
+Task 5 (Validation)
+
+```
+
+### No Changes:
+[If no changes were needed, state: "Implementation plan is already in sync with specification."]
+```
+
+---
+
+## Key Principles
+
+- **Specs are the WHAT:** Requirements, user scenarios, success criteria
+- **Beads are the HOW:** Implementation tasks, technical breakdown, execution order
+- **Non-Interactive**: Execute reconciliation without user prompts
+- **Epic Hierarchy**: ALWAYS use `--parent <epic-id>` when creating tasks
+- **Traceability**: The Epic contains the spec reference; child tasks don't need to repeat it
+- **Be Atomic**: Tasks should be independently completable and testable
+- **Think Dependencies**: Make blocking relationships explicit in the task graph
+- **Use `bd update`**: NEVER use `bd edit` — always use `bd update` for modifications
+- **Report Clearly**: Output a concise summary of all changes made

package/src/assets/command/brainstorm.md

@@ -0,0 +1,60 @@
+---
+name: brainstorm
+model: github-copilot/claude-sonnet-4.5
+agent: plan
+description: "Help turn ideas into fully formed designs and specs through natural collaborative dialogue."
+---
+
+# Brainstorming Ideas Into Designs
+
+## Overview
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
+
+<brainstorming_subject>
+$ARGUMENTS
+</brainstorming_subject>
+
+## 1. The Process
+
+**Understanding the idea:**
+
+- Check out the current project state first (files, docs, recent commits): use the @codebase-analyser to get advanced insights on the codebase
+- Ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+- Reply to the user's question: bidirectional flow helps both parties to align on the idea
+
+**Exploring approaches:**
+
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+
+- Once you believe you understand what you're building, present the design
+- Break it into sections of 200-300 words
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+## 2. The Design Redaction
+
+**Documentation:**
+
+- Write the validated design to `specs/thoughts/YYYY-MM-DD-<topic>.md`
+- Use elements-of-style:writing-clearly-and-concisely skill if available
+- Commit the design document to git
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design in sections, validate each
+- **Be flexible** - Go back and clarify when something doesn't make sense