goopspec: Instructions file for Codex

AGENTS.md

Guidelines for AI agents working in this codebase.

Build & Test Commands

bun install                                          # Install workspace dependencies
bun run --cwd packages/opencode-plugin build         # Build the plugin
bun run --cwd packages/opencode-plugin typecheck     # Type check the plugin
bun run --cwd packages/opencode-plugin test           # Run all plugin tests
bun run --cwd packages/opencode-plugin lint          # Run Biome lint on src
bun run --cwd packages/opencode-plugin lint:fix       # Fix Biome issues in src
bun run --cwd packages/opencode-plugin format        # Format src with Biome

# Testing
bun test packages/opencode-plugin/                   # Test plugin package
bun test packages/opencode-plugin/src/tools/goop-status/index.test.ts  # Single file
bun test -t "goop_status"                             # Tests matching name (regex)
bun test --changed=main                               # Only tests affected by git diff vs main (traces imports)
bun test --bail=3 --timeout=10000                     # Bounded run
bun test --watch                                      # Watch mode

⚠️ rtk test gotcha — HIGH severity

rtk bun test reports "0 passed / N skipped" for runs that actually execute thousands of tests. Only rtk proxy bun test ... is trustworthy. This caused real confusion during execution — a run that passed 1960 tests was reported as "0 passed / 44 skipped". Always use rtk proxy for test commands, never bare rtk.

Project Structure

packages/
└── opencode-plugin/       # @goopspec/opencode-plugin — MCP tools, hooks, and orchestration logic

packages/opencode-plugin/src/
├── core/                  # Types, config, resolver
├── tools/                 # MCP tool implementations
│   ├── goop-read-db/      # Read workflow docs from GoopSpecDB
│   ├── goop-write-db/     # Write/update workflow docs; auto-renders markdown sidecar
│   ├── goop-read-section/ # Read structured document sections
│   ├── goop-write-wave/   # Upsert wave/task progress rows
│   ├── goop-blocker/      # Open, resolve, and list workflow blockers
│   ├── goop-dashboard/    # Render cross-workflow dashboard
│   ├── goop-save-note/    # Save a Field Note to the global knowledge base
│   ├── goop-search-notes/ # Search Field Notes with FTS + tag filtering
│   └── ...                # Other tool directories
├── hooks/                 # OpenCode plugin hooks
├── features/              # Feature modules (memory, state, db, routing, model-routing)
│   └── db/                # GoopSpecDB — unified SQLite database (schema, migrations, types)
├── shared/                # Utilities (logger, paths)
├── test-utils.ts          # Shared test utilities
└── index.ts               # Plugin entry point

packages/opencode-plugin/
├── agents/                # 15 agent markdown definitions
├── commands/              # 9 slash command definitions
├── references/            # 19 consolidated reference documents (incl. field-notes-protocol)
└── templates/             # File templates