context-creation

context-creation

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 docs are derived from what is already on disk.

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

Phase 1 — Pre-flight confirmation · gate: BLOCK

Confirm the repository is a brownfield codebase safe for scout-based extraction:

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 scout-based extraction.

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 — Scout dispatch · gate: BLOCK

A scout is a restricted, read-only role, not an unconstrained general-purpose agent. A scout reads one targeted slice of the codebase and returns a structured findings report — file paths, line numbers, and named values only, never raw code excerpts. Scouts are internal to this skill; they are never invoked from a command.

Dispatch six isolated scout subagents simultaneously. If the active host cannot provide isolated subagents, BLOCK context creation and report the host capability gap. The general inline-role fallback does not apply here: this skill's report-only synthesis contract depends on the orchestrator never loading the scouts' raw source into its own context. Each reads only its assigned slice:

• Scout 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, license fields. Additionally report, at the repository root only: which of package.json / pyproject.toml / Cargo.toml / composer.json carry a version field (candidate release manifests), which of CHANGELOG.md / CHANGES.md / HISTORY.md are present (candidate changelogs), and any existing tag naming convention visible in the repo (e.g. a v* tag) — the inputs Phase 3/5 use to draft .codearbiter/release-targets.md.
• Scout B — Infrastructure. Read CI/CD config (.github/workflows/, .gitlab-ci.yml, Jenkinsfile, .circleci/config.yml), Dockerfile*, docker-compose*.yml, Makefile, *.tf, IaC. Report CI/CD platform, build/test/lint commands, deployment targets, environment names, containerization, IaC tool.
• Scout C — Architecture. Read the source tree (names and structure only), entry points (main.ts, index.ts, app.py, server.go), and imports in entry points only. Report component list, entry points, module boundaries, architectural pattern, public interfaces.
• Scout D — Security posture. Read auth files (auth*, middleware*, guard*, jwt*, session*, oauth*), crypto import lines, secret-loading sites (process.env, os.environ, vault/KMS call sites — paths and line numbers only, never values), .env.example (never .env). Report auth mechanism, crypto libraries, secret-loading patterns (paths + lines, no values), vault/KMS integration, hardcoded-secret risk files (paths only).
• Scout E — Testing. Read test files and test config (vitest.config.*, jest.config.*, pytest.ini, Makefile test flags), coverage config. Report test framework, runner command, coverage tool, coverage thresholds in config, naming convention, approximate test count by type, fixtures.
• Scout F — Data model. Read migration files (migrations/, drizzle/, alembic/, db/migrate/), schema definitions (schema.ts, *.prisma, *.sql, models/), ORM config, DB connection config (keys only, never credentials). Report database type, ORM/query builder, entity names, migration tool, approximate entity count, multi-tenancy patterns.

The orchestrator reads only the scout reports in later phases — never the raw source — to preserve working context. A scout that finds nothing returns an explicit "not found" report, never silence.

Content hashes: Scouts additionally emit a git hash-object <path> content oid per cited file in the hash field of their evidence entry. The scout already Read those files — no additional pass is needed, and no raw content is forwarded to the orchestrator.

Gate: all six scout reports returned. A missing report is a blocking gap — do not proceed with an incomplete picture. Re-dispatch a failing scout before Phase 3.

Phase 3 — Synthesis · gate: BLOCK

Draft every surviving project-state doc from the six reports, working only from the reports. Map source to destination:

Classify every finding by confidence:

• HIGH — directly and unambiguously in a report (e.g., "jest" in package.json). Write it as fact.
• MEDIUM — inferred from an indirect signal (directory layout implies layered architecture, no explicit config). Write it with a note: inferred from [signal], verify before relying on it.
• LOW — no signal, or conflicting signals. Write a [CONFIRM-NN] placeholder.

Every [CONFIRM-NN] carries: a sequential ID, one sentence on what is unknown, why it matters, and what would resolve it. IDs are sequential with open-questions.md.

.codearbiter/release-targets.md is HIGH-confidence only when Scout A found exactly one candidate manifest and exactly one candidate changelog at the repository root. Draft the row then, in the grammar ${CLAUDE_PLUGIN_ROOT}/hooks/_releaselib.py's module docstring declares — a single-target project needs only prefix, manifest, changelog, payload:

<!-- release-targets -->
[app]
prefix: v
manifest: package.json
changelog: CHANGELOG.md
payload: .
<!-- /release-targets -->

(prefix defaults to v unless Scout A found a different existing tag convention; payload is . for a single-package repository.) Zero, or more than one, candidate manifest or changelog is LOW confidence — the same "no signal, or conflicting signals" rule above — and gets a [CONFIRM-NN] instead of a guessed row; this doc is never scaffolded from an ambiguous scan, and the file is simply not written until the gap is resolved in Phase 4.

Gate: every surviving doc drafted; every low-confidence inference carries a [CONFIRM-NN]. No silent omission. A domain with no scout signal gets a doc with a [CONFIRM-NN] for the whole section — never an empty file.

Phase 4 — Gap interview · gate: BLOCK

Resolve [CONFIRM-NN] items with the user. Ask only what the scouts could not answer with HIGH confidence.

1. Present the [CONFIRM-NN] list grouped by category — gaps the scan could not resolve.
2. Ask ONE targeted question per item. No compound questions. Do not re-ask anything scouts answered with HIGH confidence.
3. Per answer: if it resolves the gap, replace the placeholder with content; if the user explicitly defers, keep the placeholder, mark it deferred with the date, and record it in open-questions.md; if the answer is vague, challenge it and demand a concrete answer before recording anything.

Gate: every [CONFIRM-NN] has exactly one outcome — resolved (replaced with content) or explicitly deferred (marked and recorded in open-questions.md). No item is silently dropped. Do not proceed with unacknowledged gaps.

Phase 5 — Project-state write · gate: BLOCK

Write the surviving docs to <project-root>/.codearbiter/. Every doc carries actual content — no unresolved placeholder may remain where a value was determined:

Authoring marker — required for release-targets.md only. That path is enrolled in the protected-state registry as marker-gated (hook H-22), so a Write against it is refused unless a fresh authoring marker exists. This lane is a sanctioned author of it, so it mints one immediately before the write and removes it immediately after — the same one-pass shape /release's back-fill lane uses:

mkdir -p "$(git rev-parse --show-toplevel)/.codearbiter/.markers"
touch "$(git rev-parse --show-toplevel)/.codearbiter/.markers/release-targets-authoring"

Write the file, then:

rm -f "$(git rev-parse --show-toplevel)/.codearbiter/.markers/release-targets-authoring"

Skip both commands entirely when this run is not writing release-targets.md — a marker minted for a write that never happens is a 30-minute window nothing needed. No other file in the table above is enrolled, so none of them take a marker.

If scouts found existing decision records (docs/decisions/, adr/), summarize them as entries under .codearbiter/decisions/ in the standard ADR format. If a record cannot be fully parsed, summarize what is known, flag the uncertainty, and note the source path for review.

Provenance and code-map (small addition, not a Phase 5 rebuild):

• Write ONE provenance file per derived doc to .codearbiter/.provenance/<doc>.json via _provenancelib.write_provenance and new_record. Each entry carries: path (repo-relative), hash (the scout's git hash-object oid), drift_trigger (from _provenancelib.classify_source(path)), and the claims array with lines, claim, and confidence drawn from the scout evidence.
• Synthesize .codearbiter/code-map.md (concern → path → ≤1-line role) from Scout C (architecture) evidence. Use concern headings (## <concern>) and column-0 bullets (- \path` — role`). Keep it coarse — module/concern granularity only, no full file listing.

Do NOT scaffold any cut doc — see ${CLAUDE_PLUGIN_ROOT}/includes/cut-docs.md for the canonical never-scaffold list. Maturity lives in the stage: frontmatter of CONTEXT.md, not a separate file.

Gate: every surviving doc written; CONTEXT.md frontmatter carries arbiter: enabled and stage:; no resolved value left as a placeholder. Deferred [CONFIRM-NN] items are acceptable only in open-questions.md.

Phase 6 — Initialization lock · gate: BLOCK

Lock the project state as initialized and return to normal orchestration:

1. Write the <!--INITIALIZED--> marker into the body of CONTEXT.md.
2. List .codearbiter/ and display the populated tree.
3. Confirm each required file is present and non-empty: CONTEXT.md (with arbiter: enabled frontmatter and the <!--INITIALIZED--> body marker), tech-stack.md, coding-standards.md, security-controls.md, open-questions.md, open-tasks.md, overrides.log.
4. State the return to normal operation: extraction complete, project state initialized and locked, $ca-feature available to begin work. Deferred questions live in open-questions.md.

Gate: arbiter: enabled set and <!--INITIALIZED--> present in CONTEXT.md; every required file present and non-empty. Do not close this skill without confirming both markers are written.

Hard rules

• MUST NOT write <!--INITIALIZED--> while any [CONFIRM-NN] is unaddressed — every gap must be resolved or explicitly deferred to open-questions.md first.
• MUST NOT resolve a [CONFIRM-NN] by guessing — surface the question to the user or defer it.
• MUST NOT proceed past Phase 2 with fewer than six scout reports.
• MUST NOT run Phase 2 inline — isolated scout subagents are required for the report-only synthesis boundary.
• MUST NOT load raw source into the orchestrator context after Phase 1 — synthesize from scout reports only.
• MUST NOT record a scout finding that exposes a secret value — paths and line numbers only.
• MUST NOT scaffold a cut doc — see ${CLAUDE_PLUGIN_ROOT}/includes/cut-docs.md for the canonical never-scaffold list. Maturity is the stage: frontmatter number in CONTEXT.md.
• MUST NOT run when CONTEXT.md already carries <!--INITIALIZED--> — stop and route to normal operation.