§ 01

Import format reference

Two formats, auto-detected, from a paste, a picked file, or anything dropped into data/inbox/.

Sections

Every ## Heading becomes a card: the heading is the title, leading key: value lines set fields, an ### Acceptance subsection becomes the acceptance criteria, everything else is the prompt. Optional frontmatter sets file-wide defaults:

---
cwd: /Users/you/project
model: sonnet
worktree: true
openPr: true
group: auth-refactor
queue: true
---

## Fix the flaky login test
model: opus
priority: 2
The test in auth.spec.ts fails intermittently because…

### Acceptance
- passes 10x in a row

## Update the README badges
after: Fix the flaky login test

Recognized keys (case/space-insensitive): cwd (dir/repo), model, effort, permissions, priority (0–3), worktree, openPr (pr), agent, skills, acceptance, group (batch), base (prBaseBranch — for repos whose branch guards reject PRs straight into main), after (deps/needs — the exact title of an earlier card; repeat the line for several), sequential (chain every card in the file to the one above it), and queue (autoqueue — launch every card on import instead of leaving them in Backlog; chained cards park in Queued and cascade as prerequisites ship). A card with no body uses its title as the prompt.

Checklist

A file with no ## headings: every unchecked - [ ] item becomes a card (checked items are skipped).

Imported cards land in Backlog tagged import, and the Sensei gets one triage ping per batch.

§ 02

The Sensei: actions & autonomy levels

The Sensei is an LLM manager — itself a claude -p structured-output call on your subscription — that triages new cards (model/effort/skills/priority routing), dispatches queued work, reviews finished cards against their acceptance criteria and their actual PR diff, chains multi-card plans with dependencies, and answers you in chat.

Review & fix actions

A review card carries its real PR diff into the Sensei’s context, not just the agent’s self-report — the diff is what catches ordering, logic, and safety issues a self-report misses. From there:

• followup_task resumes the same agent session with a precise, named fix instead of burning a full retry — reserved for small, specific flaws; reject_task still handles approach-level failures that need a fresh attempt.
• merge_pr ships the card’s PR itself once every CI check on it is green and the base branch is correct, instead of approving and leaving a “done” card still blocking its dependents. It skips with a note when checks are red, pending, or haven’t reported yet.
• It resolves entries in the error tracker (permission stops, wrong-base PRs, failed launches) by fixing the operation, not the code, then marking the entry handled.

Repeated or stale actions are no-ops rather than errors — running a card that’s already running, approving one already done — so a Sensei decision made against a snapshot that’s since changed underneath it can’t double-fire a run.

Autonomy ladder

Level	Can do without you
suggest (default)	nothing — every action waits for your ✓
semi	create / route / run cards; approve-reject verdicts still wait
auto	everything, within guardrails

Deleting cards is never available to the manager, at any level. Guardrails (max launches/hour, max retries/task, a permission ceiling it can’t assign beyond) sit on top of the ladder; a guardrail-blocked action becomes a suggestion instead of executing.

Management style: freeform standing instructions (“prefer haiku for docs tasks”, “never auto-approve migrations”) — no code changes needed.

§ 03

Dependencies & merge-gate semantics

Give a card Runs after prerequisites (or after / sequential when importing) and it waits in Queued until every one of them is actually done.

“Actually done” is stricter than the column a card sits in. A dependency isn’t satisfied by a card just reaching Done — if that card opened a PR that’s still open and unmerged, the dependent keeps waiting; a merged PR, or a card that never opened one, releases it. That's the merge gate: a card can look finished on the board while still blocking everything queued behind it, until the PR itself lands.

The Sensei's merge_pr action (see § 02) exists partly to close this gate on its own — merging a green PR itself rather than leaving a “done” card sitting on top of blocked dependents. The Sensei also chains multi-card plans itself, and imported cards chain the same way via after:/sequential: (§ 01).

§ 04

Groups & lanes

Cards sharing a Group field cluster under one collapsible header on the board instead of appearing as separate cards in every column. Three rules govern how a group behaves:

• Only one card per group is ever in progress — a group is a single lane, not a parallel batch, so related work runs in a defined order rather than all at once.
• A ▶ button on the group header queues the whole batch in one action, instead of launching each card by hand.
• Finishing a group fires one notification for the whole batch, not one per card — useful when a plan imports as a dozen small cards and you only want one ping.

Imported markdown sets the group with the group (or batch) key in frontmatter or a card's leading fields (§ 01); groups and dependencies compose — a grouped card can also carry after: prerequisites, and both constraints apply together.