Skip to content

The .codearbiter/ Directory Reference

.codearbiter/ is codeArbiter’s project-state store: a root-level directory, outside .claude/, so it survives even if the plugin itself is uninstalled. It holds the project’s own record (its spec, selected work state, decisions, and audit trail), separate from the plugin code that reads and writes it. /ca:init scaffolds it; /ca:create-context (existing codebase) or /ca:decompose (greenfield) populates it. Its presence and content is the plugin’s actual contract with your repo: if you want to know what codeArbiter knows about your project, or what it will do next, this directory is where to look.

Enforcement itself is gated on one file in here: CONTEXT.md. Everything else described below only matters once that file carries arbiter: enabled.

The table below maps every stock path the scaffold or a governed lane produces or reads. Some appear when the owning workflow first needs them (plans/decomposition/, .markers/, .provenance/, spikes/, reports/). The state file reference covers most of these paths in detail: format, lifecycle, and what happens if one is deleted. The HTML knowledge and decomposition files, the native work records and .gitattributes have no entry there; this table is their reference.

New scaffolds record narrative context as native HTML knowledge: context/project.html, context/tech-stack.html, context/coding-standards.html, context/security-controls.html and context/code-map.html, plus greenfield decomposition/project.html. CONTEXT.md frontmatter carries context-format: html for them. Repositories scaffolded earlier keep the Markdown documents and .provenance/ records until their owner converts them explicitly with knowledge.py convert, agent-recorded content, a mapping from every returned section to saved records or notes, and convert --finish <token> --coverage @checklist.json. In both formats CONTEXT.md owns activation and stage, and the scope blocks in security-controls.md stay the operative migration, CI and deploy configuration.

New HTML scaffolds have no legacy work board. Knowledge initialization creates work/project.json together with the initialized marker, so clones share one project ID before either creates its first work item. Explicit --format markdown scaffolds the legacy boards; an existing HTML project with a board remains legacy-owned until its selected adoption.

Project plans are not feature execution plans

Section titled “Project plans are not feature execution plans”

In an HTML-knowledge repository, greenfield decomposition is one native document, decomposition/project.html, whose capability, component, phase and work-item records hold the intended architecture, phased plan and backlog; reconcile reads them by stable record ID. In a Markdown-format repository, greenfield decomposition creates three named Markdown documents: plans/01-architecture-breakdown.md, plans/02-phased-build-plan.md and plans/03-task-backlog.md. They own project architecture, phased delivery and the project backlog. Reconcile consumes their exact filenames. They are not legacy feature pairs to convert to HTML. Brownfield context creation does not manufacture this set.

Feature/sprint specifications and execution plans are a different layer. New full-lane work uses a same-slug typed HTML pair when the installed package has its qualified native capability; existing Markdown pairs remain on their exact legacy path; small-lane work remains inline with its triage record. Review specifications and plans explains the review, progress and recovery boundaries.

PathWritten byRead byEditable by hand?
CONTEXT.md/ca:init; context workflows through the native writerevery enforcement hook (arbiter_active()), the orchestratorNo: use the context writer; preserve activation frontmatter
code-map.mdContext workflows through the native writerfeature/task orientation, context checksNo: refresh selected claims through /ca:context-check
context/*.htmlHTML-format context workflows through knowledge.py and the native engineknowledge.py relevant, task-context, reviewersNo: change records with knowledge.py; a Git conflict uses knowledge.py merge-conflict
decomposition/project.htmlHTML-format /ca:decomposeInterview resume, reconcile, knowledge.py promoteNo: change records with knowledge.py
.gitattributes/ca:init (HTML format) and knowledge.py convert --finishGitKeep it: it stops line-ending conversion of native HTML artifacts
open-tasks.md (legacy owner)/ca:task through taskwrite.pyselected work facade, statusline, SessionStartNo: guarded to the legacy writer (hook H-22)
done-tasks.md (legacy owner)/ca:standup’s selected archival sweeplegacy history, read on demandNo: guarded (hook H-22, append-only)
work/project.json, work/*.html (native owner)HTML knowledge initialization creates the project ID; work.py creates and updates items through the native engineselected work calls and derived viewsNo: use stable Work IDs and native operations
views/work/*.html (derived)work.py view <WORK-ID> --savebrowser, local reviewRegenerate after work changes; never edit as canonical state
work/provider.jsonwork.py provider-configureexplicit GitHub syncNo: finite provider binding; no credential value is stored
work/project-provider.jsonwork.py project-configureoptional GitHub Projects item and single-select effectsNo: binds to the issue provider; no credential value is stored
work/transition-map.jsonwork.py transition-map-configureoptional native start/complete/reopen tracker intentNo: finite mapping; absent until explicitly configured, with no credential value
legacy/open-tasks.md, legacy/done-tasks.mdselected journaled work adoptionhistorical byte-exact snapshotsNo: retained originals, not writable boards
open-questions.mdthe orchestrator, when a [CONFIRM-NN] is raised/ca:status, SessionStart, the statuslineYes
decisions/*.md, decision-log.md/ca:adr only/ca:adr-status, /ca:reconcile, post-write-edit.py (H-12)No: guarded to /ca:adr
specs/*.mdLegacy feature/sprint workflows already owned by Markdownwriting-plans, /ca:statusYes
plans/01-architecture-breakdown.md, 02-phased-build-plan.md, 03-task-backlog.mdGreenfield decomposeHuman project review, reconcileReview through the owning project-planning procedure; preserve exact filenames
Other legacy plans/*.mdwriting-plans for an existing Markdown specexecuting-plans, subagent-driven-development, /ca:statusPreserve the selected format, agreed scope and execution state
specs/*.html, plans/*.htmlNew full-lane feature/sprint workflows through the internal typed-artifact engine (default)The same workflow readers through validated, scoped readsNo: use typed engine operations
plans/decomposition//ca:decomposeInterview resume and context provenancePreserve the recorded answers and decisions through the owning workflow
checkpoints/*.mdcheckpoint-aggregator agent (/ca:checkpoint)/ca:audit, /ca:status-adjacent readsYes
audits/*.md/ca:audithumans (report only)Yes
reports//ca:tribunal and named handoff/evidence workflowsthe owning workflow on resume, humansYes, but not while an owning run is in flight
sprint-log.md/ca:sprint/ca:status, /ca:auditNo: append-only, guarded (H-05)
overrides.log/ca:override, the mode-plane flip (mode --dangerous/--ops/--arbiter, MODE: <name> enter/exit)statusline, /ca:status, /ca:audit, staleness-warnNo: append-only, guarded (H-05)
triage.log/ca:feature small-lane triage/ca:auditNo: append-only, guarded (H-05)
gate-events.logevery block()/remind()/warn() call in the hooks(durable sink; no reader ships yet)No: append-only, guarded (H-05)
.markers/security-pass.py, migration-pass.py, prompt-submit.py (mode marker), /ca:adrthe commit-gate hooks (pre-bash.py, pre-write.py, pre-edit.py)No: guarded, and hand-writing one is friction and an audit trail, not a proof (see .markers/)
.provenance/*.jsoncontext-creation, decompose, context-check (re-scout/re-baseline)SessionStart (drift line), commit-gate (auto-heal)Not by hand: regenerate via /ca:context-check
security-controls.md, tech-stack.md, coding-standards.mdContext workflows through the native writerreviewer agents, the crypto/secret gatesNo: update selected content with its paired provenance
last-checkpoint/ca:checkpoint after its report is written/ca:status, the statusline (overrides-since-checkpoint)Not normally: it’s a counter, not a note
spikes/*.md/ca:spikehumans, /ca:feature (seeds brainstorming)Yes

The state file reference documents most paths in the table: format, who may change them, and what happens if one is deleted or goes stale. The HTML knowledge and decomposition files, the native work records and provider bindings, the retained legacy/ boards and .gitattributes are covered only by the table above.