roadmap

ロードマップ：軽量なプロジェクトアイデアトラッカー

gitignore 対象の ROADMAP.md で、プロジェクトの機能バックログを管理します。アイデアをすばやく記録し、PR やリリース後に進捗を追跡し、類似リポジトリから競合情報を収集し、定期的に見直して優先順位を適切に保ちます。

プロジェクト管理システムではありません。フェーズも、実行計画も、マイルストーンもありません。プロジェクトとともに変化する、シンプルなメモ帳です。

使用する場面

• プロジェクトの機能アイデア、ブレインストーミング、「もし〜だったら」という考えを記録する
• PR やリリースで公開されたアイデアを追跡する
• 競合または類似リポジトリを調査して、機能のヒントを得る
• アイデアのバックログを見直し、優先順位を付ける
• ROADMAP.md がないプロジェクト用に、新しい ROADMAP.md を作成する
• ユーザーが「ロードマップに追加して」「次に何を作るべき？」「競合は何をしている？」と言った場合

使用しない場面

• フェーズ、マイルストーン、実行計画を含む構造化されたプロジェクト管理
• タスクの依存関係を含むスプリントまたはイテレーションの計画
• コードレビューまたは PR レビュー — code-review を使用してください
• プロジェクトのドキュメントや README の作成 — update-docs を使用してください
• ROADMAP.md に記載されたバージョン番号やリリースのハイライト文の事実との食い違い — update-docs を使用してください。このスキルが管理するのは項目のステータスです。モード 2 では、リリース済みの [planned]／[exploring] 項目を「リリース済み」に移動します。ヘッダーのバージョンとハイライト文は update-docs が管理し、どの項目をリリース済みとするかはロードマップが管理します。
• バグやインシデントの追跡 — イシュートラッカーを直接使用してください

---

AI のセルフチェック

ROADMAP.md の作成または変更を行う前に、次の点を確認してください。

• Gitignore 対象：ROADMAP.md が .gitignore に含まれている（または、ユーザーが明示的に gitignore 対象外を選択している）
• シークレットなし：項目に API キー、内部 URL、機密性の高いビジネス情報が含まれていない
• 出典の明記：競合情報に、出典となるリポジトリまたはプロジェクトが記載されている
• 重複なし：新しいアイデアが既存の項目と重複していない（文言だけでなく意図を確認する）
• 形式を維持：既存のファイル構造に沿って編集し、ユーザーが変更を依頼していないセクションは再フォーマットしない
• リリース済み項目の出典：完了した項目に、関連する PR、リリース、またはコミットが記載されている
• 競合データの捏造なし：競合リポジトリに関する機能、イシュー数、ユーザー需要の主張には、実際のリンクまたは引用がある（推測ではない）
• 優先度の過剰設定なし：P0 項目は、願望ではなく本当に作業を妨げる要因である
• 根拠の質を明記：競合情報、ユーザーフィードバック、仮定には、出典と確度を記載する
• バックログの健全性を維持：古いアイデアは、際限なく優先順位を付け直すのではなく、保留または削除する
• 横断的なエージェントの衛生管理を適用する — references/agent-hygiene.md を参照

ロードマップの形式

セクション（順序固定）

すべての ROADMAP.md で、以下のセクションをこの順序で使用します。空のセクションは省略できますが、順序は変更できません。一貫性があるとファイルをすばやく確認できます。省略されていたセクションに内容を追加する場合は、既存のセクションに対する正式な位置に作成してください。

# Roadmap

> Project: {name} | Updated: {date} | Current: v{version}
> Local planning doc, gitignored. Not a commitment.

## Snapshot

{1-2 paragraphs: project state, what the next milestone means, current focus}

## Exit Criteria

What "done" means for the next milestone. Each criterion has a verdict.

### {Criterion Name}

**Verdict**: Pass | Fail | Partial

- {Requirement}
- {Requirement}

## Now - P0

Blocks the next milestone or release. Active work only.

- [in-progress] {Description} - {area} | PR #{n}
- [planned] {Description} - {area}

## Next - P1

Committed direction. Happens after Now is clear.

- [planned] {Description} - {area}
- [exploring] {Description} - {area}

## Later - P2

Good ideas, no timeline. Revisit during review.

- {Description} - {context}

## Experiments

Low confidence. Build only with real demand signal.

- {Description} - {what would validate it}

## Shipped

### v{X.Y.Z} ({date})

- ~~{Description}~~ - {area} | PR #{n}, v{X.Y.Z} ({date})

## Competitive Intel

### {owner/repo}

- {Feature} ({strong signal | weak signal | noise}) - {evidence}
- User demand: {issue links, discussion quotes, vote counts}

## Parked

Items deferred with reason.

- {Description} - {reason for parking}

項目の形式

項目は、配置場所に応じて 2 つの階層に分かれます。

アクティブな項目（Now、Next） — ステータスと追跡情報を含む構造化された形式：

- [status] Description - area | tracking

ステータスの値：exploring、planned、in-progress

Area の値は、コンポーネントまたはドメインを示すプロジェクト固有の略称です（例：ui、api、backend、infra、docs、auth）。プロジェクトの構造から判断してください。不明な場合は推測せず、area を省略してください。

バックログ項目（Later、Experiments） — 簡潔で、すばやく記録できる形式：

- Description - context or source

昇格に伴い、項目に構造を追加します。Later にある簡単なアイデアは、Next に移動した時点で追跡対象の項目になります。

リリース済み項目には、必ず出典を記載します。

- ~~Description~~ - area | PR #N (or MR #N), vX.Y.Z (date)

ROADMAP.md がすでに存在する場合

まず既存の構成を確認します。この形式と一致しない場合は、次のように対応します。

• 追加モードまたは更新モードでは、既存の構成に沿って作業し、構成を変更しません
• レビューモードでは、現在の構成が整理されていない場合、この形式への移行を提案します
• ユーザーから構成変更の依頼があった場合は、すべての内容を保持しながら、セクションごとに移行します

---

優先順位付けの実践

• 優先順位付けの意味が保たれるよう、対応中の P0/P1 項目を絞ります。
• 重複するアイデアはまとめ、長いメモを繰り返しコピーする代わりに、根拠へのリンクを記載します。
• 近いうちに対応する各項目を、明確なユーザー、ビジネス、または技術上の成果に結び付けます。
• 実装を始める前に、完了条件を記録します。
• 確約事項と実験を分け、推測に基づく作業でデリバリーが圧迫されないようにします。

---

ワークフロー

ステップ 0：アクティビティの検出（呼び出しのたびに実行）

ロードマップの状況を報告する前に、利用可能なリポジトリルート、ROADMAP.md、無視ルール、README、および主要なパッケージ／プロジェクトのメタデータを確認します。確認できた状態、存在しない状態、利用できない状態を区別し、リポジトリを確認できない場合に、ロードマップが存在しない、または無視されていると推測してはいけません。利用できなかったプロジェクトの情報を明記します。

ROADMAP.md がまだ存在しない場合、またはアクティビティのクエリが成功し、最近のアクティビティが見つからなかった場合は、リマインダーを省略します。クエリの失敗は、根拠が利用できないこととして報告します。

それ以外の場合は、最近のプロジェクトアクティビティを確認します。

command -v gh; command -v glab   # forge CLI: gh (GitHub), glab (GitLab), or git-only
# GitHub
gh pr list --state merged --limit 10 \
  --json number,title,mergedAt
# GitLab
glab mr list --merged --per-page 10

# Always available (portable - no GNU date required)
git tag --sort=-creatordate | head -5
git log --oneline --since="2 weeks ago" | head -15

gh も glab も利用できない場合は、「PR の追跡は利用できません。すべてを追跡するには gh または glab をインストールしてください」と一度だけ伝え、git のデータ（タグとコミット）のみで続行します。

マージ済み PR や新しいリリースが未対応のロードマップ項目に該当するようであれば、作業を続ける前に簡潔に伝えます。

「お知らせです。前回のロードマップ更新以降、PR #142 と v0.15.0 が取り込まれました。 まずこれらを完了扱いにしますか？ それとも、依頼されたモードで続けますか？」

作業を止めてはいけません。ユーザーから反応がなければ、依頼された作業を続けます。

---

モード 1：アイデアの追加（デフォルト）

適用条件：ユーザーがプロジェクトにアイデアを提示した場合、「ロードマップに追加して」と依頼した場合、または機能について説明した場合。

ステップ 1：必要に応じて初期設定する

1. プロジェクトルートに ROADMAP.md が存在するか確認します（モノレポでは、ユーザーがパッケージを指定していない限り git ルートを既定とします。ROADMAP.md が複数ある場合はユーザーに確認します）。
2. 内容を書き込む前に、ユーザーが明示的に追跡を選択していない限り、/ROADMAP.md が無視対象になっていることを確認します。必要に応じて、次を追加します。

   # Project roadmap (local planning doc)
   /ROADMAP.md
   

   git check-ignore --no-index ROADMAP.md で確認し、git ls-files --error-unmatch ROADMAP.md も実行します。すでに追跡されているファイルは、無視ルールを追加しても追跡されたままです。ユーザーに知らせず追跡を解除してはいけません。
3. ファイルが存在しない場合は、スターター構成を使って作成します。README または主要なマニフェストを読み、実際の情報に基づいて Snapshot を記入します。追加した無視ルールがあれば報告します。

ステップ 2：アイデアを整理して配置する

ユーザーの入力から、実行可能な項目を抽出します。各アイデアについて、次のようにします。

• 明確で簡潔な説明を書きます（ユーザーの言葉遣いは保ち、不明瞭な部分だけ整えます）。
• 適切な優先度の区分に配置します（本当に判断が難しい場合は質問し、特に指示がなければ P1 とします）。
• アイデアの出所、実現できること、言及された制約などの背景を追加します。

適切なセクションに追記します。既存の項目の順序は変更しません。

ステップ 3：競合状況の調査を提案する

ロードマップに競合情報のセクションがなく、今回が最初のアイデア追加の場合は、次のように質問します。

「{project-name} に役立ちそうな機能のアイデアを探すため、類似リポジトリを調査しましょうか？」

この質問はセッションごとに一度だけ行います。断られた場合は、再度質問しません。

---

モード 2：更新／完了扱い

適用条件：ユーザーが「ロードマップを更新して」と依頼した場合、項目を完了扱いにするよう求めた場合、または PR のマージ後／リリース後。

ROADMAP.md が存在しない場合は、まずモード 1（初期設定）に案内します。

次のチェックリストをコピーし、進捗を記録します。

• ステップ 1：最近のアクティビティを収集した（または指定された PR を取得した）
• ステップ 2：該当項目を提示し、確認を得た
• ステップ 3：確認済みの項目を出典情報とともに Shipped に移動し、ヘッダーの日付を更新した
• ステップ 4：ファイルを再読した。確認済みの項目が対応中の優先度区分に残っている、または出典情報がない場合は修正し、ステップ 4 に戻った

Step 1: 最近の活動を収集する

# Always available (portable - no GNU date required)
git log --oneline --since="2 weeks ago"
git tag --sort=-creatordate | head -5

# GitHub
gh pr list --state merged --limit 20 \
  --json title,number,mergedAt
# GitLab
glab mr list --merged --per-page 20

ユーザーが期間を指定した場合は、期間を調整します。ユーザーが特定の PR を直接指定した場合（例：「PR #45」）は、期間で絞り込んだ一覧に頼らず、gh pr view 45 --json title,mergedAt（または glab mr view 45）を使って取得します。

Step 2: 活動をロードマップの項目に照合する

コミットメッセージ、PR タイトル、リリースノートを、未完了のロードマップ項目と比較します。 意味的に照合します。「ダークモードのサポートを追加」は「ダークモードのテーマオプション」に一致します。

変更を加える前に、該当候補をユーザーに提示します。

次の候補が見つかりました：

• PR #142「ダークモードの切り替えを追加」->「ダークモードのテーマオプション」（P1）に一致
• v0.15.0 リリースにバックアップ／復元が含まれる ->「バックアップと復元」（P0）に一致

これらにチェックを付けますか？

Step 3: ファイルを更新する

ユーザーがすでにどの項目がリリースされたかを明示している場合（例：「PR #45 でダークモードを追加」）、確認済みとして扱います。「チェックを付けますか？」と再度尋ねるのではなく、予定している変更を確認用に提示します。

確認済みの一致項目について：

1. 取り消し線を適用します：~~description~~
2. Item format にあるリリース済み項目の形式で出典を追加します：- area | PR #N, vX.Y.Z (date)（PR とリリースの両方が該当する場合は、両方を含めます）
3. 「Shipped」セクションに移動します（存在しない場合は作成します）。バージョンまたは日付ごとにまとめます。

ヘッダーの Updated: の日付を更新します。

Step 4: 編集内容を確認する

ROADMAP.md を読み直します。確認済みの各項目が「Shipped」配下に PR またはリリースの出典とともに一度だけ記載され、未確認の項目には変更が加えられていないことを確認します。漏れがあれば修正して、この手順を繰り返します。

---

Mode 3: 競合調査

トリガー：ユーザーが競合の調査を依頼する、リポジトリ URL を提示する、または Mode 1 の提案を受け入れる。

対象の選定、forge CLI コマンド、厳密な適合性フィルタリング、承認フロー、Competitive Intel の書式については、references/competitive-scan.md を読みます。

Mode 3 では、対象を限定しリアクション数順に並べた forge クエリ、またはその forge でリアクション数による並べ替えができない場合は、同等の方法を記録したものが必要です。リポジトリサイズに合わせて、基準に記載された強い候補／弱い候補／ノイズのしきい値を適用し、すべての候補に出典を付けて、書き込む前に候補をユーザーに提示して承認を得ます。

---

Mode 4: レビュー／優先順位付け

トリガー：ユーザーがロードマップのレビューや優先順位付けを依頼する、または「次に何に取り組むべきか」と尋ねる。

Step 1: 読み込みと要約

ROADMAP.md を読みます。次の内容を要約して提示します。

• 優先度ごとの項目数
• 現在進行中の項目（記録されている場合）
• 最近リリースされた項目
• 古い項目：60 日以上更新されていない項目は、アーカイブまたは優先順位の再検討の候補です（項目ごとの日付または記録された履歴を使用します。git blame では無視されたファイルの日付を特定できず、ファイルの mtime から個々の項目の経過日数を判断することはできません）

Step 2: 対応策を提案する

現在の状況に基づいて、次のいずれかに該当するものを指摘します。

• 取り組まれていない P0 項目 - 緊急であるはずです。説明または優先度の引き下げが必要です
• 60 日以上更新されていない項目 - 理由を添えて保留するか、優先度を上げます。放置しても優先事項にはなりません
• 関連項目が複数の優先度に分散している - まとまりのある取り組みとしてグループ化します
• リリース済みの項目がアクティブなセクションに残っている - 「Shipped」に移動します
• 構成が不足している - 整理方法の改善を提案します

Step 3: 構成の改善を提案する

ロードマップの構成が不明確な場合は、次の改善を提案します。

• すべてが単一のリストになっている場合に、優先度別の区分を追加する
• プロダクト開発とプロモーション／市場投入を分ける
• プロジェクトの状況を示す「Snapshot」セクションを追加する
• 主要なマイルストーンに終了条件を追加する
• 確信度の低いアイデア向けに「Experiments」セクションを作成する

提案を提示します。ユーザーが承認したものだけを適用します。

Step 4: 変更を適用する

ユーザーの承認を得て、項目を整理し、優先順位を変更し、保留または削除します。黙って削除してはいけません。理由を添えて Parked に移動するか、削除について明示的に確認します。

---

参照ファイル

• references/trigger-integration.md - Claude Code のフック、GitHub Actions、git フックのオプションの自動トリガー設定です。組み込みのアクティビティ検出の代わりに、またはそれに加えて、プッシュを起点とするロードマップの更新をユーザーが希望する場合に参照してください。
• references/competitive-scan.md - 競合・リポジトリのスキャンワークフロー、エビデンスのしきい値、ROADMAP.md の Competitive Intel の書式について説明しています。

出力要件

要件の全文は references/output-contract.md を参照してください。

• スキル名: ROADMAP
• 成果物の保存先: deliverables
• モード: 条件付き。既存のロードマップの分析、レビュー、監査、改善（例：「自分の ROADMAP.md をレビューして」）を依頼された場合は、references/output-contract.md のレポートの分量とエビデンスに関するルールを適用し、成果物を docs/local/deliverables/roadmap/<YYYY-MM-DD>-<slug>.md に書き込みます。ロードマップの作成または更新（主なモード。ユーザーの作業ディレクトリにある ROADMAP.md に書き込みます）を依頼された場合は、要件に縛られずに応答します。作成モードの出力先は docs/local/ ではなく、作業ディレクトリの ROADMAP.md です。
• 重大度: P0 | P1 | P2 | P3 | info（共有要件を参照。監査・レビューモードでのみ使用します）。

関連スキル

• 競合スキャン（モード 3）では、Web 取得だけでは不十分な場合に、ホストのブラウジングツールを使用して競合のリポジトリやドキュメントを読み取ります。
• git - 更新モード（モード 2）では、出荷済みの作業と照合するために git の履歴と PR データを読み取ります。
• code-review - コードの正確性をレビューします。このスキルは何を構築するかを追跡し、code-review はそれを実装するコードを評価します。
• update-docs - プロジェクトのドキュメントを更新し、ヘッダーのバージョンとリリースのハイライト文が事実から乖離していないか ROADMAP.md を監査します。このスキルは優先順位付け、情報の記録、競合情報、項目のステータスを担当します（モード 2 では、出荷済みの項目をアクティブな優先度層から移動します）。update-docs は、記載されたバージョンとハイライト文が HEAD と同期した状態を保つ役割を担います。

ルール

1. デフォルトで gitignore に追加します。 ROADMAP.md を作成または書き込む前に、.gitignore に含まれていることを確認してください。ユーザーが git で追跡するよう明示的に依頼した場合に限り、この手順を省略します。
2. 競合情報の出典を明記します。 他のリポジトリから得たアイデアには、すべて出典タグを付けます。外部の機能を独自のアイデアとして提示してはいけません。
3. チェック済みにする前に確認を求めます。 一致する項目を提示し、ユーザーに確認してもらいます。曖昧な一致だけを根拠に、ロードマップの項目を自動で完了にしてはいけません。
4. ヘッドレスモード。 非対話型のコンテキスト（--bare、Cursor Automations、Codex exec）では、確認プロンプトを省略し、モード 2 では完全一致する項目だけを適用し、モード 3 では強いシグナルがある項目だけを追加し、モード 1 では競合スキャンを提案しません。