feat(skill): MCP-first backend resolution (Phase 0) + dual op tables

The skill never used the engine's MCP server in real sessions: MCP tool
schemas are deferred in Claude Code (need a ToolSearch load before they
are callable), the SKILL.md allowed-tools gate excluded both ToolSearch
and the mcp__* tools, and every instruction site hardcoded script.py.
The model checked "is engine_preflight available?", saw nothing
callable, and silently took the CLI fallback every run.

- SKILL.md: new mandatory "Phase 0: Engine Backend Resolution" — load
  the engine tools via ToolSearch (select by id, keyword fallback),
  announce MCP-mode vs CLI-mode, and forbid script.py for MCP-covered
  ops while in MCP-mode; allowed-tools now include ToolSearch +
  mcp__atlas-engine + both plugin-scoped server ids
- SKILL.md: "Script Commands Reference" + "Backend operations" merged
  into one normative dual-column "Engine operations" table (op -> MCP
  tool -> script.py), plus an explicit script/agent-only table
- phases/GENERATE.md, phases/HANDOFF.md: MCP-mode route above every
  CLI call site, with verified tool parameter names (load_template,
  validate_prd, calc_tasks, parse_prd, tm_parallel_expand,
  detect_capabilities, next_task, set_task_status)
- install.sh: /atlas alias skill heredoc gets the same allowed-tools
  superset and a do-not-skip-Phase-0 instruction
- skills/*/SKILL.md (9 bundled plugin skills): same allowed-tools
  additions; go orchestrator gets the deferred-tools ToolSearch note

CLI-mode stays first-class for codex/gemini and zero-dependency
installs; script.py behavior is unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: claude

SKILL.md

@@ -15,11 +15,16 @@ allowed-tools:
   - Skill
   - AskUserQuestion
   - WebSearch
+  - ToolSearch
+  - mcp__atlas-engine
+  - mcp__plugin_prd-taskmaster_go
+  - mcp__plugin_atlas-go_go
 ---
 
 # prd-taskmaster — the Atlas engine
 
-Zero-config goal-to-tasks engine. AI handles discovery and content; `script.py` handles mechanics.
+Zero-config goal-to-tasks engine. AI handles discovery and content; the engine backend (MCP
+server preferred, `script.py` fallback — see Phase 0) handles mechanics.
 
 **Command:** `/atlas` is the canonical invocation (or `/prd-taskmaster`, or just say "I want to
 build …"). The full plugin install also exposes phase skills; this standalone skill runs the whole
@@ -38,17 +43,55 @@ CLI/MCP parsing.
 Activate: PRD, product requirements, taskmaster, task-driven development, "I want to build X", any goal.
 Skip: API docs, test specs, project timelines, PDF creation.
 
+## Phase 0: Engine Backend Resolution (MANDATORY — before any other engine operation)
+
+The engine has two interchangeable backends: the **atlas-engine MCP server** (preferred)
+and **script.py** (zero-dependency fallback). Resolve which one this session uses NOW.
+Do NOT silently default to script.py.
+
+**Claude Code note — deferred tools:** MCP tools are often *deferred*: their names appear
+in a system-reminder list but they are NOT callable until you load their schemas with the
+`ToolSearch` tool. "I don't see a callable engine_preflight tool" does NOT mean the server
+is absent — it almost always means you have not run ToolSearch yet.
+
+Resolution procedure, in order:
+
+1. If a `ToolSearch` tool exists in your session:
+   a. `ToolSearch(query="select:mcp__atlas-engine__engine_preflight")`
+   b. If no match: `ToolSearch(query="+engine preflight atlas", max_results=10)` — this
+      also catches plugin-scoped ids such as `mcp__plugin_prd-taskmaster_go__engine_preflight`.
+   c. If a schema loads → **MCP-mode = ON**. Record the prefix (e.g. `mcp__atlas-engine__`).
+      If both user-scope and plugin-scope match, prefer `mcp__atlas-engine__`.
+2. No ToolSearch, but an `engine_preflight` MCP tool is already directly callable →
+   **MCP-mode = ON** with that prefix.
+3. Otherwise → **MCP-mode = OFF** (CLI-mode).
+
+Announce the result before Phase 1, exactly one line:
+`Engine backend: MCP (<prefix>*)` or `Engine backend: script.py (CLI fallback)`.
+
+Hard rules for the rest of the run:
+
+- **MCP-mode ON:** every operation in the "Engine operations" table below MUST use its MCP
+  tool. Running `python3 script.py <cmd>` for an op that has an MCP tool in this session's
+  prefix is a compliance failure — the only exceptions are ops in the "Script/agent-only"
+  table and ops whose tool is missing from the resolved prefix (some plugin installs expose
+  fewer tools — fall back to script.py for just those ops).
+- **MCP-mode OFF:** use the script.py commands exactly as documented below. Other harnesses
+  (codex, gemini) have no ToolSearch and may have no MCP server — CLI-mode is fully
+  supported and not a degraded experience.
+- If an MCP call errors mid-run (server died/disconnected), say so explicitly, flip to
+  CLI-mode, and continue.
+
 ## Phase 1: Zero-Config Preflight
 
 Run preflight and auto-detect everything. Ask zero setup questions.
 
-**MCP (preferred — ONE batched call, no script spam):** if an `engine_preflight`
-MCP tool is available in your session (plugin install, or the engine's MCP server
-registered), call it once — it covers preflight + taskmaster detection + provider
+**MCP-mode (from Phase 0 — ONE batched call, no script spam):** call
+`<prefix>engine_preflight` once — it covers preflight + taskmaster detection + provider
 configuration + capabilities and returns a `summary` list to present verbatim.
-Skip the individual script calls below entirely.
+Skip every individual script call below entirely.
 
-**CLI fallback (zero-dependency installs):** one batched subcommand, same result:
+**CLI-mode (zero-dependency installs):** one batched subcommand, same result:
 
 ```bash
 python3 ~/.claude/skills/prd-taskmaster/script.py engine-preflight
@@ -163,50 +206,59 @@ always fully usable on its own.
 
 ## Feedback
 
-At debrief time, every executing agent records how the run went. Prefer the MCP
-`feedback_submit` tool; fallback is `python3 script.py feedback-add --rating <1-5>
+At debrief time, every executing agent records how the run went. MCP-mode:
+`<prefix>feedback_submit` / `<prefix>feedback_report`. CLI-mode:
+`python3 script.py feedback-add --rating <1-5>
 --agent <name> --harness <claude-code|codex|gemini|api|other> --task-ref <id>
 --well <text> --failed <text> --suggest <text>`. Feedback is stored in
 `.atlas-ai/feedback.jsonl`; summarize it with `python3 script.py feedback-report`.
 
-## Script Commands Reference
+## Engine operations
+
+This table is normative — instruction sites reference operations by name. In MCP-mode use
+the MCP tool (substitute the Phase-0 prefix); in CLI-mode use the script.py command.
+
+| Operation | MCP tool (MCP-mode) | script.py (CLI-mode / fallback) |
+|-----------|---------------------|---------------------------------|
+| `engine-preflight` | `engine_preflight` | `engine-preflight` |
+| `preflight` | `preflight` | `preflight` |
+| `detect-taskmaster` | `detect_taskmaster` | `detect-taskmaster` |
+| `backend-detect` | `backend_detect` | `backend-detect` |
+| `init` | `init_project` | `init-project` |
+| `init-taskmaster` | `init_taskmaster` | `init-taskmaster` |
+| `validate-setup` | `validate_setup` | (covered by `engine-preflight`) |
+| `detect-capabilities` | `detect_capabilities` | `detect-capabilities` |
+| `load-template` | `load_template` | `load-template --type comprehensive\|minimal` |
+| `calc-tasks` | `calc_tasks` | `calc-tasks --requirements <count> [--scale solo\|team\|enterprise]` |
+| `validate-prd` | `validate_prd` | `validate-prd --input <path>` |
+| `backup-prd` | `backup_prd` | `backup-prd --input <path>` |
+| `parse-prd` | `parse_prd` | `parse-prd --input <path> --num-tasks N [--tag]` |
+| `rate` | `rate_tasks` | `rate [--tag] [--no-research]` |
+| `expand` | `expand_tasks` | `expand [--id N ...] [--no-research] [--tag]` |
+| `tm-parallel` | `tm_parallel_expand` | `tm-parallel` |
+| `next` | `next_task` | `next-task [--tag]` |
+| `set-status` | `set_task_status` | `set-status --id <id> --status <status> [--tag]` |
+| `fleet-waves` | `compute_fleet_waves` | `fleet-waves` |
+| `feedback-add` | `feedback_submit` | `feedback-add --rating <1-5> ...` |
+| `feedback-report` | `feedback_report` | `feedback-report` |
+
+Backend behavior is identical through either interface: the `taskmaster` backend wraps native
+TaskMaster operations safely (init/parse/rate/expand, including `tm-parallel`); the `native`
+backend uses direct API calls or returns `agent_action_required`; `next`/`set-status` are
+engine-native under every backend.
+
+## Script/agent-only operations (no MCP tool — always script.py, any mode)
 
 | Command | Purpose |
 |---------|---------|
-| `engine-preflight` | ONE batched call: preflight + taskmaster + providers + capabilities + summary |
-| `preflight` | Detect environment state |
-| `detect-taskmaster` | Find MCP or CLI taskmaster |
-| `backend-detect` | Detect resolved backend, both backend capabilities, and ai_ops |
-| `init-project` | Initialise the resolved backend project state |
-| `parse-prd --input <path> --num-tasks N [--tag]` | Parse a PRD through the resolved backend |
-| `expand [--id N ...] [--no-research] [--tag]` | Expand selected or all pending tasks through the resolved backend |
-| `rate [--tag] [--no-research]` | Rate task complexity through the resolved backend |
-| `init-taskmaster` | task-master init with `.mcp.json` protection |
 | `configure-providers` | Configure native Claude/Codex + local Perplexity API Free defaults |
 | `detect-providers` | Auto-detect AI providers |
-| `detect-capabilities` | Scan for available skills/tools; returns tier + recommended mode with reason |
-| `load-template --type comprehensive\|minimal` | Load PRD template |
-| `calc-tasks --requirements <count> [--scale solo\|team\|enterprise]` | Recommended task count (scale-banded) |
-| `validate-prd --input <path>` | Quality checks + placeholder detection |
-| `backup-prd --input <path>` | Timestamped backup |
-| `validate-tasks [--input <path>]` | Validate manually-authored tasks.json |
+| `validate-tasks [--input <path>] [--require-phase-config]` | Validate manually-authored tasks.json |
 | `enrich-tasks` | Add phaseConfig metadata to tasks |
 | `parallel-plan [--missing-only]` | Emit per-task research packets for parallel subagents |
 | `parallel-apply --input <results.json>` | Merge parallel research results atomically |
 | `parallel-extract --output <path>` / `parallel-inject --input <path>` | Tagged ⇄ flat tasks bridge |
-
-## Backend operations
-
-This table is normative — instruction sites reference operations by name.
-
-| Operation | Command (both backends) | Notes |
-|-----------|--------------------------|-------|
-| `init` | `script.py init-project` | `taskmaster` backend wraps native TaskMaster initialization safely; `native` backend uses direct API initialization or returns `agent_action_required`. |
-| `parse-prd` | `script.py parse-prd --input <path> --num-tasks N [--tag]` | `taskmaster` backend wraps native TaskMaster PRD parsing; `native` backend uses direct API parsing or returns `agent_action_required`. |
-| `rate` | `script.py rate [--tag] [--no-research]` | `taskmaster` backend wraps native TaskMaster complexity/rating; `native` backend uses direct API rating or returns `agent_action_required`. |
-| `expand` | `script.py expand [--id N ...] [--no-research] [--tag]` | `taskmaster` backend wraps native TaskMaster expansion, including `tm-parallel` for expand; `native` backend uses direct API expansion or returns `agent_action_required`. |
-| `next` | `script.py next-task [--tag]` | Engine-native under every backend; next/set-status are engine-native under every backend. |
-| `set-status` | `script.py set-status --id <id> --status <status> [--tag]` | Engine-native under every backend; next/set-status are engine-native under every backend. |
+| `economy-report` | Summarize telemetry per (op_class, model) |
 
 ## Parallel Research & Complexity
 
@@ -290,3 +342,4 @@ All commands default `--tag` to `.taskmaster/state.json` currentTag and run from
 7. Phase files must be Read explicitly — they are not auto-loaded
 8. Native/free provider defaults are enforced by `configure-providers`; do not drift back to paid Anthropic/Perplexity APIs unless native/free routes are unavailable
 9. Perplexity API Free research must be normalized through `parallel-apply`; native TaskMaster research is only acceptable when it returns valid structured output and validation passes
+10. Phase 0 backend resolution is mandatory — in MCP-mode, script.py is forbidden for any op that has an MCP tool in the resolved prefix

install.sh

@@ -370,8 +370,18 @@ description: >-
   invokes /atlas, says "I want to build", or asks for a PRD / task-driven build.
 allowed-tools:
   - Read
-  - Skill
+  - Write
+  - Edit
+  - Grep
+  - Glob
   - Bash
+  - Skill
+  - AskUserQuestion
+  - WebSearch
+  - ToolSearch
+  - mcp__atlas-engine
+  - mcp__plugin_prd-taskmaster_go
+  - mcp__plugin_atlas-go_go
 ---
 
 # /atlas — the Atlas engine
@@ -382,8 +392,9 @@ This is a thin alias. Immediately Read and follow the full engine skill:
 Read ${SKILL_DIR}/SKILL.md
 \`\`\`
 
-Then execute that skill's pipeline (Preflight -> Discovery -> Generate -> Handoff)
-exactly as written, carrying over whatever goal or arguments the user provided.
+Then execute that skill's pipeline (Backend Resolution -> Preflight -> Discovery ->
+Generate -> Handoff) exactly as written, carrying over whatever goal or arguments the
+user provided. Do not skip the skill's Phase 0 (engine backend resolution via ToolSearch).
 ALIASEOF
     ok "Installed /atlas alias skill -> ${ALIAS_DIR}"
 

phases/GENERATE.md

@@ -1,13 +1,15 @@
 # Phase: Generate & Validate — Spec Creation and Task Parsing
 
-## Tool preference (applies to every step below)
+## Backend mode (applies to every step below)
 
-The engine's deterministic operations are available as MCP tools when ANY engine
-server is registered — tool ids look like `mcp__atlas-engine__<name>` (user-scoped
-server) or `mcp__plugin_prd-taskmaster_go__<name>` (plugin install). **Always
-prefer the MCP tool over the script.py equivalent** (same names: load_template,
-validate_prd, calc_tasks, engine_preflight, compute_fleet_waves, ...). The
-script.py commands below are the zero-dependency fallback only.
+Backend mode was resolved in SKILL.md Phase 0. If you have NOT resolved it (e.g. this
+phase file was entered directly), run the Phase 0 procedure now — in Claude Code that
+means `ToolSearch(query="select:mcp__atlas-engine__engine_preflight")` (keyword fallback
+`ToolSearch(query="+engine preflight atlas", max_results=10)`) BEFORE any bash. Tool ids
+look like `mcp__atlas-engine__<name>` (user-scoped server) or
+`mcp__plugin_prd-taskmaster_go__<name>` (plugin install). **In MCP-mode, using script.py
+for an MCP-covered op is a compliance failure.** The script.py commands below are the
+CLI-mode path (zero-dependency installs, codex/gemini harnesses).
 
 
 ## The One Rule
@@ -36,6 +38,8 @@ Decide based on discovery depth:
 - **Comprehensive**: 4+ detailed answers, complex project
 - **Minimal**: Quick project, thin answers, user wants speed
 
+**MCP-mode**: `<prefix>load_template(type="comprehensive")`
+**CLI-mode**:
 ```bash
 python3 ~/.claude/skills/prd-taskmaster/script.py load-template --type comprehensive
 ```
@@ -74,6 +78,8 @@ Key rule: Every `[placeholder]`, `{{variable}}`, `[TBD]`, `[TODO]` must be repla
 
 ## Step 3: Validate Spec Quality
 
+**MCP-mode**: `<prefix>validate_prd(input_path=".taskmaster/docs/prd.md")`
+**CLI-mode**:
 ```bash
 python3 ~/.claude/skills/prd-taskmaster/script.py validate-prd --input .taskmaster/docs/prd.md
 ```
@@ -89,13 +95,19 @@ Returns: `score`, `grade`, `checks`, `warnings`, `placeholders_found`.
 ## Step 4: Parse Tasks via Backend
 
 Calculate task count:
+
+**MCP-mode**: `<prefix>calc_tasks(requirements_count=<count>)`
+**CLI-mode**:
 ```bash
 python3 ~/.claude/skills/prd-taskmaster/script.py calc-tasks --requirements <count>
 ```
 
 Parse through the normative backend operation:
 
 **backend op parse-prd**:
+
+**MCP-mode**: `<prefix>parse_prd(prd_path=".taskmaster/docs/prd.md", num_tasks=<recommended>)`
+**CLI-mode**:
 ```bash
 python3 ~/.claude/skills/prd-taskmaster/script.py parse-prd --input .taskmaster/docs/prd.md --num-tasks <recommended>
 ```
@@ -186,6 +198,9 @@ free local proxy / no API key /
                                      parallel-plan → N research subagents → parallel-apply
 ```
 
+In MCP-mode, the NATIVE-PARALLEL path is `<prefix>tm_parallel_expand` (instead of
+`script.py tm-parallel`) and serial expansion uses `<prefix>rate_tasks` / `<prefix>expand_tasks`.
+
 This keeps TaskMaster's model-agnostic AI (any configured API does the expansion/research) while
 parallelizing it externally. Never run multiple `expand --id` concurrently in ONE directory — the
 10s lock-stale window vs 30–120s AI calls is a real race; isolation dirs (tm-parallel) exist for

phases/HANDOFF.md

@@ -20,6 +20,8 @@ HANDOFF CHECKLIST:
 
 ## Step 1: Detect Capabilities
 
+**MCP-mode** (from SKILL.md Phase 0): `<prefix>detect_capabilities()`
+**CLI-mode**:
 ```bash
 python3 ~/.claude/skills/prd-taskmaster/script.py detect-capabilities
 ```
@@ -107,11 +109,12 @@ Read the project's `./CLAUDE.md`. Append the TaskMaster workflow section if norm
 ```markdown
 ## Task Execution Workflow (prd-taskmaster)
 
-When implementing tasks, use backend operations:
-1. `script.py next-task` -- get next dependency-ready task
-2. `script.py set-status --id <id> --status in-progress` -- mark started
+When implementing tasks, use backend operations (MCP tool when the engine MCP server is
+available — e.g. `mcp__atlas-engine__next_task` — otherwise script.py):
+1. `next` op — MCP `next_task` or `script.py next-task` -- get next dependency-ready task
+2. `set-status` op — MCP `set_task_status(id, status="in-progress")` or `script.py set-status --id <id> --status in-progress` -- mark started
 3. Implement the task (follow the plan step linked to this task)
-4. `script.py set-status --id <id> --status done` -- mark complete
+4. `set-status` op — MCP `set_task_status(id, status="done")` or `script.py set-status --id <id> --status done` -- mark complete
 5. Update TodoWrite with progress
 6. Repeat from step 1
 

skills/customise-workflow/SKILL.md

@@ -17,6 +17,10 @@ allowed-tools:
   - Edit
   - Bash
   - AskUserQuestion
+  - ToolSearch
+  - mcp__atlas-engine
+  - mcp__plugin_prd-taskmaster_go
+  - mcp__plugin_atlas-go_go
 ---
 
 # customise-workflow

skills/discover/SKILL.md

@@ -13,6 +13,10 @@ allowed-tools:
   - Skill
   - AskUserQuestion
   - Write
+  - ToolSearch
+  - mcp__atlas-engine
+  - mcp__plugin_prd-taskmaster_go
+  - mcp__plugin_atlas-go_go
 ---
 
 # Phase 1: Discover

skills/execute-fleet/SKILL.md

@@ -10,6 +10,10 @@ allowed-tools:
   - Read
   - Bash
   - Skill
+  - ToolSearch
+  - mcp__atlas-engine
+  - mcp__plugin_prd-taskmaster_go
+  - mcp__plugin_atlas-go_go
 ---
 
 # execute-fleet

skills/execute-task/SKILL.md

@@ -17,6 +17,10 @@ allowed-tools:
   - Bash
   - Skill
   - Agent
+  - ToolSearch
+  - mcp__atlas-engine
+  - mcp__plugin_prd-taskmaster_go
+  - mcp__plugin_atlas-go_go
 ---
 
 # execute-task

skills/expand-tasks/SKILL.md

@@ -17,6 +17,10 @@ allowed-tools:
   - Glob
   - Grep
   - AskUserQuestion
+  - ToolSearch
+  - mcp__atlas-engine
+  - mcp__plugin_prd-taskmaster_go
+  - mcp__plugin_atlas-go_go
 ---
 
 # Expand Tasks with Research v1.0

skills/generate/SKILL.md

@@ -14,6 +14,10 @@ allowed-tools:
   - Edit
   - Bash
   - Skill
+  - ToolSearch
+  - mcp__atlas-engine
+  - mcp__plugin_prd-taskmaster_go
+  - mcp__plugin_atlas-go_go
 ---
 
 # Phase 2: Generate