Skip to content

Plan a New Project

Greenfield 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:

RecordPurposeReview 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:

HostStart 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.

Repositories that keep the Markdown format

Section titled “Repositories that keep the Markdown format”

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

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.md

Phased build plan

What 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.md

Task backlog

What work is next?

Priority, phase, owner, estimate and dependencies make the work discussable. Unresolved assignments remain visible.

Read 03-task-backlog.md

Illustrative 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.