queue-driven-workflow

name	queue-driven-workflow
description	Use when doing any multi-step or planning work in a cleanvibe-scaffolded project — enforces plan-into-queue.md-first, the todo.md→queue.md→devlog.md flow, delete-don't-check completion, task-tool mirroring, and tests/CI discipline.

Queue-driven workflow

Workflow Rules

• Commit early and often. Every meaningful change gets a commit with a clear message explaining why, not just what.
• Plan into queue.md first, then execute. When entering planning mode (or doing any non-trivial multi-step work), the FIRST action is to write the plan into queue.md as concrete items. Only then begin executing. This means an interrupted session can resume from the queue — the plan does not live only in chat context.
• Finishing an item = delete from queue.md + append to devlog.md, then commit and push. IMPORTANT: when a queue item is done, delete the item from queue.md and append a dated entry to devlog.md recording what was completed, in the same commit as the work, then push. NEVER mark an item done in place (no [x], no "✓", no "DONE" — a checked box left in queue.md is the failure mode this rule exists to prevent). queue.md only ever holds not-yet-done work; devlog.md is where "done" lives.
• Mirror queue.md into the task tool. TaskCreate items as you add them to queue.md; mark in_progress when starting; completed when done. The two views must not drift.
• Keep CLAUDE.md up to date. As the project takes shape, record architectural decisions, conventions, and anything needed to work effectively in this repo.
• Update README.md regularly. It should always reflect the current state of the project for human readers.

Queue and longer-horizon work

• queue.md — what's being worked on right now. Items get deleted on completion; do not leave checkmarks or status indicators behind. If it's not in queue.md, it's not in scope for the current session.
• todo.md — the long-term horizon of the project. Multi-session goals, architectural ambitions, future capabilities. Items in todo.md are abstract: they describe a destination, not a step. todo.md is the basis for queue.md: when work begins, an item is pulled from todo.md, decomposed into concrete executable steps in queue.md, mirrored into the task tool, and executed. As queue.md drains, refill it by pulling and decomposing the next todo.md item.
• devlog.md — where "done" lives. Every queue item that is finished gets deleted from queue.md and appended as a dated entry here, in the same commit as the work. Releases (tag + one-line note) and notable milestones also go here. devlog.md exists so queue.md can stay strictly delete-only without losing the historical trail.
• Flow: todo.md (abstract horizons) → queue.md (concrete steps) → task tool (in-flight work) → devlog.md + git log (history). Items only ever flow forward; do not leave done items behind in todo.md or queue.md.
• Session end condition: the project's first session ends when queue.md is empty, the only items left in todo.md are still too abstract to break down further, and the repository is online with green CI. At that point, stop and hand back to the user.

Testing

• Write unit tests early. As soon as there is testable logic, create a test file. Use pytest for Python projects or the appropriate test framework for the language in use.
• Set up CI as soon as tests exist. Create a .github/workflows/ci.yml GitHub Actions workflow that runs the test suite on push and pull request. Keep the workflow simple — install dependencies and run tests.
• Keep tests passing. Do not commit code that breaks existing tests. If a change requires updating tests, update them in the same commit.