work

Work an epic

Run one epic's tasks in order, one at a time, until VibeDoc says the epic is finished or a human is needed. VibeDoc picks the order: vibedoc_next_task respects Depends on, skips blocked tasks and tasks another agent has claimed, and moves the claimed task to in-progress so the board shows who is working on what. Don't choose tasks yourself, and don't work on a task you did not claim.

Argument: an epic id such as R037. If there is none, ask which epic to work on (vibedoc_get_roadmap lists them). Work on one epic only.

Before the loop

Read the project's CLAUDE.md once. Task files quote the relevant rules, but the commands (build, lint, package manager), bans and commit rules are only in CLAUDE.md. You need them for every task.

The loop

1. Claim. Call vibedoc_next_task { "epic": "<id>" }. The reply starts with one of three markers:

   • 🔨 Claimed — go to step 2. The reply contains the full task file.
   • ⏳ Nothing ready — see the stop rules below.
   • ✅ Epic … is finished — see the stop rules below.

   If a reply ends with a 🗺️ Roadmap out of sync hint for this epic (for example, set it to in-progress), apply it with vibedoc_update_roadmap_item, so the roadmap matches the board.

2. Read the task. If the reply has a ⚠️ Changes requested line, a human sent this task back from review: that note is the first thing to fix, and the rest of the spec still applies. A 🤖 Last auto run failed line names the Playwright spec that failed last time: read the failing step in the task's report, and make that spec pass before done. Read its Goal, Scope, Files, Implementation notes, Acceptance criteria and Verify. The task file is the spec. Stay inside its Scope: later tasks in the epic own the rest, and if you do their work now, their diffs will conflict with yours.

   A ## Related spec block lists requirements of the capability spec you are working in (vibedoc_get_spec reads one in full). Keep them true. If the task really has to change one of them, the epic's ## Spec changes should say so; if it doesn't, do the task as written and say in your report which requirement changed. Never edit docs/specs/ yourself: a person merges the epic's spec changes when it is done.

3. Implement the task, following the project's patterns. When the task adds or changes a doc whose content has a shape (an order of steps, a flow, states, options, a timeline), show it with a Mermaid fence or a visual block (<!-- vibedoc:steps|cards|compare|timeline --> above a plain list) instead of only prose: see visuals.md for which type to pick and the size rules.

4. Verify. Run every command in the task's Verify block, and check each acceptance criterion you can check. If something fails and the fix is inside the task's scope, fix it and run Verify again. If the task changed any .md file, also call vibedoc_check_docs { "path": "<file>" } for each one and fix its errors (broken links, bad frontmatter, spec changes that won't merge) before done; warnings are yours to judge.

5. Done. Only when Verify passes: write a manual test report (below). If the task changed something a user sees in the browser, write the spec for it next (Write the spec) and run it (Run the spec): a UI task with a spec is done only when the spec passes. Then call vibedoc_update_task { "taskId": "<id>", "status": "done", "manualTests": "<report>" } (plus "spec": "<path>", "autoResult": "passed" when you wrote and ran one), then commit that task's changes, following the repo's commit rules (message format, attribution, which files to stage). Each task leaves the app in a working state. When you commit after each task, it is safe to stop at any point, and a human can review or revert one task at a time.