harness-plan

Harness Plan

Harness の統合プランニングスキル。 以下の3つの旧スキルを統合:

• planning (plan-with-agent) — アイデア → Plans.md への落とし込み
• plans-management — タスク状態管理・マーカー更新
• sync-status — Plans.md と実装の同期確認

Quick Reference

ユーザー入力	サブコマンド	動作
"計画を作って" / /harness-plan create	create	対話型ヒアリング → Plans.md 生成
"タスクを追加して" / /harness-plan add	add	Plans.md に新タスク追加
"完了にして" / /harness-plan update	update	タスクマーカーを cc:完了 に変更
"今どこ？" / /harness-plan sync	sync	実装とPlans.mdを照合・同期
/harness-sync	sync	進捗確認（独立 sync surface と同等）
/harness-plan create	create	計画作成

Literal companion commands（CC 2.1.108+）

• /recap: 久しぶりに戻った時に要約を取り直してから sync へ入る
• /undo: /rewind の別名。直前の plan 更新を即座に戻したい時にそのまま使う

サブコマンド詳細

create — 計画作成

See references/create.md

アイデア・要件をヒアリングし、実行可能な Plans.md を生成する。

フロー:

1. 会話コンテキスト確認（直前の議論から抽出 or 新規ヒアリング）
2. 何を作るか聞く（max 3問）
3. 技術調査（WebSearch）
4. 機能リスト抽出
5. 優先度マトリクス（Required / Recommended / Optional）
6. TDD 採用判断（テスト設計）
7. Plans.md 生成（cc:TODO マーカー付き）
8. 次のアクション案内

create 完了時のセッション起動案内（必須）

create が終わったら、説明だけで終わらせず、新しいセッションの起動コマンド と 起動後にそのまま入れる最初の指示プロンプト をセットで案内する。

優先順位は次の通り:

1. 未完了タスクが 1 件だけ、または最初の 1 件だけ始めるのが自然
   • 起動コマンド: claude
   • 最初の入力: /harness-work <task番号>
2. 依存の薄いタスクが複数あり、まとめて進めるのが自然
   • 起動コマンド: claude
   • 最初の入力: /breezing all
   • 代替: /harness-work all
3. 長時間実行や再入が前提
   • 起動コマンド: ENABLE_PROMPT_CACHING_1H=1 claude
   • 最初の入力: /harness-loop all
   • 代替: /breezing all

最低でも次の 3 行を含める:

• 新しいセッションの起動コマンド:
• 起動後の最初の入力:
• 向いている場面:

例:

新しいセッションの起動コマンド: claude
起動後の最初の入力: /breezing all
向いている場面: Phase 1 の task が複数あり、まとめて進めるほうが自然なため

長時間系を勧める場合は、Claude Code セッション起動コマンドも併記する:

新しいセッションの起動コマンド: ENABLE_PROMPT_CACHING_1H=1 claude
起動後の最初の入力: /harness-loop all
向いている場面: 5 分を超える待機や resume をまたぐ長時間タスクのため

補足:

• scripts/claude-longrun.sh はこのリポジトリの開発補助スクリプトで、plugin install 後の consumer 環境には配布されない
• そのため、consumer 向け案内では常に ENABLE_PROMPT_CACHING_1H=1 claude の 1 行コマンドを優先する
• リポジトリ開発中だけ同等のラッパーを使いたい場合、bash scripts/claude-longrun.sh はローカル checkout 上では利用してよい

CI モード (--ci): ヒアリングなし。既存の Plans.md をそのまま利用してタスク分解のみ行う。

add — タスク追加

Plans.md に新しいタスクを追加する。

/harness-plan add タスク名: 詳細説明 [--phase フェーズ番号]

タスクは cc:TODO マーカーで追加される。

update — マーカー更新

タスクのステータスマーカーを変更する。

/harness-plan update [タスク名|タスク番号] [WIP|完了|blocked]

マーカー対応表:

コマンド	マーカー
WIP	cc:WIP
完了 / done	cc:完了
blocked	blocked
TODO	cc:TODO

sync — 進捗同期

実装状況と Plans.md を照合し、差分を検出・更新する。

See references/sync.md

フロー:

1. Plans.md の現状取得
2. Plans.md フォーマット検出（v1: 3 カラム / v2: 5 カラム）
3. git status / git log から実装状況取得
4. エージェントトレース確認（.claude/state/agent-trace.jsonl）
5. Plans.md と実装の差分検出
6. 未更新マーカーの自動修正提案
7. 次のアクション提示

レトロスペクティブ（デフォルト ON）: cc:完了 タスクが 1 件以上あれば自動的に振り返りを実行する。 見積もり精度、ブロック原因パターン、スコープ変動を分析し、学びを記録。 sync --no-retro で明示的にスキップ可能。

team mode / issue bridge

Plans.md は正本のまま維持し、GitHub Issue 連携は opt-in の team mode だけで使う。

• solo 開発では bridge を使わない
• team mode は tracking issue を 1 つ作り、その配下に task ごとの sub-issue payload を dry-run で生成する
• scripts/plans-issue-bridge.sh は実際に GitHub を更新せず、常に dry-run の payload を返す
• Plans.md への変更はこの bridge では行わない

参照:

• docs/plans/team-mode.md

Plans.md フォーマット規約

フォーマット

# [プロジェクト名] Plans.md

作成日: YYYY-MM-DD

---

## Phase N: フェーズ名

| Task | 内容 | DoD | Depends | Status |
|------|------|-----|---------|--------|
| N.1  | 説明 | テスト通過 | - | cc:TODO |
| N.2  | 説明 | lint エラー 0 | N.1 | cc:WIP |
| N.3  | 説明 | マイグレーション実行可能 | N.1, N.2 | cc:完了 |

DoD（Definition of Done）: 検証可能な完了条件を 1 行で記述。「いい感じ」「ちゃんと動く」は禁止。Yes/No で判定できる形にする。

Depends: タスク間の依存関係。-（依存なし）、タスク番号（N.1）、カンマ区切り（N.1, N.2）、フェーズ依存（Phase N）。

optional briefs / manifest

harness-plan create は、必要なときだけ brief を付ける。

• UI を含むタスクでは design brief
• API を含むタスクでは contract brief
• brief は「何を作るか」を短く固定する補助資料で、Plans.md を置き換えない
• skill frontmatter の一覧は scripts/generate-skill-manifest.sh で machine-readable JSON にできる

参照:

• docs/plans/briefs-manifest.md

マーカー一覧

マーカー	意味
pm:依頼中	PM から依頼済み
cc:TODO	未着手
cc:WIP	作業中
cc:完了	Worker 作業完了
pm:確認済	PM レビュー完了
blocked	ブロック中（理由を必ず記載）

関連スキル

• harness-sync — 実装と Plans.md を同期する
• harness-work — 計画したタスクを実装する
• harness-review — 実装のレビュー
• harness-setup — プロジェクト初期化