prd-taskmaster

# prd-taskmaster — the Atlas engine

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
pipeline inline.

**Script:** `~/.claude/skills/prd-taskmaster/script.py` (all commands output JSON). It is a thin
shim over the bundled `prd_taskmaster/` package — the single source of truth shared with the plugin.

**Manual flag:** If the user says `--manual`, `manual=true`, or "do it manually", perform the
TaskMaster mechanics yourself: write `.taskmaster/docs/prd.md`, write `.taskmaster/tasks/tasks.json`
with tasks and subtasks, run `validate-tasks`, then run `enrich-tasks`. Do not block on TaskMaster
CLI/MCP parsing.

## When to Use

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_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-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 every individual script call below entirely.

**CLI-mode (zero-dependency installs):** one batched subcommand, same result:

```bash
python3 ~/.claude/skills/prd-taskmaster/script.py engine-preflight
```

**From preflight JSON, determine the state:**

| Condition | Action |
|-----------|--------|
| `prd_path` exists + `task_count > 0` | Ask: execute tasks / update PRD / new PRD / review |
| `backend.ai_ops == "agent"` | Backend resolves automatically; print ONE info line: add an API key or install `task-master-ai` for headless AI ops; proceed |
| manual flag present | Proceed using Native Mode (TaskMaster optional), regardless of TaskMaster CLI/MCP state |
| `has_taskmaster == false` + backend selected | Run `init-project` (below), then continue |
| `has_taskmaster` but no PRD | Proceed to Discovery |
| `has_crash_state` | Offer: resume from crash point or start fresh |

**Initialise the project if needed, then auto-configure providers** (silent). Use
`init-project` for the resolved backend. For the `taskmaster` backend, this preserves
an existing `.mcp.json`; raw `task-master init` overwrites it with a placeholder template.
Use `init-taskmaster` only when explicitly operating the `taskmaster` backend:

```bash
python3 ~/.claude/skills/prd-taskmaster/script.py init-project         # only when .taskmaster/ absent
python3 ~/.claude/skills/prd-taskmaster/script.py init-taskmaster      # taskmaster backend only
python3 ~/.claude/skills/prd-taskmaster/script.py configure-providers
python3 ~/.claude/skills/prd-taskmaster/script.py detect-providers
```

If `configure-providers` returns `recommended_action: "init_taskmaster"`, run
`init-project` first; if the backend is explicitly `taskmaster`, `init-taskmaster`
is also safe and preserves `.mcp.json`.

Report compact status:
```
  ✓ Backend: taskmaster-api|native-api|agent
  ✓ Detected: TaskMaster (MCP|CLI)
  ✓ Detected: Provider (Claude Code|Codex CLI|Anthropic API)
  ✓ Detected: Research (Perplexity API Free|Perplexity MCP|Perplexity API|fallback)
```

**Gate: backend resolved (always true). Report ai_ops capability. Proceed to Discovery.**

### Provider Defaults

Always prefer subscription/native providers before paid API keys:

1. Main: `claude-code` / `sonnet` when `claude` exists; otherwise `codex-cli` / `gpt-5.2-c