Getting started

Pilotbook is a CLI. The graph is markdown in your repo. You will have a compiled brief in a few minutes.

Requires Node 20+.

Install

Consumers — pick one:

npx pilotbook init

npm i -g pilotbook
pb init

pnpm add -D pilotbook
pnpm exec pb init

pilotbook and pb are the same binary.

This repository is itself a Pilotbook project. Contributors use the local build, not a published install:

pnpm install
pnpm build
pnpm pb next

See CONTRIBUTING.md.

What init writes

From the repo root, pb init creates (skipping files that already exist):

pilotbook.config.yml
templates/epic.md
templates/story.md
templates/task.md
templates/adr.md
templates/business-rule.md
templates/idea.md
docs/backlog/epics/
docs/backlog/stories/
docs/backlog/tasks/
docs/adr/
docs/business-rules/
docs/ideas/
.gitignore                    # appends .pb
.cursor/rules/pilotbook.mdc
.cursor/skills/<name>/SKILL.md   # discover, shape, architect, implement, groom, prioritize
.claude/skills/pilotbook-<name>.md
AGENTS.md

--ai defaults to true. Pass --ai=false to skip agent wiring. Always-apply files tell the agent to run pb instructions overview and follow that router — they do not inline the skill bodies.

On an existing install, upgrade unedited shipped skills without clobbering local edits:

pb init --refresh-skills

You should see:

initialized /path/to/repo
wrote: pilotbook.config.yml, templates/epic.md, …

First items

Never invent IDs. pb new allocates them.

pb new epic --title "Multi-tenant workspaces"
pb new story --epic EPIC-001 --title "Create a workspace"
pb new task --story US-001 --title "Workspaces schema" --area db

You should see files like:

docs/backlog/epics/EPIC-001-multi-tenant-workspaces.md
docs/backlog/stories/US-001-create-a-workspace.md
docs/backlog/tasks/TASK-001-workspaces-schema.md

Open the task, then compile the context pack:

pb brief TASK-001
pb lint

lint should print lint ok: N items, 0 warning(s) on a fresh graph. Warnings are allowed; errors exit 1.

First explore

If the demand is a sentence, not a task, do not start with pb next. Calibrate, search, then capture:

pb instructions overview
pb profile --json
pb similar "ops dashboard" --type idea,epic,story
pb ground "ops dashboard"
pb new idea --title "Ops dashboard"
pb clarify IDEA-001

You should see docs/ideas/IDEA-001-ops-dashboard.md with Why, JTBD, Personas, Prior art, and Evidence sections. Fill those, then:

pb promote IDEA-001 --to epic --title "Ops dashboard"

You should see promoted IDEA-001 → EPIC-00N. Load shape next and write user stories — full session: Explore.

Look at the board

pb ui

Opens http://127.0.0.1:4173 (loopback only). Reloads when markdown on disk changes. Ctrl+C stops it.

CI

Add to GitHub Actions (or any runner with Node 20+):

- run: npx pilotbook lint --format github

--format github emits ::error file=…,line=… annotations. See CI.

Next

• Concepts — types, status, why files do not move
• Explore — calibrate, research, idea → epic → stories
• Ship — pick unblocked work and verify it
• Set up Notion — bind existing databases as a human board
• Agents — Cursor, Claude Code, MCP