App init

Source of truth: the registry row in _processes/_shared/request-types.md and the agent prompt _processes/00_app/app-init.prompt.md (contract: _processes/00_app/APP_CONTRACT.md).

The flow

app-init runs outside the per-job pipeline. It first inspects the host project at ../ with a deliberately deep, read-only two-level survey (a root-orientation pass, then one read-only sub-agent per detected host section) to map the 12 contract concerns. In parallel it probes runtime availability (claude unconditionally true; codex via a trivial codex exec availability probe). It runs a tight AskUserQuestion questionnaire for anything inspection could not confidently answer, then writes a contract-valid app.md and config.json, self-checks the loose-heading match, and finally authors an operation_record job born complete in 4_done/ so the run is tracked like every other action.

What it is for

app-init exists to make the workflow runnable on a brand-new host. Per-job agents and most workflow prompts open with the directive "Read app.md first" and refuse to run while app.md is missing, empty, or the bootstrap placeholder. The documented exceptions are app-install, which runs before app-init and does not require app.md, and claude-agents-md-files, which maintains root instruction files and also requires no valid app.md. Producing the first valid app.md for normal workflow work is app-init's entire job.

• First-run setup. It writes app.md + config.json by inspecting the host project, then exits. Once it succeeds, the per-job pipeline and most workflow agents unblock.
• Run it once. On a new host, run app-install first when you need the helper app, then app-init before normal per-job and app-context work. claude-agents-md-files can also run without a valid app.md because it targets only the host's root instruction files.
• Drift is a different agent. Refreshing a valid-but-stale app.md after host drift is the job of app-update; app-init routes you there and writes nothing on an already-initialised host.

The logic

app-init sits in the operation layer with shape op-card. Unlike the action and pipeline types, it is direct-invoked: you send its prompt path yourself and it runs immediately. It is not orchestrator-routed and never enters the stage pipeline.

• Direct-invoked. No orchestrator dispatches it; the user pastes the prompt path (or its content) and the agent executes.
• Records its own work. At end-of-run it authors an operation_record job born complete in 4_done/ (D-44, D-54) — a small, report-only, no-Git folder — so every action the workflow performs is tracked. It writes only its own record and never moves or edits another job's state.
• Claude-only in v1. app-init relies on Claude Code's AskUserQuestion facility for its questionnaire. Non-Claude runtimes (Codex / Aider / Cursor) use the documented manual port flow at _docs/how-to-port.md instead.

The fields

Its "inputs" are simply the host project at ../ that it inspects, plus the user's answers to its questionnaire. Its "outputs" are the two host-context files it writes (and, at end-of-run, its own tracked operation_record folder).

How to run it

app-init is an op-card: there is no intake to drop and no orchestrator to route it. Send the prompt path directly to a fresh Claude Code session (run it from inside _code_workflow/ — it requires workflow-internal mode for its one-time bootstrap).

_processes/00_app/app-init.prompt.md

See also