CARVES is a project dispatch console for AI coding agents.
Keep using Codex, Claude Code, Cursor, Gemini CLI, or another agent to write code. CARVES organizes goal, plan, task, evidence, review, and project memory so AI coding becomes project work instead of scattered conversations.
This overview keeps only the public user-facing mechanisms: six mechanism groups, each with lower-level technical documents you can drill into.
Plain-language function
Understand the job first, then read the mechanism names.
Problem
What problem does it solve?
AI agents can produce code quickly, but long projects drift: goals stay in chat, plans change silently, results claim “done” without evidence, and the next session starts by guessing.
Goals leave chat and become project records.
Evidence returns before acceptance.
Handoff keeps the next run attached.
Highlights
What is the visible value?
CARVES does not replace Codex, Claude Code, Cursor, or Gemini CLI. It sits beside them as a local dispatch console where goal, plan, task, evidence, review, and handoff remain visible.
Agent writes.
CARVES dispatches.
Human accepts, rejects, or replans.
Key tech
How does it work technically?
It is not just a stronger prompt. CARVES uses local records and checks: Card and TaskGraph organize project work, CodeGraph and context packs bound understanding, and Guard, Evidence, Review, Handoff, Audit, Shield, and Matrix make results inspectable.
Local-first project records.
Bounded execution packets.
Summary-only proof and self-check lane.
Project Dispatch
Card / Planning Draft / TaskGraph
Lower mechanisms
Turn a request into a goal, a provisional plan, and traceable tasks.
CARVES lets users keep talking to an agent, but it does not leave project intent inside a long chat. A request becomes a Card, the Card becomes a planning draft, and approved work becomes a TaskGraph.
The stable point is separation: suggestions are not execution authority, and execution results are not automatically accepted.
Why it is inspectable
Goals are captured before task breakdown.
Plans start as drafts and need approval before execution.
Tasks carry boundaries, dependencies, status, evidence references, and acceptance conditions.
Continuous Understanding
CodeGraph / Project Intent / Context Pack
Lower mechanisms
Build a scoped picture of the project instead of guessing from chat.
Continuous understanding means the agent reads the current task through CodeGraph, project intent, TaskGraph state, memory, evidence, and review results.
The point is not to load more text. The point is to load the right project facts for the task being advanced.
Why it is inspectable
Code structure starts from local indexes instead of guesswork.
Project intent is explicit and human-confirmable.
Context packs are scoped to the current task rather than dumping the whole project into a prompt.
Flow diagram
flowchart LR
A["Current Task"] --> B["Context Pack"]
C["CodeGraph"] --> B
D["Project Intent"] --> B
E["TaskGraph"] --> B
F["Memory"] --> B
G["Evidence / Review"] --> B
B --> H["Agent receives bounded context"]
Safe Execution
Execution Packet / Workspace Lease / Guard
Lower mechanisms
Put agent work inside task scope, workspace expectations, and patch checks.
Safe execution does not stop the agent from working. It makes the work happen with task boundaries, controlled workspace expectations, evidence requirements, and patch checks.
Execution and completion are separate. A worker result still needs evidence, boundary checks, and review before acceptance.
Why it is inspectable
Execution starts from an explicit task packet.
Workspace or lease boundaries reduce accidental project pollution.
Guard checks diff, path, and risk before review or merge.
Flow diagram
flowchart LR
A["Approved Task"] --> B["Execution Packet"]
B --> C["Managed Workspace / Lease"]
C --> D["Agent / Worker executes"]
D --> E["Result + Diff + Evidence"]
E --> F["Guard Check"]
F --> G["Review Gate"]
G -->|Accept| H["Writeback / Complete"]
G -->|Reject| I["Rework"]
G -->|Replan| J["Planning"]
Evidence Acceptance
Evidence / Review Gate / Shield
Lower mechanisms
Make “done” depend on evidence and review, not agent confidence.
In CARVES, “done” is not just a sentence from the agent. The result needs evidence such as diff, tests, logs, artifacts, run output, or explanation, then a review gate decides accept, reject, replan, block, or reopen.
This keeps task state anchored in evidence and decision instead of confidence tone.
Why it is inspectable
Evidence comes before acceptance.
Review decisions are explicit and traceable.
Shield can evaluate summary evidence without becoming certification.
Flow diagram
flowchart LR
A["Worker Result"] --> B["Evidence"]
B --> C["Shield Self-check"]
B --> D["Review Gate"]
C --> D
D -->|Accept| E["Task Accepted"]
D -->|Reject| F["Rework"]
D -->|Replan| G["Planning"]
D -->|Block| H["Blocked"]
Keep project attachment, runtime binding, and the next action readable.
Continuous handoff is CARVES’ answer to broken threads, agent switches, and lost context. It separates attachment, runtime binding, and session handoff into readable artifacts.
The next agent should not guess whether the project is attached, where the Runtime is, or what the previous session left behind.
Why it is inspectable
Attachment can be read back.
Runtime root can be resolved without copying Runtime docs into the target project.
Next action, blocker, evidence references, and confidence can be handed off.
Flow diagram
flowchart LR
A["Attach Handshake"] --> B["Runtime Manifest"]
B --> C["Handoff Packet"]
C --> D["Next Agent Resume"]
Auditable Loop
Audit / Matrix / Commit Hygiene
Lower mechanisms
Read history, prove the local composition path, and close work cleanly.
Auditable loop covers what happens after work has happened: read back history, prove the local governance chain can compose, and close the work without throwing every dirty file into git.
It is the difference between “the agent changed things” and “we can inspect what happened, which proof lane ran, and what should be committed.”
Why it is inspectable
Audit reads history without mutating Guard or Handoff truth.
Matrix proves the Guard -> Handoff -> Audit -> Shield local path can compose.
Commit hygiene keeps local residue from becoming project truth by accident.
Flow diagram
flowchart LR
A["Guard Decisions"] --> C["Audit"]
B["Handoff Packets"] --> C
C --> D["Summary / Timeline / Explain"]
C --> E["shield-evidence.v0"]
E --> F["Shield"]
F --> G["Matrix Proof"]
H["Dirty Worktree"] --> I["Commit Hygiene"]
I --> J["Commit Plan"]
J --> K["Closure"]
Project Dispatch / Card
Card is the goal anchor.
It turns a user idea into a target that can be discussed, approved, split, and reviewed.
A Card prevents the project goal from floating inside chat history. It records what problem is being solved, why it matters, what is in scope, what is out of scope, and what success should look like.
A draft Card is not approval. Human confirmation is still the step that lets downstream planning begin.
Goal is explicit.
Scope is visible.
Tasks can trace back to the approved target.
Flow diagram
flowchart LR
A["User idea / request"] --> B["Card draft"]
B --> C{"Human decision"}
C -->|Approve| D["Approved Card"]
C -->|Reject| E["Rejected / Archived"]
D --> F["TaskGraph draft"]
F --> G{"Human decision"}
G -->|Approve| H["Executable Tasks"]
G -->|Replan| F
Boundary
Card does not decide product direction for the user. It makes direction reviewable.
Project Dispatch / Planning Draft
Planning Draft keeps plans provisional.
The agent may propose a path, but the proposal does not become executable truth by itself.
Planning Draft is the gap between idea and execution. It lets the agent suggest decomposition, risks, sequence, and evidence requirements before any task is treated as authorized.
This keeps planning useful without letting the agent create and approve its own work.
Plan first.
Approval before execution.
Replan remains normal when the draft is weak.
Flow diagram
flowchart LR
A["Approved Card"] --> B["Planning draft"]
B --> C{"Review plan"}
C -->|Approve| D["TaskGraph draft"]
C -->|Revise| B
C -->|Reject| E["Stop / Archive"]
D --> F{"Approve TaskGraph"}
F -->|Approve| G["Executable Tasks"]
F -->|Replan| B
Boundary
Planning Draft does not guarantee the plan is correct. It makes the plan inspectable before work starts.
Project Dispatch / TaskGraph
TaskGraph is the project progress ledger.
It records tasks, dependencies, status, evidence, review results, blocks, rework, and next steps.
TaskGraph is not a to-do list or a wiki. It records how a project is moving: which Card a task belongs to, which tasks depend on others, where work is blocked, and which results have evidence and review.
This lets the next agent continue from project facts instead of guessing from old chat context.
Progress is readable.
Dependencies are explicit.
Rejected paths can stay visible.
Flow diagram
flowchart LR
A["Approved Card"] --> B["TaskGraph draft"]
B --> C{"Approve TaskGraph"}
C -->|Approve| D["Task Nodes"]
C -->|Replan| B
D --> E["Execution Packet"]
E --> F["Worker Result"]
F --> G["Review Gate"]
G -->|Accept| H["Task Completed"]
G -->|Reject| I["Task Rework"]
G -->|Replan| B
Boundary
TaskGraph should reference evidence and review material, not become a giant evidence dump.
Continuous Understanding / CodeGraph
CodeGraph is the local structure map.
It records modules, files, callable units, dependencies, summaries, and task-relevant scope.
CodeGraph gives CARVES a structured map of the codebase. An agent can start from modules, files, callable units, and dependency facts instead of browsing randomly.
For large projects, this matters because context is limited and guesses drift quickly.
Structure before summary.
Local project facts.
Scoped reading path.
Flow diagram
flowchart LR
A["Source files"] --> B["CodeGraph scan"]
B --> C["Manifest"]
B --> D["Index"]
B --> E["Module shards"]
B --> F["Dependency shards"]
C --> G["Context Pack"]
D --> G
E --> G
F --> G
G --> H["Agent reads scoped structure facts"]
Boundary
CodeGraph is not a complete semantic brain or proof of correctness.
Continuous Understanding / Intent
Project Intent keeps direction visible.
It records what the project is for and what direction should guide work.
Project Intent is the user-facing direction layer. It helps the agent understand why the project exists before changing implementation details.
The intent can be drafted from README and structure, but human confirmation is the part that makes it useful as project direction.
Purpose is readable.
Direction is explicit.
Old assumptions can be corrected.
Flow diagram
flowchart LR
A["README / user discussion / CodeGraph"] --> B["Intent draft"]
B --> C{"Human review"}
C -->|Accept| D["Accepted Project Intent"]
C -->|Revise| B
C -->|Reject| E["Discard / pause"]
D --> F["Card / Planning"]
Boundary
Project Intent is not automatically long-term truth until it is reviewed.
Continuous Understanding / Context Pack
Memory / Context Pack carries only relevant context.
It combines task, code structure, history, constraints, and evidence into a bounded packet.
A context pack is not a full memory database. It is the current task’s selected context: what matters now, what has already happened, what must not be repeated, and which evidence or review facts matter.
This keeps long projects from restarting at zero without flooding the agent with everything.
Bounded memory.
Task-specific context.
Continuity without full project dump.
Flow diagram
flowchart LR
A["Long-term Memory"] --> E["Context Pack"]
B["TaskGraph"] --> E
C["CodeGraph"] --> E
D["Evidence / Review"] --> E
F["Current Task Scope"] --> E
E --> G["Agent bounded context"]
Boundary
Context packs do not make the agent all-knowing. They reduce context loss and drift.
Safe Execution / Execution Packet
Execution Packet tells the worker what is allowed.
It packages task scope, constraints, evidence requirements, and expected output before work starts.
Execution Packet is the handoff from approved task to actual work. It prevents the agent from receiving only a vague natural-language command.
It should make scope, non-goals, evidence requirements, and expected result clear enough for review later.
Task scope.
Evidence requirements.
Limits before execution.
Flow diagram
flowchart LR
A["Approved Task"] --> E["Execution Packet"]
B["TaskGraph"] --> E
C["CodeGraph scope"] --> E
D["Memory / Context"] --> E
F["Acceptance / Evidence requirements"] --> E
E --> G["Worker / Agent"]
G --> H["Result + Evidence"]
Boundary
Execution Packet guides work; it is not a guarantee that the result will be correct.
It binds execution to a task and workspace so work does not casually contaminate the main project.
Managed workspace is a containment pattern. The agent should work in a controlled area or bounded lease when possible, so failed attempts and task-specific residue do not automatically become project truth.
This is about practical project hygiene, not a claim of operating-system sandboxing.
Task-bound work.
Clear ownership window.
Lower risk of main tree pollution.
Flow diagram
flowchart LR
A["Approved Task"] --> B["Lease"]
B --> C["Managed Workspace"]
C --> D["Worker executes"]
D --> E["Patch / Diff / Artifacts"]
E --> F["Submit for Review"]
F --> G{"Review Gate"}
G -->|Accept| H["Writeback"]
G -->|Reject| I["Keep / Rework / Cleanup"]
G -->|Replan| J["Return to Planning"]
Boundary
Managed workspace is not an OS sandbox or syscall-level security boundary.
Safe Execution / Guard
Guard checks patch admission boundaries.
It reviews patch, diff, path, budget, and risk signals before work moves toward review or merge.
Guard exists because small AI tasks can drift into unrelated files, risky deletes, or oversized changes. It checks whether a patch should be allowed, reviewed, or blocked.
Guard does not own session continuity or final review. It is the patch admission gate in the local proof path.
Diff boundary.
Path and change budget.
Allow / review / block style result.
Flow diagram
flowchart LR
A["Worker Patch / Diff"] --> B["Guard Check"]
C["Task Scope"] --> B
D["Path Policy"] --> B
E["Risk Rules"] --> B
B --> F{"Guard Decision"}
F -->|Pass| G["Review Gate"]
F -->|Warn| H["Human Review Required"]
F -->|Block| I["Reject / Replan"]
Boundary
Guard is not real-time write prevention, automatic rollback, or an OS sandbox.
Evidence Acceptance / Evidence
Evidence is the material behind a result.
It records diff, tests, logs, artifacts, run output, or explanation so review has something to inspect.
Evidence is what prevents completion from being a vibe. It tells the human what changed, how it was checked, and what supports the claim that the task can move forward.
The evidence can be lightweight, but it should be readable after the chat is gone.
Diff or change summary.
Test or run output.
Artifact or proof reference.
Flow diagram
flowchart LR
A["Worker Result"] --> B["Evidence Artifact"]
B --> C["Review Gate"]
B --> D["TaskGraph refs"]
B --> E["Handoff refs"]
C --> F{"Decision"}
F -->|Accept| G["Accepted Evidence"]
F -->|Reject| H["Rework Evidence"]
F -->|Replan| I["Planning Evidence"]
Boundary
Evidence supports review. It does not prove absolute correctness.
Evidence Acceptance / Review Gate
Review Gate decides what happens to the result.
It turns a worker result into accept, reject, replan, block, or reopen with a reason.
Review Gate is where human control returns. The worker can produce a candidate result, but review decides whether the project accepts it.
Rejected and replanned work should leave a reason so the next run does not repeat the same path blindly.
Accept.
Reject.
Replan.
Block or reopen when needed.
Flow diagram
flowchart LR
A["Worker Result"] --> B["Evidence"]
C["Guard / Shield"] --> D["Review Gate"]
B --> D
D --> E{"Decision"}
E -->|Accept| F["Writeback as accepted"]
E -->|Reject| G["Reject / Rework"]
E -->|Replan| H["Back to planning"]
E -->|Block| I["Mark blocked"]
Boundary
Review Gate does not replace professional code review, QA, or human judgment.
Evidence Acceptance / Shield
Shield is local governance self-check.
It reads summary evidence and reports Guard / Handoff / Audit dimensions, Lite score, and badge output.
Shield makes workflow governance visible. It checks whether the project has basic evidence for boundary checks, handoff, and audit readback.
It is useful because users can see what governance evidence exists without uploading source, raw diffs, prompts, model output, secrets, or credentials by default.
Standard G/H/A dimensions.
Lite score.
Local badge output.
Flow diagram
flowchart LR
A["Guard Evidence"] --> D["shield-evidence.v0"]
B["Handoff Evidence"] --> D
C["Audit Evidence"] --> D
D --> E["Shield Evaluate"]
E --> F["Standard G/H/A"]
E --> G["Lite Score"]
E --> H["Badge"]
Boundary
Shield is not certification, model safety rating, source audit, or semantic correctness proof.
Continuous Handoff / Attach Handshake
Attach Handshake records how the project was connected.
It records attach request and acknowledgement so the next agent does not re-init by guesswork.
Attach Handshake turns “this project is connected to CARVES” into a readable fact. It can record target repo, git root, runtime root, host session, attach status, and attached time.
This is the first layer of continuity: the project can prove it has already been received by the CARVES attach path.
Attach status.
Runtime root hint.
Host session and attached time.
Flow diagram
flowchart LR
A["carves init / attach"] --> B["Attach Request"]
B --> C["CARVES Host"]
C --> D["Attach Acknowledgement"]
D --> E["attach-handshake.json"]
E --> F["Next Agent Confirms Project Is Attached"]
Boundary
Attach Handshake is not project planning, task progress, or review evidence.
Continuous Handoff / Runtime Manifest
Runtime Manifest records the runtime binding.
It tells the target project which CARVES Runtime it should resolve back to.
Runtime Manifest is the longer-lived binding record. It helps CLI, Host, and agent entrypoints locate the Runtime root, runtime version, client version, and binding state.
The target project should keep its own project truth, while the manifest points back to CARVES rules and docs when needed.
Runtime root.
Version and session metadata.
Fallback when handshake is unavailable.
Flow diagram
flowchart LR
A["Target Repo"] --> B[".ai/runtime.json"]
B --> C["Resolve Runtime Root"]
C --> D["Load Runtime Docs / Rules"]
C --> E["Host / CLI Readiness"]
C --> F["Agent Handoff Readback"]
Boundary
Runtime Manifest records runtime binding. It does not record task progress.
Continuous Handoff / Handoff Packet
Handoff Packet tells the next session where to resume.
It stores current objective, completed facts, remaining work, blockers, evidence references, and next action.
Handoff Packet is the actual session continuity packet. It should help the next human or agent understand where the work stopped and what must happen next.
It lowers restart cost without pretending to be a universal memory database or planner.
Current objective.
Remaining work.
Blockers and evidence refs.
Next action.
Flow diagram
flowchart LR
A["Outgoing Session"] --> B["Handoff Packet"]
B --> C["Inspect Packet"]
C --> D{"Resume Status"}
D -->|ready| E["Next Agent Continues"]
D -->|stale| F["Reorient First"]
D -->|blocked| G["Ask Human / Stop"]
D -->|done| H["No Next Action"]
Boundary
Handoff Packet is not standalone memory, planning authority, or final truth.
Auditable Loop / Audit
Audit is read-only history and evidence discovery.
It reads Guard and Handoff records and emits summary, timeline, explain, and Shield evidence.
Audit helps users look back after many AI-assisted actions. It can summarize Guard decisions, discover Handoff packets, explain records, and generate privacy-aware summary evidence for Shield.
Its value comes from being read-only: it discovers evidence without inventing or mutating truth.
Summary.
Timeline.
Explain.
shield-evidence.v0.
Flow diagram
flowchart LR
A["Guard decisions"] --> C["Audit"]
B["Handoff packet"] --> C
C --> D["Summary"]
C --> E["Timeline"]
C --> F["Explain"]
C --> G["shield-evidence.v0"]
G --> H["Shield"]
Boundary
Audit does not score, certify, or mutate Guard / Handoff truth.
Auditable Loop / Matrix
Matrix proves the local composition path.
It orchestrates Guard -> Handoff -> Audit -> Shield and records summary-only proof artifacts.
Matrix shows that the four peer modules can compose in a normal local repository. It records artifact manifest, proof summary, and verification reason codes.
Matrix matters because the proof chain should be runnable and inspectable, not just described in docs.
Local proof lane.
Artifact manifest.
Summary-only bundle.
Flow diagram
flowchart LR
A["Guard"] --> B["Handoff"]
B --> C["Audit"]
C --> D["shield-evidence.v0"]
D --> E["Shield"]
E --> F["Matrix Proof"]
F --> G["Matrix Verify"]
Boundary
Matrix is not a fifth safety engine, upload service, or certification system.
Auditable Loop / Commit Hygiene
Commit hygiene separates project output from local residue.
It helps identify which paths belong in git and which are local residue or need review.
AI projects often end with a dirty worktree. Commit hygiene is the closure mechanism that prevents temporary files, tool residue, and unclassified paths from being swept into git add ..
It makes the final state inspectable: what is project truth, what is target output, what is residue, and what still needs human review.
Dirty path classification.
Commit plan.
Closure boundary.
Boundary
Commit hygiene does not replace the human decision to commit.
wiki ->
A public wiki graph for the CARVES mechanism.
The upper layer is a clickable technical graph. Click a node, or an internal link inside the explanation, to switch the current section in place.
Enter CARVES through one doorway and three product surfaces.
The graph now shows only two visual layers: CARVES Entry on top, then Console, Project Loop, and Proof Chain underneath.
Badges inside each card are detail switches. They explain a control point, concept, module group, or boundary without turning the graph into a deeper hierarchy.
Console explains where human control stays visible.
Project Loop explains how AI agent work becomes bounded project work.
Proof Chain explains which local proof modules make the loop inspectable.
AI agents can execute quickly. The unresolved problem is whether humans can still see the direction, inspect the plan, demand evidence, and decide what counts as accepted work.
CARVES does not replace Claude, Codex, Cursor, Copilot, or another agent shell. It keeps human control points visible around the agent workflow.
Human owns direction, acceptance, rejection, and replanning.
Agent still performs reasoning and execution.
CARVES keeps the work bounded, memorable, evidenced, and reviewable.
CARVES turns loose AI chat into a stable loop: Goal / Card -> Plan -> Execution -> Evidence -> Review.
The loop is the public workflow model. It keeps a project from drifting through a long conversation without a bounded card, a plan, or returned evidence.
Goal and Card define what is being advanced.
Plan constrains the path before execution starts.
Evidence returns before acceptance.
Review keeps accept, reject, and replan as human-held gates.
CARVES should not make users believe an agent just because the agent says it is done. The result needs commands, artifacts, summaries, or proof records that can be inspected.
Review is not a decorative label. It is the human decision to accept, reject, or replan before claiming completion.
The proof chain is how CARVES keeps the control loop from becoming a slogan. Guard, Handoff, Audit, Shield, and Matrix each own a bounded part of the local proof path.
The current public proof story is local-first and summary-only. It does not require default upload of source, raw diff, prompts, model responses, secrets, credentials, or customer payload.
Guard checks patch admission. Handoff writes continuity packets. Audit discovers evidence read-only. Shield evaluates local summary evidence. Matrix proves the local composition path.
Matrix is not a fifth safety engine, and Shield output is not certification. The value is that each module has a bounded owner, input, output, and non-claim.
Current non-claims stay part of the technical map.
CARVES.Site can explain the mechanism, but it does not become the Runtime truth owner, an operator console, a review surface, or a writable dashboard.
The public docs must not claim production readiness, NuGet.org publication, package signing, hosted verification, public certification, public leaderboard, semantic correctness proof, broad language support, or verified Unity support.