Walkthrough

You'll take a small initiative, Billing, from a scope.md to a board with its first phase's tasks on it. The terminals show real Carol output, trimmed where marked. It was captured with v0.1.14 against Carol's test tracker, for a repository called acme/shop, so the issue numbers start at 1. None of the commands on this page has changed since, so v0.1.22 prints the same.

1. Write the scope. A scope.md with a Phases table.
2. Set up the repo. carol doctor, then carol bootstrap, once.
3. Mirror the scope. A pinned scope issue, a ticket and a board.
4. Publish a PRD. A milestone, an epic and one issue per task.
5. Fill the board. Every task on it, with a Status.
6. Check where it stands. carol status, then run and sync.

Step 1: Write the scope

An initiative is a directory under docs/. Its scope.md holds the destination and one row per phase. Save this as docs/billing/scope.md:

# Scope: Billing

## Destination

Customers get itemised invoices and can refund an order themselves. Done when both ship behind the existing checkout.

## Notes

- Payments go through the existing Stripe account.

## Decisions so far

- Invoices are rendered on the server.

## Phases

| Phase | Title | PRD | Status | Depends on |
|-------|-------|-----|--------|------------|
| phase-01 | Invoices | docs/billing/prds/prd-01-invoices.md | ready | |
| phase-02 | Refunds | | researching | phase-01 |

## Not yet specified

- Whether refunds over $500 need a second approver.

## Out of scope

- Multi-currency.

Phase-02 waits on a question only a person can answer, so it gets a grilling ticket, docs/billing/tickets/refund-limit.md:

---
type: grilling
question: Do refunds over $500 need a second approver?
status: open
blocks: [phase-02]
blocked-by: []
---

## Question

Is a single approver enough for every refund, or is there a threshold?

## Findings

Phase-01 is ready and has its PRD, docs/billing/prds/prd-01-invoices.md: two tasks, written with zurdo-prd-author and passing zurdo validate. Planning files has every rule these files follow.

Step 2: Set up the repo

carol doctor checks your gh login, the base labels and that Zurdo answers. On a new repository the labels check fails, and carol bootstrap is the fix:

$ carol bootstrap
bootstrap: acme/shop (12 ops)
  create_label zurdo:epic #5319E7
  create_label zurdo:task #1D76DB
  create_label zurdo:pending-review #FBCA04
  create_label zurdo:failed #B60205
…
$ carol bootstrap --apply
$ carol doctor
ok  labels
ok  zurdo
ok  skills

Step 3: Mirror the scope

$ carol scope docs/billing/scope.md
carol: defer: phase-02 has no epic yet
scope: acme/shop (9 ops)
  create_issue "Scope: Billing" [<!-- zurdo-github scope=billing -->]
  pin_issue [<!-- zurdo-github scope=billing -->]
  create_issue "Do refunds over $500 need a second approver?" [<!-- zurdo-github scope=billing ticket=refund-limit -->]
  add_sub_issue [<!-- zurdo-github scope=billing -->] <- [<!-- zurdo-github scope=billing ticket=refund-limit -->]
  create_project "Billing"
  link_project_repo "Billing" <- acme/shop
  set_project_metadata "Billing"
  add_project_item "Billing" <- [<!-- zurdo-github scope=billing -->]
  add_project_item "Billing" <- [<!-- zurdo-github scope=billing ticket=refund-limit -->]
$ carol scope docs/billing/scope.md --apply
…
$ carol scope docs/billing/scope.md
carol: defer: phase-02 has no epic yet
scope: acme/shop (0 ops)

Issue #1 is the pinned scope issue. Its body copies the destination, notes, decisions and the Phases table. The ticket is issue #2, a sub-issue of #1, labelled zurdo:grilling. The board, Billing, takes its title from # Scope: Billing.

carol scope sweeps every ticket under tickets/. Use carol ticket <file> to mirror just one. When a ticket's status becomes resolved, the next run posts its ## Findings as a comment and closes the issue.

Step 4: Publish the PRD

$ carol publish docs/billing/prds/prd-01-invoices.md
publish: acme/shop (12 ops)
  create_label effort:low #BFD4F2
  create_label effort:medium #BFD4F2
  create_milestone "Invoices"
  create_issue "Invoices" [<!-- zurdo-github prd=docs/billing/prds/prd-01-invoices.md epic -->]
  create_issue "Render an invoice" [<!-- … task=task-01 -->]
  create_issue "Email the invoice" [<!-- … task=task-02 -->]
  add_sub_issue [<!-- … epic -->] <- [<!-- … task=task-01 -->]
  add_sub_issue [<!-- … epic -->] <- [<!-- … task=task-02 -->]
  add_blocked_by [<!-- … task=task-02 -->] <- [<!-- … task=task-01 -->]
  add_sub_issue [#1] <- [<!-- … epic -->]
…
$ carol publish docs/billing/prds/prd-01-invoices.md --apply

The epic, #3, lists its tasks in a table and says Part of #1. Task #4 is labelled effort:medium and ready-for-agent. Task #5 is blocked by #4, because its Depends-on names task-01. A PRD stored outside the initiative still publishes: pass --scope <n> yourself.

Step 5: Fill the board

$ carol board docs/billing/prds/prd-01-invoices.md
board: acme/shop (5 ops)
  set_status_options "Billing" Todo,In Progress,Pending Review,Done,Failed
  add_project_item "Billing" <- [<!-- … task=task-01 -->]
  set_project_item_status "Billing" [<!-- … task=task-01 -->] = Todo
  add_project_item "Billing" <- [<!-- … task=task-02 -->]
  set_project_item_status "Billing" [<!-- … task=task-02 -->] = Todo
$ carol board docs/billing/prds/prd-01-invoices.md --apply

The board now holds the scope issue, the ticket and both tasks. Each card's Status comes from the task's run: passed is Done, passed-pending-review is Pending Review, failed is Failed. Without --project, board uses the initiative's board.

The scope issue's Phases table now has an epic to show. Run carol scope once more, and its plan rewrites the scope issue's body so phase-01's row reads #3 and Invoices in the Epic and Milestone columns.

Step 6: Check where it stands

$ carol status billing
Status — Billing (docs/billing/)
Destination: Customers get itemised invoices and can refund an order themselves.
phase-01  Invoices  ready  prd-01-invoices.md  no run
phase-02  Refunds  researching  —  no run
Handoff: none.

From here the loop turns over to Zurdo. Run the PRD, then sync its outcome back:

zurdo run docs/billing/prds/prd-01-invoices.md
carol sync  docs/billing/prds/prd-01-invoices.md --apply
carol board docs/billing/prds/prd-01-invoices.md --apply

sync comments each task's outcome on its issue, labels failed and pending-review tasks, and closes the ones that passed. board moves their cards. Sync to your tracker covers both in depth.

When you stop before the initiative is done, leave a handoff. Once phase-01 is done, set its row to done, answer the ticket, and run carol scope again.

Next: Planning files