chore: initial commit

2 weeks ago · 2c4c2d6570
18 changed files with 830 additions and 0 deletions
--- a/.ai/.manifest.json
+++ 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"
    }
  ]
 }
--- a/.ai/HANDOFF.template.md
+++ 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.
 ---
 ### <TASK_ID> — <ROLE> — <YYYY-MM-DDTHH:MM:SSZ>
 | 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 | `<hash> <conventional commit message>` (implement only) |
 | Verdict | PASS \| PASS_WITH_NOTES \| FAIL (review only) |
 | Blocking Findings | Numbered list or "none" (review only) |
 | Next Role | plan \| implement \| review \| none |
 ---
--- a/.ai/PLAN.template.md
+++ 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.
--- a/.ai/REVIEW.template.md
+++ 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`
--- a/.ai/TASKS.template.md
+++ 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 |
--- a/.ai/config.json
+++ 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
    }
  }
 }
--- a/.ai/prompts/implementer.md
+++ 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 `<type>(<scope>): <user-facing change>`.
 - 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: `### <TASK_ID> — <role> — <UTC timestamp>`
  - 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(<scope>): 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: `### <TASK_ID> — <role> — <UTC timestamp>`
  - table with all applicable fields
--- a/.ai/prompts/planner.md
+++ 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 `<type>(<scope>): <user-facing change>`.
 - 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: `### <TASK_ID> — <role> — <UTC timestamp>`
  - table with all applicable fields
--- a/.ai/prompts/po.md
+++ 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.
--- a/.ai/prompts/reviewer.md
+++ 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 `<type>(<scope>): <user-facing change>`.
 - 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: `### <TASK_ID> — <role> — <UTC timestamp>`
  - table with all applicable fields
--- a/.claude/settings.json
+++ b/.claude/settings.json
@ -0,0 +1,11 @@
 {
  "autoUpdatesChannel": "stable",
  "includeCoAuthoredBy": false,
  "mcpServers": {
    "aide": {
      "command": "aide",
      "args": ["mcp"],
      "env": {}
    }
  }
 }
--- a/.gitattributes
+++ b/.gitattributes
@ -0,0 +1 @@
 *.sh text eol=lf
--- a/.gitignore
+++ 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
--- a/AGENTS.md
+++ 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 <new-file>`
 ## 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.
 <!-- 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:
  - 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 <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.
 ## 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 <branch-name>`.
 - 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 `<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 -->
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1 @@
@AGENTS.md
--- a/README.md
+++ 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/<scope>
 ```
 ### 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`.
--- a/ROADMAP.md
+++ 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.
 <!-- Example: remove or replace this section -->
 ## Priority 2
 Objective: optional second objective.
 - Replace with optional planned outcome.
 <!-- Example: remove or replace this section -->
 ## Priority 3
 Objective: optional third objective.
 - Replace with optional planned outcome.
--- a/ROADMAP.template.md
+++ 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.
 <!-- Example: remove or replace this section -->
 ## Priority 2
 Objective: optional second objective.
 - Replace with optional planned outcome.
 <!-- Example: remove or replace this section -->
 ## Priority 3
 Objective: optional third objective.
 - Replace with optional planned outcome.