Concepts

Pilotbook is a knowledge graph whose nodes are markdown files with YAML frontmatter. The CLI does not own the graph. Git does.

The chart and the directions

• The chart is the files: epics, stories, tasks, ideas, ADRs, business rules, and the edges between them.
• The directions are pb brief <ID>: a compiled, authority-ordered pack an agent can follow without improvising architecture.

pb lint and pb brief are pure functions of files on disk. No event log, no SQLite, no server for the core loop. The CLI, MCP server, and local UI are transports over the same operations.

Types

Six builtin types. There is no builtin bug type.

Type	Prefix	Default directory	Parent
epic	EPIC- (3 digits)	docs/backlog/epics	—
story	US- (3 digits)	docs/backlog/stories	epic
task	TASK- (3 digits)	docs/backlog/tasks	story (optional)
adr	ADR- (4 digits)	docs/adr	—
business-rule	BR- (3 digits)	docs/business-rules	—
idea	IDEA- (3 digits)	docs/ideas	—

Prefixes and padding are configurable. See config.

IDs

IDs are allocated by pb new. Never invent them, never reuse them, never hand-edit promoted_to. That is BR-001.

Filenames must be {id}-<slug>.md, for example TASK-001-workspaces-schema.md. Lint fails filename-mismatch otherwise. Status changes by editing frontmatter, not by moving files.

Status

Work items (epic, story, task):

backlog → todo → in-progress → review → done

Also: blocked, cancelled.

Kind	Statuses
Work	backlog, todo, in-progress, review, blocked, done, cancelled
ADR	proposed, accepted, rejected, superseded, deprecated
Business rule	draft, active, deprecated
Idea	raw, exploring, promoted, rejected

Priority is P0 … P3. Phase is a number. Area on tasks is backend, frontend, db, infra, or docs.

File layout

Default root is docs:

pilotbook.config.yml
templates/
docs/
  backlog/
    BOARD.md          # generated by pb board
    epics/
    stories/
    tasks/
  adr/
  business-rules/
  ideas/
.pb/                  # gitignored cache (manifest, Notion map, JUnit)

Discovery walks up from cwd for pilotbook.config.yml or pilotbook.config.yaml, then the git root.

Two loops

1. Explore — pb profile calibrates the agent; a vague demand becomes a researched idea (prior art + evidence), then an epic, then shippable stories. Explore.
2. Ship — pb next picks unblocked work, pb brief loads governing rules, you implement, pb verify stamps evidence. Ship.

Agents load pb instructions overview (the only explore/ship router), then one skill (pb skill discover or pb skill implement). Agents.

Repo maturity is derived at read time (pb profile). It is never a frontmatter field.