Architecture breakdown
What owns what?
UI, persistence and the CSV serializer have explicit responsibilities. A deployment choice remains an open question.
Read 01-architecture-breakdown.mdGreenfield means the project has no meaningful source to inspect yet. codeArbiter therefore starts from your intent, not a guessed architecture. The interview records the intended project: its architecture, a phased build plan and a backlog. It also populates the context that later work reads.
New projects keep decomposition in one native HTML document,
.codearbiter/decomposition/project.html. Each record has a stable ID, so renaming or reordering
never breaks a reference to it:
| Record | Purpose | Review it for |
|---|---|---|
question | One interview question with its status and your actual answer | Answers recorded the way you meant them; deferrals that are really still open |
capability | What the product does, who starts it, its inputs and outputs | Missing capabilities and anything that belongs in a later phase |
component | Intended parts, responsibilities, connections and integrations | Missing owners, incorrect boundaries and hidden integrations |
phase | MVP and later phases with measurable completion | Whether the first phase is useful and each completion test is observable |
work_item | Bounded tasks with roles, dependencies and time-boxed spikes | Whether work is estimable and uncertainty is investigated rather than concealed |
These records describe what you intend to build. They never claim that code exists.
Open the intended repository in your coding host. In a separate native terminal, run
git rev-parse --show-toplevel and git status --short to confirm its root and existing changes.
Changing a terminal directory does not necessarily change the repository open in the host.
Preserve any existing work. If there is meaningful source, use
Understand an existing project instead.
Bring the problem, primary users, a concrete description of a useful first version, hard constraints, and the things you explicitly are not building. A sketch or requirements note is useful input, not something the agent should silently treat as approved truth. Do not supply production credentials or confidential examples that the configured provider must not receive.
Describe the goal naturally, or use an explicit entry:
| Host | Start the greenfield route |
|---|---|
Claude Code | /ca:init --greenfield |
Codex | $ca-init --greenfield |
Pi | /ca-init --greenfield |
init scaffolds the state store when needed and enters decomposition. The existing decompose
command remains a compatibility entry for that same strategy. An initialized project returns to
normal work; selected context changes use context-check. Meaningful existing source routes to
the brownfield populator. Neither case permits overwriting existing project records.
The interview covers vision and problem, users and flows, functional scope, technical shape, integrations and infrastructure, then risks and unknowns, in whatever order the conversation makes natural. Questions focus on missing facts and consequential choices; inapplicable areas are recorded with their reason.
Answer in observable terms. Instead of “make exports work well,” identify who exports, what is exported, the format, the empty case, and how a reviewer could tell whether it works. codeArbiter challenges vague answers and explains architectural trade-offs. You own material choices. A genuinely unresolved answer stays an open question, not an invented fact.
Each question is saved when it is asked and your answer as soon as you give it, so closing the
session loses nothing. User-decided architectural choices go through the decision-lifecycle
owner and are linked from decision records; draft choices stay proposed until you decide.
From your answers, codeArbiter adds capability, component, phase and work-item records, each linked to the answers it rests on, and shows them to you. For the saved-search example, ask whether CSV export belongs in the first useful release, whether the export component owns formatting rather than storage, and whether the backlog leaves an investigation for any unresolved external integration.
A useful revision request is: “The first phase must export existing saved searches, but must not add account sharing. Update the records consistently.” Corrections update the records in place; a wording or method refinement does not need a fresh confirmation, and settled questions are not asked again. Your actual confirmation is itself saved as an answered question. Confirmation does not authorize later scope expansion or a merge.
Population adds records to five HTML knowledge documents under .codearbiter/context/: project,
tech-stack, coding-standards, security-controls and code-map. Each record carries its basis, so
what you decided, what was proposed and what is still unknown stay distinct. Planned commands are
recorded as proposed and unrun; the code map stays empty until real code exists, because intended
components live in decomposition.
Each approved work item is promoted once to the task board through its owning writer; repeating
the promotion does nothing. Questions, decisions and audit history remain intact. Then
knowledge.py initialize checks that the knowledge documents exist and parse and that the task
board is well formed, and records the <!--INITIALIZED--> marker. Open questions do not prevent
it. A refusal names the document to repair; do not append the marker manually.
Initialization records population; it does not establish accurate implementation, passing tests or installed-host enforcement. Use Protect your first repository for host qualification and Build a feature for the next selected change.
The decomposition backlog is project planning. A later feature’s execution plan breaks a selected change into coherent, verifiable tasks with actual dependencies. The two serve different scopes: new full-lane feature and sprint work has a separate typed specification-and-plan contract.
Re-entering decomposition reads the saved records and continues with the open question that matters most for what you want to do next. An explicit restart retires earlier records with a reason; it never deletes them.
Later, when architecture, roadmap, backlog or prior decisions disagree, reconcile reads the
decomposition records by their stable IDs. It presents variances for your choice and records the
outcome. It does not silently rewrite records, fix code or create an ADR itself. When real source
and manifests arrive, context-check adds what the code actually contains to the code map and
reconciles intended and implemented facts, keeping the interview records.
A repository scaffolded before HTML knowledge, or one whose owner keeps the Markdown format,
follows the unchanged procedure. Conversion is never silent: knowledge.py convert prepares
empty HTML documents and lists the Markdown sections to read. After their meaning is
recorded, map every section to saved records or notes in a JSON checklist.
convert --finish <token> --coverage @checklist.json switches formats only when
all meaningful sections are mapped; the transaction retains the original bytes.
The project before the first feature
What owns what?
UI, persistence and the CSV serializer have explicit responsibilities. A deployment choice remains an open question.
Read 01-architecture-breakdown.mdWhat becomes useful first?
MVP saves searches. v1 exports them. Collaboration waits for a separate decision. Each phase has an observable finish.
Read 02-phased-build-plan.mdWhat work is next?
Priority, phase, owner, estimate and dependencies make the work discussable. Unresolved assignments remain visible.
Read 03-task-backlog.mdIllustrative Markdown documents for the same saved-search product. These were authored for explanation, not generated by a completed interview. They retain unresolved decisions deliberately; no approval, initialization, or automatic cross-document synchronization is claimed.
In that format the interview writes each completed layer beneath
.codearbiter/plans/decomposition/, and _session.md records the phase, remaining questions and
actual confirmations. It then writes three project-planning documents under .codearbiter/plans/:
File under .codearbiter/plans/ | Purpose |
|---|---|
01-architecture-breakdown.md | Components, responsibilities, connections, system diagram, integrations and open architectural questions |
02-phased-build-plan.md | MVP, v1 and v2 goals; included and deferred work; rationale, risks and measurable definitions of done |
03-task-backlog.md | Prioritized, phase-grouped work with role assignments, dependencies and time-boxed spikes |
Open all three files before approving; existing confirmation covers unchanged artifacts. The
native writer’s --context-draft and --context-apply operations populate five
document/provenance pairs, and --context-finalize validates the thirteen required outputs: five
document/provenance pairs, the task board, question board and audit log. Read back the result and
retain the interview, plans and decision history as provenance sources. reconcile reads these exact three
filenames in that format.
For practice with the older Markdown format, follow Academy’s prerequisites before U04: initialize greenfield and brownfield projects. That pinned lesson does not yet verify the HTML knowledge and decomposition route above. The decompose reference contains the exact phase contract.
Open the greenfield execution map to follow the command, owning skill and applicable roles from entry to initialized state. The other initialization route is an alternative, not a next phase.