Skip to main content

Take Your First Turn

The smallest useful Keel session is not "open the app and click around." It is: scaffold the project, read what the board is telling you, and then make the first structured move.

Expected

A new board starts mostly empty

On day one, health and doctor will tell you the board has no active mission yet. That is orientation, not failure.

Important

Bootstrap with `keel new`

`keel new` scaffolds the board, installs commit-boundary hooks, and writes the downstream foundation docs that agents need to understand the repo.

Practical

Capture IDs as you go

Commands such as `mission new`, `epic new`, and `voyage new` return IDs. Use the returned IDs in the next move.

1. Start in a fresh Git repository​

keel new harbor
cd harbor

keel new creates the board scaffold, initializes Git when needed, installs Keel's git hooks for commit-boundary validation, and writes the downstream foundation docs plus keel.toml.

Before you create planning work, hydrate the root docs it scaffolds: CONSTITUTION.md, POLICY.md, ARCHITECTURE.md, USER_GUIDE.md, AGENTS.md, GEMINI.md, CLAUDE.md, and INSTRUCTIONS.md.

2. Read the board before creating work​

keel health --scene
keel doctor --status
keel heartbeat
keel mission next --status

On a brand-new board:

  • keel health --scene shows whether the system is structurally healthy
  • keel doctor --status reports that no mission exists yet
  • keel heartbeat shows whether recent repository activity is still energizing the board
  • keel mission next --status returns a non-zero exit with a suggestion to create a mission

That is the expected opening posture. Keel is telling you the board has no direction yet.

keel heartbeat is the canonical pacemaker surface now. If you want the deeper contract behind that command and the scenes that depend on it, read Heartbeat And Pacemaker and Scene Surfaces.

3. Create the first planning stack​

Create the smallest stack that can produce a real delivery slice:

keel mission new "Launch the first public docs"
keel mission activate MISSION-ID

keel epic new --problem "Readers cannot understand Keel quickly." "Teach the product story"

keel voyage new \
  --epic EPIC-ID \
  --goal "Ship an onboarding path that explains the board model." \
  "Narrative onboarding"

keel voyage plan VOYAGE-ID
keel voyage start VOYAGE-ID

keel story new --epic EPIC-ID --voyage VOYAGE-ID "Write the opening guide"
keel story start STORY-ID

Replace MISSION-ID, EPIC-ID, VOYAGE-ID, and STORY-ID with the values returned by the CLI.

That stack is what lets Keel talk about a slice precisely. The story is the tracked item, but the slice is the full ready-to-execute cut: active mission, active epic, planned voyage, authored PRD/SRS/SDD, and one backlog story that is ready to start.

If you hear "created a Keel slice," read it as "the board can now show the lineage, artifacts, implementation boundary, and next move for one executable story."

4. Pull the next move from the lane​

Once the first story exists, return to the board instead of inventing your own queue:

keel next --role operator
keel flow --scene

keel next --role operator is the delivery pull surface. keel flow --scene gives you the board-wide picture of whether the circuit is open, healthy, or waiting on something.

5. Close the slice with evidence​

The turn is not complete when the code or content exists. It is complete when the board can show why the slice should be trusted.

keel story record STORY-ID --ac 1 --msg "Manual proof captured during first-run review."
keel story submit STORY-ID
keel story accept --role manager STORY-ID

The exact evidence command you use will vary by story. The contract does not: attach proof, submit the slice, accept it with an explicit role.

6. Repeat the turn loop​

01

Orient

keel health --scene

Read the board before acting. Check for drift, blocked work, and missing integrity.

02

Inspect

keel mission next --status

Understand what the system thinks matters now at the strategic and tactical level.

03

Pull

keel next --role operator

Take one role-scoped move from the delivery lane instead of browsing an unbounded backlog.

04

Ship

keel story submit STORY-ID

Move the slice into review only when the implementation and its evidence are ready together.

05

Close

keel story accept --role manager STORY-ID

Accept the slice with an explicit role, then let the next turn begin from a clean board state.

Once you can perform this loop without guessing, you are ready for the foundations and persona-specific tracks.

note

If you prefer a tighter engineering loop, you can continue to run the binary through cargo run -- ... while you learn the system. Keel's operating model does not depend on a specific editor or AI vendor.