harness-plan

# Harness Plan

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

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

## Quick Reference

| ユーザー入力 | サブコマンド | 動作 |
|------------|------------|------|
| "計画を作って" / `/harness-plan create` | `create` | Spec delta / skip reason → Plans.md task 生成 |
| "タスクを追加して" / `/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` | spec.md / Plans.md 二正本の計画作成 |
| `/harness-plan list` | `list` | `plans/manifest.json` の named Plans を一覧 |
| `/harness-plan switch <name>` | `switch` | active plan を `.claude/state/active-plan.json` に保存 |

## Literal companion commands（CC 2.1.108+）

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

## サブコマンド詳細

### 標準の計画品質契約

See [references/planning-quality.md](${CLAUDE_SKILL_DIR}/references/planning-quality.md)

`harness-plan` は、spec.md product contract and Plans.md task contract の co-required planning output を作る planning surface である。
precedence は `spec.md > sub-spec > Plans.md` のまま維持する。
Plans.md は task ledger、root `spec.md` は product contract であり、上下関係は崩さない。
渡された情報をそのまま Plans.md に落とさない。
計画作成や大きな task 追加では、最新情報・既存仕様・記憶・TeamAgent / サブエージェントによる複数視点の議論を確認し、
このプロダクトに取り入れるべき要素だけを task contract に変換する。
`/harness-plan create` は `Spec delta` または `Spec skip reason` と `Plans.md` task 生成をセットで返す。
出力には必ず `Spec delta` または `Spec skip reason` を含める。
`Spec delta` / `Spec skip reason` は Harness が生成し、consumer は承認・修正だけ行う。

**Non-trivial planning gate**:

単発・軽微タスクでない planning は、TeamAgent またはサブエージェント前提で扱う。
ここでの non-trivial は、複数 task / 複数 file / 複数 session / product behavior / API / data model / 権限 / 課金 / 外部連携 / 配布面 / セキュリティに影響する依頼を指す。
Task tool が使える場合は Product / Architecture / Security / QA / Skeptic の独立視点を走らせる。
使えない場合は `サブエージェント未使用` と明示し、同じ観点を単独で分けて評価する。

non-trivial planning の出力には、次の検証を必ず含める。

- `team_validation_mode`: `not_required_lightweight` / `native` / `subagent` / `manual-pass` / `unavailable`
- `spec.md` / sub-spec / `Plans.md` の整合性
- harness-mem / harness-recall / repo memory による車輪の再発明防止確認
- プロダクト目的から外れていないか
- セキュリティ、権限、秘密情報、サプライチェーンに問題がないか
- lint / formatter baseline があるか。source code changes を含む plan で未設定なら、実装 task の前に setup task を置く
- ちゃんと動く計画か。つまり test / smoke / CI / review / release gate が task DoD に落ちているか

軽量 task は `team_validation_mode: not_required_lightweight` でよい。
non-trivial planning は `native` / `subagent` / `manual-pass` のいずれかを使う。
`unavailable` のまま Required にしてはいけない。
Product / Architecture / Security / QA / Skeptic は検証 perspective であり、agent_type 名ではない。
利用可能な TeamAgent / Task サブエージェントに perspective として依頼し、任意 agent spawn を要求しない。
Security gate は秘密情報の実読取を要求しない。
`.env` や secret の read が必要になる場合は Risk Gate として止め、許可された既存 guard / evidence で確認する。

**適用する場面**:

- `create` で新しい計画を作る
- `add` で product behavior / API / 権限 / 課金 / 外部連携 / 配布面に影響する task を足す
- ユーザーが外部プロダクト、競合、仕様案、改善案、比較材料を渡した
- 既存仕様や過去判断との衝突リスクがある

**軽く扱ってよい場面**:

- marker 更新だけの `update`
- status 照合だけの `sync`
- typo、format、README/CHANGELOG のみ
- 既存 spec とテストで正解が固定されている狭い変更

**品質フロー**:
1. 入力情報を分解し、評価対象・採点軸・不確かな事実を明示する
2. 最新情報を取得する。外部事実は WebSearch / 公式ドキュメント / 一次情報を優先し、重要点は複数ソースでクロスチェックする
3. 既存仕様・root `spec.md`・Plans.md・README・docs・CLAUDE.md・関連 skill を確認する
4. harness-mem / harness-recall / `.claude/agent-memory/` / `.claude/state/` など、利用可能な記憶面を project-scoped で確認する
5. non-trivial planning では TeamAgent / Task サブエージェントを使い、Product / Architecture / Security / QA / Skeptic など異なる視点で独立レビューする
6. source code changes を含む plan では lint / formatter baseline を確認し、未設定なら setup task を先行させる
7. 中立的な採点レビューを出し、Required / Recommended / Optional / Reject に分類する
8. `$easy` 形式で、提案内容・理由・どうなるのかを報告する
9. 採用する案だけを root `spec.md` / Plans.md / test task へ落とし込む

### create — 計画作成

See [references/create.md](${CLAUDE_SKILL_DIR}/references/create.md)

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

**フロー**:
1. 会話コンテキスト確認（直前の議論から抽出 or 新規ヒアリング）
2. 何を作るか聞く（max 3問）
3. **計画品質チェック**（最新情報、既存仕様、記憶、TeamAgent / サブエージェント複数視点レビュー、採点）
4. 技術調査（WebSearch）
5. 機能リスト抽出
6. **spec.md / Plans.md 二正本チェック**（Spec delta または Spec skip reason + Plans.md task）
7. 優先度マトリクス（Required / Recommended / Optional / Reject）
8. TDD 採用判断（テスト設計）
9. Plans.md 生成（`cc:TODO` マーカー付き）
10. 次のアクション案内

### spec.md / Plans.md 二正本チェック（デフォルト）

Plans.md は「やるべきこと」の task contract、root `spec.md` は「何が正しいか」の product contract として扱う。
co-required planning output は両方の出力を必須にするという意味であり、precedence は `spec.md > sub-spec > Plans.md` のまま維持する。
実装がぶれる可能性がある時は、Plans.md 生成前に root `spec.md` を更新する。
`create` と product-impacting `add` は毎回 root `spec.md` を読む。

優先する保存先:

1. root `spec.md`
2. consumer repo に root `spec.md` がない時だけ、既存の project spec / architecture / product compass
3. consumer repo に root `spec.md` がない時だけ、`docs/spec/00-project-spec.md`
4. 既存規約がある repo では、その規約に沿った spec path

作成/更新が必要な条件:

- ユーザーに見える振る舞い、API、データモデル、権限、課金、外部連携を決める task
- 複数の実装方針があり、選び方で product behavior が変わる task
- 過去または今回の会話で「仕様が曖昧で実装がぶれた」兆候がある task
- Plans.md には作業内容があるが、project としての正解条件が安定文書にない task

不要な条件:

- typo、format、dependency bump、README/CHANGELOG のみ
- 動作変更なしの狭い refactor
- 既存 spec とテストで正解が十分に固定されている修正

出力契約:

- `Spec delta`: product contract を更新する時に、対象 spec path と変更点を書く
- `Spec skip reason`: product contract を更新しない時に、理由を書く
- `Spec delta` / `Spec skip reason` は Harness が生成し、consumer は承認・修正だけ行う
- docs-only / mechanical task でも `Spec skip reason` を task context / sprint contract に残す
- missing search result、unavailable memory、未読ファイルを absent と断定しない。`not_observed != absent`
- ユーザーに spec を一から書かせない。agent が既存 spec と入力から最小 delta を作り、曖昧な時だけ判断分岐を出す

参照:

- `docs/plans/spec-ssot.md`

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

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

優先順位は次の通り:

1. 未完了タスクが 1 件だけ、または最初の 1 件だけ始めるのが自然
   - 起動コマンド: `claude`
   - 最初の入力: `/harness-work <task番号>`
2