Levix-Digital/plan-memory

📐 プロジェクト計画メモリスキル (plan-memory)

パス: <skills_root> はこのスキルが含まれるフォルダ（この SKILL.md のフォルダの親）です。コマンド実行時は実際の絶対パスを使用してください。

plan-memory スキルは、プロジェクトの 100% 完全で圧縮されていないアーキテクチャ計画、戦略的ロードマップ、およびマルチステップの設計図 を保持し、プロジェクトに携わる全員で共有します。

• 信頼できる情報源: プロジェクトリポジトリ内の docs/plans/<plan_id>.md にある、計画ごとに1つの Markdown ファイル（YAML フロントマター + 計画本文）。計画はバージョン管理され、レビューされ、コードとともにマージされます。フォルダはプロジェクトの .dev-cycle.json の "plans_dir" で変更できます。
• 検索インデックス: ~/.ai-code-agent-memory/plan-memory/db にあるローカルの ChromaDB（PLAN_MEMORY_DB で上書き可能）、コレクション名は plan_index。これは 使い捨て可能 です。すべてのコマンドはファイルから（SHA-256 によって）インデックスを同期し、rebuild_index（エンジン）で再作成します。
• プロジェクト: カレントディレクトリ（または --dir）の Git リポジトリから解決されます。.dev-cycle.json の project_name、存在しない場合はリポジトリフォルダ名をケバブケースに正規化したものを使います。--project で上書きできます。
• レベル: バックログ（docs/BACKLOG.md）は、発見作業なしで作業を秒単位で捕捉し、エピックの下にグループ化します。ロードマップ（docs/ROADMAP.md）はリリースを順序付け、アイテムを割り当てます。計画は、ユーザーがバックログアイテムを昇格させたときに作成され、発見と計画を保持します（「バックログ」および「ロードマップ」を参照）。
• Spec Kit エンベロープ: プロジェクトが Spec Kit を使用する場合、機能計画は Spec Kit フォルダ（specs/NNN-slug/）のエンベロープ（spec_dir）であり、詳細を保持します。検索、ドリフト検出、get_plan は、計画とともにフォルダの成果物を読み取ります（「Spec Kit を使用した計画」を参照）。
• 基本原則: ゼロ圧縮 / ゼロ損失。計画は（Mermaid 図、表、手順、数式、根拠を含めて）完全に保存され、すべての開発者とセッションに対する永続的な知識となります。

---

🏛️ 計画ファイル形式

---
plan_id: my_app_blueprint_v1_2_0_two_stage_search
project: my-app
title: Two-stage search with local re-ranking
kind: feature              # feature (default) | bug
version: v1.2.0
status: in_progress        # draft | planned | active | in_progress | completed | superseded
author: Jane Doe           # git user.name of whoever created it
created_at: '2026-10-15T16:36:00'
updated_at: '2026-10-16T09:10:00'
session_id: 8abbc3bf-...   # conversation where the plan was conceived (optional)
tags: [search, reranker]
supersedes: my_app_blueprint_v1_1_0_search
superseded_by: null
parent_plan_id: null
backlog_items: [FEAT-004]  # backlog items the plan delivers (optional)
spec_dir: specs/004-reranker  # Spec Kit folder with the plan's detail (optional)
milestones:
- name: M1 Runtime base
  done: true
  done_at: '2026-10-15'
  by: Jane Doe
- name: M2 Reranker
  done: false
status_log:
- at: '2026-10-15T16:36:00'
  by: Jane Doe
  status: active
  note: Plan created
---

# Plan title

...full plan body in Markdown...

• スクリプトは フロントマターのみを書き換えます。本文は save_plan によって一度書き込まれるか（または手動で編集されます）。マイルストーンとステータスの変更は、小さく読みやすい差分を生成します。
• ファイル名は計画 ID です。系統フィールド（supersedes、superseded_by、parent_plan_id）は他の計画 ID を参照します。
• スクリプトは決してコミットしません。 エージェントは、計画ファイルをそれが記述する作業とともにコミットします（「チームワークフロー」を参照）。

---

⚙️ コマンド

すべてのスクリプトは <skills_root>/plan-memory/ にあり、--dir <project dir>（デフォルト: カレントディレクトリ）と --project <name> を受け付けます。

1. 計画の保存/更新（系統付き）（save_plan）

docs/plans/<plan_id>.md に計画全体を、カットや要約なしで書き込みます。既存の ID を保存すると、タイトル、本文、フィールドが更新され、作成者、作成日、マイルストーンの進捗は保持されます。--supersedes は古い計画を superseded とマークします。save_plan はネイティブエンジンで実行されます。sh シェル（Linux、macOS、Git Bash）の場合:

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory save_plan \
  --title "Integrated Roadmap: Python -> Rust, Model Router & Model Kit" \
  --file "path/to/plan.md" \
  --version "v1.2.0" \
  --tags "roadmap,rust_refactor,model_router" \
  --milestones "Priority 1,Priority 2,Milestone 3" \
  --status "active" \
  --session-id "<session_id>" \
  --supersedes "<old_plan_id>"

PowerShell の場合は、代わりに & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory save_plan [arguments] を実行してください。 オプション: --id（デフォルト: <project>_<title> のスラッグ）、--parent-id、--file の代わりに --content、--kind feature|bug、--backlog-items "BUG-001,FEAT-002"（アイテムをリンクし、planned 状態にします）、--spec-dir specs/NNN-slug（計画はその Spec Kit フォルダのエンベロープになります）。

2. マイルストーン＆進捗トラッカー（check_milestone）

check_milestone はネイティブエンジンで実行されます。sh シェル（Linux、macOS、Git Bash）の場合:

# 最新のアクティブな計画（または --id <plan_id>）の進捗とチェックリスト:
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --list

# マイルストーンを完了としてマーク（日付と作成者を記録）:
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --milestone "Priority 1" --notes "Completed via PR #319"

# マイルストーンを保留に戻す:
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --milestone "Priority 1" --uncheck

PowerShell の場合は、代わりに & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory check_milestone [arguments] を実行してください。 最初に完了したマイルストーンは、active 状態の計画を in_progress に変更します。最後のマイルストーンは completed に変更します。

3. アーキテクチャドリフト検出（detect_drift）

実装提案、課題、新しいプロンプトをアクティブな計画と比較します。意味的類似性、マイルストーンのカバレッジと順序、およびプロジェクト自身のアンチパターンルールをチェックします。detect_drift はネイティブエンジンで実行されます。sh シェル（Linux、macOS、Git Bash）の場合:

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory detect_drift --proposal "Priority 1: build the native ReAct orchestrator in Rust, replacing the Python LangGraph"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory detect_drift --file "path/to/proposal.md" --strict   # exit code != 0 on conflict

PowerShell の場合は、代わりに & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory detect_drift [arguments] を実行してください。

アンチパターンルールはプロジェクトの .dev-cycle.json の drift_rules キーにあります（--dir から上方向に検索されます）。ルールがない場合は、類似性とマイルストーンのみがチェックされます。

"drift_rules": [
  { "tech": "langchain", "conflict_msg": "The baseline plan removes LangChain." },
  {
    "tech": "parallel database",
    "negative_markers": ["single source", "settings.db"],
    "proposal_allow": [],
    "conflict_msg": "Proposal hints at a parallel database, violating the single source of truth."
  }
]

ルールは、有効な計画（active / in_progress）が tech を拒否マーカーとともに言及し、かつ提案が許可されたフレーズなしで tech に言及している場合に競合を発生させます。

• negative_markers（オプション）: 拒否を示す単語。デフォルト: remove、replace、without、forbidden、... およびそのポルトガル語相当語（既存の計画がまだ翻訳されていない間は保持されます）。
• proposal_allow（オプション）: 言及を許容可能にするフレーズ。デフォルト: without <tech>、remove <tech>、replace <tech>、... およびそのポルトガル語相当語。

4. 計画一覧（list_plans）

list_plans はネイティブエンジンで実行されます。sh シェル（Linux、macOS、Git Bash）の場合:

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory list_plans [--status active] [--kind bug]

PowerShell の場合は、代わりに & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory list_plans [arguments] を実行してください。

5. 完全な計画の読み取り（get_plan）

get_plan はネイティブエンジンで実行されます。sh シェル（Linux、macOS、Git Bash）の場合:

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory get_plan --id "<plan_id>"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory get_plan                  # latest active plan

PowerShell の場合は、代わりに & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory get_plan [arguments] を実行してください。

6. 意味検索（search_plans）

search_plans はネイティブエンジンで実行されます。sh シェル（Linux、macOS、Git Bash）の場合:

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory search_plans --query "how to implement the model router in chat" [--limit 5] [--all-projects]

PowerShell の場合は、代わりに & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory search_plans [arguments] を実行してください。

7. ライフサイクルステータスの更新（update_plan_status）

計画のステータスを設定し、ステータスログに記録し、リンクされたバックログアイテムをそれに合わせて更新します。update_plan_status はネイティブエンジンで実行されます。sh シェル（Linux、macOS、Git Bash）の場合:

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory update_plan_status --id "<plan_id>" --status "completed" --notes "Priority 1 and 2 delivered."

PowerShell の場合は、代わりに & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory update_plan_status [arguments] を実行してください。

8. エクスポート（export_plan）

計画を別の場所に、JSON または Markdown（フロントマターあり/なし）としてコピーします。export_plan はネイティブエンジンで実行されます。sh シェル（Linux、macOS、Git Bash）の場合:

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory export_plan --id "<plan_id>" --format json --output-dir "out/"

PowerShell の場合は、代わりに & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory export_plan [arguments] を実行してください。

9. インデックスの再構築（rebuild_index）

rebuild_index はネイティブエンジンで実行されます。sh シェル（Linux、macOS、Git Bash）の場合:

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory rebuild_index [--project <name>] [--dir <path>]

PowerShell の場合は、代わりに & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory rebuild_index [arguments] を実行してください。

---

📥 バックログ（backlog）

計画の最初のレベル: 1つの Markdown ファイル（.dev-cycle.json の backlog.file、デフォルトは docs/BACKLOG.md）。最初の add によって templates/BACKLOG_TEMPLATE.md から作成されます。

## Bugs | Features | Improvements | Adjustments | Epics | Closed

### BUG-001: Frontier preset selects an outdated model id
- **Severity**: high              # bugs: critical | high | medium | low
- **Status**: open                # open | planned | in_progress (done | dropped | duplicate | superseded under Closed)
- **Found**: 2026-10-16, v0.45.0, PR #333
- **Plan**: -                     # plan id once promoted
- **Description**: `/preset frontier` sets `claude-3-7-sonnet`, which the provider may reject.

機能（FEAT-NNN）、改善（IMP-NNN）、調整（ADJ-NNN）には Priority（high、medium、low）があり、Severity はありません。エピック以外のアイテムには - **Epic**: EPIC-NNN を付けることができます。エピック（EPIC-NNN、## Epics セクション）は、完全な製品のアイテムをグループ化します。Priority、Status（閉じられるまで open）、Found、Description を持ちます。Plan はなく、昇格されることもありません。昇格されるのはそのアイテムです。validate は、開いているエピックのアイテムがすべてクローズされている場合に警告します。ID は再利用されません。クローズされたアイテムは ## Closed の下に - **Closed**: ノート（日付とプルリクエスト、理由、duplicate of <ID>、または superseded by <ID>[, <ID>...]）とともに残ります。アイテムが、異なるより適切に定義されたアイテムに置き換えられた場合（発案後に分割または再形成されたアイデア）、それは superseded（取って代わられた）と見なされます。duplicate（重複）は、同じリクエストが2回捕捉されたものです。

backlog はネイティブエンジンで実行されます: sh シェル（Linux、macOS、Git Bash）の場合は "<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory backlog <command> [arguments]。PowerShell の場合は、代わりに & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory backlog [arguments] を実行してください。

タスク	コマンド
捕捉	backlog add --type bug|feature|improvement|adjustment|epic --title "<t>" --description "<d>" [--severity S] [--priority P] [--epic EPIC-NNN] [--found-in "v1.2.0, PR #12"]
失敗した手動テストの捕捉	backlog add --from-failed --run vX.Y.Z-rc.N [--severity S]
サマリー（新しい作業の前にまずバグ）	backlog summary [--json]
一覧表示、表示	backlog list [--type T] [--status S] [--epic EPIC-NNN] [--all] [--json]、backlog show <ID>
変更	backlog set <ID> [--title] [--description] [--severity] [--priority] [--status] [--plan] [--epic ID|-]
計画へ昇格	backlog promote <ID> [<ID> ...] [--title T] [--id PLAN_ID] [--version V] または --into <PLAN_ID>
クローズ	backlog close <ID> [--ref "PR #12"]、drop <ID> --reason R、duplicate <ID> --of <ID>、supersede <ID> --by <ID>[,<ID>...]、reopen <ID>
検証	backlog validate

• 捕捉のコストはゼロ: 発見も計画も不要。ユーザーは /backlog コマンドで行います。エージェントは、現在のスコープ外で見つけたバグに対して行います。
• 昇格は、templates/BUG_PLAN_TEMPLATE.md（すべてのアイテムがバグ: 再現手順、証拠と根本原因、修正設計、回帰テスト）または templates/FEATURE_PLAN_TEMPLATE.md から draft 状態の計画を作成し、アイテムをその Backlog items セクションにコピーし、双方向にリンクします。発見はその計画に書き込まれ、承認のために active として再度保存されます（マイルストーン付き）。
• リンクされたアイテムは計画に従う: 計画が draft または active の間は planned、進行中は in_progress、完了すると done としてクローズされます（エンジンの check_milestone と update_plan_status）。
• トリアージはユーザーの判断: エージェントは単独で昇格、ドロップ、または優先順位の再設定を行いません。
• スクリプトは決してコミットせず、読み取れない構造のファイルの書き換えを拒否するため、手動編集が失われることはありません。

---

🗺️ ロードマップ（roadmap）

納品順のプロダクトリリース（.dev-cycle.json の roadmap.file、デフォルトは docs/ROADMAP.md）。最初の add によって templates/ROADMAP_TEMPLATE.md から作成されます。