kagan AGENTS.md

AGENTS.md

Kagan is an OpenCode plugin that supervises coding tasks on a kanban board, with one git worktree per task. Before changing lifecycle behavior, read .specs/README.md for the spec authority and read order. src/domain/task/metadata.ts is the authoritative metadata schema.

Commands

• Use Bun 1.3 or newer; CI pins 1.3.14. Run bun install, then bun run setup once after cloning to enable the .githooks/pre-commit hook.
• bun run verify is the agent-facing curated gate. It runs the declared source complexity, comment, and circular-dependency checks, auto-formats with oxfmt, plus the local test script.
• bun run check is the full check-only gate used by pre-commit and CI. It runs verifyx all --check, including its automatic test step, then package validation. CI checkout fetches full history so the new-comment check compares against the PR merge base.
• Run one built-in check with bunx verifyx lint, bunx verifyx format, bunx verifyx check-types, or bunx verifyx duplicate-code. Use bun run package for package checks.
• verify:complexity is two-tier: pure logic (src/**/*.ts excluding src/tui/** and src/tui.tsx) must clear maintainability index 52; the TUI surface (src/tui/**/*.{ts,tsx}, src/tui.tsx) clears 50 because its JSX render functions are inherently lower-scoring. Simplify the failing function first; split only when responsibilities genuinely diverge. Merging or unsplitting is valid when cohesion beats MI churn from artificial file boundaries. Use verifyx complexity --sloc-scope function to score SLOC from each function body instead of the whole file. Never game the metric by deleting comments, joining lines, or fragmenting a coherent function. The exact command is pinned by test/guards/validation.test.ts.
• Run the full suite with bun run test, not bare bun test. The script supplies --conditions browser; bunfig.toml supplies the Solid preload. Bun positional test filters can also match a local gitignored references/ checkout because its exclude applies only to test discovery.
• Focus a test with an anchored path and the browser condition, for example bun test ./test/domain/task/policy.test.ts --conditions browser.
• bun run plugin:install installs a raw development snapshot globally. Re-run it after source edits and restart OpenCode. bun run plugin:install:prod installs the packed production artifact; bun run plugin:reset removes Kagan from global OpenCode config.