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: Driver-authored generation still honours the selected task provider. For atlas-kanban, write candidates and run plan, then materialize, as described below. Only in taskmaster-file mode perform the legacy TaskMaster mechanics yourself: write .taskmaster/docs/prd.md and .taskmaster/tasks/tasks.json, validate and enrich.

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: Task ownership, before legacy initialisation

Task storage is independent of the optional generation backend. Resolve it BEFORE init-project, engine-preflight, or any legacy task-state command:

• Existing .atlas-workflow.json: honour task_provider exactly.
• No config, but any file under .taskmaster/ already exists: taskmaster-file, with a Legacy notice. Empty Taskmaster folders and a bare docs/prd.md stay new. Provider metadata (.atlas-workflow.json, .atlas-ai/plan.json and .atlas-ai/materializations.json) lives outside .taskmaster/ and does not count. Never silently migrate it. import-preview --project-root "$PROJECT_ROOT" --project "$ATLAS_PROJECT" is read-only and marks history as not fresh verification. Changing provider is an explicit owner decision.
• Otherwise: atlas-kanban, the default in-house path, with no Taskmaster runtime, API key, .taskmaster initialisation or second task store required.

Use explicit absolute PROJECT_ROOT and ATLAS_SCRIPT paths, PYTHON (normally python3), a stable ATLAS_PROJECT name and an authorised ATLAS_BOARD on this host. Do not invent a board or fall back to file mode if the owner is unavailable. A remote owner_host is refused; run on that owner host instead.

For the new-project default (or an existing atlas-kanban config), persist the selection. The omitted --task-provider honours existing configs rather than switching them:

"$PYTHON" "$ATLAS_SCRIPT" provider-configure --project-root "$PROJECT_ROOT" --board "$ATLAS_BOARD"

Read the returned config. For atlas-kanban, run doctor --project-root "$PROJECT_ROOT" (MCP: doctor(project_root=...)) and report the diagnostics. Before the first materialisation, reachability is UNKNOWN and exit 1 is expected because there is no canonical task reference yet; help advertises syntax only. Continue Discovery, then the atlas-kanban branch of phases/GENERATE.md, then the atlas-kanban branch of phases/HANDOFF.md. Do NOT run the legacy initialisation, parse/expand, enrichment, task-state or per-task dry-run verification paths below. The manual flag selects driver-authored planning, not a different task provider.

Legacy taskmaster-file preflight only

The remainder of this phase and Native Mode below apply ONLY to taskmaster-file. 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:

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

From preflight JSON, determine the state:

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:

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-codex when codex exists.
2. Fallback: codex-cli / gpt-5.2-codex when available; otherwise claude-code / sonnet.
3. Research: local Perplexity API Free through TaskMaster openai-compatible provider:
   • model: sonar
   • baseURL: http://127.0.0.1:8765
   • .env key: OPENAI_COMPATIBLE_API_KEY="local-perplexity-api-free" (dummy local key only)

Do not require ANTHROPIC_API_KEY or paid PERPLEXITY_API_KEY when native Claude/Codex and Perplexity API Free are available.

Phase 2: Discovery

Read the phase file and follow it:

Read ~/.claude/skills/prd-taskmaster/phases/DISCOVER.md

Progressive, adaptive, domain-agnostic discovery via superpowers:brainstorming.

Gate: Discovery complete and user approved design. Proceed to Generate.

Phase 3: Generate & Validate

Read the phase file and follow it:

Read ~/.claude/skills/prd-taskmaster/phases/GENERATE.md

Generate and validate the spec for both providers. For atlas-kanban, hash a storage-independent plan, materialise through the owner and read canonical IDs back. For taskmaster-file only, parse tasks and enrich them with metadata.

Gate, conditional on the persisted provider:

• atlas-kanban: approved/validated spec, hashed plan, successful whole-plan materialisation and canonical IDs read back. A partial is not completion. Proceed to canonical Handoff.
• taskmaster-file: PRD validated GOOD+ and tasks created through TaskMaster parse/expand OR Native Mode. Proceed to file-mode Handoff.

Native Mode (TaskMaster optional, taskmaster-file only)

Formerly "Manual Mechanics Mode". Only for the persisted taskmaster-file provider, the engine produces the same validated task graph without TaskMaster. In that provider, use it when the user passes --manual, TaskMaster isn't installed, or its parsing/expansion is a poor fit. Absence of TaskMaster and the manual flag NEVER switch atlas-kanban to file mode; use driver-authored candidates and plan/materialize there.

1. Generate .taskmaster/docs/prd.md normally.
2. Manually write .taskmaster/tasks/tasks.json in TaskMaster-compatible shape:
   • top-level object with tasks: []
   • each task has id, title, description, details, testStrategy, status, dependencies, priority, and subtasks
   • every task has at least 2 subtasks with id, title, description, status, and dependencies
3. Run:

   python3 ~/.claude/skills/prd-taskmaster/script.py validate-tasks
   python3 ~/.claude/skills/prd-taskmaster/script.py enrich-tasks
   python3 ~/.claude/skills/prd-taskmaster/script.py validate-tasks --require-phase-config

4. Treat successful validation + enrichment + phaseConfig validation as equivalent to TaskMaster parse + expand.

Phase 4: Handoff

Read the phase file and follow it:

Read ~/.claude/skills/prd-taskmaster/phases/HANDOFF.md

For atlas-kanban, follow phases/HANDOFF.md: report canonical IDs/status, doctor diagnostics and hand acceptance to the parent for its separate reservation/external-session protocol. For taskmaster-file only, detect capabilities, recommend ONE execution mode, hand off. Modes (user-facing names): Verified Loop (recommended when superpowers + a loop runner are present), Auto-Execute (TaskMaster's native loop), Plan & Drive (plan only). Atlas Fleet — parallel multi-session execution — appears as an Atlas Pro option when a licensed atlas-launcher is detected; otherwise it shows as a locked teaser pointing to https://atlas-ai.au/pro. The free engine is always fully usable on its own.

Gate: atlas-kanban requires canonical IDs/status read back, doctor diagnostics reported and explicit parent handoff. For taskmaster-file only: user chose mode and handoff complete.

Feedback

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.

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.

Render the progress panel at each phase boundary (and on demand) via status / render_status — the boxed phase tracker, validation scorecard, ship-check gates, and execute progress.

Backend behavior is identical through either interface: the taskmaster backend wraps native TaskMaster operations safely (init/parse/rate/expand); 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)

Parallel Research & Complexity (taskmaster-file only)

For atlas-kanban, research informs candidates before hashing the plan; do not run these file-store expansion operations. The legacy decision tree below is taskmaster-file only.

Decision tree for expansion + research (token-economy aware):

Manual flag                        → Native Mode (unchanged)
pending tasks ≤ 3                  → TaskMasterBackend.expand internal: serial NATIVE
                                     rate --research, then expand per task (main dir)
task-master ≥ 0.43 AND research
  role is a REAL structured API    → TaskMasterBackend.expand internal: NATIVE-PARALLEL
  (sonar/anthropic/openai… key)      one serial analyze-complexity, then N isolated workdirs each running
                                     native `expand --id N --research` with an economy-tier model; ONE
                                     atomic harvest merge. Failed packets → agent-parallel rerun.
free local proxy / no API key /
  TM provider errors / TM < 0.43   → native/agent path: AGENT-PARALLEL (fallback):
                                     parallel-plan → N subagents → parallel-apply

Why isolation dirs: task-master 0.43+ uses proper-lockfile + atomic writes, but its 10s lock-stale window vs 30–120s AI calls makes concurrent invocations in ONE directory unsafe — N isolated project dirs sidestep the lock entirely and double as the per-attempt model mechanism (expand has no --model flag; each workdir carries its own config.json). The free local Perplexity proxy returns prose where TaskMaster needs strict JSON — that is why the proxy keeps the agent-normalized path while real APIs get the native path.

Pattern — the parallelism lives in the AGENT, not the script:

python3 ~/.claude/skills/prd-taskmaster/script.py parallel-plan --missing-only   # research packets JSON
# AGENT: split packets into N groups (by lane/domain), spawn N parallel research
#   subagents; each verifies files in-repo + researches APIs and returns
#   [{id, complexityScore, recommendedSubtasks, reasoning, researchNotes, subtasks[]}]
# AGENT: concatenate results -> results.json
python3 ~/.claude/skills/prd-taskmaster/script.py parallel-apply --input results.json   # ONE atomic write
#   + writes .taskmaster/reports/task-complexity-report[_<tag>].json (TaskMaster format)
#   + returns needs_more_subtasks (score >= threshold w/ too-few subtasks) for a second pass

If the perplexity-api-free MCP wrapper times out or says the proxy is unreachable, check direct proxy health:

curl -sS -X POST http://127.0.0.1:8765/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"sonar","messages":[{"role":"user","content":"Return exactly: ok"}],"max_tokens":16}'

If direct curl works, continue: use MCP, direct proxy calls, or agent research to produce the results.json schema, then normalize prose into valid JSON before parallel-apply. Do not block on native task-master analyze-complexity --research.

Tag bridge for explicit flat-file workflows (the script also reads tagged TaskMaster files directly):

python3 ~/.claude/skills/prd-taskmaster/script.py parallel-extract --output /tmp/flat.json
python3 ~/.claude/skills/prd-taskmaster/script.py validate-tasks --input /tmp/flat.json
python3 ~/.claude/skills/prd-taskmaster/script.py enrich-tasks  --input /tmp/flat.json
python3 ~/.claude/skills/prd-taskmaster/script.py validate-tasks --input /tmp/flat.json --require-phase-config
python3 ~/.claude/skills/prd-taskmaster/script.py parallel-inject --input /tmp/flat.json

All commands default --tag to .taskmaster/state.json currentTag and run from the project root.

Context

Standalone: Works on its own. Takes any goal, produces spec + tasks. Produces: atlas-kanban: .atlas-ai/prd.md, a hashed plan and canonical owner references, not a mutable local task store. taskmaster-file only: spec.md + tasks.json in .taskmaster/. Then: atlas-kanban hands canonical acceptance/IDs to the parent. taskmaster-file hands off to Verified Loop / Auto-Execute / Plan & Drive, or Atlas Fleet with Atlas Pro.

Critical Rules

1. Zero setup questions — detect everything, ask only discovery questions
2. Discovery via superpowers:brainstorming — one question at a time, adaptive
3. Domain-agnostic — works for any goal (app, pentest, business, anything)
4. Validate PRDs catch placeholders — mustache, TBD, TODO patterns fail validation
5. Manual flag means driver-authored generation, never skipping validation: atlas-kanban uses candidates + plan/materialize; taskmaster-file only does the TaskMaster mechanics manually.
6. Handoff recommends ONE mode — present best fit, not equal choices
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