Planning in the open with Carol

How Carol mirrored the whole Site launch initiative onto GitHub, from scope and tickets to 14 PRDs and their run status, and how the read-only views keep it honest.

The plan for this site lives in Markdown files in the repository. Carol projects those files onto GitHub so anyone can follow the work without opening the repo. Every issue on the board came from a file. None was made by hand.

What gets mirrored

The Site launch initiative began with three planning files:

docs/site-launch/scope.md, with the destination, the key results and the phases table;
docs/site-launch/tickets/stack-and-hosting.md, the grilling ticket that settled Next.js on AWS Amplify Hosting;
docs/site-launch/prds/prd-01-public-site.md, the phase-01 PRD with seven tasks.

It grew from there: more tickets and PRDs, five design records, a handoff and a lessons/ folder. Carol v0.1.20 also mirrors a scope's contracts and its ticket edges.

Carol mirrors scope, ticket and PRD to issues and the Site launch board

Each station, on GitHub

Scope. carol scope mirrors scope.md as the scope issue (#1 for this initiative) and sets up its board:

carol scope docs/site-launch/scope.md --apply

Research. carol ticket mirrors each ticket as a sub-issue of the scope issue. The stack-and-hosting ticket became #3. When a ticket is resolved, its findings are posted on the issue and the issue is closed.

carol ticket docs/site-launch/tickets/stack-and-hosting.md --apply

Publish. For phase-01, two commands put the PRD on GitHub:

carol publish docs/site-launch/prds/prd-01-public-site.md --apply
carol board docs/site-launch/prds/prd-01-public-site.md --apply

The first created a milestone, an epic (issue #4) and one issue per task (#5 to #11). The second put them on the Site launch board. Neither needs a flag for this repo. --scope is only for a PRD outside docs/<initiative>/prds/, and the board defaults to the initiative's own.

Phase review. When a phase is done, its review updates scope.md and closes the phase's epic.

One way, by design

The planning files are the source of truth. GitHub is a projection of them, so Carol never reads an issue and edits a file from it.

Status comes back the other way. After a run, carol sync writes each task's result onto its issue and the epic:

a comment on every task;
passed tasks closed;
tasks waiting on review labelled zurdo:pending-review;
failed tasks labelled zurdo:failed;
a status table on the epic.

Planning files flow one way to GitHub; run status syncs back

Every write is planned first. Without --apply, Carol only prints the operations it would run. Re-planning prd-01's sync on 2026-10-29 printed this:

sync: numeron-lab/web.zurdo.sh (0 ops)

Zero operations means GitHub already matches the files. That holds per Carol version, though. The same day, carol publish on prd-01 planned 1 op, a set_issue_body on the epic, because a newer Carol renders the epic's body differently from the one that published it.

The mirror by the numbers

The Site launch initiative's record as of its phase-10 review, 2026-10-28:

Number	What it counts	Source
14 epics	one per PRD, 5 of them follow-ups	`gh issue list`, by `zurdo:*` label
66 task issues	one per task in those PRDs	`gh issue list`, by `zurdo:*` label
4 tickets, 2 scopes	ticket and scope issues	`gh issue list`, by `zurdo:*` label
1	failed task left open: #32, prd-02-docs-port's Lighthouse gate, still labelled `zurdo:failed`. A follow-up PRD redid it	`carol score --report`, `gh issue list`
45 of 48	tasks an agent worked that passed on the first attempt; 2 more passed on a retry	`carol score --report`
0 ops	a re-run of `carol sync` on prd-01, read 2026-10-29	`carol sync` dry-run
3m43s, 3m11s	from a dist release to its docs on this site: Zurdo v1.33.0 (#89), Carol v0.1.20 (#91)	phase-10 review in `scope.md`

The failed task stays open on purpose. The board shows what happened, not what we wished had happened.

The read-only views

Three commands read the files and the run state and write nothing:

carol status maps each phase of an initiative: its run state, row conflicts in the phases table, and how fresh the handoff is. It works offline.
carol score --report puts each run task's outcome beside the authoring warnings its PRD drew. The 45 of 48 above comes from it.
carol handoff check validates docs/site-launch/handoff.md, written at every session stop, so the next session starts from a handoff that is well-formed.

Carol also has an engine path, carol propose then carol specify, where Carol drafts a PRD and a person reviews it in a pull request. It is not used here yet.