/ca-create-context

name: ca-create-context
description: Build source-backed project context through bounded inspection, optional agents, and record-level knowledge writes.
argument-hint: (none)

context-creation

<!-- catalog-compatibility-notice:start --> > Compatibility route. Prefer `$ca-init --brownfield` for new usage. This installed route remains > functional under the command-route compatibility policy at [includes/command-compatibility.md](../../includes/command-compatibility.md); > continue with the unchanged brownfield workflow below. <!-- catalog-compatibility-notice:end -->

Wrap an existing codebase in project state, without guessing. Routed to by `/create-context`, and by startup when `.codearbiter/CONTEXT.md` exists but carries no `<!--INITIALIZED-->` body marker and meaningful source code is present. When no meaningful source exists, this is the wrong skill — route to `decompose` instead.

This back-fills from existing source. It complements `$ca-init`, which scaffolds an empty `.codearbiter/` for a fresh project; here the context is derived from what is already on disk. Load [includes/knowledge.md](../../includes/knowledge.md) for the record vocabulary and the `knowledge.py` verbs used below.

An initialized refresh is requested through `$ca-status drift` and the existing `context-check` owner after an explicit scoped or full selection. An explicit initialized brownfield project-model request also uses the existing `decompose` owner for intended target, phases, and candidate work. This initial-population route keeps its `<!--INITIALIZED-->` lock; an initialized repository never clears the marker or re-enters Phase 6 to refresh content.

Pre-flight

Read these, or STOP and surface the gap — never guess project identity or a command:

• `<project-root>/.codearbiter/CONTEXT.md` — if it already carries `<!--INITIALIZED-->`, context exists. Stop and route to normal operation.
• `knowledge.py format`. A `markdown` scaffold is an older one: offer `knowledge.py convert` before writing. Read every returned Markdown section, add its meaning as records or notes, then map each section ID to its saved references (use `[]` only for `content=false`). Finish with `knowledge.py convert --finish <token> --coverage @checklist.json`. If the user keeps the Markdown format, load [routines/context-creation/references/markdown-format.md](../../routines/context-creation/references/markdown-format.md) and follow that unchanged procedure instead of this one; never convert silently.
• The repository root listing (one level deep) — the source surface this skill extracts from.

The excluded set (not "meaningful source"): `.git/`, `.codearbiter/`, `.claude/`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `LICENSE`, `.gitignore`, `.gitmodules`, and standard tooling dotfiles (`.editorconfig`, `.prettierrc`, etc.). Meaningful source MUST exist beyond it.

Resume after an interrupted initial population

Inventory the actual `.codearbiter/` files first. If the scaffold stopped partway through, rerun `init-codearbiter.py --root <exact repository root>` only while the project is uninitialized; it creates only absent files. Never clear the directory, reset a marker, or replace an existing task board, question board or append-only audit record to make a retry pass.

Run `knowledge.py create-missing` and read each document's records: they are the progress already saved. Every `knowledge.py` write is retry-safe — an identical record is reused and a lost response replays — so continue from what is there instead of starting over. A refused write names a changed document; read it again before retrying.

Phase 1 — Pre-flight confirmation · gate: BLOCK

Confirm the repository is a brownfield codebase ready for bounded source inspection:

1. Confirm `<!--INITIALIZED-->` is absent from `CONTEXT.md`. 2. Confirm meaningful source code is present beyond the excluded set. 3. Identify the primary source directories (`src/`, `backend/`, `frontend/`, `lib/`, `app/`, or equivalent).

State the finding to the user: existing source detected, beginning bounded source inspection.

Gate: `<!--INITIALIZED-->` absent AND meaningful source present. If the marker is present, stop and route to normal operation. If no meaningful source exists, stop and route to `decompose`. Neither condition met → do not proceed.

Phase 2 — Bounded inspection

Use direct bounded inspection or optional scoped agents, whichever reduces repeated reading for this repository. Cover six logical categories for initial or explicitly full work; a scoped refresh inspects only the selected affected categories and retains prior coverage separately. Six categories do not require six agents or parallel execution. Start with paths and targeted searches, then read only the source needed to support the current claims. Keep actual host permissions, excluded paths and secret-handling rules in force. Do not run repository scripts merely because a manifest declares them.

When delegation helps, give each agent a finite path/category assignment, current source identity, output limit and stopping condition. Respect the host's actual concurrency and tool limits. Retain failed, partial and conflicting reports; narrow an oversized assignment instead of truncating it or repeatedly relaunching unchanged work. Direct inspection may resolve missing coverage or check a contested claim. A role label or a read-only instruction is not evidence of containment or independent verification. Describe the tools and boundaries actually observed, without claiming a trusted sandbox from an agent name. A separately required containment policy still applies to its own scope; a repository-only profile fixture does not impose that policy on ordinary work.

The categories are:

• **A — Tech stack.** Read `package.json`, lockfiles, `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`, `*.gemspec`, `Gemfile`. Report languages, runtime versions, frameworks, key dependencies, the dependency manager, l