Carol

Project management for Zurdo-driven repositories: your planning files and Zurdo's run state, mirrored onto your tracker.

Carol v0.1.22

Zurdo runs one PRD and verifies it. Carol manages everything around that run: the initiative the PRD belongs to, the questions it waits on, the issues your team reads, and where the work stands when you come back to it.

acme/shop
$ carol scope docs/billing/scope.md
scope: acme/shop (9 ops)
  create_issue "Scope: Billing" [<!-- zurdo-github scope=billing -->]
  pin_issue [<!-- zurdo-github scope=billing -->]
  create_project "Billing"
…
$ carol scope docs/billing/scope.md --apply
Every write is planned first. Nothing changes until --apply.

Your plan lives in Markdown files in the repository. Carol projects those files onto your tracker, one way, and reads Zurdo's run results back onto the same items. Today the tracker is GitHub: issues, milestones, sub-issues and a Projects board.

ZurdoCarol
Unit of workOne PRDAn initiative: a scope.md with phases, tickets, and one PRD per phase
ReadsThe PRD, .zurdo/config.toml, the working treeYour planning files, plus Zurdo's JSON output
Writes.zurdo/<slug>/ run stateTracker items and a board, only with --apply
DecidesWhether each criterion passedNothing on its own. It mirrors what you and Zurdo decided.

Where Carol fits in the loop

A phase goes round the same loop every time. Zurdo owns the middle of it. Carol keeps the tracker in step at each edge, so nobody copies run results into issues by hand.

The PRD loop: scope, author, a verify gate that sends findings back to author, run, review, and a decide step that returns to scope for the next PRDThe PRD loop: scope, author, a verify gate that sends findings back to author, run, review, and a decide step that returns to scope for the next PRD
StepZurdoCarol
1 · Scope—carol scope mirrors scope.md as a pinned scope issue and a board. carol ticket files the open questions under it.
2 · Authorzurdo-prd-author writes the PRDcarol publish makes a milestone, an epic and one issue per task. carol board puts them on the board.
3 · Verifyzurdo validate, zurdo analyze—
4 · Runzurdo runcarol status shows the phase in flight, or crashed if the run died.
5 · Reviewzurdo report, zurdo reviewcarol sync posts each task's outcome, sets labels and closes passed tasks. carol board moves the cards.
6 · Decide—You update scope.md and run carol scope again.

The Walkthrough goes round this loop once, with real output.

Two ways to drive it

You type the commands scope, ticket, publish, board, sync. You write the PRD and start the run. This is where everyone starts, and it needs only your own tracker login.

Carol drives, you steer propose, specify, run and report move a phase from proposal to reported run as a GitHub App. carol tick takes one step and carol watch loops it. You approve on pull requests and labels. See The engine loop.

Principles

  • Files are canonical. scope.md, tickets and PRDs are the source of truth. The tracker is a projection: Carol never reads your plan back from it.
  • Plan, then apply. Every command that writes prints its plan and stops. With --apply it writes, then reads each write back to confirm it stuck.
  • Markers are identity. Every item Carol creates carries a hidden marker naming the file (and task) it came from. A re-run updates that item and never makes a duplicate.
  • Zurdo's JSON is the only run state. Carol never opens .zurdo/ itself. It asks the zurdo binary (zurdo report, zurdo state list, zurdo validate). In the engine loop, run posts that JSON on the run pull request, and report reads it from there.

Keep Zurdo current. If your .zurdo/config.toml uses a table your installed Zurdo doesn't know, every zurdo report fails and carol sync exits 6. carol specify needs Zurdo 1.30.0 or later.

Next: Installation