Opt a Repository In
The repository opt-in is shared by Claude Code, Codex, and Pi. Run /ca:init in Claude Code,
$ca-init in Codex, or /ca-init in Pi; all three create or observe the same .codearbiter/
directory. See the Claude Code + Codex evidence for a
worked mixed-host example, and Pi for Pi’s parent-process trust boundary.
The plugin installs once, globally. Enabling enforcement is a per-repo step you run once inside each repository you want covered. Complete the plugin install before starting here.
You will need: Python 3 on your PATH, git config user.email set, and the plugin installed.
The work, from your side
From an installed adapter to a verified repository
Repository initialization. Existing code and a new project take different context-building paths; neither an installed adapter nor an activation flag proves enforcement.
You + codeArbiter
Choose the repository
- What you get
- A repository-owned .codearbiter/ state directory, or the existing state for inspection.
- Before moving on
- Use the intended repository and host. Do not overwrite existing project context.
You review the project facts
Build the context
- What you get
- For a new project: architecture breakdown, phased build plan and task backlog. For existing code: source-backed context and identified gaps.
- Before moving on
- Approve the three greenfield documents before population. In brownfield, resolve or explicitly defer the gaps the source cannot answer.
You inspect the result
Check the populated state
- What you get
- Project context and the repository opt-in in .codearbiter/CONTEXT.md.
- Before moving on
- Check actual project facts and initialized state. An enabled flag on a stub is not a completed context build.
Your installed host + you
Prove the boundary
- What you get
- A fresh-session briefing and the documented Doctor probe result.
- Before moving on
- The harmless H-03 probe should be blocked. Stop and diagnose an absent briefing or a probe that executes.
Reading map, not a captured run or live status. Only the actual artifacts, approvals and fresh checks establish what has completed.
Follow the initialization route that matches this repository
These are alternatives, not consecutive phases. The greenfield interview creates project-planning documents; brownfield extraction derives context from existing code. Neither route ends in an implemented feature or a pull request.
New project: interview, three documents, initialization
Follow the work, not a catalog
Initialize a new project from intent
Choose this route only when meaningful source does not yet exist. A decomposition persona is not an extra agent dispatch. Existing source selects the separate brownfield route.
Rows identify roles. Gold commands enter or define a procedure; blue skills coordinate work; green agents perform bounded roles. Arrows cross rows in execution order. A dashed arrow reuses a procedure rather than calling its entry again. Dashed nodes are conditional roles selected for the work.
Chapter 1 / 3
Choose the new-project route
Why is an activation flag not enough?
Link to this chapter- command
/ca:init: scaffold once
The scaffolder writes activation and empty state but no initialization sentinel. It refuses to overwrite existing state; an uninitialized stub enters its selected populator directly.
Result: An enabled stub that is not ready for normal work.
no meaningful source → The stub must pass through its greenfield populator.
Source for step 1 - command
/ca:decompose: selected strategy
Automatic detection or --greenfield chooses the decomposition workflow. Source-shape mismatches remain stops rather than forced population.
Result: The explicitly selected greenfield route.
interview owner → The selected skill prepares persistence before questioning.
Source for step 2 - skill
decompose: establish or resume drafts
Create any missing knowledge documents and read the decomposition records. Answered questions stay settled; resume with the open question that matters most for the next step, not a fixed first-unfinished phase.
Result: Durable interview records and the next relevant open question.
Source for step 3
Before continuing: A writable project-state scaffold and a valid new-project interview or explicit resume choice. An initialized project is not reinitialized.
Continuations, returns and repeat paths
- fresh or resumed interview. Continue from the saved answers; nothing settled is asked again. Next: decompose: record questions and answers. Owning contract
Chapter 2 / 3
Confirm the intended project
What did the interview produce that the user must inspect?
Link to this chapter- skill
decompose: record questions and answers
Explore problem, users, capabilities, technical shape, integrations and risks in the order the conversation makes natural. Each question is saved when asked and each actual answer as soon as it is given. ADR attribution uses the decision-lifecycle owner; unresolved facts remain open questions.
Result: Answered and open question records, with linked draft decisions.
complete durable input → Synthesis rereads the saved answers and linked decisions rather than trusting conversation memory.
Source for step 4 - skill
decompose: synthesize records
From the answered questions and linked ADRs, add capability, component, phase and work-item decomposition records, each linked to the answers it rests on.
Result: Intended architecture, phased delivery and proposed work as records.
user review → No population until the user confirms the records match their choices.
Source for step 5 - skill
decompose: confirm the project definition
Show the synthesized records, apply corrections with record updates and save the user's actual confirmation as an answered question. A wording or method refinement needs no fresh confirmation; remaining gaps stay open questions.
Result: The confirmed project definition before population.
Source for step 6
Before continuing: Capability, component, phase and work-item records the user confirmed. They describe intended architecture, not a typed feature execution plan or existing code.
Continuations, returns and repeat paths
- records confirmed. Population consumes the confirmed records, not a guessed summary. Next: decompose: populate project context. Owning contract
- Requested corrections. Update the records and show them again; preserve the recorded intent. Next: decompose: synthesize records. Owning contract
Chapter 3 / 3
Populate and initialize
What exists when control returns to normal operation?
Link to this chapter- skill
decompose: populate project context
Add knowledge records for what is known, each with its basis; planned commands stay proposed and unrun, and unknowns stay unknown. Promote each approved work item once with knowledge.py promote; decision-lifecycle owns actual ADR choices.
Result: Populated knowledge documents and promoted tasks, with open questions and intended roadmap retained.
then initialize → Initialization records structural availability only; it does not require every question answered or any command run.
Source for step 7 - skill
decompose: native initialization
knowledge.py initialize checks that the five knowledge documents exist and parse and the task board is well formed, then commits the initialization marker. Open questions do not prevent it; a refusal names the document to repair.
Result: Initialized project state; no implied feature, commit or PR completion.
Source for step 8
Before continuing: Five HTML knowledge documents, promoted work on the task board, the question board, audit header and native initialization. Decomposition holds intended design; the code map records only what code exists.
Continuations, returns and repeat paths
Five HTML knowledge documents, decomposition records holding the answered interview and confirmed intended architecture, promoted work on the task board, and native initialization. Unknowns stay recorded as unknown. Continue already-authorized work; population alone does not prove implementation or verification.
Existing code: six categories, evidence, initialization
Follow the work, not a catalog
Initialize existing code from evidence
Choose this route when meaningful source exists. Initial or full work covers six logical categories through direct bounded inspection or optional scoped agents; scoped refreshes cover only declared affected categories through context-check. Actual host permissions and excluded paths apply. An agent label does not prove containment or semantic correctness.
Rows identify roles. Gold commands enter or define a procedure; blue skills coordinate work; green agents perform bounded roles. Arrows cross rows in execution order. A dashed arrow reuses a procedure rather than calling its entry again. Dashed nodes are conditional roles selected for the work.
Chapter 1 / 3
Inspect bounded source evidence
Who reads the code, and what crosses the context boundary?
Link to this chapter- command
/ca:init: scaffold once
Create the enabled stub only when absent. Select the existing-code populator rather than treating the activation flag as completed initialization.
Result: The project-state scaffold.
source exists → Choose the brownfield populator for existing code.
Source for step 1 - command
/ca:create-context: selected strategy
Automatic detection or --brownfield selects this existing workflow. A completed initialization marker or wrong source shape retains the route’s stop.
Result: A valid existing-code extraction request.
validate source shape → The skill validates its own preconditions.
Source for step 2 - skill
context-creation: confirm the source
Confirm meaningful code, an uninitialized context and primary source directories. Check actual host permissions before reading; ordinary work does not require a special scout profile.
Result: A bounded source surface to inspect.
bounded inspection → Inspect the selected source directly or delegate finite assignments within actual host permissions.
Source for step 3 - skill
context-creation: direct or delegated inspection
Inspect stack, infrastructure, architecture, security, testing and data model for initial/full work; scoped refresh covers affected categories. Optional agents receive finite assignments within host limits. Retain citations, source identities, conflicts and unknowns without secret values.
Result: Bounded evidence for the declared scope; agent labels and hashes do not verify semantics.
Source for step 4
Before continuing: Initial/full work accounts for all six categories with inspected evidence and explicit unknowns. Scoped refresh retains the declared affected coverage; missing reports can be resolved through direct inspection.
Continuations, returns and repeat paths
- bounded evidence. Account for six logical categories for initial/full work, or exactly the affected categories for scoped refresh. Direct inspection may resolve missing coverage; failed or uninspected work remains unknown. Next: context-creation: source-backed synthesis. Owning contract
- Missing or contested evidence. Narrow the assignment or directly reinspect the source within actual host permissions. Retain the failed attempt and unknown scope; do not invent a successful report. Next: context-creation: direct or delegated inspection. Owning contract
Chapter 2 / 3
Resolve the evidence gaps
Which claims are known, and which need the user?
Link to this chapter- skill
context-creation: source-backed synthesis
Turn inspected evidence into project, stack, standards, security and code-map records, each with its basis; source-observed records cite their source and are scoped to the paths they govern. Reinspect disputed or changed sources when useful; do not turn an inferred claim into a verified fact.
Result: Draft records with the evidence and unresolved facts visible.
missing facts → Only the needed user facts are asked, not a second greenfield interview.
Source for step 5 - skill
context-creation: resolve or defer
Ask only missing material user-owned decisions. Record actual resolutions or explicit deferrals through the question owner. Real unresolved prerequisites stop dependent work; unrelated uncertainty stays visible without blocking independent work.
Result: Actual decisions and explicit gaps, without invented approval or deferral.
resolved or deferred → Apply supported claims and actual decisions while preserving human content, protected owners and explicit unknowns.
Source for step 6 - skill
context-creation: write project state
Write the records with knowledge.py add and update. Each write is checked and journaled by the native engine and is safe to retry; no per-document approval receipt is required. Board mutations retain their own helper; a release-target row remains conditional on real evidence or a resolved declaration.
Result: Populated knowledge documents and separately maintained task state.
Source for step 7
Before continuing: Real values come from cited inspection and actual owner decisions. Uncertainty remains visible; independent solvable work need not wait for unrelated gaps.
Continuations, returns and repeat paths
- bind derived claims. Source-derived records retain their citations instead of only their final prose. Next: context-creation: cite evidence. Owning contract
Chapter 3 / 3
Bind sources and finish
What keeps this context inspectable after the interview?
Link to this chapter- skill
context-creation: cite evidence
Each source-observed record cites the files it rests on, and each document keeps a baseline commit, so knowledge.py stale later lists exactly the records whose sources changed. Citations do not manufacture semantic review.
Result: Traceable source pointers and the current code map.
structural check → Initialization checks that the documents exist and parse, not that every question is answered.
Source for step 8 - skill
context-creation: initialization lock
For initial population only, knowledge.py initialize checks that the five knowledge documents exist and parse and the task board is well formed, then commits the marker. Unknown records and open questions do not prevent it. Initialized refresh retains its marker and never initializes again.
Result: Initialized source-backed context, not an implemented change.
Source for step 9
Before continuing: The initialized marker and required files are present. The resulting evidence is inspectable; it is not a guarantee that every inferred claim is correct.
Continuations, returns and repeat paths
Populated HTML knowledge records, each with its basis and cited sources, including a path-scoped code map. Material user-owned questions retain actual resolutions or explicit deferrals; other unknowns remain visible as unknown records. It does not invent a greenfield decomposition.
Open the two-route diagram · Greenfield diagram · Brownfield diagram. The same source-bound models drive these images and the reading views above.
Know what completion means
Section titled “Know what completion means”Installed means the host has the adapter. Activated means the repository carries the recognized opt-in. Initialized means its context has been populated and the body marker is present. Verified means the appropriate host probe produced its documented evidence. None of the first three substitutes for the fourth, and the probe does not judge whether your project requirements are good.
Choose the context-building path before starting. Plan a new project explains the substantial greenfield interview and its three documents. Understand an existing project explains scout extraction, source evidence and the gap interview. Brownfield extraction does not invent the greenfield plan set.
1. Scaffold the State Store
Section titled “1. Scaffold the State Store”Open the target repository in one supported host and invoke its native command:
| Host | Command |
|---|---|
Claude Code | /ca:init |
Codex | $ca-init |
Pi | /ca-init |
/ca:init creates .codearbiter/ at the repo root and routes to the right context builder for your situation. If the directory already exists, it will not overwrite what is there.
2. Complete the Context Build
Section titled “2. Complete the Context Build”/ca:init routes based on whether the repository has existing code:
| Your situation | Routed to | What it does |
|---|---|---|
Existing codebase | /ca:create-context | Scouts the source and back-fills .codearbiter/ |
New project, no code yet | /ca:decompose | A layered interview that builds .codearbiter/ from scratch |
Review the routed procedure’s outputs before moving on. Greenfield writes the architecture breakdown, phased build plan and task backlog for your explicit approval before population. Brownfield derives context from scout reports and asks you to resolve or explicitly defer gaps. The resulting context files supply later planning, review and enforcement with project facts. Do not mark a stub initialized just because the activation flag exists.
3. Confirm the Activation Flag
Section titled “3. Confirm the Activation Flag”Open .codearbiter/CONTEXT.md and confirm the leading frontmatter:
---arbiter: enabled---Two things to verify:
- The frontmatter block opens on line 1 and closes with a matching
---. arbiter: enabledappears inside that block.
A file with no frontmatter at all is silently dormant. A frontmatter block that opens but never closes surfaces a malformed-state error rather than treating the repo as disabled.
Once the flag is present and the block is closed, the next supported-host session opens with the orchestrator active and every gate armed.
4. Restart and Prove Enforcement
Section titled “4. Restart and Prove Enforcement”Close the current session and open a fresh one in the same repository. The first response should include the codeArbiter startup briefing: stage, blocking questions, in-flight tasks, and a pointer to the command catalog.
Then run doctor using the same host syntax convention:
| Host | Command |
|---|---|
Claude Code | /ca:doctor |
Codex | $ca-doctor |
Pi | /ca-doctor |
Doctor’s harmless H-03 probe should be blocked. If the briefing is absent or the probe executes, the repository is not proven active. Follow Troubleshooting before starting governed work.
Common Stops
Section titled “Common Stops”| Symptom | Meaning | Recovery |
|---|---|---|
Init reports an existing .codearbiter/ directory | Project state already exists | Inspect it; do not overwrite another session’s context |
The repo has source but no initialized marker | Brownfield context is incomplete | Complete the routed create-context flow |
Frontmatter opens but does not close | Activation state is malformed | Repair the frontmatter structure, then restart |
Fresh session has no briefing | Plugin trust, interpreter, cache, or activation failed | Run doctor and use the symptom table in Troubleshooting |
For the full catalog of what the gates enforce and how they fail, see Enforcement & Security.