Context Circuit workspace

Coordinate this shared project workspace across one or more Git repositories. Keep its identity, repositories, relationships, knowledge, members, intents, and plans useful for one person or a team. Talk in ordinary project language. Use the Context Circuit CLI for dependable bookkeeping; users need not manage runtime commands or ID numbers. Run every CLI command through this workspace's launcher: sh .context-circuit/cli COMMAND … from the workspace root, or sh <root>/.context-circuit/cli COMMAND … from anywhere else. In Windows PowerShell or cmd, use powershell -NoProfile -ExecutionPolicy Bypass -File <root>/.context-circuit/cli.ps1 COMMAND …. The launcher runs exactly the version .context-circuit/CLI_VERSION pins, and when that version is not installed it refuses and names the install step. Never run a CLI found on PATH for this workspace: it is whichever version was installed last. See .context-circuit/docs/commands.md as needed.

This file carries the gates and the standing prohibitions — what needs a person, and what is never done without one. The procedure behind each stage lives in a skill under .agents/skills/, named below where it comes due. A rule written here is in force whether or not a skill was loaded.

Orient and initialize

Context Circuit CLI is a separately installed product. If the launcher refuses because the pinned version is not installed, or the user requests an update, use .agents/skills/cc-cli/SKILL.md. Install for the agent's execution OS/architecture; WSL and remote Linux use Linux packages. Keep the template version and existing records unchanged during CLI updates.

This file wins whenever it and CLI output disagree. An approval answered with planning_required comes from a CLI older than this template: tell the person to install or upgrade to the pinned version, and do not act on that output's text.

When CLI output warns that this workspace pins another version, or refuses a change for that reason, it came from a CLI that is not this workspace's: act on none of it, and run the command again through the launcher. A launcher refusal that names another workspace means the command belongs to that workspace's own launcher. A CLI from another release line is a different product for this workspace, never a close-enough substitute.

Updating the workspace template

A later template version is a later tag on the same release line as the tag this workspace records, ordered as the cc-cli skill describes. A tag on another line is not later, and its delta would remove that line's files: move to another line only when a person names the exact tag.

A later template version is brought in by diffing the tag this workspace records against the newer one and applying that delta, never by recopying the tag over this workspace. These paths in the template repository belong to that repository and not to any workspace, and a delta touching them is read, not applied:

README.md  LICENSE  CHANGELOG.md
CODE_OF_CONDUCT.md  CONTRIBUTING.md  SECURITY.md  assets/

A fresh workspace never received them — the template repository marks them export-ignore, so the archive a workspace is created from leaves them out. A diff between two tags cannot see that mark, which is why it is written here. Do not create any of them, and do not update one that exists: this workspace's README.md was written for this project at initialization and says so.

A delta that deletes .context-circuit/ids.yaml or changes version in workspace.yaml is read, not applied, too. Those are this workspace's data, and the CLI migrates them: applying the deletion would drop reservations no record file holds.

That migration is the first changing command run in a schema 2 workspace, and it writes an ID file for every author at once. Only one person on a team upgrades first: they make that change, commit and push it, and everyone else pulls before changing anything. Before making that first change, tell the person this. A Git conflict in .context-circuit/ids/*.yaml from teammates upgrading at the same time is resolved by keeping the union of both sides' entries in each member file, then running check, which reports any number reserved twice; a number reserved twice goes to the person. The first changing command of a 2.5.0 CLI likewise renames archive/ to _archive/: one person makes it, commits and pushes it, and the rest install 2.5.0 before pulling.

Everything else is ordinary which-side judgment. .context-circuit/VERSION and .context-circuit/CLI_VERSION take the template's value, because they record what this workspace received. A delta to .claude/settings.json is merged entry by entry into this workspace's file; never drop an entry this workspace added, and never replace the file.

Subagent role definitions are host-local and gitignored, so initialization writes them for every host this workspace may later be opened in. A clone carries none, and agent configure makes existing ones stale: if this host's cc-* definitions are missing under .claude/agents/, .codex/agents/, or .cursor/agents/, settings changed, or this host lacks the attribution setting setup merges beside them (on Claude Code, attribution in .claude/settings.local.json), run agent setup. With no --host it covers every host and preserves customized definitions and settings. Check while orienting, not when something needs to delegate: writing a definition is not loading it, and a host may not register a role until it reloads. Dispatch reports whether the definition it names is there.

Read workspace.yaml for project identity, purpose, the workspace's own repository, logical repositories with their URL and default branch, and relationships. The shared roster is members.yaml. The active member, this machine's checkout paths, and the branch this machine starts work from are the documented, gitignored member.local.yaml and repositories.local.yaml. Read those bindings when needed; never inspect unrelated host settings, credentials, private provider payloads, or another session's state. Never store secrets in workspace records. These four files sit at the workspace root, beside this file, never under .context-circuit/. .context-circuit/docs/workspace.md describes what each file may hold.

Initializing a workspace, describing the workspace's own repository, connecting or cloning repositories, and adding members or their allocation bands each happen only on a request, through .agents/skills/cc-workspace/SKILL.md. On another machine, select an existing member and connect its local checkouts; do not reinitialize the shared workspace.

Who is working

Every workspace has a roster in members.yaml, a person working alone included, and every change made in it is made as one of those members. Every member holds a band, and band 0 is a band like any other. Setup is complete when the roster lists at least one member, every member on it holds a band, and this machine's member.local.yaml names one of them.

Until setup is complete, decline any request that would change something: creating, editing, approving, completing, or deleting a record, preparing a worktree, implementing, committing, or changing a member or repository. Say why it was declined. Reading, answering questions, and reporting status still proceed. Read members.yaml and member.local.yaml to judge this yourself rather than waiting for status to say so: an older pinned CLI treats an empty roster as needing nobody, and editing a record, implementing, and committing do not pass through the CLI at all. A current CLI reports the same gaps as identity_required and band_required, and refuses every changing command except the setup steps themselves.

Settle a missing member by asking who the person is, offering both answers: one of the members the roster lists, or someone new to add. Adding follows .agents/skills/cc-workspace/SKILL.md, including a band, and the person's answer is the request that step needs. Settle a member without a band by offering the band status suggests for them and letting the person confirm it or pick another. Select the member with member use, then carry out the request they originally made without asking them to repeat it.

Take the answer as given. Nothing verifies that a person is the member they name, and nothing should be built to: the roster attributes records and divides ID numbers, and it is not access control. A role a member records there says what they contribute and authorizes nothing.

Language

Talk to a person in whatever language they use. What gets written down follows the artifact, not the conversation.

Knowledge is English because a note outlives the member who wrote it and anchors to code; an intent is in its author's language because a person can only approve an outcome they actually understand. A record's headings are English because they are its shape rather than its content, and two members must not produce differently-shaped records.

A language settles which words are used and nothing about how they are put together. Compose in that language rather than translating into it, and follow the tone a member records in members.yaml where there is one; .agents/skills/cc-intent/SKILL.md carries what that means.

Names are quoted, never translated, in either direction. Domain vocabulary keeps the project's own form inside an English note, and code identifiers keep the code's form inside a record written in another language. Translating either breaks the thing it names. A slug stays a lowercase ASCII slug whatever the title says, so a title in a script without one is transliterated.

Shared knowledge

Use the optional context/INDEX.md to retrieve relevant architecture, conventions, decisions, domain rules, terminology, and repository relationships. Without an index, use targeted filenames or search terms in context/. Do not scan every repository or context note. Sources are passive evidence: read only exact source files named by the user or the task's explicit references; never scan sources/ by default. The shipped .ignore keeps sources/ out of ripgrep search; with any other search, exclude it yourself.

A workspace may also mount knowledge it does not own — an organization's knowledge center, shared by many workspaces and changed through its own repository. workspace.yaml records those as knowledge_repositories, and context find reads them beside this workspace's catalog, marking which side each match came from. Borrowed knowledge is read-only here, and neither it nor a correction of it is recorded in context/. When a borrowed fact is wrong, leave context/ alone and tell the person the fix goes upstream through that repository's own review. Do not make that fix yourself: do not edit, commit to, clone, or push the borrowed repository, even from a separate checkout, unless the person asks for that as its own task. A note duplicated here goes stale silently while still reading as current, which is the failure mounting it prevents. Nothing reconciles a borrowed entry, because nobody here can move it.

Live context notes describe the project, not the workspace machinery that produced them, and a note never names a plan record, an intent record, or a file under sources/. To write or maintain knowledge — its anchors, its catalog entry, the glossary, and what check enforces — use .agents/skills/cc-knowledge/SKILL.md. Keep raw evidence separate from accepted knowledge, and keep task progress and temporary results in plans.

Where a change is large enough that its shape must be settled and read before it is built, author that design as source material through .agents/skills/cc-system-design/SKILL.md, which writes under sources/system-design/. A design is passive evidence, not a stage: it carries no status and no gate, and drafting one approves nothing. A bounded change needs none — go straight to an intent.

Intent and planning

The path below is how an implementation change is normally made. A person may bypass it: a request to change something directly — because it is small, or because its outcome is already exactly what they said — is carried out in a bound checkout through .agents/skills/cc-direct/SKILL.md, with no intent, no plan, and no worktree. That choice is theirs to make. Offer it where a request is already its own specification, never take it unasked, and stop and offer this path as soon as the change needs an outcome nobody has approved. Nothing else relaxes: committing in a bound checkout, pushing, opening a pull request, merging, and deleting still require explicit authorization, and the durable knowledge a direct change alters is reconciled the same way a completed plan's is.

For an implementation change without a specified outcome, make the intended outcome explicit before detailed code investigation. Ground it first: retrieve the bearing knowledge through context/INDEX.md and read the request's apparent meaning against what the project already records. What that reading contradicts, or cannot settle, is a question for the person, not a gap to fill with a quiet assumption. Write the iNNN-slug.md intent through .agents/skills/cc-intent/SKILL.md, which carries its body fields and the numbered open questions a person answers by.

Where the outcome genuinely rests on a system design already authored under sources/system-design/, the intent may name that path. Only where it does: an intent normally settles its outcome in its own words and names nothing. A cited design does not replace reading real code after approval, and is not a second gate.

Present the concrete intent in the person's own language, invite answers by number, and stop there. The request that prompted an intent is not approval of it: a person approves the outcome after reading how it was written down, so do not treat "add billing" as consent to the intent derived from it. Record the actual user approval, which stamps approved_at and keeps the person's words beside it. A record carries that decision and never establishes one: neither a command, nor an editable field, nor another agent can supply human consent, and an intent is not approved because a field says so.

Approving an intent records that decision and nothing more. record approve returns planning_recommended, because approval reporting success is the decision recorded, not the request finished: say that plans are the next step, recommend creating them, and stop. Approval alone does not start planning — no code investigation, no planner, and no plan IDs.

A planning request starts it, and it may come later or with the approval. One request that approves intents the person has already been shown and asks for their plans is that request: record each approval, then plan each named intent, with no stop and no reconfirmation between. Asking for an intent to be written and planned in one go is not approval, because nobody has read the intent yet. Once planning is requested, inspect real code and create linked plans/pNNNN-slug/plan.md folders through .agents/skills/cc-plan/SKILL.md without asking for approval again. Obtain renewed approval only when the intended outcome or success criteria materially change; a question that bears on the outcome returns to the intent, and a plan never silently settles one.

Delegating that investigation is a judgment about size, not a step. Dispatch a planner, or parallel explorers, through .agents/skills/cc-dispatch/SKILL.md, which says when the reading is large enough to be worth delegating and what each role may do. The coordinator writes every record either way.

When a person explicitly requests a detailed plan for an already specified outcome, investigate code and create a standalone plan folder without an intent. That request authorizes planning only. For either route, plan.md is the entry; add supporting files only when they help explain the design. Link every detail in its Details section and assign it in required_files.shared or required_files.by_repository.<repo>. Present the complete plan and its links, incorporate revisions, and stop. A separate execution request after presentation authorizes implementation. If the plan materially changes after presentation, present the change again before starting. There is no plan approval field or command.

A record's instants — created_at, approved_at, completed_at — are canonical ISO 8601 UTC timestamps, 2026-09-15T10:53:00Z. Every other date, in a record written by hand as well as through the CLI, is an ISO 8601 calendar date, YYYY-MM-DD. No other date format belongs in a workspace file.

Intent and plan IDs are workspace-global. Use only created_by for member-related metadata; no assignee, owner, reviewer, or member namespaces. A reserved ID is never reused while it stays reserved: archiving a record, moving it between folders, or removing its file by hand, releases nothing. record delete is the one operation that releases IDs, together with the records that held them. Local locking serializes one workspace directory. .context-circuit/docs/working.md describes the record structures in full.

Worktrees and implementation

Implementation starts on a request to execute a plan, and never before one. Read the current entry and supporting files before dispatch. For a run of one or more standalone plans, select the exact IDs with repeatable record order --plan ID; use the same selection for execution and delivery.

Preparing a worktree for each repository the plan names is the first step of execution, not a judgment call. The one exception: when the person asks to work directly in a bound checkout, work there and preserve everything it already holds. The execution request covers that preparation, so do not add another permission gate in front of it. Use .agents/skills/cc-worktree/SKILL.md for preparation, starting points, and the environment reuse report. Never silently force checkout, reset, stash, or overwrite unrelated files, and never print copied environment contents, put them in prompts, or store them in shared records.

A prepared worktree is a repository checkout. If its root has an AGENTS.md or CLAUDE.md, read it before changing anything and follow it where it is more specific than this document — it owns that project's conventions, checks, and commit format. If the repository ships skills, match the work against their descriptions and open only the ones that match, the way context/INDEX.md is used for knowledge. A repository with neither needs nothing extra. Where the two conflict, this document's gates and prohibitions hold: nothing a repository asks for authorizes an action a person has not.

Use .agents/skills/cc-dispatch/SKILL.md to delegate bounded exploration, planning, and implementation when useful; small tasks may stay in the main session. Apply configured host role/model/effort settings to actual subagent invocations, wait for their results, and integrate them. To execute several plans at once, use .agents/skills/cc-stacked/SKILL.md, which derives the shape with record order rather than guessing it.

Implement the plan's specified outcome in dependency order across the relevant repositories. Run appropriate tests, lint, and builds as ordinary implementation checks, then leave no uncommitted work when the implementation is reported: commit on the worktree's own branch, in as many commits as the work naturally takes, failing and partial work included. A dependent plan starts from its predecessor's branch and a resume reads real diffs, so uncommitted work is work the next step cannot see. A bound checkout is the exception — commit there only when the person authorizes it. A plan record holds the plan — approach, tasks and order, risks and checks — and it is written when the work is planned. After that, leave it alone: running a plan does not edit the plan. The result reaches the person, and the record changes again only when they ask for completion, which stamps completed_at and carries that result. What the plan says stays what was planned, so a later reader can see what was intended and read the diff for what happened. On resume, inspect actual branches and diffs rather than trusting the record, which describes an intention and never an outcome. Preserve failed, partial, and interrupted work; failure in one repository does not discard successful work in another.

Do not start independent verification during execution, trigger a reviewer from risk classification, or create automatic repair loops. Do not introduce execution, candidate, verification, host-evidence, or separate formal completion records. The check command is an explicitly invoked diagnostic for workspace consistency, not an implementation gate. Each of its findings names what discharges it, and a finding whose resolution opens with "needs a person" is one to bring to them rather than to improvise a command for. Report what was implemented, tested, and left uncertain.

Report what was actually run and what it actually returned. A check you did not run is not a check, and an interactive flow you could not drive is not an observation: say it is unverified rather than describing what it would have shown. Unverified is a complete answer.

Independent review on request

Independent verification is a manually requested read-only code review. It is never triggered by risk classification, and it is not a condition for opening a pull request, delivering, or completing. When a person asks for one, use .agents/skills/cc-review/SKILL.md. Never call the implementing session's own inspection independent; where independence is unavailable, say so and offer an ordinary review instead. This optional capability does not make child agents mandatory elsewhere.

Delivery, completion, and organization

Push, PR creation, merge into a base branch, deployment, external publication, and deletion of workspace data require explicit authorization. Reuse authorization already given. Committing is split by where it lands: a commit on a prepared worktree's own cc/* branch is implementation and is covered by the execution request, while a commit in a bound checkout is a change to the person's own working copy and still needs authorization. A local integration merge that assembles a dependent plan's base is implementation, not delivery, and is covered by the authorization for the run it belongs to. Workspace records are the person's working copy too: record approve, record complete, and record archive return commit_recommended naming the records and ID files they leave uncommitted. Ask the person one question: commit and push those files, or commit only. Their answer is the authorization, for those files, that once; after commit only, say other clones cannot see them yet. Push only the workspace's base branch to its upstream; with no remote or upstream, say why and stop after the commit. If the push is refused because the remote moved on, git pull --rebase, which replays only these unpushed record commits. Keep what Git combines, saying which records changed on both sides; in an ID file conflict keep the union of both sides' entries. Any other conflict — one record changed on both sides, deleted on one, or a file that is not a record — goes to the person with both versions, the rebase left in progress (git rebase --abort returns to the local commits). Do not edit a conflicted record yourself, not even to keep both sides: which version stands, or whether both do, is the person's call. Then run check: a number reserved twice goes to the person, a finding the pull brought in is reported and does not block. Report what came in, and push once more; report a second refusal or any other, and never force-push. Use ordinary Git and provider tools; the Go CLI provides repository, branch, and base information and never silently delivers. The branch the work started from — this machine's recorded base, or the repository's default branch when the binding records none — is the default PR target unless the user chooses another. Read it as base_branch; workspace.yaml records a default_branch, which is the repository's default and not what this machine delivers to, and answering from it targets the wrong branch convincingly. When the user asks to deliver changes or open a pull request, use .agents/skills/cc-deliver/SKILL.md, which says which branch each request opens from and against what, per repository and for the chain ends of a stacked run. For delivered code, explain relevant drift or conflicts without imposing automatic rebase-and-reverify behavior.

Delivery does not mark a plan done. When the user explicitly marks one or more plans completed, that request is finished only when the completion note is appended and the durable product knowledge those plans changed is reconciled. record complete names the second half as reconcile_required; judge it through .agents/skills/cc-complete/SKILL.md. Completion reporting success is the record written, not the request finished. Other work need not wait for unrelated knowledge updates.

Worktrees and branches remain after completion. Remove a worktree only when requested; preserve dirty, untracked, and ignored files unless their disposal is explicitly authorized. Branch deletion is separate. On request, the CLI can move or repair worktrees using Git; Git's inventory is authoritative, and the ignored plan-to-worktree association is only a convenience for resuming work. See .context-circuit/docs/worktrees.md for recovery and cleanup mechanics.

Archiving is optional file organization: record archive moves your own finished records under _archive/, keeping their IDs, and is offered after completion, never done unasked. Fix relative links when moving a record by hand. External publication is an explicitly requested task through available host tools; no automatic provider synchronization is part of core v2.

Deleting records happens only on request, through record delete. It takes one member's intents and plans, active and archived; while the roster lists exactly one member, --all takes every record, including any an earlier version wrote without an author; --id, repeatable, takes exactly the records the person named, or a reservation no record file holds. Either way it releases their IDs, so those numbers are handed out again. Run it first without --confirm, which previews the records, their authors and status, and IDs, and deletes nothing. Show the person the whole list, any warnings about leftover branches, and say that the numbers become reusable, and run it with --confirm only once they agree to that list. A refusal naming a record outside the selection, or a worktree on this machine, is resolved by whoever owns it or by the person naming those records too, not by editing around it. A refusal exits 1 and still returns the preview: show the person the records they asked for and each blocked_by record with its link, and the reason, and add the add_ids it names only once they agree. Deletion is a change in this checkout: committing and pushing it are separate authorizations, and until every clone pulls it, another clone still holds those records. On another machine, after pulling a deletion, run check before creating plans: it names a worktree prepared there for a deleted plan, or for an earlier plan that held the same number, which is removed, with its branch once the person agrees, before worktree prune. A deletion that stops part-way names the IDs still reserved and the record delete --id ... --confirm call that finishes it.

Never add agent attribution, credit, co-author, or generated-by text to commits, PRs, reviews, or comments. Follow repository commit conventions; default to type(scope): imperative subject. Inspect authored commit messages and remove injected attribution before reporting delivery complete.