AGENTS.md · alvinunreal/oh-my-opencode-slim

Sections

1. Project Overview
2. Commands
3. Code Style
4. Project Structure
5. Key Dependencies
6. Development Workflow
7. Release Workflow
8. Prompt Cache Safety
9. Pre-Push Code Review
10. Repository Map
11. Debugging Issues
12. Cloned Dependency Source
13. Agent Operating Context

First lines (shown under the repo's MIT license)

# Agent Coding Guidelines

This document provides guidelines for AI agents operating in this repository.

## Project Overview

**oh-my-opencode-slim** - A lightweight agent orchestration plugin for OpenCode, a slimmed-down fork of oh-my-opencode. Built with TypeScript, Bun, and Biome.

## Design Constraints

oh-my-opencode-slim is a **lightweight harness**. Every change is reviewed against:

- **Lightweight first** — adopt the smallest implementation that meets the requirement; no speculative abstraction, redundant configuration, or unnecessary indirection.
- **No duplicate design** — when OpenCode v2 already owns a mechanism, reuse or observe it instead of building a parallel plugin-side state machine. Check the pinned host source under `.slim/clonedeps/repos/opencode/` before adding plugin-side machinery.
- **One source of truth for tool instructions** — tool usage lives in tool descriptions; never restate it in agent prompts. When prompt prose and a tool description overlap, deleting the prose is the preferred change.
- **Model-facing bytes are a budget** — prompts and tool descriptions are paid on every request, in every preset. Removal is the preferred change; an addition must state the behavior it buys, verified by rendering and counting, and must serve the cheapest supported preset, not just the dev default.

## Commands

| Command | Description |
|---------|-------------|
| `bun run build` | Build TypeScript to `dist/` (both index.ts and cli/index.ts) |
| `bun run typecheck` | Run TypeScript type checking without emitting |
| `bun test` | Run all tests with Bun |
| `bun run lint` | Run Biome linter on entire codebase |
| `bun run format` | Format entire codebase with Biome |
| `bun run check` | Run Biome check with auto-fix (lint + format + organize imports) |
| `bun run check:ci` | Run Biome check without auto-fix (CI mode) |
| `bun run dev` | Build and run with OpenCode |

**Running a single test:** Use Bun's test filtering with the `-t` flag:
```bash
bun test -t "test-name-pattern"
```

## Code Style

### General Rules
- **Formatter/Linter:** Biome (configured in `biome.json`)
- **Line width:** 80 characters
- **Indentation:** 2 spaces
- **Line endings:** LF (Unix)
- **Quotes:** Single quotes in JavaScript/TypeScript
- **Trailing commas:** Always enabled

### TypeScript Guidelines
- **Strict mode:** Enabled in `tsconfig.json`
- **No explicit `any`:** Generates a linter warning (disabled for test files)
- **Module resolution:** `bundler` strategy
- **Declarations:** Generate `.d.ts` files in `dist/`

### Imports
- Biome auto-organizes imports on save (`organizeImports: "on"`)
- Let the formatter handle import sorting
- Use path aliases defined in TypeScript configuration if present

### Naming Conventions
- **Variables/functions:** camelCase
- **Classes/interfaces:** PascalCase
- **Constants:** SCREAMING_SNAKE_CASE
- **Files:** kebab-case for most, PascalCase for React components

### Error Handling
- Use typed errors with descriptive messages
- Let errors propagate appropriately rather than catching silently
- Use Zod for runtime validation (already a dependency)

### Test Time
- Tests never bind to real time (`ts-no-test-timers`): no `Bun.sleep()`,
  guessed `setTimeout` waits, or duration-based settling.
- Drive timer code deterministically with `src/utils/test-timers.ts`
  (`createTimerHarness`, `tick`). Scheduling components accept injected
  `setTimeout`/`clearTimeout` seams (see `BackgroundJobSupervisor`,
  `createBackgroundJobTerminalGate`); wire the harness there, not via
  global spies.
- Keep observation-time (`now`) seams separate from scheduling when event
  timestamps are the subject of the test.
- Integration tests that exercise real platform timing may keep a real
  delay: keep rare and comment why deterministic control will not work.

### Git Integration
- Biome integrates with git (VCS enabled)
- Commits should pass `bun run check:ci` before pushing

## Project Structure

```
oh-my-opencode-slim/
├── src/
│   ├── agents/       # Agent factories (orchestrator, explorer, oracle, etc.)
│   ├── cli/          # CLI entry point
│   ├── config/       # Constants, schemas, MCP defaults
│   ├── hooks/        # OpenCode lifecycle hooks
│   ├── mcp/          # MCP server definitions
│   ├── multiplexer/  # Tmux/Zellij pane integration for child sessions
│   ├── skills/       # Skill definitions (included in package publish)
│   ├── tools/        # Tool definitions (webfetch, AST-grep, etc.)
│   └── utils/        # Shared utilities (session, task, logger, env, etc.)
├── dist/             # Built JavaScript and declarations
├── docs/             # User-facing documentation
├── biome.json        # Biome configuration
├── tsconfig.json     # TypeScript configuration
└── package.json      # Project manifest and scripts
```

## Key Dependencies

- `@opencode-ai/plugin` - OpenCode server and TUI plugin contracts
- `@opencode-ai/sdk` - OpenCode AI SDK
- `@opentui/core` / `@opentui/solid` - Optional TUI rendering stack
- `zod` - Runtime validation

## Development Workflow

1. Make code changes
2. Update docs when behavior, commands, configuration, workflows, or user-facing output changes
   - Check `README.md` plus relevant files in `docs/`
   - Keep examples, command snippets, and feature lists in sync with the code
   - If no doc update is needed, explicitly confirm that in your final summary
3. Run `bun run check:ci` to verify linting and formatting
4. Run `bun run typecheck` to verify types
5. Run `bun test` to verify tests pass
6. Commit changes. Eval outputs are ignored run artifacts; do not commit edits made by eval sessions.

## Release Workflow

For plugin or Companion releases, follow `docs/release.md`. It documents the
required diff inspection, companion asset workflow, GitHub release creation,
tagging, verification, and npm publish order.

## Prompt Cache Safety

Provider prompt caches are exact byte-prefix matches over the rendered
request (tools → system → messages). Any byte that changes earlier in the
payload invalidates the cache for everything after it, so every request in
the session re-pays full input cost and latency. Past regressions in this
repo all came from hooks rewriting or repositioning earlier conversation
content.

Rules when touching anything that feeds the outgoing payload (hooks,
agent prompts, config constants):

- Inject content only through `src/hooks/cache-safe-injection.ts`:
  deterministic content via `appendTaggedSyntheticPart` (tail of an existing
  message), per-turn volatile content via `stripTaggedContent` +
  `appendTrailingVolatileMessage` (trailing message, end of payload).
- Never mutate or reorder earlier messages, and never let timestamps,
  randomness, or per-request IDs reach content before the payload tail.
- Keep system prompts and tool sets frozen for the lifetime of a session.

Enforcement (all run in `bun test` / CI):

- `src/hooks/cache-safety.property.test.ts` — prefix-stability and
  determinism properties over the real transform pipeline, with a drift
  guard pinned to the composition in `src/index.ts`. New transform steps
  must be added to `src/hooks/cache-safety-harness.test.ts`.
- `src/hooks/cache-payload.snapshot.test.ts` — golden snapshots of injected
  prompt surfaces; failing means the change busts caches once fleet-wide and
  must be updated deliberately via `bun test --update-snapshots`.
- `src/cache-safety-tripwire.test.ts` — bans volatile-input patterns in