prd-taskmaster

prd-taskmaster — Atlas エンジン

設定不要の、目標をタスクに変換するエンジンです。発見とコンテンツの作成は AI が担い、エンジンのバックエンド（MCP サーバーを推奨、代替手段は script.py — Phase 0 を参照）が処理を行います。

コマンド： 正式な呼び出し方法は /atlas です（または /prd-taskmaster、あるいは「…を作りたい」と伝えるだけでもかまいません）。プラグインを完全にインストールすると、各フェーズのスキルも利用できます。このスタンドアロンのスキルは、パイプライン全体をインラインで実行します。

スクリプト： ~/.claude/skills/prd-taskmaster/script.py（すべてのコマンドが JSON を出力します）。同梱の prd_taskmaster/ パッケージを呼び出す薄いラッパーであり、プラグインと共有する唯一の信頼できる情報源です。

手動フラグ： ユーザーが --manual、manual=true、または「手動でやって」と指定した場合は、TaskMaster の処理を自分で行います。.taskmaster/docs/prd.md と、タスクおよびサブタスクを含む .taskmaster/tasks/tasks.json を作成し、validate-tasks を実行してから enrich-tasks を実行してください。TaskMaster CLI/MCP による解析が完了するまで待ってはいけません。

使用する場面

有効にする場合：PRD、製品要件、TaskMaster、タスク駆動開発、「X を作りたい」など、あらゆる目標。 使用しない場合：API ドキュメント、テスト仕様、プロジェクトのタイムライン、PDF の作成。

Phase 0：エンジンのバックエンド解決（必須 — 他のエンジン操作を行う前に実施）

エンジンには、相互に切り替え可能なバックエンドが 2 つあります。atlas-engine MCP サーバー（推奨）と script.py（依存関係不要の代替手段）です。このセッションで使用するバックエンドを今すぐ解決してください。script.py を黙って既定のバックエンドにしてはいけません。

Claude Code に関する注意 — 遅延読み込みツール： MCP ツールは多くの場合、遅延読み込みされます。名前がシステムリマインダーの一覧に表示されていても、ToolSearch ツールでスキーマを読み込むまでは呼び出せません。「呼び出し可能な engine_preflight ツールが見当たらない」ことは、サーバーが存在しないという意味ではありません。ほとんどの場合、まだ ToolSearch を実行していないだけです。

次の手順を順番に実施して、バックエンドを解決してください。

1. セッションに ToolSearch ツールがある場合： a. ToolSearch(query="select:mcp__atlas-engine__engine_preflight") b. 一致する結果がなければ、ToolSearch(query="+engine preflight atlas", max_results=10) を実行します。これにより、mcp__plugin_prd_go__engine_preflight など、プラグインスコープの ID も見つかります。 c. スキーマが読み込まれた場合 → MCP モード = ON。プレフィックス（例：mcp__atlas-engine__）を記録します。ユーザースコープとプラグインスコープの両方で一致した場合は、mcp__atlas-engine__ を優先します。
2. ToolSearch はないものの、engine_preflight MCP ツールをすでに直接呼び出せる場合 → MCP モード = ON。そのプレフィックスを使用します。
3. それ以外の場合 → MCP モード = OFF（CLI モード）。

Phase 1 の前に、結果を次のいずれか 1 行だけで通知してください。 Engine backend: MCP (<prefix>*) または Engine backend: script.py (CLI fallback)。

以降の実行では、次のルールを厳守してください。

• MCP モードが ON の場合： 以下の「エンジン操作」表に記載されたすべての操作で、対応する MCP ツールを必ず使用してください。このセッションのプレフィックスに MCP ツールがある操作に対して python3 script.py <cmd> を実行することは、ルール違反です。例外は「スクリプト／エージェントのみ」の表に記載された操作、および解決したプレフィックスにツールがない操作です（プラグインによっては公開されるツールが少ない場合があるため、その操作だけ script.py にフォールバックしてください）。
• MCP モードが OFF の場合： 以下に記載されたとおりに script.py コマンドを使用してください。（codex、gemini などの）他のハーネスには ToolSearch がなく、MCP サーバーも利用できない場合があります。CLI モードは完全にサポートされており、機能が劣るわけではありません。
• 実行中に MCP の呼び出しでエラーが発生した場合（サーバーの停止または切断）は、その旨を明示して CLI モードに切り替え、続行してください。

フェーズ 1：ゼロ設定の事前チェック

事前チェックを実行し、すべてを自動検出します。設定に関する質問は一切しません。

MCP モード（フェーズ 0 から引き継ぎ — スクリプトを大量に呼び出さず、1 回にまとめて呼び出し）：
<prefix>engine_preflight を 1 回呼び出します。事前チェック、TaskMaster の検出、プロバイダーの設定、機能の確認を行い、そのまま提示する summary リストを返します。 以下の個別のスクリプト呼び出しはすべて省略します。

CLI モード（依存関係ゼロのインストール）： 同じ結果を得るため、サブコマンドを 1 回にまとめて実行します。

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

事前チェックの JSON から状態を判定します：

条件	アクション
prd_path が存在し、task_count > 0	タスクを実行／PRD を更新／新しい PRD を作成／レビュー、のいずれかを確認します
backend.ai_ops == "agent"	バックエンドは自動的に解決されます。ヘッドレス AI 操作には API キーを追加するか task-master-ai をインストールするよう、情報を 1 行だけ表示して続行します
manual フラグが存在する	TaskMaster CLI／MCP の状態にかかわらず、Native Mode を使用して続行します（TaskMaster は任意です）
has_taskmaster == false かつバックエンドが選択済み	init-project（以下を参照）を実行してから続行します
has_taskmaster が存在するが PRD がない	Discovery に進みます
has_crash_state	クラッシュした箇所から再開するか、最初から開始するかを提示します

必要に応じてプロジェクトを初期化し、その後プロバイダーを自動設定します（通知なし）。解決されたバックエンドには init-project を使用します。taskmaster バックエンドの場合、既存の .mcp.json は保持されます。task-master init を直接実行すると、プレースホルダーのテンプレートで上書きされます。init-taskmaster は、taskmaster バックエンドを明示的に操作する場合にのみ使用します：

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

configure-providers が recommended_action: "init_taskmaster" を返した場合、まず init-project を実行します。バックエンドが明示的に taskmaster の場合は、init-taskmaster も安全に使用でき、.mcp.json は保持されます。

簡潔なステータスを報告します：

  ✓ 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)

ゲート：バックエンドは必ず解決済みです。ai_ops 機能を報告します。Discovery に進みます。

プロバイダーのデフォルト

有料 API キーよりも、サブスクリプション型／ネイティブのプロバイダーを常に優先します：

1. メイン：claude が存在する場合は claude-code ／ sonnet。それ以外の場合、codex が存在すれば codex-cli ／ gpt-5.2-codex。
2. フォールバック：利用可能な場合は codex-cli ／ gpt-5.2-codex。それ以外の場合は claude-code ／ sonnet。
3. リサーチ：TaskMaster の openai-compatible プロバイダーを介したローカルの Perplexity API Free：
   • モデル：sonar
   • baseURL：http://127.0.0.1:8765
   • .env キー：OPENAI_COMPATIBLE_API_KEY="local-perplexity-api-free"（ローカル用のダミーキーのみ）

ネイティブの Claude／Codex と Perplexity API Free が利用可能な場合、ANTHROPIC_API_KEY や有料の PERPLEXITY_API_KEY を必須にしないでください。

フェーズ 2：Discovery

フェーズファイルを読み、その指示に従います：

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

superpowers:brainstorming を介した、段階的かつ適応的で、ドメインに依存しない Discovery です。

ゲート：Discovery が完了し、ユーザーが設計を承認しました。Generate に進みます。

フェーズ 3：生成と検証

フェーズファイルを読み、その指示に従います：

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

仕様を生成し、品質を検証し、タスクを解析してメタデータを追加します。

ゲート：PRD が GOOD 以上と検証され、TaskMaster の parse／expand または Native Mode を通じてタスクが作成されました。Handoff に進みます。

Native Mode（TaskMaster は任意）

以前は「Manual Mechanics Mode」と呼ばれていました。エンジンは TaskMaster を使わずに、同じ検証済みタスクグラフを生成します。ユーザーが --manual を指定した場合、TaskMaster がインストールされていない場合、またはその解析／展開が適していない場合に使用します。

1. 通常どおり .taskmaster/docs/prd.md を生成します。
2. TaskMaster 互換の形式で .taskmaster/tasks/tasks.json を手動で作成します：
   • トップレベルのオブジェクトに tasks: [] を含めます
   • 各タスクに id、title、description、details、testStrategy、status、dependencies、priority、subtasks を含めます
   • すべてのタスクに、id、title、description、status、dependencies を含むサブタスクを 2 つ以上設定します
3. 次を実行します：

   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. 検証、エンリッチメント、phaseConfig の検証が成功した場合、TaskMaster の parse ＋ expand と同等として扱います。

フェーズ 4：引き継ぎ

フェーズファイルを読み、その指示に従います。

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

機能を検出し、実行モードを 1 つ推奨して、引き継ぎます。モード（ユーザー向けの名称）： Verified Loop（superpowers とループランナーが存在する場合に推奨）、Auto-Execute （TaskMaster 標準のループ）、Plan & Drive（計画のみ）。Atlas Fleet — 並列マルチセッション 実行 — は、ライセンス済みの atlas-launcher が検出された場合に Atlas Pro のオプションとして 表示されます。それ以外の場合は、https://atlas-ai.au/pro を示すロックされた予告として表示されます。無料エンジンは 常に単独で完全に使用できます。

ゲート：ユーザーがモードを選択し、引き継ぎが完了していること。

フィードバック

デブリーフ時に、実行中の各エージェントは実行結果を記録します。MCP モード： <prefix>feedback_submit / <prefix>feedback_report。CLI モード： 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>。フィードバックは .atlas-ai/feedback.jsonl に保存されます。python3 script.py feedback-report で要約します。

エンジン操作

この表は規範です。各指示箇所では、操作名を参照します。MCP モードでは MCP ツールを使用します（Phase-0 のプレフィックスに置き換えてください）。CLI モードでは script.py コマンドを使用します。

操作	MCP ツール（MCP モード）	script.py（CLI モード／フォールバック）
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	（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]
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
status	render_status	status [--phase P] [--format boxed|ascii|json] [--all]

各フェーズの境界で（および要求に応じて）、status / render_status を使って進捗パネルを表示します — フェーズトラッカー（ボックス表示）、検証スコアカード、リリースチェックゲート、実行の進捗を表示します。

バックエンドの動作はどちらのインターフェースでも同一です。taskmaster バックエンドはネイティブの TaskMaster 操作（init/parse/rate/expand）を安全にラップします。native バックエンドは直接 API 呼び出しを使用するか、agent_action_required を返します。next / set-status は すべてのバックエンドでエンジンネイティブです。

スクリプト／エージェント専用の操作（MCP ツールなし — 常に script.py を使用し、任意のモードで実行）

コマンド	目的
configure-providers	ネイティブの Claude／Codex とローカルの Perplexity API Free のデフォルトを設定します
detect-providers	AI プロバイダーを自動検出します
validate-tasks [--input <path>] [--require-phase-config]	手動で作成した tasks.json を検証します
enrich-tasks	タスクに phaseConfig メタデータを追加します
parallel-plan [--missing-only]	並列サブエージェント向けのタスクごとのリサーチパケットを出力します
parallel-apply --input <results.json>	並列リサーチの結果をアトミックにマージします
parallel-extract --output <path> / parallel-inject --input <path>	タグ付き ⇄ フラットなタスクのブリッジ
economy-report	(op_class, model) ごとのテレメトリを要約します

並列リサーチと複雑度

拡張とリサーチの判断ツリー（トークン効率を考慮）：

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

分離ディレクトリを使う理由：task-master 0.43 以降では proper-lockfile とアトミック書き込みが使われていますが、ロックの有効期限は 10 秒である一方、AI 呼び出しは 30～120 秒かかるため、1 つのディレクトリでの同時実行は安全ではありません。N 個の分離されたプロジェクトディレクトリを使えばロックを完全に回避でき、試行ごとにモデルを設定する仕組みとしても機能します（expand には --model フラグがなく、各作業ディレクトリに個別の config.json があるためです）。無料のローカル Perplexity プロキシは、TaskMaster が必要とする厳密な JSON ではなく文章を返します。そのため、このプロキシではエージェントで正規化する経路を維持し、実際の API ではネイティブ経路を使います。

パターン — 並列化を担うのはスクリプトではなくエージェントです。

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

perplexity-api-free MCP ラッパーがタイムアウトするか、プロキシに到達できないと表示された場合は、直接プロキシの稼働状態を確認してください。

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}'

curl が直接動作する場合は、そのまま続行してください。MCP、プロキシへの直接呼び出し、またはエージェントによるリサーチを使って results.json スキーマを作成し、parallel-apply の前に文章を有効な JSON に正規化してください。ネイティブの task-master analyze-complexity --research の完了を待つ必要はありません。

明示的なフラットファイルのワークフロー向けのタグブリッジ（スクリプトはタグ付きの TaskMaster ファイルも直接読み取ります）：

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

すべてのコマンドでは、--tag のデフォルトとして .taskmaster/state.json の currentTag が使われ、プロジェクトルートから実行されます。

コンテキスト

単独で動作： 単独で使用できます。任意の目標を受け取り、仕様とタスクを生成します。 生成物： spec.md + tasks.json（.taskmaster/ 内）。 次の手順： 実行モード（Verified Loop／Auto-Execute／Plan & Drive）に引き継ぐか、Atlas Pro を使った複数セッションの並列実行には Atlas Fleet を使用します。

重要なルール

1. セットアップに関する質問はゼロ — すべてを検出し、ディスカバリーに必要な質問のみを尋ねます
2. superpowers:brainstorming を使ってディスカバリーを行います — 質問は一度に 1 つずつ、状況に応じて調整します
3. ドメインを問いません — アプリ、ペンテスト、ビジネスなど、あらゆる目標に対応します
4. PRD の検証でプレースホルダーを検出します — mustache、TBD、TODO のパターンがあると検証に失敗します
5. manual フラグは「TaskMaster の処理を手動で行う」という意味であり、「検証を省略する」という意味ではありません
6. 引き継ぎではモードを 1 つだけ推奨します — 選択肢を同等に並べるのではなく、最適なものを提示します
7. フェーズファイルは明示的に Read する必要があります — 自動では読み込まれません
8. ネイティブ／無料プロバイダーのデフォルトは configure-providers によって適用されます。ネイティブ／無料の経路が利用できない場合を除き、有料の Anthropic／Perplexity API に戻さないでください
9. Perplexity API Free のリサーチは parallel-apply を通して正規化する必要があります。ネイティブの TaskMaster リサーチが許容されるのは、有効な構造化出力が返され、検証に合格した場合のみです
10. フェーズ 0 でのバックエンド解決は必須です — MCP モードでは、解決済みのプレフィックスに MCP ツールがある操作について script.py を使用してはいけません