# PRD: codiva

## 概要

codiva は、対象のGitリポジトリで起動する TUI アプリケーション。ユーザーが自然文で指示を投げるたびに、独立した git worktree 上で Claude Code セッション（Claude Agent SDK 経由）がバックグラウンド起動し、複数タスクを並列に進行させる。ユーザーは一覧画面で全セッションの進捗をリアルタイムに把握し、必要に応じて個別セッションに入って追加指示や許可応答を行う。

「指示を次々投げるだけで、並列に実装が進む」体験の提供が目的。

## ユーザーストーリー

1. **起動**: 開発者は対象リポジトリのルートで `codiva` を実行すると、TUI が立ち上がる。
2. **タスク投入**: 入力欄に「HogeHoge機能を実装してください」と入力して Enter を押すと、新しいセッションが作成され、即座に次の指示を入力できる（投入がブロックされない）。
3. **並列実行**: 各セッションは専用の git worktree + ブランチ上で動くため、互いのファイル変更が干渉しない。
4. **進捗一覧**: セッション一覧に以下がリアルタイム表示される:
   - タスク名（指示文の要約 or 先頭N文字）
   - 状態バッジ: `実行中` / `Step 4/7`（TODO進捗） / `質問あり` / `許可待ち` / `完了` / `失敗`
   - 動作時間（実際に動いた時間のみを換算。ユーザー操作待ち等の idle 時間は含めない）、ブランチ名
5. **セッション詳細**: 一覧からセッションを選択すると詳細ビューに入り、メッセージログの閲覧、追加指示の送信、許可要求への応答（許可/拒否）ができる。
6. **完了処理**: 完了したセッションの変更概要（diff stat）を確認し、ベースブランチへのマージまたは破棄（worktree削除）を選べる。
7. **終了**: アプリ終了時、実行中セッションは中断されるが、worktree とブランチは残る（作業内容は失われない）。

## 機能要件

### MVP（Phase 0〜5）

| ID | 要件 |
|----|------|
| F-1 | 対象リポジトリ直下で起動し、Gitリポジトリでない場合・コミットが1つもない場合はエラーメッセージを表示して終了する |
| F-2 | 指示文の入力ごとに worktree（`.codiva/worktrees/<slug>`）とブランチ（`codiva/<slug>`）を作成し、Agent SDK セッションを起動する |
| F-3 | セッション状態を SDK メッセージストリームから導出し、一覧に反映する（詳細は ARCHITECTURE.md の状態機械を参照） |
| F-4 | Claude が TodoWrite で管理する TODO リストから `Step n/m` 形式の進捗を表示する |
| F-5 | ツール使用の許可要求（canUseTool）を UI に表示し、ユーザーの許可/拒否をセッションに返す。応答までセッションはブロックされる |
| F-6 | 稼働中のセッションに追加のユーザーメッセージを送信できる（streaming input） |
| F-7 | Claude の応答が質問で終わった場合、`質問あり` 状態として表示する |
| F-8 | 完了セッションの diff stat 表示、ベースブランチへのマージ、worktree/ブランチの削除ができる |
| F-9 | キーボード操作のみで完結する（マウス不要） |
| F-10 | 対象リポジトリの `.codiva/prompt.md` にリポジトリ固有の追加指示（例: 「作業完了時に PR を出す」）を書け、全セッションの systemPrompt に自動注入される。ファイルが無ければ従来どおり無指示。CLAUDE.md（`settingSources` 経由）とは独立に両立する。ファイルは手で書くほか、一覧画面の `/prompt` コマンドから TUI 内で編集・保存できる（以降の新規セッションに反映） |

### MVP対象外（Backlog / Phase 6以降）

> 注: この節は MVP 策定時点の切り分け。以下のうち復元・コスト表示・設定ファイル・デスクトップ通知は
> Phase 6 で実装済み（`docs/ARCHITECTURE.md` の Phase 6 節を参照）。マウス操作も Phase 10 で追加され、
> F-9「マウス不要」は「マウス任意（無くても完結）」に緩和されている。未実装として残るのは他エージェント対応と複数リポジトリ管理。

- アプリ再起動後のセッション復元（SDK の `resume` を利用） … **実装済み（Phase 6）**
- Claude Code 以外のエージェント（Codex 等）対応 … 未実装
- 複数リポジトリの同時管理 … 未実装
- コスト（トークン/USD）表示 … **実装済み（Phase 6）**
- 設定ファイル（モデル選択、permissionMode カスタマイズ等） … **実装済み（Phase 6）**
- デスクトップ通知 … **実装済み（Phase 6）**

## 非機能要件

| ID | 要件 |
|----|------|
| N-1 | 同時 10 セッションまで実用的に動作する（セッションごとに Claude Code サブプロセスが1本立つ前提） |
| N-2 | ストリーミング出力による TUI の再描画で入力遅延を体感させない（描画スロットリング） |
| N-3 | コアロジック（core/ 配下）はユニットテストのカバレッジ 80% 以上 |
| N-4 | クラッシュ時にも worktree 上の作業内容が失われない（worktree は使い捨てにしない） |

## 前提・制約

- 実行環境: Node.js >= 20、macOS / Linux。ユーザーは `claude` CLI にログイン済み（または `ANTHROPIC_API_KEY` 設定済み）であること。
- 技術スタック: TypeScript (strict, ESM) + Ink 7 + @anthropic-ai/claude-agent-sdk。詳細は TECH_NOTES.md。
- worktree ディレクトリ `.codiva/` は対象リポジトリの `.git/info/exclude` に自動追記する（対象リポジトリの `.gitignore` を汚さない）。

## 成功基準（MVP受け入れシナリオ）

サンプルリポジトリで `codiva` を起動し:

1. 3件の指示を連続投入 → 3セッションが並列で動き、一覧に進捗（Step n/m）が表示される
2. うち1件で許可要求が発生 → `許可待ち` 表示 → 詳細ビューで許可 → 実行が継続する
3. 完了したセッションの diff stat を確認し、マージ → ベースブランチに変更が取り込まれ、worktree が削除される
4. 別の1件に追加指示を送信 → セッションが追加指示を反映して作業を続ける