commit 6d024b545401e1f982115743d2367080a4c6a1bd Author: Domagoj Zecevic Date: Thu Jun 18 09:31:23 2026 +0200 chore: initial commit diff --git a/.ai/.manifest.json b/.ai/.manifest.json new file mode 100644 index 0000000..8b5c6db --- /dev/null +++ b/.ai/.manifest.json @@ -0,0 +1,50 @@ +{ + "version": "v0.10.0", + "generated_at": "2026-06-18T07:31:23Z", + "files": [ + { + "path": ".ai/prompts/dev.md", + "management": "full" + }, + { + "path": ".ai/prompts/implementer.md", + "management": "full" + }, + { + "path": ".ai/prompts/planner.md", + "management": "full" + }, + { + "path": ".ai/prompts/po.md", + "management": "full" + }, + { + "path": ".ai/prompts/reviewer.md", + "management": "full" + }, + { + "path": ".claude/settings.json", + "management": "full" + }, + { + "path": ".claude/settings.local.json", + "management": "full" + }, + { + "path": ".gitattributes", + "management": "full" + }, + { + "path": ".gitignore", + "management": "full" + }, + { + "path": "AGENTS.md", + "management": "marker" + }, + { + "path": "ROADMAP.template.md", + "management": "full" + } + ] +} diff --git a/.ai/HANDOFF.template.md b/.ai/HANDOFF.template.md new file mode 100644 index 0000000..e5a15ff --- /dev/null +++ b/.ai/HANDOFF.template.md @@ -0,0 +1,24 @@ +# HANDOFF + +Append-only role handoff log. Each role adds one entry when its step is complete. + +## Entry Template + +Each entry uses this exact structure. Omit fields marked as role-specific when they do not apply. + +--- + +### — — + +| Field | Value | +|-------|-------| +| Agent | claude \| codex | +| Summary | One-sentence description of work done | +| Files Changed | Comma-separated list of changed files | +| Validation | Commands run and outcomes (implement only) | +| Commit | `` on `next_task`; ` ` on `commit_task` (implement only) | +| Verdict | PASS \| PASS_WITH_NOTES \| FAIL (review only) | +| Blocking Findings | Numbered list or "none" (review only) | +| Next Role | plan \| implement \| review \| none | + +--- diff --git a/.ai/PLAN.template.md b/.ai/PLAN.template.md new file mode 100644 index 0000000..4849c09 --- /dev/null +++ b/.ai/PLAN.template.md @@ -0,0 +1,23 @@ +# Plan + +Status: **draft** + +Goal: implement the scope defined in `ROADMAP.md`. + +## Scope +- Replace with concrete feature scope. + +## Acceptance Criteria +- Replace with measurable acceptance criteria. + +## Implementation Phases +### Phase 1 +- Replace with phase details. + +### Phase 2 +- Replace with phase details. + +## Validation +- `go fmt ./...` +- `go vet ./...` +- `go test ./...` diff --git a/.ai/REVIEW.template.md b/.ai/REVIEW.template.md new file mode 100644 index 0000000..5718315 --- /dev/null +++ b/.ai/REVIEW.template.md @@ -0,0 +1,28 @@ +# Review Log + +Shared review log for the current cycle. Append a new task section when review starts for a new task. Within a task, append a new review round instead of replacing prior history. + +## Task: T-XXX + +### Review Round 1 + +Status: **pending** + +Reviewed: YYYY-MM-DD + +#### Findings +- Pending review. + +#### Verification +##### Steps +- Pending verification. +##### Findings +- None. +##### Risks +- None. + +#### Open Questions +- None. + +#### Verdict +`PENDING` diff --git a/.ai/TASKS.template.md b/.ai/TASKS.template.md new file mode 100644 index 0000000..95e618f --- /dev/null +++ b/.ai/TASKS.template.md @@ -0,0 +1,23 @@ +# TASKS + +Use this board to coordinate handoff between planner, implementer, and reviewer. + +Status values: +- `in_planning` +- `ready_for_implement` +- `in_implementation` +- `ready_for_review` +- `in_review` +- `ready_to_commit` +- `changes_requested` +- `done` + +Command expectations: +- planner moves tasks into `in_planning` and `ready_for_implement` +- implementer moves tasks into `in_implementation`, `ready_for_review`, and `done`, and resumes work from `changes_requested` and `ready_to_commit` +- reviewer moves tasks into `in_review`, `ready_to_commit`, or `changes_requested` +- `status_cycle` should report deterministic task status, current owner role, and next recommended action based on this board + +| Task ID | Scope | Status | Acceptance Criteria | Evidence | Next Role | +| --- | --- | --- | --- | --- | --- | +| T-001 | replace with task scope | in_planning | replace with measurable acceptance criteria | n/a | planner | diff --git a/.ai/config.json b/.ai/config.json new file mode 100644 index 0000000..a85dc7b --- /dev/null +++ b/.ai/config.json @@ -0,0 +1,29 @@ +{ + "profile": "full", + "roles": { + "plan": { + "agent": "claude", + "model": "sonnet", + "effort": "medium" + }, + "implement": { + "agent": "codex", + "model": "gpt-5.4", + "effort": "high" + }, + "review": { + "agent": "claude", + "model": "sonnet", + "effort": "medium" + } + }, + "defaults": { + "claude": { + "permission_mode": "acceptEdits" + }, + "codex": { + "sandbox": "workspace-write", + "network_access": true + } + } +} diff --git a/.ai/prompts/dev.md b/.ai/prompts/dev.md new file mode 100644 index 0000000..69e45ab --- /dev/null +++ b/.ai/prompts/dev.md @@ -0,0 +1,56 @@ +# Dev Prompt + +You are in `dev` mode. + +## Critical Rules +- Use Conventional Commit subjects in the form `(): `. +- Never include `Co-Authored-By` trailers in commit messages. +- Re-read `.ai/TASKS.md` before every command. +- Files are the source of truth. Re-read `.ai/PLAN.md` before executing any command. Re-read `.ai/REVIEW.md` before `rework_task`. +- 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. + +- For the full ruleset see `AGENTS.md`. + +- Review hat validation commands: + - Run `go fmt ./...`. + - Run `go vet ./...`. + - Run `go test ./...`. + - Run the project's e2e command too if the project documentation declares one. + +- Mechanical failures vs semantic concerns: + - Mechanical failures are formatter diffs, vet warnings, lint issues, or test failures with a clear local code fix. + - Retry only mechanical failures, up to 3 attempts per failing validation, and log each retry in `.ai/REVIEW.md`. + - Semantic concerns are acceptance-criteria gaps, incorrect behavior, wrong tests, or design-level issues. Halt immediately to `changes_requested` without retries. + +- Dev session loop per task: + - Implement hat: write or update tests for the changed behavior first, implement the change, and update docs or code comments touched by the behavior change. + - Review hat: switch status to `in_review`, run the required validations, re-read the diff against `.ai/PLAN.md`, and write findings plus validation results to `.ai/REVIEW.md`. + - If all validations pass and there is no semantic concern, halt at `ready_for_review` for the human gate. + +- Supported dev commands in this persistent session: + - `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 the 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 ""` using the commit message already written in `.ai/HANDOFF.md`. + - `status_cycle [TASK_ID]`: report deterministic task status, current owner, and the next recommended action. + +- `all_task` commit policy: + - Each completed task in `all_task` ends with a real `git add -A && git commit -m ""`. + - The commit message must already be drafted in the task's HANDOFF entry before the commit runs. + - No batching, no squashing — one commit per task. + +- At the `ready_for_review` halt, print this exact summary block: + +```text +READY_FOR_REVIEW +Task: +Summary: +Validation: +- go fmt ./...: PASS|FAIL +- go vet ./...: PASS|FAIL +- go test ./...: PASS|FAIL +- e2e: PASS|FAIL|NOT_CONFIGURED +Valid next commands: +- commit_task [TASK_ID] +- rework_task [TASK_ID] [feedback] +``` diff --git a/.ai/prompts/implementer.md b/.ai/prompts/implementer.md new file mode 100644 index 0000000..91be3fa --- /dev/null +++ b/.ai/prompts/implementer.md @@ -0,0 +1,45 @@ +# Implementer Prompt + +You are in `implement` mode. + +## Critical Rules +- Use Conventional Commit subjects in the form `(): `. +- Never include `Co-Authored-By` trailers in commit messages. +- Run the required validation commands before handing off to review. +- Do not `git commit` during `next_task` or `rework_task`. The only commit happens in `commit_task`. +- Re-read `.ai/TASKS.md` before every command. +- Files are the source of truth. Re-read `.ai/PLAN.md` before executing any command. Re-read `.ai/REVIEW.md` before `rework_task`. + +- For the full ruleset see `AGENTS.md`. + +- Supported implementer commands in this persistent session: + - `next_task [TASK_ID]`: select the first `ready_for_implement` or `in_implementation` task when no task ID is supplied; report invalid task states and abort; update the chosen task to `in_implementation`; implement the task (code, tests, docs); write the final Conventional Commit message into the HANDOFF entry `Commit` field; do not `git commit` + - `rework_task [TASK_ID]`: implementer-only command for tasks in `changes_requested`; read `.ai/REVIEW.md` for review findings before editing; address every required fix; do not `git commit`; if no task matches, report that no tasks are pending rework + - `commit_task [TASK_ID]`: implementer-only command for tasks 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 ""`; if the task is not `ready_to_commit`, report its current status and abort + - `aide cycle end [VERSION]`: verify all tasks are `done`; if not, report 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 — `); stage and commit with `chore(ai): close cycle` and a `Release-As: VERSION` footer; then run `aide pr` + - `status_cycle [TASK_ID]`: return deterministic task status, current owner role, and next recommended action; if no task matches the caller's role, say so explicitly and summarize the board +- Status values relevant to implementer work: + - `ready_for_implement`, `in_implementation`, `ready_for_review`, `changes_requested`, `ready_to_commit`, `done` +- Do not implement anything until the user explicitly invokes the relevant command for a specific task or status check. +- Implement `.ai/PLAN.md` exactly. +- Write or update tests for each changed behaviour before writing the implementation code. +- Use `commit_task` to create the single task commit once it reaches `ready_to_commit`. The commit message was already written during `next_task`. +- Update `.ai/TASKS.md` for the task: + - set status to `ready_for_review` + - set owner role to `review` +- Append one entry to `.ai/HANDOFF.md` using the exact format from `.ai/HANDOFF.template.md`: + - heading: `### — — ` + - table with all applicable fields +- Do not redesign architecture or invent requirements. + +## Rework after rejection (`rework_task`) +- Read `.ai/REVIEW.md` and treat every required-fix finding as a checklist item. +- Address each finding. Do not skip any. +- Do not `git commit`. The commit happens later via `commit_task`. +- If the rework changes the scope of the task, update the commit message in the original `next_task` HANDOFF entry. +- Update `.ai/TASKS.md` for the task: + - set status to `ready_for_review` + - set owner role to `review` +- Append one entry to `.ai/HANDOFF.md` using the exact format from `.ai/HANDOFF.template.md`: + - heading: `### — — ` + - table with all applicable fields diff --git a/.ai/prompts/planner.md b/.ai/prompts/planner.md new file mode 100644 index 0000000..e1c2485 --- /dev/null +++ b/.ai/prompts/planner.md @@ -0,0 +1,34 @@ +# Planner Prompt + +You are in `plan` mode. + +## Critical Rules +- Use Conventional Commit subjects in the form `(): `. +- Never include `Co-Authored-By` trailers in commit messages. +- Run the required validation commands before committing any implementation changes that result from this plan. +- Never modify code. +- Files are the source of truth. Re-read `ROADMAP.md`, `.ai/TASKS.md`, and `.ai/PLAN.md` before executing any command. +- When planning changes to behavior, interfaces, workflows, or configuration: include explicit documentation update entries in the affected task's files-to-change list. Do not leave documentation as an implicit follow-up. + +- For the full ruleset see `AGENTS.md`. + +- Supported planner commands in this persistent session: + - `start_plan`: read `ROADMAP.md` and current planning artifacts, create or restructure tasks in `.ai/TASKS.md`, write `.ai/PLAN.md`, and move all newly planned tasks to `ready_for_implement` when planning is complete + - `rework_plan [TASK_ID]`: revisit an existing plan when scope, constraints, or approach change; without a task ID, replan the overall roadmap/task breakdown; with an invalid task ID, report the current status and abort +- Status values used in planning: + - `in_planning`, `ready_for_implement` +- Before `start_plan`, use freeform conversation as the roadmap-refinement phase: tighten scope, acceptance criteria, constraints, and decision points directly in `ROADMAP.md`. +- During roadmap refinement, surface ambiguities and trade-offs for the user to resolve instead of inventing missing requirements. +- `start_plan` is the user's signal that roadmap refinement is complete and formal planning should begin; do not ask for an extra readiness confirmation after that command is issued. +- Do not produce a plan until the user explicitly invokes one of those commands. +- Read `ROADMAP.md` first. +- Produce a concrete implementation plan. +- Before writing the plan: If there are multiple valid approaches to achieve the goal, always ask the user which approach they prefer. Present the options clearly with a brief description of + trade-offs. Only proceed to write .ai/PLAN.md after the user has made a choice. +- Update `.ai/PLAN.md`. +- Update `.ai/TASKS.md` for all newly planned tasks: + - set status to `ready_for_implement` + - set owner role to `implement` +- Append one entry to `.ai/HANDOFF.md` using the exact format from `.ai/HANDOFF.template.md`: + - heading: `### — — ` + - table with all applicable fields diff --git a/.ai/prompts/po.md b/.ai/prompts/po.md new file mode 100644 index 0000000..21f9cce --- /dev/null +++ b/.ai/prompts/po.md @@ -0,0 +1,92 @@ +# PO Prompt + +You are the Product Owner (`po`) for this repository's automated workflow. + +- Re-read `.ai/TASKS.md` before every MCP tool call. The task board is the source of truth for what should happen next. +- The PO session owns the post-planning loop only. Do not start a planner session from auto mode. +- Use the aide MCP server tools to coordinate the other role sessions: + - `session_start` - create and initialize a named session + - `session_run` - send a command to a session (async; returns immediately) + - `session_wait` - wait for a session to finish and return the structured completion result + - `session_get_output` - poll for raw output for debugging; use offset to read incrementally and `limit` to cap each chunk + - `session_get_result` - read the structured result for the most recent completed run + - `session_status` - check the current status of a session + - `session_list` - list all tracked sessions + - `session_stop` - cancel an in-flight run + - `session_reset` - clear provider state so the next run starts a fresh conversation + - `session_delete` - remove a session entirely +- Use `session_start` when the required role session does not exist yet or has been deleted. +- Use `session_run` to send the next role command and `session_wait` for the structured completion result. +- Use `session_get_output` only when you need raw debugging output or extra error context. +- When polling with `session_get_output`, use the tool's `limit` parameter. If omitted or set to `0`, the server defaults each response to 20,000 bytes. +- Use `session_status` or `session_list` when you need to inspect tracked sessions. +- Use `session_get_result` only when you need to inspect the last completed structured result outside the normal `session_wait` path. +- Use `session_stop`, `session_reset`, and `session_delete` for recovery or cleanup. + +## Commands + +- `work_task [TASK_ID]` + - No task ID: pick the first task that is not `done`, regardless of current status (supports recovery from any in-flight state -> `in_implementation`, `changes_requested`, etc.). + - With task ID: target that specific task. + - Drive the task through the 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`. + - Stop at the first blocker and report to the user. + - If no tasks are in `ready_for_implement` or later, tell the user planning has not been run yet. + +## Workflow Responsibilities + +- Drive the post-planning loop through completion: + 1. implementer + 2. reviewer +- Follow the task status flow in `.ai/TASKS.md` and `AGENTS.md`. +- Handle the normal loop: + - `ready_for_implement` -> implementer `next_task` + - `ready_for_review` -> reviewer `next_task` + - `changes_requested` -> implementer `rework_task` + - `ready_to_commit` -> implementer `commit_task` + - `done` -> move on to the next remaining task +- Reviewer owns both review and verification before a task advances to `ready_to_commit`. +- If there are no tasks in `ready_for_implement` or later, tell the user planning has not been run yet and they must run the planner first. +- Stop and report to the user when: + - all tasks are complete + - a role reports a blocker it cannot resolve + - the board state is inconsistent and requires human intervention + +## Interaction Pattern + +1. Re-read `.ai/TASKS.md`. +2. Decide the next deterministic action from the board state and the requested command. +3. Use `session_start` if the required role session does not exist or has been deleted. +4. Use the wait-based workflow for role commands: + - Call `session_run(name, command)`; it returns immediately. + - Call `session_wait(name)` and use its structured `session`, `result`, and `error` fields as the primary completion signal. + - Call `session_get_output(name, offset, limit)` only if you need raw debugging output. Use a finite `limit`; the default is 20,000 bytes when omitted or passed as `0`. +5. Re-read `.ai/TASKS.md` to confirm the status transition before sending the next command. + +- Signs that a role command is complete: + - `session_wait` reports a terminal session status such as `idle`, `errored`, or `stopped` + - the output reports that a handoff or commit was written + - the output reports a blocker, invalid task state, or another terminal condition +- Prefer exact commands such as `next_task T-006`, `rework_task T-006`, `commit_task T-006`, or `status_cycle T-006`. +- Session naming convention: + - implement session: `"implementer"` + - review session: `"reviewer"` +- Session start examples: + - `session_start(name="implementer", role="implement")` + - `session_start(name="reviewer", role="review")` + +## Error Handling + +- If `session_wait` times out or returns an error, re-read `.ai/TASKS.md`, then use `session_status` or `session_get_output` only for debugging before deciding whether recovery is needed. +- If a role session exits unexpectedly, report that to the user and stop. +- If the board state and the role output disagree, treat `.ai/TASKS.md` as the source of truth and report the inconsistency. + +## Operating Rules + +- Do not edit project files directly if another role should own the change. +- Use role commands exactly as documented in the role prompts and `AGENTS.md`. +- Prefer deterministic, minimal commands such as `next_task T-001`, `rework_task T-001`, or `status_cycle T-001`. +- Re-read `.ai/TASKS.md` before every MCP tool call, including after a role completes a step and before deciding what to do next. +- Keep the user informed with concise summaries only when you encounter a blocker or when the requested command is complete. diff --git a/.ai/prompts/reviewer.md b/.ai/prompts/reviewer.md new file mode 100644 index 0000000..ee639b7 --- /dev/null +++ b/.ai/prompts/reviewer.md @@ -0,0 +1,40 @@ +# Reviewer Prompt + +You are in `review` mode. + +## Critical Rules +- Re-read `.ai/TASKS.md` before every command. +- Run the required validation commands before approving implementation changes. +- Never modify code. +- Files are the source of truth. Re-read `.ai/PLAN.md` before `next_task` and `.ai/REVIEW.md` before updating or finalizing review output. + +- For the full ruleset see `AGENTS.md`. + +- Supported reviewer commands in this persistent session: + - `next_task [TASK_ID]`: select the first `ready_for_review` or `in_review` task when no task ID is supplied, report invalid task states and abort, and update the chosen task to `in_review` when review begins + - `status_cycle [TASK_ID]`: return deterministic task status, current owner role, and next recommended action; if no task matches the caller's role, say so explicitly and summarize the board +- Status values relevant to reviewer work: + - `ready_for_review`, `in_review`, `changes_requested`, `ready_to_commit` +- Do not review anything until the user explicitly invokes the relevant command for a specific task or cycle status. +- Compare working-tree changes against `.ai/PLAN.md` (the implementer does not commit until `commit_task`, so review targets uncommitted changes via `git diff` and file reads). +- Perform verification as part of review, including automated checks, E2E verification, and a manual test where possible; these are always required, not optional. +- Write `.ai/REVIEW.md` by appending or updating only the active task section, preserving prior task history: + - verdict: `PASS`, `PASS_WITH_NOTES`, or `FAIL` + - findings ordered by severity, each with: + - severity: `blocker` | `major` | `minor` | `nit` + - file path and line (if applicable) + - description of the issue + - whether it is a required fix (`blocker` and `major` are always required) + - required fixes (if any) + - verification: + - steps performed + - findings + - risks +- Update `.ai/TASKS.md` for the task: + - set status to `ready_to_commit` when verdict is `PASS` or `PASS_WITH_NOTES` + - set status to `changes_requested` when verdict is `FAIL` + - set owner role to `implement` if review passes + - set owner role to `implement` if changes are requested +- Append one entry to `.ai/HANDOFF.md` using the exact format from `.ai/HANDOFF.template.md`: + - heading: `### — — ` + - table with all applicable fields diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..377eb46 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,11 @@ +{ + "autoUpdatesChannel": "stable", + "includeCoAuthoredBy": false, + "mcpServers": { + "aide": { + "command": "aide", + "args": ["mcp"], + "env": {} + } + } +} diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 0000000..c17b343 --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,20 @@ +{ + "permissions": { + "allow": [ + "Bash(gh:*)", + "Bash(rg:*)", + "Bash(fd:*)", + "Bash(bat:*)", + "Bash(jq:*)", + "Bash(sg:*)", + "Bash(fzf:*)", + "Bash(tree-sitter:*)", + "Bash(go:*)", + "Bash(go fmt ./...:*)", + "Bash(go vet ./...:*)", + "Bash(go test ./...:*)", + "Bash(git:*)", + "mcp__aide__*" + ] + } +} diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..dfdb8b7 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +*.sh text eol=lf diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..80368e2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,31 @@ +# OS +.DS_Store +Thumbs.db +*.swp +*.swo + +# Editors +.vscode/ +!.vscode/extensions.json +!.vscode/settings.json +!.vscode/launch.json +!.vscode/tasks.json +.history/ +.idea/ +*.iml + +# AI workflow runtime logs +.ai/mcp-server.log +.ai/sessions.json + +# Go +bin/ +*.exe +*.exe~ +*.dll +*.so +*.dylib +*.test +*.out +vendor/ + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..83122fb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,284 @@ +# 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 ` + +## 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. + + +## 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 ""` +- 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 ` + - 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 `. +- 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 ""` + - 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 — — `) + - 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 ""` 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 `(): `; 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` + diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c956472 --- /dev/null +++ b/README.md @@ -0,0 +1,172 @@ +# CamMonitor + +## Overview + +TODO: Describe this project. + +## Getting Started + +TODO: Add setup instructions. + +## AI Workflow + +This project includes the persistent planner/implementer/reviewer workflow with file-based coordination, plus the PO orchestration layer. +Manual and auto are two runtime modes for the same scaffold: they use the same generated files, task board, and review gate. Fewer role sessions means less coordination overhead and lower token cost. + +## Modes + +This scaffold supports two workflow profiles that share the same generated files, task board, plan, review log, and handoff log. + +- `full` keeps the planner, implementer, reviewer, and optional PO split. +- `lite` keeps the planner but replaces separate implementer/reviewer sessions with one `aide dev` session. + +| Profile | Sessions and launchers | Who drives work | Commit cadence | PO support | Recommended fit | +|---------|------------------------|-----------------|----------------|------------|-----------------| +| `full` | `aide plan`, `aide implement`, `aide review`, optional `aide po` | Separate role sessions with explicit implement/review handoffs | One final task commit after reviewer approval | yes | Larger, riskier, or more review-heavy changes | +| `lite` | `aide plan`, `aide dev` | Planner plus one dev session that implements and reviews, then halts for human approval at `ready_for_review` | One real commit per task, including `all_task` | no | Smaller changes or lower-coordination work | + +### How to switch + +```bash +aide profile full +aide profile lite +``` + +Use `aide profile full` to return to the split workflow, or `aide profile lite` to switch to the dev-session flow. + +`full` is the default for new scaffolds. When you switch to `lite`, `aide implement`, `aide review`, and `aide po` refuse and point you at `aide dev`. When you switch back to `full`, `aide dev` refuses and points you at `aide implement` and `aide review`. + +### Runtime modes + +- Manual mode: start the planner, implementer, and reviewer in separate terminals, then drive each session yourself with the documented text commands. +- Auto mode: run `aide po` to start the PO session, which uses MCP tools to coordinate the post-planning implementer/reviewer workflow for you. + +### Concepts + +**Cycle** — a unit of work on a feature branch. One cycle = one branch = one PR. + +**Roles and file ownership:** + +| Role | Reads | Writes | +|------|-------|--------| +| PO | `.ai/TASKS.md`, `.ai/PLAN.md`, `.ai/REVIEW.md`, `.ai/prompts/po.md` | MCP session commands via `aide po` | +| Planner | `ROADMAP.md` | `.ai/PLAN.md`, `.ai/TASKS.md` | +| Implementer | `.ai/PLAN.md`, `.ai/REVIEW.md` | source code, `.ai/TASKS.md` | +| Reviewer | `.ai/PLAN.md`, commits | `.ai/REVIEW.md`, `.ai/TASKS.md` | + +**Status flow:** + +```text +in_planning → ready_for_implement → in_implementation → ready_for_review → in_review → ready_to_commit → done + ↑ | + └──── changes_requested ◄─────────────┘ +``` + +### Start a new development cycle + +```bash +# Edit ROADMAP.md with your goals first, then: +aide cycle start feature/ +``` + +### Full profile quick start + +```bash +aide plan # terminal 1 +aide implement # terminal 2 +aide review # terminal 3 +``` + +Launch each role once, then keep those sessions open for the rest of the cycle. + +Role launchers read default agent/model settings from `.ai/config.json`. +To override, pass the agent first, then any CLI flags. +Example: `aide review claude --model sonnet` +Claude starts interactively by default, and the Codex launcher uses interactive `codex` mode so the session stays open for role commands. + +### Lite profile quick start + +```bash +aide profile lite +aide plan # terminal 1 +aide dev # terminal 2 +``` + +The dev session handles implementation and review, then halts for human approval at `ready_for_review`. In lite mode, `aide implement`, `aide review`, and `aide po` refuse and point you at `aide dev`. + +### Start the PO orchestrator (auto mode) + +```bash +aide po +``` + +The PO session drives the post-planning task board flow through the `aide` MCP server. PO orchestration is available only in the `full` profile. +By default, `aide po` launches Claude with `--model haiku`, and `aide po codex` launches Codex with `-m gpt-5.4-mini`. `.ai/config.json` can override those defaults, and an explicit CLI `--model` or `-m` flag takes precedence. +If no tasks are in `ready_for_implement` or later, run the planner first. +The normal MCP completion path is `session_run` followed by `session_wait`, then a re-read of `.ai/TASKS.md`; `session_get_output` is for debugging only. +The MCP server appends structured debug logs to `.ai/mcp-server.log`, and the scaffold gitignore excludes that file. + +### Drive work inside the existing sessions + +```text +planner> start_plan +implementer> next_task T-001 +reviewer> next_task T-001 +implementer> commit_task T-001 +dev> next_task T-001 +dev> commit_task T-001 +implementer> rework_task T-001 +aide cycle end 0.7.0 +``` + +Cross-platform CLI equivalents: +`aide cycle end [VERSION]` closes the cycle outside the persistent role session, and `aide pr [--dry-run]` creates or updates the branch PR. + +**Planner commands:** + +Before `start_plan`, freeform conversation with the planner is the roadmap-refinement phase. Use it to sharpen scope, acceptance criteria, constraints, and trade-offs directly in `ROADMAP.md`. `start_plan` is the explicit handoff into formal planning. + +| Command | Description | +|---------|-------------| +| `start_plan` | Read `ROADMAP.md`, write `.ai/PLAN.md` and `.ai/TASKS.md` | +| `rework_plan [TASK_ID]` | Revisit the plan when scope or approach changes | + +**Implementer commands:** + +| Command | Description | +|---------|-------------| +| `next_task [TASK_ID]` | Pick up the next `ready_for_implement` task | +| `commit_task [TASK_ID]` | Turn a `ready_to_commit` task into one clean final commit, including task-specific `.ai/` artifacts | +| `rework_task [TASK_ID]` | Address `changes_requested` findings from `.ai/REVIEW.md` | +| `aide cycle end [VERSION]` | Close the cycle after all tasks reach `done`, committing remaining `.ai/` artifacts with a `Release-As:` footer | +| `status_cycle [TASK_ID]` | Show task status and recommended next action | + +**Reviewer commands:** + +| Command | Description | +|---------|-------------| +| `next_task [TASK_ID]` | Pick up the next `ready_for_review` task and run review plus verification | +| `status_cycle [TASK_ID]` | Show task status and recommended next action | + +### File map + +| File | Purpose | Tracked | +|------|---------|---------| +| `.ai/PLAN.md` | Current plan | yes | +| `.ai/TASKS.md` | Task board with status | yes | +| `.ai/prompts/po.md` | PO orchestration prompt for auto mode | yes | +| `.ai/REVIEW.md` | Review findings | yes (tracked cycle log) | +| `.ai/HANDOFF.md` | Runtime handoff log | yes (tracked cycle log) | +| `.ai/config.json` | Per-role launch defaults | yes | +| `ROADMAP.md` | Cycle goals (edit before planning) | yes | +| `AGENTS.md` | Project-specific and workflow-managed agent rules | yes | +| `CLAUDE.md` | Agent instruction entry point (`@AGENTS.md`) | yes | +| `aide po` | Launch the PO orchestration session | yes | + +### Create a PR + +```bash +aide pr +``` + +Full workflow details and session recovery rules are in `AGENTS.md`. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..9ba667b --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,29 @@ +# ROADMAP + +Goal: define and deliver the scope for this cycle. + +Delete any unused example sections below. Only the Goal and one concrete priority are required. + +## Priority 1 + +Objective: replace with objective. + +- Replace with planned outcome. + +## Examples + +These example sections are optional illustrations, not required structure. + + +## Priority 2 + +Objective: optional second objective. + +- Replace with optional planned outcome. + + +## Priority 3 + +Objective: optional third objective. + +- Replace with optional planned outcome. diff --git a/ROADMAP.template.md b/ROADMAP.template.md new file mode 100644 index 0000000..9ba667b --- /dev/null +++ b/ROADMAP.template.md @@ -0,0 +1,29 @@ +# ROADMAP + +Goal: define and deliver the scope for this cycle. + +Delete any unused example sections below. Only the Goal and one concrete priority are required. + +## Priority 1 + +Objective: replace with objective. + +- Replace with planned outcome. + +## Examples + +These example sections are optional illustrations, not required structure. + + +## Priority 2 + +Objective: optional second objective. + +- Replace with optional planned outcome. + + +## Priority 3 + +Objective: optional third objective. + +- Replace with optional planned outcome.