/setup

name: setup
description: >-
  Phase 0 of the prd-taskmaster pipeline. Resolves the active backend,
  initializes the project, configures the provider stack when the TaskMaster
  backend is active (DETECT-FIRST — never overwrite a working user config),
  and verifies the AI pipeline. Autonomous: zero user questions unless a hard
  block is hit. Declares the Setup phase complete so DISCOVER can follow.
user-invocable: false
allowed-tools:
  - Read
  - Bash
  - Skill
  - ToolSearch
  - mcp__atlas-engine
  - mcp__plugin_prd_go
  - mcp__plugin_prd-taskmaster_go
  - mcp__plugin_atlas-go_go

Phase 0: Setup

Declarative phase skill. Invoked by the prd-taskmaster orchestrator when `current_phase` is null or `SETUP`. Never called directly by a user.

Task provider routing comes first

Before the entry gate or init-project below, follow SKILL.md Phase 1 task ownership: `provider-configure --project-root ROOT --board BOARD` persists the new-project `atlas-kanban` default; `doctor --project-root ROOT` reports read-only diagnostics. With no persisted provider choice, any file under `.taskmaster/` stays taskmaster-file; empty folders and a bare `docs/prd.md` stay new. Provider metadata is outside `.taskmaster/`. For atlas-kanban, complete that setup branch and return the actual config and doctor diagnostics to the orchestrator. It routes Discovery next, then the plan/materialize and canonical handoff branches. Do not initialise `.taskmaster`, run the legacy pipeline gates below, or fabricate validate_setup evidence for canonical cards. All remaining steps on this page apply only to taskmaster-file.

Entry gate

1. Call `mcp__plugin_prd_go__check_gate(phase="SETUP", evidence={})` for diagnostics.

`check_gate` is an EXIT gate: it verifies you have the evidence to *advance*, not to *enter*. On first entry you have no evidence yet (Step 4 below produces `validate_setup.ready=true`), so a `gate_passed: false` result here is EXPECTED — the state machine's legal transitions (`None → SETUP`) already guarantee only legal entry.

• **First entry** (no evidence yet): note the result and continue with the Procedure.
• **Re-entry**: if the gate reports violations, report them and stop — it protects

against re-running a completed phase or skipping ahead.

Enforce the gate when you ADVANCE (after the procedure), not on entry.

Procedure (5 steps, abort on hard failure)

Step 1: Backend detection

Run backend detection:

python3 script.py backend-detect

The native engine is the sole generator and needs no external binary — a keyless host CLI (`claude` / `codex` / `gemini`) on PATH, or a provider API key, is sufficient (see Chunk 7's `atlas setup` wizard). The `task-master` binary is no longer required or supported; `backend-detect` reports its presence purely as informational. Continue with the resolved (native) backend.

Step 2: Project init

Check whether the current project has a `.taskmaster/` directory (the engine still reads/writes the `.taskmaster/` file format for tasks and config).

If missing, run backend op `init`:

python3 script.py init-project

This initialises the native project state and the `.taskmaster/` file format. If `.taskmaster/` is present, continue.

Step 2.5: Customisation bootstrap (REQUIRED — closes execute-task deadlock)

`execute-task` requires `.atlas-ai/customizations/system-prompt-template.md` to exist as a precondition (its Entry gate halts otherwise). It cannot create the file from inside the loop — the failure mode is a hard halt with no recovery path.

This step ensures the file exists BEFORE execute-task ever runs:

PLUGIN_SKEL="${CLAUDE_PLUGIN_ROOT}/skel/customizations"
mkdir -p .atlas-ai/customizations
if [ ! -f .atlas-ai/customizations/system-prompt-template.md ]; then
  if [ -d "$PLUGIN_SKEL" ]; then
    cp -n "$PLUGIN_SKEL"/*.md .atlas-ai/customizations/  # -n: no-clobber, copy starter pack
  else
    : > .atlas-ai/customizations/system-prompt-template.md  # empty is fine per execute-task Entry gate
  fi
fi

The starter pack (`domain-vocabulary.md`, `system-prompt-template.md`, `task-enrichment-rules.md`, `verification-preferences.md`) is editable — users tune them to project-specific terminology. Empty is acceptable; the file simply must exist.

Also scaffold `.atlas-ai/ship-check.py` if it doesn't already exist:

if [ ! -f .atlas-ai/ship-check.py ] && [ -f "${CLAUDE_PLUGIN_ROOT}/skel/ship-check.py" ]; then
  cp "${CLAUDE_PLUGIN_ROOT}/skel/ship-check.py" .atlas-ai/ship-check.py
  chmod +x .atlas-ai/ship-check.py
fi

(Codified 2026-06-04 — yesterday's run halted at execute-task Entry because `system-prompt-template.md` was missing; the file had to be manually `touch`-ed from outside the loop.)

Step 3: Provider configuration — DETECT-FIRST

When the TaskMaster backend is active, **read `task-master models` output BEFORE setting anything.** This is the load-bearing rule. A working user config must NOT be overwritten silently. When the native backend is active, provider configuration is handled by the resolved backend and this TaskMaster-specific step is informational only.

| `task-master models` output | Action | |---|---| | Main / Research / Fallback all populated with a supported provider | SKIP — go to Step 4. | | Main set, Research/Fallback empty | Partial mutate — fill the empty roles only. | | All three empty (fresh install) | Full configure — use the default stack below. | | Provider flagged unsupported / deprecated | Ask the user before mutating. |

**Why DETECT-FIRST:** v4 dogfood (2026-04-13, LEARNING #9) caught the skill overwriting a working `gemini-cli / gemini-3-pro-preview` config because the procedure wasn't branch-aware. Detect first, mutate only the empty slots.

**Default stack (fresh install only):**

task-master models --set-main gemini-3-pro-preview --gemini-cli
task-master models --set-research gemini-3-pro-preview --gemini-cli
task-mas