commit 2c4c2d657085ebb96676b56db5d429350afb8521 Author: Domagoj Zecevic Date: Sat Sep 5 15:22:32 2026 +0200 chore: initial commit diff --git a/.ai/.manifest.json b/.ai/.manifest.json new file mode 100644 index 0000000..06e8410 --- /dev/null +++ b/.ai/.manifest.json @@ -0,0 +1,46 @@ +{ + "version": "v0.8.1+dirty", + "generated_at": "2026-09-05T13:22:31Z", + "files": [ + { + "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..4d51519 --- /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 | ` ` (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..905309b --- /dev/null +++ b/.ai/PLAN.template.md @@ -0,0 +1,21 @@ +# 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 +- Replace with project-specific validation commands. 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..fbffcfe --- /dev/null +++ b/.ai/config.json @@ -0,0 +1,27 @@ +{ + "roles": { + "plan": { + "agent": "claude", + "model": "sonnet", + "effort": "medium" + }, + "implement": { + "agent": "codex", + "model": "gpt-5.4" + }, + "review": { + "agent": "claude", + "model": "sonnet", + "effort": "medium" + } + }, + "defaults": { + "claude": { + "permission_mode": "acceptEdits" + }, + "codex": { + "sandbox": "workspace-write", + "network_access": true + } + } +} diff --git a/.ai/prompts/implementer.md b/.ai/prompts/implementer.md new file mode 100644 index 0000000..85dd991 --- /dev/null +++ b/.ai/prompts/implementer.md @@ -0,0 +1,43 @@ +# 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 committing. +- Stage all changes with `git add -A`. +- Files are the source of truth. Re-read `.ai/TASKS.md` and `.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, and update the chosen task to `in_implementation` when work begins + - `rework_task [TASK_ID]`: implementer-only command for tasks in `changes_requested`; read `.ai/REVIEW.md` for review findings before editing; if no task matches, report that no tasks are pending rework + - `commit_task [TASK_ID]`: implementer-only command for tasks in `ready_to_commit`; stage all `.ai/` artifact changes (`.ai/TASKS.md`, `.ai/HANDOFF.md`, `.ai/PLAN.md`, `ROADMAP.md`, etc.) and squash all WIP commits plus those staged changes into a single Conventional Commit describing the user-visible outcome, then move the task to `done`; 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 states and abort; if `VERSION` is not supplied, ask the user for it before proceeding; close the cycle with a `chore(ai): close cycle` commit carrying `Release-As: VERSION`; 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. +- Update tests as needed. +- Use `commit_task` to create the single final Conventional Commit for the task once it reaches `ready_to_commit`. +- 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. +- Create exactly one commit with a Conventional Commit message that references the rework (e.g. `fix(): address review findings`). +- 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..1020804 --- /dev/null +++ b/.ai/prompts/po.md @@ -0,0 +1,88 @@ +# 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_get_output` - poll for output; use offset to read incrementally + - `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, then poll with `session_get_output`. +- Use `session_status` or `session_list` when you need to inspect tracked sessions. +- 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 polling workflow for role commands: + - Call `session_run(name, command)`; it returns immediately. + - Loop: call `session_get_output(name, offset)` and set `offset = total_bytes`. + - Stop when `running == false`. + - Treat all returned chunks concatenated as the full output. +5. Re-read `.ai/TASKS.md` to confirm the status transition before sending the next command. + +- Signs that a role command is complete: + - the output reports a new task status such as `ready_for_review`, `ready_to_commit`, or `done` + - 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 polling returns no new output while `running == true`, check `.ai/TASKS.md` and `session_status` before deciding whether the session is stuck. +- 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..0d71c90 --- /dev/null +++ b/.ai/prompts/reviewer.md @@ -0,0 +1,41 @@ +# Reviewer Prompt + +You are in `review` 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 approving implementation changes. +- Never modify code. +- Files are the source of truth. Re-read `.ai/TASKS.md` before executing any command. 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 implementation changes against `.ai/PLAN.md`. +- Perform verification as part of review, including automated checks, E2E checks, and exploratory/manual validation when the task calls for them. +- 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/.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..abb5d3e --- /dev/null +++ b/.gitignore @@ -0,0 +1,21 @@ +# 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 + + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..85f3ac5 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,227 @@ +# 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 +- Define project validation commands here when you add them for this repository. + +## 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: + - waits for explicit user start signal + - implements `.ai/PLAN.md` + - updates tests + - updates affected documentation and code comments whenever behavior, interfaces, or workflows change + - stages task-specific `.ai/` artifact changes with the task commit when applicable + - stages files with `git add -A` + - commits with a Conventional Commit message + - updates `.ai/TASKS.md` status to `ready_for_review` + - appends a handoff entry to `.ai/HANDOFF.md` including commit hash + - must not invent requirements +- Implement Mode (`commit_task` after review): + - only for tasks in `ready_to_commit` + - stages `.ai/` artifact changes and includes them in the squashed commit + - squashes WIP commits into one Conventional Commit with a release-note-ready subject + - updates `.ai/TASKS.md` status to `done` + - appends a handoff entry to `.ai/HANDOFF.md` including commit hash +- Implement Mode (rework after rejection): + - reads `.ai/REVIEW.md` findings as a checklist + - addresses every finding marked as required fix + - re-runs validations + - stages and commits with a Conventional Commit referencing the rework + - updates `.ai/TASKS.md` status from `changes_requested` to `ready_for_review` + - appends a handoff entry to `.ai/HANDOFF.md` including commit hash + +## 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. + +## Runtime Modes +- 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 +- Both modes 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, then keep those sessions open for the rest of the cycle. +- When using auto mode, let the PO session manage those role sessions instead of driving them directly yourself. +- 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` +- 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 + - 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`) + - uses MCP tools internally (`session_start`, `session_run`, `session_get_output`, `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: + - `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` + - stage all `.ai/` artifact changes (`.ai/TASKS.md`, `.ai/HANDOFF.md`, `.ai/PLAN.md`, `ROADMAP.md`, etc.) as part of the squash + - squash WIP commits into a single Conventional Commit describing the user-visible outcome + - update the task to `done` + - 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 + - close the cycle with a `chore(ai): close cycle` commit 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: + - `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 + +## Commit Conventions +- Commit behavior by role: + - `plan` role never commits. + - `review` role never commits. + - `implement` role must stage all changes and create a Conventional Commit after validations pass. + - `.ai/` artifact changes produced by a task are staged and committed as part of that task's Conventional Commit via `commit_task`. + - `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..90496be --- /dev/null +++ b/README.md @@ -0,0 +1,136 @@ +# youtubedownloader + +## 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. + +### 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/ +``` + +### Start persistent role sessions (manual mode) + +```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. + +### Start the PO orchestrator (auto mode) + +```bash +aide po +``` + +The PO session drives the post-planning task board flow through the `aide` MCP server. +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 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 +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.