tangerine: Instructions file for Codex

Tangerine

Local background coding agent platform. Configured ACP-compatible local agents + web dashboard.

Setup

1. Read specs/architecture.md and specs/v0-scope.md
2. bun install
3. bun link (make tangerine available globally)
4. bun run check before commit

Structure

packages/
  shared/src/      # @tangerine/shared — types, config schema, constants
  server/src/
    api/           # Hono server (REST + WebSocket + test/webhook routes)
    agent/         # ACP client runtime + configured agent command abstraction
    tasks/         # Task lifecycle, cleanup, health, retry, PR/worktree management
    integrations/  # GitHub webhook handler + polling
    db/            # SQLite schema + queries
web/
  src/             # Vite + React dashboard
specs/             # Architecture and design docs
skills/            # Agent skill definitions (tangerine-tasks, platform-setup)

Key Decisions

• ACP-only: configured ACP-compatible commands behind one AgentFactory abstraction
• Local-server architecture: agents spawn locally, not in per-project VMs
• Git worktrees for task isolation
• Project-agnostic: each project defines setup + test commands
• Multiplayer-ready data model (user_id nullable for v0)
• Local-first, upgradeable to hosted

Related Projects

• orange: ~/workspace/orange/ — workflow engine (future integration)
• External ACP adapters: Claude Agent, Codex ACP, OpenCode ACP, Pi, or custom commands

Rules

• Bun runtime, bun:test for tests
• No any
• Commits: type(scope): msg
• Comments explain "why" not "what"
• Keep specs up to date: When changing architecture, DB schema, APIs, or agent providers, update the corresponding file in specs/. Specs are the source of truth for design decisions — stale specs cause bugs.
• Spec-first for new features: New features or architecture changes → write/update the spec before coding. Bug fixes, small refactors, spikes → code first, update specs if architecture changed. At the start of each task, ask: "Does this need a spec update first?"
• Gate UI on capabilities, not titles: Use task.capabilities.includes("feature") to show/hide UI features per task type. Use task.type (worker/reviewer/runner) as the source of truth for task behavior — capabilities are derived from type in manager.ts. Add new capabilities in shared/types.ts → assign by type in manager.ts → check in UI.
• Never prompt a running worker with new scope: /prompt is only for unblocking or clarifying a worker's existing scope. New or unrelated requirements must go in a new task — never tacked onto a running one via /prompt.
• Skills live in skills/: When updating agent skills (tangerine-tasks, platform-setup), edit skills/<name>/SKILL.md in this repo — not ~/.claude/skills/. The repo is the source of truth.
• Daemon vs foreground startup: tangerine start runs as a detached daemon — the server process (start.ts) writes stdout/stderr to the log file, not the terminal. Anything a user needs to see at startup (errors, warnings, URLs) must be printed in daemon.ts (the launcher), not start.ts. When touching startup output or checks, ask: "Will the user see this in daemon mode?"
• No inline duplication: If the same logic appears in more than one place, extract it into a shared module immediately. Don't copy-paste and adjust — find the right abstraction level and put it there once.