| Section | What's Covered |
|---|---|
| Core Concepts | Beads, North Star, Lossless, Grounding, Calibration, Drift |
| Requirements & Planning | REQ, AC, ADR, Rigor Tier, Priorities, Spikes, Gates |
| Execution | TDD, 3-Iteration Limit, ADaPT, Verification |
| Multi-Agent Coordination | Agent Mail, File Reservations, Claims, Orchestrator Pattern |
| Tools | bd, bv, ubs, cass, cm, MCP, Warp-Grep, Exa |
| Slash Commands | /prime, /advance, /calibrate, /decompose, /ground |
| Phrases | Common expressions and their meaning |
|
The pre-pipeline phase where you surface every decision hiding in your idea through curiosity-driven interrogation of frontier models. Discovery happens before formal planning begins.
See | ||||||||||||
|
The unit of work in this system. A bead is a task with a description, status, priority, dependencies, and verification requirements. Managed with the Beads can have sub-beads (e.g., | ||||||||||||
|
A one-page document that anchors the entire project. Contains: goal, success metrics, rigor tier, non-goals, and stop/ask rules.
| ||||||||||||
|
A plan or spec where nothing is left to interpretation. Another agent could implement it without asking clarifying questions. "Lossless" means no guessing required, not "exhaustively long." | ||||||||||||
|
Verifying claims against real sources before acting on them. Three types:
Research: | ||||||||||||
|
A hard stop between phases to check alignment. Detects drift, resolves disagreements, updates the plan. Triggered by Research: | ||||||||||||
|
When implementation gradually diverges from the original plan. Causes: long context, forgotten requirements, accumulated decisions. Calibration catches drift before it compounds. Research: |
|
A numbered requirement describing what the system must do. Format: Requirements describe outcomes, not solutions. Example: | ||||||||||||
|
Testable conditions that prove a requirement is met. Format:
Example: | ||||||||||||
|
A log entry documenting a significant decision. Contains:
| ||||||||||||
|
How much process a project needs:
| ||||||||||||
| ||||||||||||
|
A timeboxed investigation to reduce uncertainty. Run before committing to an approach. Example: "Spike: Can we integrate with their API?" (output: yes/no + notes) | ||||||||||||
|
A checkpoint that must pass before proceeding:
|
|
Writing tests before implementation. In this system, TDD is mandatory. Tests go in the bead description before code is written. Research: |
|
Never attempt more than 3 repair cycles on failing code. After 3 failures: stop, decompose, or escalate. Research: |
|
Only break tasks into smaller pieces when execution fails. Don't pre-decompose based on guesses. Flow: Start coarse → Attempt execution → If fails after 3 tries → Decompose only the failing part Research: |
|
Evidence that a bead is complete:
|
|
The coordination system for multiple AI agents. Provides:
| ||||||
|
A randomly generated identifier (e.g., "BlueLake", "GreenCastle"). Assigned at registration. Names are memorable identifiers, not role descriptions. | ||||||
|
A lock on files or directories that prevents other agents from editing simultaneously. Set before editing, released when done. Prevents merge conflicts and duplicate work. | ||||||
|
Message subjects announcing when an agent starts or finishes a task:
All agents see these to avoid stepping on each other. | ||||||
|
A coordination pattern where one agent (orchestrator) assigns work to others (workers) and synthesizes results. Research: |
|
Command-line tool for task management. bd create "Task name" # Create a bead
bd ready --json # See unblocked beads
bd update ID --status ... # Update a bead
bd close ID --reason "..." # Close a bead
bd dep add child blocker # Add dependency |
|
Analyzes the bead graph and recommends next tasks. bv --robot-next # Single best next task
bv --robot-triage # Full analysis
bv --robot-alerts # Risks and stale itemsAlways use |
|
Security scanner that catches vulnerabilities before commit. ubs --staged # Scan staged changes
ubs --staged --fail-on-warning # Strict modeMandatory before every commit. |
|
Searches past Claude Code sessions to find similar solutions. cass search "query" --robot
cass timeline --today --jsonAlways use |
|
Retrieves learned patterns and anti-patterns for your current task. cm context "what I'm doing" --json |
|
A standard for giving AI assistants additional capabilities. MCP servers provide tools to Claude Code. |
|
MCP tool for fast parallel codebase search. Use to understand how things work across multiple files. |
|
MCP tool for web search. Use to verify documentation, find best practices, research libraries. |
| Command | Purpose |
|---|---|
/prime |
Start a new session. Registers with Agent Mail, checks inbox, discovers tasks. |
/advance |
Full bead lifecycle: close current, discover, claim, reserve files, work (TDD-first), announce. |
/calibrate |
Run a calibration checkpoint. Checks coverage, detects drift, resolves disagreements with tests. |
/decompose |
Break a phase into beads and sub-beads. Creates the task graph for execution. |
/ground |
Verify external libraries and APIs against current documentation. |
/recall |
Retrieve context from past sessions (CASS search + cross-agent learning). |
/explore |
Parallel codebase search for understanding how things work. |
/verify |
Security scanning with UBS before commits. |
/resolve |
Resolve disagreements between agents or approaches using test-based adjudication. |
/release |
Run pre-ship checklist for release readiness. Verifies tests, security, documentation. |
|
Plan as much as appropriate. Give the AI as few decisions as possible. Any decision you don't claim, you implicitly delegate. |
|
The plan is complete when there's nothing left to interpret. If an agent would need to ask a clarifying question, you're not done planning. |
|
The three rules of lossless decomposition:
|
|
Gaps become assumptions. Assumptions become architecture. Bad architecture becomes a rewrite. This is why discovery matters. |
|
The time gets spent either way. You either spend it upfront thinking through decisions, or later untangling decisions the model made without you. |
|
AI output is not truth. Truth is tests that pass, code that compiles, behavior you can observe. |
|
When agents disagree, they write tests that distinguish the approaches. Test results decide, not arguments. |
|
Don't ask "are you sure?" That makes the AI second-guess correct answers. Instead, run tests and use results as feedback. |
|
A predefined trigger for when the AI should pause and ask the user. Defined in the North Star Card. |
|
Checking whether you have enough information before starting. If you'd have to guess, gather more context first. |
|
You can't prompt your way to reliability. You need a system where failures get caught before they matter. |