opencode-agent-skills AGENTS.md

Agent Guidelines

Commands

• Package manager: Bun (not npm/yarn)
• Test: bun test or just test
• Single test: bun test path/to/file.test.ts or bun test --grep "pattern"
• Typecheck: bun run typecheck (runs tsc --noEmit)
• Build: just build

Code Style

• TypeScript strict mode with noUncheckedIndexedAccess - always check array/object access
• ES modules - use import/export, no CommonJS
• Node imports - use node: prefix (e.g., import * as fs from "node:fs/promises")
• Zod for runtime validation schemas
• Naming: camelCase for functions/variables, PascalCase for types/interfaces
• JSDoc comments (/** */) for public functions
• Error handling: try/catch with graceful fallbacks; silent catches OK for optional operations
• Async/await - prefer over raw promises
• Path safety: validate user paths don't escape base directories using path.resolve

Project Structure

• Single plugin file at src/plugin.ts
• Plugin exports a single Plugin function that returns tools and event handlers

Issue Tracking with bd (beads)

IMPORTANT: This project uses bd (beads) for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.

Why bd?

• Dependency-aware: Track blockers and relationships between issues
• Git-friendly: Auto-syncs to JSONL for version control
• Agent-optimized: JSON output, ready work detection, discovered-from links
• Prevents duplicate tracking systems and confusion

Quick Start

Check for ready work:

bd ready --json

Create new issues:

bd create "Issue title" -t bug|feature|task -p 0-4 --json
bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
bd create "Subtask" --parent <epic-id> --json  # Hierarchical subtask (gets ID like epic-id.1)

Claim and update:

bd update bd-42 --status in_progress --json
bd update bd-42 --priority 1 --json

Complete work:

bd close bd-42 --reason "Completed" --json