solo-build

/build

このスキルは単独で完結しています。外部のビルド／実行スキル（superpowers など）に委任せず、以下のタスクループ、TDD ルール、完了フローに従ってください。

実装計画にあるタスクを実行します。docs/plan/ にある plan.md を見つけ、次の未完了タスクを選び、TDD ワークフローで実装してコミットし、進捗を更新します。

ライブコンテキスト

• ブランチ：!git branch --show-current 2>/dev/null
• ステータス：!git status --short 2>/dev/null | head -10
• 最新のコミット：!git log --oneline -3 2>/dev/null

使用するタイミング

/plan が spec.md と plan.md を含むトラックを作成した後に使用します。これは実行エンジンです。

パイプライン：/plan → /build → /deploy → /review

MCP ツール（利用可能な場合に使用）

• session_search(query) — 類似の問題を以前どのように解決したかを検索します
• project_code_search(query, project) — プロジェクト間で再利用可能なコードを検索します
• codegraph_query(query) — ファイルの依存関係、インポート、呼び出し元を確認します

MCP ツールが利用できない場合は、Glob + Grep + Read を使用します。

事前確認

1. コンテキストを検出する — 計画ファイルの場所を確認します：

   • docs/plan/*/plan.md を確認します — 標準の場所です
   • 存在するものを使用します。
   • conductor/ やその他のディレクトリは検索しないでください。docs/plan/ のみを対象にします。

2. docs/workflow.md が存在する場合は、ワークフロー設定を読み込みます：

   • TDD の厳密さ（strict / moderate / none）
   • コミット戦略（Conventional Commits 形式）
   • 検証チェックポイントのルール
   • 統合テストセクション — 存在する場合は、記載されたパスに触れるタスクの完了後に、指定された CLI コマンドを実行します docs/workflow.md がない場合は、デフォルト設定（moderate TDD、Conventional Commits）を使用します。

3. Git フックがインストールされていることを確認します：

   スタック YAML（templates/stacks/{stack}.yaml）を読みます。pre_commit フィールドに、使用するシステムと実行内容が記載されています：

   • husky + lint-staged → JS/TS スタック（eslint + prettier + tsc）
   • pre-commit → Python スタック（ruff + ruff-format + ty）
   • lefthook → モバイルスタック（swiftlint/detekt + formatter）

   次に、フックシステムが有効であることを確認します：

   # husky
   [ -f .husky/pre-commit ] && git config core.hooksPath | grep -q husky && echo "OK" || echo "NOT ACTIVE"
   # pre-commit (Python)
   [ -f .pre-commit-config.yaml ] && [ -f .git/hooks/pre-commit ] && echo "OK" || echo "NOT ACTIVE"
   # lefthook
   [ -f lefthook.yml ] && lefthook version >/dev/null 2>&1 && echo "OK" || echo "NOT ACTIVE"
   

   有効でない場合は、最初のコミット前にインストールします：

   • husky：pnpm prepare（または npm run prepare）
   • pre-commit：uv run pre-commit install
   • lefthook：lefthook install

   コミットで --no-verify を使用しないでください。フックに失敗した場合は、問題を修正して再度コミットします。

トラックの選択

$ARGUMENTS にトラック ID が含まれている場合：

• 検証します：{plan_root}/{argument}/plan.md が存在することを確認します（docs/plan/ を確認）。
• 見つからない場合は、docs/plan/*/plan.md で部分一致を検索し、修正案を提示します。

$ARGUMENTS に --task X.Y が含まれている場合：

• アクティブなトラック内の該当タスクに直接移動します。

引数がない場合：

1. docs/plan/ 内の plan.md ファイルを検索します。
2. 各 plan.md を読み、未完了タスクがあるトラックを見つけます。
3. 複数ある場合は、AskUserQuestion を使って確認します。
4. トラックが 0 件の場合：「計画が見つかりません。まず /plan を実行してください。」

コンテキストの読み込み

ステップ 1 — アーキテクチャ概要（MCP が利用可能な場合）

codegraph_explain(project="{project name}")

取得内容：スタック、言語、ディレクトリ階層、主要なパターン、上位の依存関係、ハブファイル。

ステップ 1.5 — RepoMap の取得（MCP が利用可能な場合）

codegraph_repomap(project="{project name}")

取得内容：主要ファイルと、それらがエクスポートするクラス／関数の YAML マップ。これを使って全体構造を把握します。

ステップ 2 — 必須ドキュメント（並行して読み込み）

1. docs/plan/{trackId}/plan.md — タスクリスト（必須）。まず ## Context Handoff セクションを読んでください。意図、主要なファイル、決定事項、リスクが簡潔にまとめられています。最初に読むべき情報です。
2. docs/plan/{trackId}/spec.md — 受け入れ基準（必須）
3. docs/workflow.md — TDD ポリシー、コミット戦略（存在する場合）
4. CLAUDE.md — アーキテクチャ、Do/Don't
5. .solo/pipelines/progress.md — 前回のイテレーションからの進捗ドキュメント（存在する場合。パイプライン固有）。前回のパイプラインセッションで実施した内容（完了したステージ、コミット SHA、最後の出力行）が記載されています。完了済みの作業を繰り返さないように活用してください。

この段階ではソースコードファイルを読まないでください。 ドキュメントのみを読みます。ソースファイルは、実行ループ（以下のステップ 3）でタスクごとに読み込みます。

再開

plan.md でタスクに [~] が付いている場合：

Resuming: {track title}
Last task: Task {X.Y}: {description} [in progress]

1. Continue from where we left off
2. Restart current task
3. Show progress summary first

AskUserQuestion で確認してから、続行してください。

コンテキストエンジニアリングのルール

references/context-engineering.md を読み、観察のマスキング、注意の配置、計画の再確認に関するルールをすべて確認してください。要点：

• 観察のマスキング： 大きな出力（50 行超）は scratch/ に書き込み、5〜10 行の要約を残します
• 注意の配置： エラーは冒頭、履歴は中間、次のステップは末尾に配置します
• 計画の再確認： 認識のずれを防ぐため、各タスクの開始時に plan.md を読み直します

タスク実行ループ

Makefile の規約： プロジェクトのルートに Makefile がある場合は、生のコマンドよりも 常に make ターゲットを優先してください。pnpm test の代わりに make test、pnpm lint の代わりに make lint、pnpm build の代わりに make build などを使います。利用可能なターゲットを確認するには、make help を実行するか Makefile を読んでください。make integration などのターゲットがある場合は、パイプライン関連のタスクの後に統合テストで使用してください。

重要 — すべて完了しているかの確認： ループに入る前に、plan.md を確認し、- [ ] または - [~] のタスクがあるか調べます。すべてのタスクが [x] の場合は、ループを完全にスキップし、以下の 完了 セクションに進んで最終確認を実行し、<solo:done/> を出力してください。

plan.md で未完了（[ ] の印が付いた）タスクごとに、順番に実行します。

1. 次のタスクを見つける

plan.md を解析し、最初に該当する行を探します：- [ ] Task X.Y:（再開時は - [~] Task X.Y:）。

2. タスクを開始する

• plan.md を更新し、現在のタスクを [ ] から [~] に変更します。
• 「Task X.Y: {description} を開始します」 とアナウンスします。

3. 調査（コーディング前に効率よく実施）

プロジェクト全体を grep したり、すべてのソースファイルを読んだりしないでください。 このタスクに必要なものだけを読み込みます。

MCP が利用可能な場合（推奨）：

1. project_code_search(query="{task keywords}", project="{name}") — プロジェクト内の関連コードを探します。上位 2〜3 件の結果だけを読みます。
2. session_search("{task keywords}") — 以前に同じ問題を解決したか確認します。
3. codegraph_query("MATCH (f:File {project: '{name}'})-[:IMPORTS]->(dep) WHERE f.path CONTAINS '{module}' RETURN dep.path") — 変更予定ファイルのインポートと依存関係を確認します。

MCP が利用できない場合（代替手段）：

1. タスクの説明で明示されているファイルパスのファイルのみを読みます。
2. プロジェクト全体ではなく、タスク対象の特定のモジュールディレクトリを glob で検索します（例：src/auth/**/*.ts）。
3. タスクにファイルの記載がない場合は、src/ または app/ に対して対象を絞ったパターンで Grep を使います。**/* は使わないでください。

禁止事項： プロジェクト全体を対象に Grep "keyword" . を実行すること。理由もなく何百行もの内容がコンテキストに流れ込みます。

プラットフォーム別の品質チェックツール

スタックごとの完全なコマンドについては、references/quality-tools.md を参照してください。クイックリファレンス：

スタック	リント	フォーマット	型チェック	コミット前チェック
Python	uv run ruff check --fix .	uv run ruff format .	uv run ty check .	uv run pre-commit run --all-files
JS/TS	pnpm lint --fix	pnpm format	pnpm tsc --noEmit	husky + lint-staged
iOS	swiftlint lint --strict	swift-format	—	lefthook
Android	./gradlew detekt	./gradlew ktlintCheck	—	lefthook

各タスクの実装後、git commit の前に実行してください。失敗したものがあれば、先に修正してから進めてください。

4. TDD ワークフロー（workflow.md で TDD が有効な場合）

まず境界に合意します： このタスクのテストで観測する公開インターフェースを明示し、テストを書く前にユーザーの確認を得てください。確認されていない境界でテストを書かないでください。

Red — 失敗するテストを書く：

• タスクの機能に対応するテストファイルを作成または更新します。
• テストを実行し、失敗することを確認します。一度も Red になっていないテストでは何も証明できません。

Green — 実装する：

• テストを通すために必要な最小限のコードを書きます。
• テストを実行し、成功することを確認します。

リファクタリング：

• テストが通る状態を保ちながら整理します。
• 最後にもう一度テストを実行します。

1 つのテスト → 1 つの実装 → 繰り返し（垂直スライス）。先にすべてのテストを書き、その後ですべてを実装すると、実際の動作ではなく想像上の動作を検証することになります。

機能の最初のテストを書く前に references/tdd-seams.md を読んでください。境界の決め方、垂直スライスと水平スライスの違い、テストが嘘をつく 4 つのケース（実装との結合、サイドチャネル、同語反復、感度不足）について説明しています。

5. 非 TDD ワークフロー（TDD が「none」または「moderate」で、タスクが単純な場合）

• タスクを直接実装します。
• 既存のテストを実行し、問題が発生していないことを確認します。
• 「moderate」の場合は、ビジネスロジックと API ルートのテストを書き、UI／設定のテストは省略します。

5.5. 統合テスト（CLI 優先）

タスクが中核となるビジネスロジック（パイプライン、アルゴリズム、エージェントツール）に関わる場合は、make integration（または docs/workflow.md に記載されている統合テストコマンド）を実行します。CLI ならブラウザーを必要とせず、UI と同じコードパスを実行できます。make integration が失敗した場合は、コミット前に修正してください。

5.6. 視覚的な確認（ブラウザー／シミュレーター／エミュレーターが利用可能な場合）

実装後、ツールが利用可能であれば、簡単な視覚的スモークテストを実行してください。

Web プロジェクト（Playwright MCP またはブラウザーツール）： Playwright MCP ツールまたはブラウザーツールが利用可能な場合：

1. 開発サーバーがまだ起動していなければ起動します（スタック YAML で dev_server.command を確認します）。
2. 現在のタスクの影響を受けるページに移動します。
3. ブラウザーのコンソールでエラー（ハイドレーションの不一致、未捕捉の例外、404）がないか確認します。
4. スクリーンショットを撮り、表示が期待どおりであることを確認します。
5. タスクがレスポンシブレイアウトに影響する場合は、モバイルのビューポート（375px）にサイズを変更して確認します。

iOS プロジェクト（シミュレーター）： パイプラインのプロンプトで iOS Simulator を使用するよう指示されている場合：

1. シミュレーター向けにビルドします：xcodebuild -scheme {Name} -sdk iphonesimulator build
2. 起動済みのシミュレーターにインストールします：xcrun simctl install booted {app-path}
3. 起動してスクリーンショットを撮ります：xcrun simctl io booted screenshot /tmp/sim-screenshot.png
4. シミュレーターのログを確認します：xcrun simctl spawn booted log stream --style compact --timeout 10

Android プロジェクト（エミュレーター）： パイプラインのプロンプトで Android Emulator を使用するよう指示されている場合：

1. デバッグ APK をビルドします：./gradlew assembleDebug
2. インストールします：adb install -r app/build/outputs/apk/debug/app-debug.apk
3. スクリーンショットを撮ります：adb exec-out screencap -p > /tmp/emu-screenshot.png
4. logcat を確認します：adb logcat '*:E' --format=time -d 2>&1 | tail -20

柔軟な対応： ブラウザー／シミュレーター／エミュレーターのツールが利用できない、または失敗する場合は、視覚的なチェックをすべて省略します。視覚テストはあくまで追加の確認であり、作業を妨げるものではありません。省略したことを記録し、タスクを続行してください。

6. タスクを完了する

コミット（コミット戦略に従う）：

git add {specific files changed}
git commit -m "<type>(<scope>): <description>"

種類：feat、fix、refactor、test、docs、chore、perf、style

コミット後に SHA を取得：

git rev-parse --short HEAD

plan.md に SHA を記録する。 タスクをコミットするたびに：

1. タスクを完了にする：[~] → [x]
2. コミット SHA をインラインで追記する：- [x] Task X.Y: description

SHA がなければ、追跡も元に戻すこともできません。タスクに複数のコミットが必要だった場合は、最後の SHA を記録してください。

7. フェーズ完了の確認

各タスクの後、現在のフェーズのすべてのタスクが [x] になっているか確認してください。

フェーズが完了している場合：

1. SHA 監査 — このフェーズの [x] タスクをすべて確認します。`` がないものがあれば、今すぐ git log から SHA を取得して追加します。すべての [x] タスクに SHA が必要です。
2. フェーズの ### Verification に記載された検証手順を実行します。
3. テストスイート全体を実行します。
4. リンターを実行します。
5. plan.md の検証チェックボックスを更新します：- [ ] → - [x]。
6. plan.md の進捗をコミットします：git commit -m "chore(plan): complete phase {N}"。
7. チェックポイント SHA を取得し、plan.md のフェーズ見出しに追記します： ## Phase N: Title 。
8. 結果を報告して、続行します：

Phase {N} complete! 

  Tasks:  {M}/{M}
  Tests:  {pass/fail}
  Linter: {pass/fail}
  Verification:
    - [x] {check 1}
    - [x] {check 2}

  Revert this phase: git revert abc1234..HEAD

自動的に次のフェーズへ進んでください。承認は不要です。

エラー処理

テスト失敗

Tests failing after Task X.Y:
  {failure details}

1. Attempt to fix
2. Rollback task changes (git checkout)
3. Pause for manual intervention

AskUserQuestion を使用して質問してください。失敗を無視して自動的に続行しないでください。

完了状況の追跡

すべてのフェーズとタスクが [x] になったら：

1. 最終検証

• ローカルビルドを実行 — デプロイ前に成功する必要があります：
  • Next.js：pnpm build
  • Python：uv build または uv run python -m py_compile src/**/*.py
  • Astro：pnpm build
  • Cloudflare：pnpm build
  • iOS：xcodebuild -scheme {Name} -sdk iphonesimulator build
  • Android：./gradlew assembleDebug
• テストスイート全体を実行します。
• リンターと型チェッカーを実行します。
• ビジュアルスモークテスト（利用可能なツールがある場合）：
  • Web：開発サーバーを起動し、メインページに移動して、コンソールにエラーがないことを確認し、スクリーンショットを撮影します
  • iOS：ビルドしてシミュレーターにインストールし、起動して、スクリーンショットを撮影し、ログを確認します
  • Android：APK をビルドしてエミュレーターにインストールし、起動して、スクリーンショットを撮影し、logcat を確認します
  • ツールが利用できない場合はスキップしてください — 完了の妨げにはなりません
• spec.md の受け入れ基準を確認します：
  • - [ ] の基準をそれぞれ確認し、満たされていることを検証します（コードを検索するか、指定されたコマンドを実行します）。
  • 基準に実行可能なコマンド（make task、cargo test、ベンチマーク、passes N/N）が含まれている場合は、実行してください。「検証不能」としてスキップしないでください。
  • 検証済みの基準について、spec.md のチェックボックスを更新します：- [ ] → - [x]。
  • 基準を満たさないものがあれば、計画を完了にしないでください。修正するか、失敗を記録してください。
  • spec の更新をコミットします：git add docs/plan/*/spec.md && git commit -m "docs: update spec checkboxes (verified by build)"

ビルド失敗時のエスカレーション

同じビルド／テストエラーが連続して 3 回以上発生した場合は、再試行を中止してください。代わりに：

1. エラーメッセージを明確に出力します。
2. 修正方法を提案します（例：cargo clean、rm -rf node_modules、ディスク容量の確認）。
3. レビューで対処できるよう、<solo:redo/> を出力します。 同じ失敗で反復を無駄にしないでください。

2. plan.md のヘッダーを更新

plan.md の冒頭で **Status:** [ ] Not Started を **Status:** [x] Complete に変更します。

3. 完了を通知

パイプラインの状態ディレクトリ（.solo/states/）が存在する場合に限り、パイプラインシグナルを出力します：

<solo:done/>

このシグナルタグを応答内の他の場所で繰り返さないでください。 出現は 1 回のみです。

4. まとめ

Track complete: {title} ({trackId})

  Phases: {N}/{N}
  Tasks:  {M}/{M}
  Tests:  All passing

  Phase checkpoints:
    Phase 1: abc1234
    Phase 2: def5678
    Phase 3: ghi9012

  Revert entire track: git revert abc1234..HEAD

Next:
  /build {next-track-id}  — continue with next track
  /plan "next feature"    — plan something new

作業の取り消し

plan.md の SHA コメントを使うと、対象を絞って取り消せます：

単一のタスクを取り消す：

# Find SHA from plan.md: - [x] Task 2.3: ... 
git revert abc1234

続いて plan.md で、そのタスクを [x] → [ ] に更新します。

フェーズ全体を取り消す：

# Find checkpoint from phase heading: ## Phase 2: ... 
# Find previous checkpoint: ## Phase 1: ... 
git revert abc1234..def5678

続いて plan.md で、そのフェーズのすべてのタスクを [x] → [ ] に更新します。

git reset --hard は絶対に使用しないでください — 履歴を保持するため、必ず git revert を使用してください。

進捗の追跡（TodoWrite）

ビルドセッションの開始時に、plan.md からタスクリストを作成して進捗を可視化します。

1. セッション開始時： plan.md を読み、未完了のタスク（[ ] と [~]）をすべて確認します。
2. 各フェーズについて、そのタスクを説明として TaskCreate を作成します。
3. 作業を進めながら TaskUpdate を実行します。タスクの開始時に in_progress、完了時に completed を設定します。
4. これにより、ユーザー（およびパイプライン）は進捗をリアルタイムで確認できます。

言い訳カタログ

次のような考えが浮かんだら、手を止めてください。手を抜こうとしています。

考え	現実
「テストするほどでもない簡単な作業だ」	簡単なコードでも壊れます。テストを書いてください。
「テストは後で追加しよう」	合格した後に書いたテストは、すぐに通っても何の証明にもなりません。
「手動でテスト済みだ」	手動テストは記録に残りません。自動テストは残ります。
「テストフレームワークが設定されていない」	設定してください。それも作業の一部です。
「ただの設定変更だ」	設定変更でビルドが壊れることがあります。検証してください。
「これは確実に動く」	根拠のない確信は推測にすぎません。コマンドを実行してください。
「X を変更してみよう」	立ち止まってください。まず根本原因を調べてください。
「テストは通った。出荷しよう」	テスト合格 ≠ 受け入れ基準の達成です。spec.md を確認してください。
「リンターの修正は後でやろう」	今すぐ直してください。技術的負債は積み重なります。
「自分の環境では動く」	ビルドを実行してください。実際の環境で検証してください。

危険信号 — 次のように考えていることに気づいたら、すぐに手を止めてください

• 「今回はテストを省略しよう」— いいえ。テストを書いてください。
• 「古いコードを参考用に残しておこう」— 削除するなら削除してください。残せばそれに合わせてしまい、新しく書けなくなります。例外はありません。
• 「ルールの精神には従っているが、文面には従っていない」— ルールの文面に反することは、精神にも反することです。
• 「今回は事情が違うので……」— 違いはありません。プロセスに従ってください。
• 「コミット前にもうひとつだけ変更しよう」— 現在の内容をコミットしてください。スコープの拡大は作業を台無しにします。
• 「計画では X となっているが、Y の方がよい」— 計画に従ってください。本当に誤りなら、まず plan.md を更新してから実装してください。

基本原則： 本番データを確認せずに一括削除しないのであれば、不要だという根拠なしにテストを省略してはいけません。

重要なルール

1. フェーズごとのチェックポイントを実行する — 次のフェーズに進む前に、テストとリンターが成功することを確認します。
2. 失敗したら停止する — テスト失敗やエラーがあれば、先に進んではいけません。
3. plan.md を最新の状態に保つ — タスクのステータスは、常に実際の進捗を反映している必要があります。
4. 各タスクの後にコミットする — Conventional Commits 形式で、アトミックなコミットを作成します。
5. コーディング前に調査する — 30 秒の検索で、30 分の再実装を避けられます。
6. 一度にひとつのタスクに取り組む — 次のタスクを始める前に、現在のタスクを完了させます。
7. テスト出力を簡潔に保つ — テストの実行時は head -50 にパイプするか、--reporter=dot／-q フラグを使います。数千行のテスト出力でコンテキストを埋めないでください。詳細に表示するのは失敗したテストだけにします。出力が大きい場合は、観測内容をマスクします（scratch/ に書き込み、概要だけを残します）。
8. 完了と報告する前に検証する — 実際のコマンドを実行し、出力全体を読み、成功を確認してからタスクを完了にします。「これで動くはず」と言ってはいけません。
9. 計画を復唱する — 各タスクの開始時に plan.md を読み直します。次に何をするか、記憶に頼ってはいけません。

よくある問題

「計画が見つからない」

原因： docs/plan/ に plan.md がありません。 対処： まず /plan "your feature" を実行して、トラックを作成します。

タスクの後にテストが失敗する

原因： 実装によって既存の機能が壊れました。 対処： エラー処理フローに従ってください。修正を試み、必要であればロールバックし、ユーザーの入力を待ちます。失敗したテストを決して省略してはいけません。

フェーズのチェックポイントに失敗する

原因： フェーズの区切りでテストまたはリンターが失敗しました。 対処： 先に進む前に失敗を修正してください。そのフェーズの検証を再実行します。