File formats · Zurdo

The planning files Carol reads in v0.1.22: scope.md and its Phases table, ticket front matter, the handoff, and the contract file.

Carol reads plain Markdown under docs/<initiative>/. A file it can't parse is a usage error (exit 2) before anything is planned. For how the files fit together, see Planning files.

File	Path
Scope	`docs/<initiative>/scope.md`
Ticket	`docs/<initiative>/tickets/<name>.md`
Contract	`docs/<initiative>/contracts/<name>.md`
Handoff	`docs/<initiative>/handoff.md`
PRD	`docs/<initiative>/prds/prd-NN-<phase>.md`, in Zurdo's grammar

scope.md

# Scope: Billing

## Destination
Customers get itemised invoices and self-serve refunds.

## Notes
## Decisions so far

## Phases

| Phase | Title | PRD | Status | Depends on | Design |
|---|---|---|---|---|---|
| phase-01 | Invoices | docs/billing/prds/prd-01-invoices.md | done | | |
| phase-02 | Refunds | | ready | phase-01 | design/refunds.md#Self-serve refunds |

## Not yet specified
## Out of scope

Part	Rule
`# Scope: <title>`	Required. Names the scope issue and the board.
`## Destination`	Its first sentence is the summary `carol status` prints.
`## Notes`, `## Decisions so far`, `## Not yet specified`, `## Out of scope`	Copied into the scope issue
Any other `##` section	Stays local
`## Phases`	A row is any table line whose first cell starts with `phase-`

The Phases table

Column	Required	Holds
Phase	Yes	`phase-NN`, the id other files use
Title	Yes	The phase's name
PRD	Yes, may be empty	The PRD's path
Status	Yes	`planned`, `researching`, `ready`, `running` or `done`
Depends on	No	Phase ids and `contract:<name>` entries, separated by commas or spaces
Design	No	`design/<topic>.md#<heading>`, matching a heading in that file exactly

An unknown phase id or contract name in Depends on is a parse error in every command. Carol never writes Status, except that specify sets running in its pull request.

Ticket front matter

---
type: research
question: Which tax rules apply to EU invoices?
status: open
blocks: [phase-03]
blocked-by: []
---

## Question
## Findings

Key	Values
`type`	`research` or `grilling`
`question`	One line. It becomes the issue title.
`status`	`open` or `resolved`
`blocks`	Phase ids this ticket blocks
`blocked-by`	Names of tickets (file names without `.md`) resolved first

The ticket's name is its file name. ## Findings is posted as a comment, and the issue closed, once the ticket is resolved.

The handoff

---
initiative: billing
stopped_at: 2026-10-05T18:40:00Z
station: run-and-sync
phase: phase-02
by: agent
---

# Handoff: Billing

## Stopped at
## Done this session
## In flight
## Waiting on a human
## Next action
## Uncommitted
## Watch out

Key	Rule
`initiative`	The handoff's directory name
`stopped_at`	UTC ISO-8601 to the second
`station`	`scope`, `research`, `phase-prd`, `publish`, `run-and-sync` or `phase-review`
`phase`	A phase in the sibling Phases table
`by`	`agent` or `user`

The title is # Handoff: <initiative title>. The seven sections appear in this order, with no others. An empty section says None., and ## Next action holds exactly one Row <n> — <action> line. carol handoff check enforces each rule.

The contract file

---
provider: billing/phase-02
provider_owner: alice
consumer: billing/phase-03
consumer_owner: bob
---

## Interface

What the provider promises, in prose.

## Acceptance Criteria

- [ ] the event type exists [grep: RefundIssued in src/billing/events.ts]

Part	Rule
`provider`, `consumer`	`<initiative>/phase-NN`, both phases of the contract's initiative
`provider_owner`, `consumer_owner`	GitHub logins. One person may own both sides.
`## Interface`	Prose. Editing it alone keeps the agreement.
`## Acceptance Criteria`	Zurdo criteria with hints, checked by `zurdo validate`. Changing them resets the agreement.

The consumer names it in Depends on as contract:<name>. See Contracts.

Next: Labels & markers