Glossary and reference
Use this page as a reference for Cards terminology, state values, and configuration schemas.
Core concepts glossary
- card — The durable, local Git-backed work object representing a single agent task. It is stored as a standalone Git repository on your local disk.
- card-repo — The local Git repository under
~/.cards/cards-repos/<id>/that stores a card's description, plan, comments, and session history. - workspace — The active project repository that you open in VS Code. This is where your production code lives and where the agent's work will eventually be merged.
- worktree — An isolated filesystem checkout of the workspace repository (located under
~/.cards/worktrees/<card-id>/) where the agent executes its tasks and runs tests in isolation. - description — The human-authored objective of a card, stored as
CARD.mdin the card-repo. This file seeds the initial context for the agent. - CARD.meta.json — The metadata sidecar file at the root of the card-repo, storing status, gates, tags, repositoryId, parentBranch, environment, and relations.
- plan — An agent-authored outline of the steps required to complete the card's objective, stored in the
plans/directory of the card-repo (one or more.mdfiles). - session — A single execution run of an agent action against a card (e.g., running the launch action).
- stream — The live-updating log of agent activity, terminal outputs, and tool calls rendered in the card details webview.
- action — A configured command (e.g.,
interview,launch,chat) that runs your agent harness with specific context. - merge gate — The safety checkpoint where you review the agent's worktree commits in the Attribution Tree and approve merging them into the workspace.
State and configuration reference
Card status values
Cards transition through a closed set of status values. You cannot add custom status values.
| Status | Phase | Description |
|---|---|---|
todo | Planning | The card has been created and described, but no agent session has run. |
active | Execution | An agent session is currently running, or has run and left uncommitted changes. |
needs_review | Verification | The agent has completed its task and is waiting for you to approve the merge gate. |
done | Completion | The changes have been merged into the workspace and the worktree has been cleaned up. |
archived | Archive | The card is archived and hidden from the active list. |
Contributor classes
Every comment, plan edit, or action in a card's history is attributed to a specific contributor class.
| Class | Entity | Description |
|---|---|---|
user | You (the developer) | Manually authored comments, description edits, and action triggers. |
agent | The coding agent | Automated plan updates, code edits, and tool execution logs. |
system | The Cards extension | Automated lifecycle events, worktree creations, and merge logs. |
Default actions
These are the standard actions shipped with the extension. You can define custom actions in your settings.config.ts using the SDK.
| Action | Purpose |
|---|---|
interview | Refines the card description by asking clarifying questions. |
launch | Starts the agent harness in the isolated worktree to execute the plan. |
chat | Starts an open-ended conversation with the agent in the worktree. |
Card gate fields
Card gates are configured per-card and stored in CARD.meta.json at the root of the card-repo. All gates are advisory checkpoints that guide the workflow but do not hard-block status transitions.
| Field | Type | Description |
|---|---|---|
planRequired | boolean | If true, the agent must submit a plan for approval before writing code. |
planApproved | boolean | Set to true when you approve the agent's plan. |
mergeRequestRequired | boolean | If true, the agent must request a merge review before completing the card. |
mergeApproved | boolean | Set to true when you approve the code changes. |