Skip to main content
Models change, chats end, sessions reset. The work should not restart every time. In Driftless a Project owns the goal, the cards, the context, and the verification, so a second agent (a different model, a fresh session, or a teammate’s client) can continue from the exact card the first one left, with the same team context loaded. This guide walks the loop end to end on the CLI, then hands the board to another agent to prove continuity.

​
Outcome

A goal that survives an agent change. One agent creates a Project and works part of the board; a different agent resolves the same Project and finishes it, pulling the same context per card, without you re-explaining anything.

​
When to use it

  • A task is too large for one session and you expect to resume it later.
  • You want to move a goal between models or clients (Claude, ChatGPT, a coding agent, a teammate) without losing state.
  • You want work that carries its own acceptance and validation, not a bare checklist.
If the work is a single edit with no continuity or verification, you do not need a Project. Reach for one when the state has to outlive the session.

​
Availability and prerequisites

ItemState
Projects and cards (CLI, API, dashboard)Available
Card context bundle on nextAvailable
require_card_validation (block done until validated)Available, workspace setting, default off
playbook_slug on the MCP driftless_project toolNot available yet (use CLI or API; the next bundle carries a playbook_hint)
You need the CLI installed and logged in (CLI setup). Over MCP or OAuth, project and card writes require the work:write scope. To assign an owner you need a member id from driftless member list.

​
Objects involved

ObjectRole in this workflow
ProjectHolds the goal and the definition of done; owns state across agents.
CardOne unit of work, with acceptance, validate, and depends_on.
Context bundleThe Knowledge next delivers with each card.
NoteA learning captured mid-loop, attached to the card.
PlaybookA Knowledge Topic the agent reads to learn how to run the project.

​
Before you begin

Confirm you are in the workspace you mean to write to. The board is shared, so a card created here is visible to every member and to the next agent. 
driftless workspace current      # confirm the active workspace
driftless member list            # member ids, for --owner

​
Context preflight

A Project delivers context two ways, so an agent rarely has to search:
  • Per card, automatically. project card next returns { card, context_bundle, project_done }. The context_bundle merges the card’s own context refs with the project’s, deduplicated: the team’s recorded memory for the area that card touches. The agent works from it instead of re-deriving what the team already knows.
  • Per project, once. A --playbook <slug> points the project at a Knowledge Topic that explains how to run it. When set, the next bundle carries a playbook_hint.
Before you create cards, check the area actually has Topics to deliver. If it does not, that is a gap to close, not a reason to guess. 
driftless context get --files "src/webhooks/**"   # what Knowledge already covers this area
If nothing matches, read the code and leave a Note first (see Govern agent learning), so the first card arrives with context instead of a blank.

​
Step-by-step workflow

1

Resolve or create the Project

List active projects to find one, or create it with a goal and (optionally) a playbook. The goal is the definition of done for the whole board.
driftless project list --status active
driftless project add "Webhook hardening" \
  --goal "Webhook handling is idempotent and order-safe" \
  --playbook webhook-runbook
You should see a new project with a <project-id> and status active.
2

Create cards with acceptance, validation, and dependencies

Each card carries what “done” means (acceptance), a command that must exit zero (--validate), an optional --owner, and --dep for ordering.
driftless project card add <project-id> \
  --title "Idempotent webhook handler" \
  --acceptance "Duplicate deliveries are a no-op" \
  --validate "npm test -- webhooks" \
  --owner <member-id>

driftless project card add <project-id> \
  --title "Ordering guard" \
  --acceptance "Out-of-order deliveries are reconciled" \
  --dep <card-id>
The second card names the first with --dep, so it stays out of next until the first is done.
3

Pull the next card and its context bundle

This is the loop tick. It returns the next actionable card plus the context to work it, in one call.
driftless project card next <project-id>
You should get back { card, context_bundle, project_done }. Work only that card; read its bundle before touching the code it points at.
4

Work the card, then validate

Make the change the card describes. If the card has a validate command, run it in your own environment. The server stores the command; it never runs it for you. A non-zero exit is stop-and-fix: repair and re-run, do not close the card.
npm test -- webhooks     # the agent runs validate in its own environment
Check the result against the card’s acceptance before moving on.
5

Capture mid-loop learning as a Note

A gotcha you hit while working the card should not wait until the end. Attach it to the card, where it rides the next next bundle and is synthesized into a draft Topic when the project closes.
driftless note add \
  --content "Provider retries deliver out of order; dedup on delivery id" \
  --project <project-id> --card <card-id>
6

Close the card and ask for the next

Move the card to done and request the next one. Repeat until the board is empty.
driftless project card status <project-id> <card-id> done
driftless project card next <project-id>
7

Hand off to another agent

A different model, session, or client continues with the same command. Nothing is re-explained: the Project still holds the goal, the remaining cards, and the per-card context.
driftless project get <project-id>          # the goal and card index, as state
driftless project card next <project-id>    # resume from the next actionable card
When next returns project_done: true, every card is done or retired and the goal is met. Marking the project done on the dashboard opens the compact, where an owner or admin selects which cards’ attached notes become draft Topics in the Inbox.
Same loop over MCP: driftless_project_card action:'next' returns the bundle, and action:'set' changes status. The REST surface mirrors it under /workspaces/:slug/projects/:projectId/cards/next; a card PATCH accepts validate_result and validate_passed to record an outcome, and add_context to attach a Topic mid-loop. See API: Projects and Cards.

​
Expected states

MomentWhat you should see
After project addA project with a <project-id>, status active.
After card addA card in todo; a dependent card that does not appear in next yet.
During next{ card, context_bundle, project_done: false }.
A card that cannot proceedSet to blocked, not done.
Failed validateCard stays open; stop-and-fix, then re-run.
End of the boardnext returns project_done: true.

​
Knowledge write-back

Match each learning to the primitive it belongs in:
  • Work that comes next stays a Card. Add it to the board rather than writing prose about it.
  • A learning discovered while working is a Note attached to the card (shown above). It rides the loop and is synthesized at close.
  • A durable why (a decision, an invariant, a gotcha a future code change would contradict) is a Topic. When the project closes, the compact drafts one from the card’s notes; an owner or admin merges it into Knowledge.
driftless note add --content "Idempotency key is required on every webhook handler" \
  --project <project-id> --card <card-id>
driftless context propose <slug>    # later: put a durable Note up for review
Do not merge a project learning into Knowledge on your own initiative. Propose it; an owner or admin decides. See Govern agent learning.

​
What not to do

  • Do not claim Driftless runs validate. Verification is report-and-surface: the server stores the command and the result you report, and never executes it.
  • Do not mark a card done to get past a failure. A failed validation is stop-and-fix. If you cannot proceed without a human decision, set it blocked.
  • Do not work more than the actionable card. The loop hands you one unit at a time on purpose; dep-gating orders the rest.
  • Do not turn every step into a Topic. Most of what happens on a board is state, not durable Knowledge.

​
Troubleshooting

  • next returns nothing actionable but the project is not done. Every remaining todo is gated by an unfinished dependency, or cards are blocked. Check project cards <project-id> and clear the blocker.
  • A card is stuck on a human decision. Set it aside without faking progress:
driftless project card status <project-id> <card-id> blocked
  • A done transition was allowed without a passing validation. That is the default (the card is surfaced as “needs verification”). To require a pass, an owner or admin enables require_card_validation on the workspace.
  • The MCP client has no playbook field. Expected: driftless_project does not expose playbook_slug yet. Set it from the CLI or API; the next bundle still delivers the playbook_hint.

​
Limits and truth states

CapabilityState
Projects, cards, and the next loopAvailable
Context bundle delivered per cardAvailable
require_card_validation blocking a doneAvailable (off by default)
Server-side execution of validateNot available (report-and-surface only)
playbook_slug on the MCP driftless_project toolNot available (use CLI or API)
Manual agent-run trigger over MCP or RESTNot available (retired)