delivery-flow

What this skill does

# Delivery Flow Orchestrator

## Design Principle

This skill is the ORCHESTRATOR. It coordinates the delivery team through a structured
pipeline but NEVER produces domain artifacts directly. All domain work — requirements,
designs, architecture, code, tests, plans — is delegated to worker skills operating as
sub-agents with isolated context. Full doctrine elaboration, Core Principles 1–7,
Anti-Patterns catalogue, and Guardrails detail: see
`delivery-team/references/shared/orchestrator-doctrine.md`.

> **Model awareness (Opus 4.7 / F-08):** Under F-08, the 4.7 runtime dispatches fewer
> sub-agents by default unless explicitly steered. "One Role = One Sub-Agent" (Phase 4)
> is a **behaviourally load-bearing** gate, not a style preference. Role-count
> under-dispatch is the highest-confidence regression mode on 4.7.

---

## Phase 0: Setup Wizard

Before the pipeline executes, check for project configuration:

### State Detection (Resume Check)

Before checking config, check for an existing pipeline state:

1. **Check for `.delivery/state.md`** in the current working directory.
2. **If state exists with `status: in_progress`**:
   - Read the YAML frontmatter to load pipeline state.
   - Announce: `> Existing pipeline found: [pipeline_id], started [date], last completed Stage [N] ([name]). Currently at Stage [N+1].`
   - **Validate**: verify all artifact files in the `artifacts` map exist on disk. If any are missing, announce which and offer: Restart from that stage / Abandon.
   - **Semantic validation**: current_stage in range 1-7, not in stages_completed, no gaps in completed+skipped.
   - **Config divergence check**: diff `config_snapshot` against current `.delivery/config.yml`. If different, warn: "Config has changed since this pipeline started. Resume uses the original config. Choose Restart to apply new config."
   - Offer the user: **Resume** / **Restart** / **Abandon**
   - Resume: load config from snapshot, skip completed stages, start at current_stage.
   - Restart: move state file to `.delivery/state-archive/state-<timestamp>.md` (cap at 5, delete oldest), start fresh.
   - Abandon: delete state file, no pipeline runs.
3. **If state exists with `status: aborted`**:
   - Announce: `> Aborted pipeline found from [date], stopped at Stage [N]. Artifacts from stages [list] are preserved.`
   - Offer: Resume / Restart / Abandon (same as above).
4. **If state exists with `status: completed`**: ignore (previous run finished normally).
5. **If no state file exists**: proceed to config check (normal flow).

1. **Check for `.delivery/config.yml`** in the current working directory.
   If `.delivery/config.yml` is not found, also check for `.delivery/config.md` (legacy format). If found, read it and announce: "Legacy config.md found. Run setup to migrate to config.yml."
2. **If config exists and is fresh** (< 30 days old):
   - Read the YAML configuration to load all project settings.
   - **Version check**: Compare `config_version` to the current schema version in
     `references/config-schema.md`. If the config is older (or has no `config_version`),
     apply defaults for any missing keys from the schema and announce:
     `> Config upgraded from v[old] to v[current]. New settings applied with defaults: [list]`
     Offer the user `setup` to configure new settings interactively.
   - **v2.6 → v2.7 migration rule**: When loading a v2.6 config (or any config that
     contains a top-level `project_type` key regardless of version), strip the
     `project_type` key in-memory and treat `config_version` as `2.7` for this run.
     Announce: `> Migrated config v2.6 → v2.7: removed project_type key (now detected per run).`
     The orchestrator applies this in-memory only — it does NOT auto-write over the
     user's `.delivery/config.yml`. Recommend the user re-run `setup` to persist the
     normalized v2.7 shape cleanly.
   - Announce: `> Config loaded from .delivery/config.yml (v[version], created [date])`
   - Apply settings: project type, tech stack, checkpoints, collaboration patterns, DoD validators, iteration limits, compliance requirements, persona config, alias theme.
   - **Read `prose_style`** (top-level; default `caveman-lite`; valid `caveman-lite | standard`); cache on loaded-config; consumed at Phase 4 Step 4 (conditional PROSE STYLE block) and Step 7 (DoD validator framing). See ADR-tk3-001.
   - **Load alias theme**: Read `aliases.theme` from config (default: `business`). If the
     value is not `business` (which uses default professional names and has no personality
     injection), load the theme file:
     1. Check `references/aliases/{theme}.yml` (built-in themes).
     2. If not found, check `{aliases.custom_path}/{theme}.yml` (custom themes, default path: `.delivery/aliases/`).
     3. If neither exists, warn: `> Alias theme '{theme}' not found. Falling back to business (no personality injection).` and set theme to `business`.
     4. If found, parse the YAML and store the `roles` mapping and `personality_strength` for use in Phase 4 Step 4. Announce: `> Alias theme loaded: {display_name} ({personality_strength} personality)`
   - For any key missing from the config, use the default from `references/config-schema.md`.
   - **Phase 1 (type detection) ALWAYS runs** from the current user request. Config no
     longer pins the project type. If the loaded config contains a bare legacy
     `project_type` key (v2.6 or earlier), tolerantly parse and **warn-and-drop**
     it: log a deprecation banner (`> Deprecated: bare project_type is ignored in
     v2.7. Use routing.force_type if you need an intentional pin.`) and continue.
     If `routing.force_type` is set in config, Phase 1 detection still runs and is
     logged, but routing uses the pin and a banner announces the override.
   - Proceed to Phase 1 (always) then Phase 2 (Memory Retrieval).

3. **If config exists but is stale** (> 30 days old):
   - Announce: `> Existing config found from [date] — it may be outdated.`
   - Offer options: Use as-is, Re-run wizard to update, Proceed with defaults.

4. **If no config exists**:
   - **STOP. Do NOT proceed to Phase 1.** The setup wizard MUST run before the pipeline can execute.
   - Run the setup wizard. Reference `references/setup-wizard.md` for the full protocol.
   - The wizard has 4 phases:
     - **Scan**: Auto-detect project state (languages, frameworks, CI/CD, git history, existing `.delivery/`)
     - **Present & Ask**: For each configuration topic, show what was detected and present 3-5 smart options. Each question supports single-select or multi-select as appropriate, plus Custom, Let's discuss, and Skip.
     - **Generate Config**: Write `.delivery/config.yml` as a pure YAML configuration file.
     - **Initialize Directory**: Create `.delivery/artifacts/`, `.delivery/memory/`, `.delivery/README.md`.
     - **Install Enforcement Hook**: If `enforcement.source_code_hook` is true (default), install a PreToolUse hook in the project's `.claude/settings.json` that warns when source code is edited outside an active delivery pipeline. See `references/setup-wizard.md` for the hook definition and installation process.
   - After the wizard completes, `.delivery/config.yml` MUST exist before proceeding.
   - If the user wants to skip the wizard entirely, they must explicitly say "skip setup" or "use defaults" — in which case, generate a minimal `.delivery/config.yml` with auto-detected defaults and proceed. The pipeline NEVER runs without a config file.

5. **User can re-run the wizard at any time** with the `setup` command.

### Quick-Start Mode

If the user says "quick start", "quick setup", or "just get started", run a 2-question wizard instead of the full 9+ question version:

1. **What language/framework?** — auto-detect from codebase, user confirms
2. **How strict?** — Prototype (minimal) / Standard (balanced) / Strict (full)

> **Note**: Project type is detected per run in Phase 1, not configured. Use `routing.force_type` if