decompose git:20261016.a9f63fcA

Immutable. This exact content never changes and is served at /api/v1/blob/a108ba28428c4758.

---
name: decompose
description: Develop greenfield context from a durable interview and initialize it through the native context writer.
argument-hint: (none)
---

# decompose

<!-- catalog-compatibility-notice:start -->
> Compatibility route. Prefer `/ca-init --greenfield` for new usage. This installed route remains
> functional under the command-route compatibility policy at <plugin-root>/includes/command-compatibility.md;
> continue with the greenfield workflow below.
<!-- catalog-compatibility-notice:end -->

Develop the project specification before implementation. Keep actual user decisions,
planned architecture and observed repository facts distinct.

## 1. Inspect and resume

Read `.codearbiter/CONTEXT.md`. An initialized project returns to normal operation;
context changes use `/ca-context-check`. Meaningful implementation source routes
to `/ca-create-context`. If the scaffold is absent, run `/ca-init` first.

Keep the interview in `.codearbiter/plans/decomposition/`: `_session.md` records the
current phase, remaining questions and actual user confirmations; each completed
layer has its own file. Read this state and resume the first unfinished step. Do not
repeat settled questions or require another approval of unchanged accepted work.
An explicit restart preserves earlier interview and decision history.

If `.codearbiter/.decompose-draft/` contains an interrupted interview, copy its session
and layer records to the durable directory before using them as source evidence.
Compare existing destinations byte-for-byte: retain identical files, and reconcile
conflicting versions without overwriting either. Temporary drafts remain until
initialization completes. Never cite a temporary file that cleanup will remove.

## 2. Capture the interview

Explain briefly that you will establish scope, architecture and a build sequence.
Ask focused questions only where existing answers do not establish the needed facts
or choices. Use these six layers; record an inapplicable category with its reason.
Persist each layer before proceeding. Each record contains the question, actual
answer, relevant trade-offs and unresolved `[CONFIRM-NN]` items. Keep each source
file within 1 MiB; split a long layer into named parts. Exclude secret values.

| Layer and file | Required outcomes |
|---|---|
| 1 — `layer-1-vision.md` | Problem, primary users, demonstrable success and exclusions. |
| 2 — `layer-2-flows.md` | User journey, non-human actors, failure experience and privilege boundaries. |
| 3 — `layer-3-functional-scope.md` | Capabilities with initiators, inputs and outputs; MVP/v1/later classification; hardest user-facing risk. |
| 4 — `layer-4-tech-shape.md` | Components and ownership, entities, state/write paths, stack and other hard constraints, technical risks, copyright holder, actual architectural choices and release intent. |
| 5 — `layer-5-integrations.md` | External dependencies, available contracts/authentication, ownership, reliability, cost and fallback requirements. |
| 6 — `layer-6-risks.md` | Material risks with mitigations, unresolved questions, bounded spikes and architecture-change triggers. |

Record a user-decided architectural choice through `decision-lifecycle` at
`<plugin-root>/routines/decision-lifecycle/SKILL.md`. It owns ADR numbering,
attribution, authoring and status transitions. Preserve draft choices as drafts
until the user actually decides; do not create an ADR merely to fill a quota.

Release intent is elicited here: capture the **tag prefix** preference and
**changelog kept** yes/no in Layer 4. No `.codearbiter/release-targets.md` row is ever written by this skill.
Greenfield runs before any manifest or tag exists. `/ca-release` or a subsequent
context refresh derives a target from the actual manifest and delivery structure.

An unresolved consequential choice blocks its dependent output. Record other gaps
as questions; a user's explicit deferral remains unresolved and is not permission.

## 3. Synthesize and confirm

Re-read the retained layer records and relevant ADRs. Write these three artifacts
under `.codearbiter/plans/`, using the recorded evidence:

- `01-architecture-breakdown.md`: components, responsibilities, connections,
  integration boundaries and remaining architectural questions.
- `02-phased-build-plan.md`: MVP and subsequent phases, scope, risks, deferrals and
  measurable completion criteria.
- `03-task-backlog.md`: prioritized, bounded tasks with roles, dependencies and
  time-boxed spikes.

Present the files for review. Apply corrections and record the user's actual
confirmation in `_session.md`; existing confirmation covers unchanged artifacts.
Proceed when the artifacts accurately represent the user's choices and each gap is
resolved or explicitly retained on the question board.

## 4. Populate context

Re-read the approved artifacts and retained interview sources. Prepare UTF-8 drafts
outside the five target paths, each at most 128 KiB. Use only relevant retained
sources for each document; planned choices must not be described as implemented facts.
Use the matching document title: `# Project: <name>`, `# Tech stack`,
`# Coding standards`, `# Security controls` or `# Code map`.
Preserve existing CONTEXT frontmatter exactly; the scaffold owns activation and stage.

| Document ID | Content |
|---|---|
| `CONTEXT` | Identity, purpose, users, scope and exclusions; frontmatter `arbiter: enabled` and one `stage:` number. |
| `tech-stack` | Intended runtime, frameworks, tooling and confirmed conventions. Mark commands without a real manifest as planned, not verified executable commands. |
| `coding-standards` | Confirmed structural/style conventions and copyright holder. |
| `security-controls` | Actual trust boundaries, authentication requirements, secret handling and prohibited primitives. |
| `code-map` | Planned concerns and ownership. Distinguish proposed paths from existing paths; state when no implementation paths exist yet. |

For each of the five documents, invoke the installed writer:

```bash
python3 "<plugin-root>/hooks/init-codearbiter.py" --root "<project-root>" --context-draft "<draft.md>" --document "<document-id>" --source ".codearbiter/plans/decomposition/<layer-file.md>"
```

Repeat `--source` for each relevant retained source, up to 64 per document. Inspect
the returned preview, exact preimage and source bindings, then apply that preview
under the existing authorization:

```bash
python3 "<plugin-root>/hooks/init-codearbiter.py" --root "<project-root>" --context-apply "<preview_ref>" --preview-sha256 "<preview_sha256>"
```

The writer commits each document and its v2 provenance record together. Do not write
those protected pairs directly. A digest records inspected bytes; it does not certify
semantic review or user authority. If source or output bytes change, inspect the
changed input and prepare a fresh preview. Reuse the same retained preview after an
uncertain response; recovery determines whether its transaction committed.

Populate the other records through their owners:

- Add each approved backlog item with `python3 "<plugin-root>/hooks/taskwrite.py" add "<task>"`.
  Compare the existing board before retrying so resumed population does not duplicate
  tasks. Never write task rows directly or mark planned work done.
- Record unresolved questions in `open-questions.md`, retaining the scaffold and
  actual resolution or deferral history. An empty question board is valid.
- Preserve `overrides.log`, `last-checkpoint` and all ADR history. The scaffold owns
  their creation; initialization does not invent audit events or acceptance evidence.

Verify all five v2 pairs, the task/question boards and audit header are present.
Do not scaffold cut documents listed in `<plugin-root>/includes/cut-docs.md`.

## 5. Finalize and return to work

Preview initialization against the exact five document/provenance pairs and the
three independent board/audit outputs:

```bash
python3 "<plugin-root>/hooks/init-codearbiter.py" --root "<project-root>" --context-finalize
```

Inspect the result and apply its `preview_ref` and `preview_sha256` with
`--context-apply`. The writer validates current outputs and source evidence, then
commits the standalone `<!--INITIALIZED-->` marker and matching CONTEXT provenance
together. Missing, stale or malformed input names the repair needed; never append
the marker manually. Recover an uncertain transaction before preparing another.

Read back the committed result and all required outputs. Keep
`.codearbiter/plans/decomposition/`, approved plans and decision history. Remove only
this run's temporary drafts after confirming no provenance source refers to them.
Record completion in `_session.md`. Report the populated context, unresolved choices
and actual checks, then continue authorized work. Initialization records population;
it does not certify host enforcement, semantic review or passing tests.

When source and manifests arrive, `/ca-context-check` refreshes the selected
context against those files. Use `_provenancelib.assess_context_provenance` to inspect
current evidence. An existing `first_input_pending` result names the bounded refresh;
otherwise select the documents affected by the new source. Preserve interview
history and the initialized marker while reconciling intended and implemented facts.