|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +Guidance for AI agents and developers working on `promptfoo/crabcode`. |
| 4 | + |
| 5 | +## Repository Purpose |
| 6 | + |
| 7 | +`crabcode` is a tmux-based multi-workspace manager for multi-repo development. The primary CLI is the Bash script in `src/crabcode`; it creates Git worktrees, manages tmux panes, saves/restores WIP state, integrates with Slack/Linear, and supports multiple coding agents. |
| 8 | + |
| 9 | +Codex is the default agent, but the codebase intentionally supports both Codex and Claude through the agent abstraction helpers in `src/crabcode`. Preserve that abstraction and avoid hardcoding one agent's session paths, CLI flags, or config file layout in new features. |
| 10 | + |
| 11 | +## Common Commands |
| 12 | + |
| 13 | +```bash |
| 14 | +# Run all local tests |
| 15 | +make test |
| 16 | + |
| 17 | +# Run Bats unit tests only |
| 18 | +make test-unit |
| 19 | + |
| 20 | +# Run integration tests |
| 21 | +make test-integration |
| 22 | + |
| 23 | +# Run integration or e2e tests in Docker |
| 24 | +make test-docker |
| 25 | +make test-e2e |
| 26 | + |
| 27 | +# Lint the main shell script |
| 28 | +make lint |
| 29 | + |
| 30 | +# Install the local CLI to /usr/local/bin |
| 31 | +make install |
| 32 | +``` |
| 33 | + |
| 34 | +For focused unit coverage while iterating on the agent abstraction, run: |
| 35 | + |
| 36 | +```bash |
| 37 | +./tests/bats/bin/bats tests/unit/test_agent_helpers.bats |
| 38 | +``` |
| 39 | + |
| 40 | +## Code Layout |
| 41 | + |
| 42 | +- `src/crabcode`: main CLI implementation and all workspace, agent, sync, Slack, WIP, and plugin commands. |
| 43 | +- `Makefile`: test, lint, Docker test, and install entrypoints. |
| 44 | +- `.github/workflows/test.yml`: Bats + Shellcheck CI with a required `CI Success` aggregate check. |
| 45 | +- `.github/workflows/release-please.yml`: release automation driven by Conventional Commit subjects. |
| 46 | +- `tests/unit/`: Bats tests for shell helper behavior. |
| 47 | +- `tests/run.sh` and `tests/e2e/`: integration and Dockerized end-to-end test harnesses. |
| 48 | +- `tests/MANUAL.md`: manual QA notes for scenarios that are hard to fully automate. |
| 49 | + |
| 50 | +## Implementation Rules |
| 51 | + |
| 52 | +- Keep shell changes compatible with `set -e` and existing Bash style in `src/crabcode`. |
| 53 | +- Prefer extending the agent helper functions (`get_agent_type`, `agent_*_for_type`, `agent_sync_*`) instead of branching directly on `claude` or `codex` throughout command handlers. |
| 54 | +- When adding repo-level agent instructions to generated workspaces, write to `AGENTS.md` for Codex mode and `.claude/CLAUDE.md` for Claude mode through the existing helper functions. |
| 55 | +- Keep user-facing command output concise and consistent with the existing colored status helpers (`info`, `success`, `warn`, `error`). |
| 56 | +- Do not commit generated runtime state from `~/.crabcode`, `.local/`, or test artifacts. |
| 57 | + |
| 58 | +## Validation |
| 59 | + |
| 60 | +- Run `make lint` after editing `src/crabcode`. |
| 61 | +- Run `make test-unit` for helper/command logic changes. |
| 62 | +- Run `make test-integration` or `make test-docker` when worktree, tmux, or filesystem behavior changes. |
| 63 | +- Run `make test-e2e` for risky changes to workspace lifecycle, agent startup, or plugin orchestration when Docker coverage is practical. |
| 64 | + |
| 65 | +## Git Workflow |
| 66 | + |
| 67 | +- Do not commit directly to `main`; use a feature branch and open a PR. |
| 68 | +- Use Conventional Commit subjects (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `build:`, `ci:`, `chore:`) so release-please can infer changelog entries and version bumps. |
| 69 | +- Keep PR descriptions specific about user-facing command changes and list the validation commands you ran. |
0 commit comments