> ## Documentation Index > Fetch the complete documentation index at: https://docs.driftless.icu/llms.txt > Use this file to discover all available pages before exploring further. # Continue a project across agents > Run one goal to completion even when the model, session, or agent changes. The Project owns the state, the context, and the definition of done, so any agent can pick up exactly where the last one stopped. Models change, chats end, sessions reset. The work should not restart every time. In Driftless a [Project](/concepts/projects) 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 | Item | State | | -------------------------------------------------------- | ------------------------------------------------------------------------------- | | Projects and cards (CLI, API, dashboard) | Available | | Card context bundle on `next` | Available | | `require_card_validation` (block `done` until validated) | Available, workspace setting, default off | | `playbook_slug` on the MCP `driftless_project` tool | Not available yet (use CLI or API; the `next` bundle carries a `playbook_hint`) | You need the CLI installed and logged in ([CLI setup](/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 | Object | Role in this workflow | | ------------------ | -------------------------------------------------------------------- | | **Project** | Holds the goal and the definition of done; owns state across agents. | | **Card** | One unit of work, with `acceptance`, `validate`, and `depends_on`. | | **Context bundle** | The Knowledge `next` delivers with each card. | | **Note** | A learning captured mid-loop, attached to the card. | | **Playbook** | A 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. ```bash theme={"theme":"github-light"} 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 ` 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. ```bash theme={"theme":"github-light"} 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](/guides/govern-agent-learning)), so the first card arrives with context instead of a blank. ## Step-by-step workflow 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. ```bash theme={"theme":"github-light"} 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 `` and status `active`. Each card carries what "done" means (`acceptance`), a command that must exit zero (`--validate`), an optional `--owner`, and `--dep` for ordering. ```bash theme={"theme":"github-light"} driftless project card add \ --title "Idempotent webhook handler" \ --acceptance "Duplicate deliveries are a no-op" \ --validate "npm test -- webhooks" \ --owner driftless project card add \ --title "Ordering guard" \ --acceptance "Out-of-order deliveries are reconciled" \ --dep ``` The second card names the first with `--dep`, so it stays out of `next` until the first is `done`. This is the loop tick. It returns the next actionable card plus the context to work it, in one call. ```bash theme={"theme":"github-light"} driftless project card next ``` You should get back `{ card, context_bundle, project_done }`. Work only that card; read its bundle before touching the code it points at. 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. ```bash theme={"theme":"github-light"} npm test -- webhooks # the agent runs validate in its own environment ``` Check the result against the card's `acceptance` before moving on. 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. ```bash theme={"theme":"github-light"} driftless note add \ --content "Provider retries deliver out of order; dedup on delivery id" \ --project --card ``` Move the card to `done` and request the next one. Repeat until the board is empty. ```bash theme={"theme":"github-light"} driftless project card status done driftless project card next ``` 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. ```bash theme={"theme":"github-light"} driftless project get # the goal and card index, as state driftless project card next # 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](/api/projects). ## Expected states | Moment | What you should see | | -------------------------- | ---------------------------------------------------------------------- | | After `project add` | A project with a ``, status `active`. | | After `card add` | A 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 proceed | Set to `blocked`, not `done`. | | Failed `validate` | Card stays open; stop-and-fix, then re-run. | | End of the board | `next` 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. ```bash theme={"theme":"github-light"} driftless note add --content "Idempotency key is required on every webhook handler" \ --project --card driftless context propose # 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](/guides/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 ` and clear the blocker. * **A card is stuck on a human decision.** Set it aside without faking progress: ```bash theme={"theme":"github-light"} driftless project card status 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 | Capability | State | | --------------------------------------------------- | --------------------------------------- | | Projects, cards, and the `next` loop | Available | | Context bundle delivered per card | Available | | `require_card_validation` blocking a `done` | Available (off by default) | | Server-side execution of `validate` | Not available (report-and-surface only) | | `playbook_slug` on the MCP `driftless_project` tool | Not available (use CLI or API) | | Manual agent-run trigger over MCP or REST | Not available (retired) | ## Related reference * [Projects](/concepts/projects) - the concept and the loop. * [CLI: Projects and Cards](/cli/projects) - every project and card command. * [API: Projects and Cards](/api/projects) - the REST surface. * [MCP & OAuth](/mcp/overview) - `driftless_project` and `driftless_project_card`. * [Govern agent learning](/guides/govern-agent-learning) - turning a card's notes into Knowledge.