# AGENTS

## Scope
- This file defines project-specific rules and configuration for agents working in this repository.

## Session Workflow
- Keep entries concise and timestamped in UTC.
- Stage newly created files explicitly:
  - `git add <new-file>`

## Validation Commands
- Run formatting after every code change:
  - `go fmt ./...`
- Prefer targeted validation while iterating; run broader validation before finishing:
  - Format: `go fmt ./...`
  - Vet: `go vet ./...`
  - Test: `go test ./...`

## Language Rules
- Use English for code comments, log/output messages, `README.md`.

## PR Policy
- Feature PRs use `aide pr`.
- `aide pr` writes the Summary, Breaking Changes, Included Commits, and Test Plan sections for feature PRs.
- A PR to `main` remains mandatory for user-reviewed changes.

## Git Rules
- Work in the current branch.

<!-- agentinit:managed:start -->
## Documentation Rules
- Every change to behavior, interfaces, workflows, or configuration must include corresponding updates to affected documentation and code comments in the same commit.
- Documentation accuracy is part of implementation scope, not a follow-up task.
- The planner must include documentation update scope explicitly in the plan whenever behavior, interfaces, workflows, or configuration change. Documentation updates are implementation scope, not a follow-up task.

## Hard Rules
- Never include `Co-Authored-By` trailers in commit messages.

## AI Workflow Rules
- Plan Mode:
  - waits for explicit user start signal
  - writes `.ai/PLAN.md`
  - updates `.ai/TASKS.md` status to `ready_for_implement`
  - appends a handoff entry to `.ai/HANDOFF.md`
  - never edits code
- Review Mode:
  - waits for explicit user start signal
  - writes `.ai/REVIEW.md`
  - updates `.ai/TASKS.md` status to `ready_to_commit` or `changes_requested`
  - appends a handoff entry to `.ai/HANDOFF.md`
  - performs review plus verification, including E2E and exploratory checks when appropriate
  - never edits code
- Implement Mode (`next_task`):
  - waits for explicit user start signal
  - implements `.ai/PLAN.md`
  - writes or updates tests for each changed behaviour before writing implementation code
  - updates affected documentation and code comments whenever behavior, interfaces, or workflows change
  - writes the final Conventional Commit message into the HANDOFF entry `Commit` field
  - does not `git commit`
  - updates `.ai/TASKS.md` status to `ready_for_review`
  - appends a handoff entry to `.ai/HANDOFF.md`
  - must not invent requirements
- Implement Mode (`commit_task` after review):
  - only for tasks in `ready_to_commit`
  - reads the commit message from the task's `next_task` HANDOFF entry
  - updates `.ai/TASKS.md` status to `done`
  - appends a handoff entry to `.ai/HANDOFF.md`
  - runs `git add -A && git commit -m "<message>"`
- Implement Mode (rework after rejection):
  - reads `.ai/REVIEW.md` findings as a checklist
  - addresses every finding marked as required fix
  - re-runs validations
  - does not `git commit`
  - updates `.ai/TASKS.md` status from `changes_requested` to `ready_for_review`
  - appends a handoff entry to `.ai/HANDOFF.md`

## AI Operating Mode
- Mode is selected by the launcher prompt/context:
  - Cycle bootstrap:
    - `aide cycle start <branch-name>`
  - Convenience wrappers:
    - `aide plan [agent] [agent-options...]` (default agent from `.ai/config.json`, fallback: `claude`)
    - `aide implement [agent] [agent-options...]` (default agent from `.ai/config.json`, fallback: `codex`)
    - `aide review [agent] [agent-options...]` (default agent from `.ai/config.json`, fallback: `claude`)
    - `aide po [agent] [agent-options...]` (launcher for the PO orchestration session)
- No `.ai/MODE` file is used.

## Modes
- `profile` in `.ai/config.json` selects the workflow shape:
  - `full` is the default profile.
  - `lite` replaces separate implementer/reviewer sessions with one `aide dev` session.
- `full` profile:
  - launch `aide plan`, `aide implement`, and `aide review` yourself in manual mode
  - optionally launch `aide po` for auto mode orchestration
  - keep the usual implementer -> reviewer -> implementer commit handoff
- `lite` profile:
  - launch `aide plan` and `aide dev`
  - implementation, review, and commit happen inside the dev session
  - Human approval still happens at `ready_for_review` in lite mode.
  - PO orchestration is not available
- Lite-mode status ownership:
  - planner still owns planning states
  - the dev session owns `in_implementation`, `in_review`, `ready_to_commit`, and `done`
  - `ready_for_review` remains the explicit human checkpoint before `commit_task`
- Lite-mode test guardrail:
  - During the review hat, if a test fails you may either change implementation code to make it pass, or add new assertions. You must not weaken or delete existing assertions to make a test pass.
  - If you believe a test is genuinely wrong for the new behavior, halt to `changes_requested`, do not retry, and write your proposed test change to `REVIEW.md` for human approval — even if you have retries remaining.
- Refusal policy:
  - `aide implement`, `aide review`, and `aide po` refuse in lite mode and point you at `aide dev` or `aide profile full`.
  - `aide dev` refuses in full mode and points you back to `aide implement` and `aide review`.
- `all_task` commit policy:
  - `all_task` may commit multiple tasks, but it still creates one real Conventional Commit per task with no batching or squashing.

## Runtime Modes
- `full` profile:
  - Manual mode:
    - you start planner, implementer, and reviewer sessions yourself in separate terminals
    - you drive task progress by sending the documented text commands directly to each session
  - Auto mode:
    - you start the PO session with `aide po`
    - the PO session uses the `aide` MCP server to run the post-planning loop by coordinating implementer and reviewer sessions for the same task flow
- `lite` profile:
  - manual only
  - you start the planner and dev sessions yourself in separate terminals
  - you drive task progress by sending the documented text commands directly to those sessions
- Both profiles use the same `.ai/TASKS.md` board, `.ai/PLAN.md` plan, review artifacts, and status transitions.

## Persistent Session Workflow
- In manual mode, no role autostarts another role.
- In auto mode, the PO session may start or reconnect to the role sessions it coordinates.
- Start a new development cycle with `aide cycle start <branch-name>`.
- Start the planner, implementer, and reviewer once in `full`, or start the planner and dev sessions once in `lite`, then keep those sessions open for the rest of the cycle.
- When using auto mode, let the PO session manage the `full` profile role sessions instead of driving them directly yourself.
- `lite` has no PO/session-orchestration path; drive `aide dev` directly.
- Every role waits in `WAIT_FOR_USER_START` state until you explicitly tell it to begin.
- After launch, steer the existing sessions with text commands instead of relaunching scripts for each step.
- Agent choice is manual when you launch each role (`claude` or `codex`) and can vary by session.
- Handoff log policy:
  - runtime log: `.ai/HANDOFF.md` (tracked cycle log)
  - tracked template: `.ai/HANDOFF.template.md`
- Handoffs are file-based:
  - planner -> implementer uses `.ai/PLAN.md` + `.ai/TASKS.md` + `.ai/HANDOFF.md`
  - implementer -> reviewer uses commit + `.ai/TASKS.md` + `.ai/HANDOFF.md`
- Recommended status flow in `.ai/TASKS.md`:
  - `in_planning` -> `ready_for_implement` -> `in_implementation` -> `ready_for_review` -> `in_review` -> `ready_to_commit` -> `done`
  - Rework loop: `changes_requested` -> `in_implementation` -> `ready_for_review` -> `in_review` -> `done`
- In `lite`, the dev session performs the implement and review hops internally, halts for the human at `ready_for_review`, then resumes with `commit_task`.
- Every role must re-read `.ai/TASKS.md` before executing any command. Additional files depend on the role and command — see each role's prompt for specifics.
- Role-specific files to reload as needed:
  - planner: `ROADMAP.md`, `.ai/PLAN.md`
  - implementer: `.ai/PLAN.md`, `.ai/REVIEW.md` when reworking review findings
  - dev: `.ai/PLAN.md`, `.ai/REVIEW.md` when reworking review findings
  - reviewer: `.ai/PLAN.md`, `.ai/REVIEW.md`
- Files are the source of truth. No role should rely on hidden session memory when file state disagrees.

## Session Commands
Use these text commands inside the already-running role sessions.
- PO session:
  - launched with `aide po [agent]` (default agent: `claude`)
  - full profile only; lite mode refuses because the dev session is driven directly instead
  - uses MCP tools internally (`session_start`, `session_run`, `session_wait`, `session_get_output`, `session_get_result`, `session_status`, `session_list`, `session_stop`, `session_reset`, `session_delete`) to coordinate role sessions
  - `codex` PO runs use inline `-c mcp_servers.aide.*` overrides, so no global Codex MCP registration is required
  - never starts a planner session; if no tasks are in `ready_for_implement` or later, tells the user to run the planner first
  - `work_task [TASK_ID]`
    - no task ID: pick the first task that is not `done`, regardless of status (supports in-flight recovery)
    - with task ID: target that specific task
    - drive through full implement -> review -> commit cycle, then stop and report
    - if no eligible task exists, report that the board has no work remaining
  - `work_all`
    - run `work_task` repeatedly until all tasks are `done` or a blocker requires human intervention
    - stop at the first blocker and report
- Planner session:
  - before `start_plan`, conversation with the planner is the roadmap-refinement phase:
    - tighten scope, acceptance criteria, constraints, and decision points directly in `ROADMAP.md`
    - surface ambiguities and trade-offs for the user to resolve instead of inventing requirements
  - `start_plan` is the gate to formal planning; once invoked, write the plan without asking for another readiness confirmation
  - `start_plan`
    - read `ROADMAP.md` and current planning artifacts
    - create or restructure tasks in `.ai/TASKS.md` as needed
    - write or rewrite `.ai/PLAN.md`
    - when planning is complete, move all newly planned tasks to `ready_for_implement`
  - `rework_plan [TASK_ID]`
    - revisit an existing plan when scope, constraints, or approach change
    - update `.ai/PLAN.md`, `.ai/TASKS.md`, and `.ai/HANDOFF.md` as needed without modifying code
    - when no task ID is supplied, replan the overall roadmap/task breakdown
    - when a task ID is supplied and it does not exist or is not appropriate for replanning, report the current status and abort
- Implementer session:
  - full profile only; lite mode refuses and points you at `aide dev`
  - `next_task [TASK_ID]`
    - select the first task in `ready_for_implement` or `in_implementation` when no task ID is supplied
    - if the supplied task is not valid for implementer work, report its current status and abort
    - when work begins, update the task to `in_implementation`
  - `rework_task [TASK_ID]`
    - implementer only
    - target a task in `changes_requested`
    - load `.ai/REVIEW.md` as the required-fix checklist for review rework
    - if no task matches, report that no tasks are pending rework
  - `commit_task [TASK_ID]`
    - implementer only
    - target a task in `ready_to_commit`
    - read the commit message from the task's `next_task` HANDOFF entry `Commit` field
    - update `.ai/TASKS.md` to `done`
    - append a `commit_task` HANDOFF entry
    - run `git add -A && git commit -m "<message>"`
    - if the supplied task is not ready to commit, report its current status and abort
  - `aide cycle end [VERSION]`
    - verify all tasks are `done`
    - if the completion condition is not met, report the blocking task states and abort
    - if no version is supplied, ask the user for it before proceeding
    - append a closing entry to `.ai/HANDOFF.md` (`### Cycle closed — <version> — <UTC timestamp>`)
    - stage and commit with `chore(ai): close cycle` and a `Release-As: x.y.z` footer
    - then run `aide pr` to update the PR
  - `status_cycle [TASK_ID]`
    - return deterministic task status, current owner role, and next recommended action
    - when no task ID is supplied, summarize tasks relevant to the caller and the overall board state
    - if no task matches the caller's role, say so explicitly and summarize the board
- Reviewer session:
  - full profile only; lite mode refuses because review runs inside the dev session
  - `next_task [TASK_ID]`
    - select the first task in `ready_for_review` or `in_review` when no task ID is supplied
    - if the supplied task is not valid for reviewer work, report its current status and abort
    - when review begins, update the task to `in_review`
    - when review and verification pass, move the task to `ready_to_commit`
  - `status_cycle [TASK_ID]`
    - return deterministic task status, current owner role, and next recommended action
    - when no task ID is supplied, summarize tasks relevant to the caller and the overall board state
    - if no task matches the caller's role, say so explicitly and summarize the board
- dev session:
  - launched with `aide dev [agent]` (default agent: `codex`)
  - lite profile only; full mode refuses and points you back to `aide implement` and `aide review`
  - `next_task [TASK_ID]`
    - pick one `ready_for_implement` task (or the supplied task), move it to `in_implementation`, run the implement hat, run the review hat, and halt at `ready_for_review` for the human
  - `all_task`
    - process every remaining non-`done` task without per-task human review, committing each completed task before moving to the next one
    - halt only if a semantic concern appears or the 3-attempt mechanical retry cap is exhausted
  - `rework_task [TASK_ID] [feedback]`
    - resume a task from `ready_for_review` or `changes_requested`, apply feedback when provided, move it to `in_implementation`, and run the implement/review loop again
  - `commit_task [TASK_ID]`
    - valid only when the task is `ready_for_review`; this is the human approval step
    - move the task through `ready_to_commit` to `done`, then run `git add -A && git commit -m "<message>"` using the commit message already written in `.ai/HANDOFF.md`
  - `status_cycle [TASK_ID]`
    - return deterministic task status, current owner role, and next recommended action

## Commit Conventions
- Commit behavior by role:
  - `plan` role never commits.
  - `review` role never commits.
  - `implement` role does not commit during `next_task` or `rework_task`. The single task commit is created by `commit_task` after review approval.
  - `aide cycle end` commits the cycle-close artifacts with a `Release-As: x.y.z` footer and can be followed by `aide pr`.
- Conventional Commit subjects must be release-note ready: describe the user-visible change or outcome, not just the implementation mechanism.
- Prefer subjects in the form `<type>(<scope>): <user-facing change>`; if the subject alone would be too vague in release notes, add a short body summarizing the key changes.

## Tool Preferences
- For shell-based JSON parsing or filtering, prefer `jq`.
- For shell-based repository search, prefer `rg` over `grep`.
- For shell-based file discovery, prefer `fd` over `find`.
- For shell-based file previews, prefer `bat` over `cat`.
- When available, use `ast-grep` (`sg`) for structural code search using AST patterns (for example, matching function signatures or type definitions).
- When available, use `fzf` for interactive fuzzy file and symbol selection in the shell.
- Respect `.gitignore` in all search operations.
- Exclude build artifacts (`dist`, `build`, `node_modules`, `vendor`, `target`) by default.

### Tool Selection

| Task | Preferred | Instead of |
|------|-----------|------------|
| Code search | `rg` (ripgrep) | `grep`, `grep -r` |
| File discovery | `fd` | `find` |
| File preview | `bat` | `cat`, `head`, `tail` |
| JSON processing | `jq` | manual parsing, `python -c` |

### Search Rules

- Always respect `.gitignore` (rg and fd do this by default).
- Exclude build artifacts: `dist`, `build`, `node_modules`, `vendor`, `target`.
- Use glob filters to narrow scope before broad scans.
- Prefer exact match (`-w`) or fixed-string (`-F`) when searching for identifiers.

### Example Commands

- Search for an identifier: `rg -n -w "Task ID" .`
- List tracked files in a subtree: `fd . .ai/prompts`
- Preview a file with line numbers: `bat -n AGENTS.md`
<!-- agentinit:managed:end -->