plan-features

目的

このスキルを使って、議論で生まれたプロジェクトの意図を、持続性のある設計と順序立てた作業に落とし込みます。Beads は進行中の機能／タスクの状態を管理します。design.md は機能の詳細な意図を管理します。planned-features.md は簡潔な人間向けロードマップとして維持します。機能選択に決定論的なリゾルバーを使えるよう、<core-dir> はインストール済みの ../dstack-core スキルディレクトリとして解決します。

起動時のバージョン情報

プロジェクトの計画状態を作成または更新する前に、plan-features について ../dstack-core/references/SKILL-VERSION.md の手順に従ってください。読み取り専用のプロジェクト調査の後、出力された正確な1行を取得し、変更前に計画への回答、または選択した Beads／設計の証跡に含めてください。結果が stale の場合は npx skills update を促します。unavailable の場合は、最新であるとの主張ができないことを記録しますが、オフラインでの作業は妨げません。

入力

ユーザーの依頼と、以下を併せて使用します。

• bd prime、現在の機能ルート、着手可能な作業、ブロックされている作業；
• docs/src/SUMMARY.md と、そこからリンクされているページ；
• docs/src/planned-features.md；
• 既存の機能設計と実装済み機能の記録；
• 既存プロジェクトを改善する際の、現在のコード、テスト、設定、アーキテクチャに関する証跡。

出力

以下を作成または更新します。

• Beads の機能ルート、ライフサイクルのステップ、実装子タスク、依存関係；
• docs/src/planned-features.md；
• 近日着手する機能、または十分に理解された機能の docs/src/features/<slug>/design.md；
• 持続性のある方針を定めるために必要な、プロジェクト固有の読者向けページ；
• ナビゲーションを変更する場合は docs/src/SUMMARY.md。

実行

1. プロジェクトの状態を読み込む

以下を実行します。

bd prime
bd list --all --type epic --label workflow:feature --json --limit 0
bd ready --json
bd blocked --json

詳細ページを選ぶ前に、ドキュメントの目次を読みます。計画の対象範囲に関連するプロジェクト固有のページと、関連する完了済み機能の記録および設計のみを読みます。

2. 計画への入力を整理する

計画への入力にトランスクリプト、会議のメモ、以前のエージェントセッションが含まれる場合は、決定事項を時系列順に処理します。

• 後から示された明示的なユーザーの決定を、それ以前の提案より優先します；
• 置き換えられた名前、ペイロード、依存関係、制約は引き継がず、履歴として扱います；
• リポジトリ上の観察事項と、持続性のあるプロダクトの意図を区別します；
• 持続性のある各決定を、ロードマップだけでなく、影響を受けるすべての design.md に記載します；
• 解決されていない矛盾は、都合のよい解釈を選ばず、質問として記録します。

3. 設計に関する質問を繰り返す

一度に1つ、的を絞った質問をします。回答によって以下が変わる質問を優先します。

• ユーザー、オペレーター、インテグレーター、メンテナーの成果；
• 機能の境界と対象外の事項；
• 所有権、データ、状態、ライフサイクル；
• アーキテクチャ、連携、信頼境界；
• 障害、復旧、サポート、展開、互換性に関する動作；
• 読者向けの正確なドキュメントページ；
• 検証と受け入れ条件；
• 依存関係の順序と並列化。

実装タスクを割り当てるすべての機能について、明確な成果、明示的な境界、既知の依存関係、正確なドキュメントへの影響、各タスクをプロダクト方針の選択なしに実行できるだけの設計意図が明らかになるまで続けます。提案する各タスクを明示的に監査します。実装エージェントは、動作、スキーマ、UX、互換性、依存関係、所有権、展開に関する方針をユーザーに尋ねずに、受け入れ条件を満たせる必要があります。

タスクの実装や受け入れ条件を大きく変える可能性のある決定は、すべてこの段階で質問します。未確定事項を保留中の決定として記録できるのは、計画中のどのタスクも妨げず、変更もしない場合に限ります。その場合は、決定の責任者と再検討するきっかけを明記します。実装可能な設計には、タスクで必要となる未解決の決定があってはなりません。ユーザーが質問の確認ループを終える前に計画を終了した場合、未解決の範囲についてタスクを作成せず、計画が未完了であることを報告します。

4. 機能を分割する

独立して価値があり、レビュー可能な機能を作成します。1つの項目に無関係な成果、担当範囲、移行、または運用上のリスクが混在している場合は、作業を分割します。アーキテクチャ上の不確実性を解消する、または後続の複数の機能を可能にする機能を優先して早期に実施します。

小文字でファイルシステム上安全なスラッグを、安定した機能識別子として使用します。他の機能ですでに使われているスラッグは使用しません。ドキュメントとロードマップ上の順序は明示し、識別子には含めません。

成果、境界、依存関係、検証、ドキュメントへの影響が明らかになったら、長期的に維持できる設計とライフサイクルを作成します。それらが未確定のままの場合は、機能をロードマップのみの状態にしておき、実装タスクは作成しません。ネイティブの計画では、ユーザーの決定が未確定であることを実装上のブロッカーとして扱ってはいけません。このような未確定事項を一時的に残せるのは、インポートされた移行作業のみです。

5. ドキュメント構成を設計する

読者が知りたいことに応じて、具体的なページを選びます。

• Introduction：目的、対象読者、範囲、境界。
• Architecture：構造、担当範囲、相互作用、不変条件、長期的な決定。
• Operator's Manual / Usage：該当する場合、デプロイ、設定、可観測性、運用、保守、復旧、トラブルシューティング。
• Development Guide：ビルド、テスト、拡張、移行、保守。
• Reference：厳密なコマンド、設定、インターフェース、スキーマ、フィールド、状態、デフォルト、制限、用語、受け入れ条件。

そのトピックをすでに扱っているページがあれば、再利用します。新たな長期的な読者ニーズには、対象を絞ったページを作成します。新しく作成したページはすべて docs/src/SUMMARY.md に登録します。

6. 機能設計を作成する

機能ディレクトリを作成し、以下を基に design.md の草案を作成します。

docs/src/features/_template/design.md

具体的なユーザーの表現、例、制約、却下された方向性、計画上の決定を保持します。作成した各設計を docs/src/SUMMARY.md の機能設計マーカーの間に登録し、ロードマップと監査用のリンクがレンダリングされたブック内で解決されるようにします。Documentation Impact では、正確なファイル名を挙げ、計画された各変更を実装用の bead に割り当てます。

7. Beads のライフサイクルを作成する

長期的な設計を進める準備ができた各機能について、リポジトリの式を展開します。

bd mol pour dstack-feature \
  --var feature_name="<title>" \
  --var feature_slug=<slug> \
  --var design_path=docs/src/features/<slug>/design.md \
  --var implemented_path=docs/src/features/<slug>/index.md \
  --var base_branch=<base> \
  --json

返されたルートが機能エピックです（展開された molecule はワークフローの意味を持つエピックです）。そのルートには workflow:feature ラベルをちょうど1つ付けます。ライフサイクルタスクと実装タスクは子孫として配置し、それぞれ固有のラベルを使用します。識別情報は直ちに正規化して記録します。別のリポジトリで実装する作業では、そのリポジトリの base_branch とともに、implementation_repository と implementation_path を明示的に設定します。

bd update <root-id> \
  --type epic \
  --title "<title>" \
  --add-label workflow:feature \
  --spec-id docs/src/features/<slug>/design.md \
  --set-metadata feature_slug=<slug> \
  --set-metadata feature_name="<title>" \
  --set-metadata design_path=docs/src/features/<slug>/design.md \
  --set-metadata implemented_path=docs/src/features/<slug>/index.md \
  --set-metadata base_branch=<base> \
  --set-metadata implementation_repository=<repository> \
  --set-metadata implementation_path=<absolute-or-repo-relative-path>

ライフサイクル ID は bd mol show <root-id> --json で一度だけ解決し、その後、後続のエージェントが bd show <root-id> --json のみで取得できるように、ルートに保存します。

bd update <root-id> \
  --set-metadata design_id=<id> \
  --set-metadata review_specification_clarity_id=<id> \
  --set-metadata review_execution_readiness_id=<id> \
  --set-metadata spec_reconcile_id=<id> \
  --set-metadata implementation_id=<id> \
  --set-metadata docs_reconcile_id=<id> \
  --set-metadata validation_id=<id> \
  --set-metadata review_implementation_integrity_id=<id> \
  --set-metadata review_delivery_integrity_id=<id> \
  --set-metadata delivery_id=<id> \
  --set-metadata workflow_kind=molecule

Beads は構造化メタデータ内の式変数を置換しません。ライフサイクル ID を解決した後、すべてのライフサイクルタスクに具体的な識別情報とパスのメタデータを設定します。{{variable}} の値を残してはいけません。

for lifecycle_id in \
  <design-id> <review-specification-clarity-id> <review-execution-readiness-id> \
  <spec-reconcile-id> <implementation-id> \
  <docs-reconcile-id> <validation-id> <review-implementation-id> <review-delivery-integrity-id> <delivery-id>
do
  bd update "$lifecycle_id" \
    --set-metadata feature_slug=<slug> \
    --set-metadata feature_name="<title>" \
    --set-metadata design_path=docs/src/features/<slug>/design.md \
    --set-metadata implemented_path=docs/src/features/<slug>/index.md \
    --set-metadata base_branch=<base>
done

ライフサイクルの作成が完了するのは、bd show <root-id> --json がエピックを示し、必要なライフサイクル ID をすべて含み、各 ID が意図した子タスクを参照し、ルートまたはライフサイクルのメタデータ値に式のプレースホルダーが含まれていない場合です。人間が使うセレクターがそのルートに解決されることも確認します。

uv run <core-dir>/scripts/resolve-feature.py <slug> --json

ロードマップの推奨事項やユーザー向けワークフローコマンドでは、不透明な Beads ハッシュを機能の主な参照として使用しないでください。監査可能性が必要な場合は、ルート ID をメタデータ、レポート、コミットの証跡に保持します。

移行されたレガシーのルートは、molecule ではなく通常のエピックである場合があります。インポーターは同じライフサイクル ID メタデータを保存するため、後続のスキルはどちらの形式でも同じインターフェースを使用できます。

8. 実装 Beads を作成する

ライフサイクル実装コーディネーターの下に、範囲が限定されたタスクを作成します。各タスクには、次の内容を含めます。

• 具体的な成果と限定されたスコープを 1 つ；
• 新たなユーザー判断を必要としない受け入れ基準；
• 関連する設計セクション；
• ドキュメントの正確な担当範囲；
• 検証コマンドまたは証拠；
• 実際の前提条件；
• 有用な場合は並列実行のメタデータ；
• 実用的なコミット境界。

用途に合う最も狭い Beads タイプを選びます。通常の範囲限定作業には task、既知の不具合には bug、明確な終了条件を伴う期間限定の実装事実調査には spike、保守作業には chore を使います。spec-reconcile の前に明示的なアーキテクチャ上または製品上の選択を解決する必要がある場合は、計画中に decision を記録します。その選択を、実装可能な状態の子タスクに先送りしてはいけません。明示的に管理されたユーザーストーリーのバックログにのみ story を使い、実行可能な作業として milestone を使ってはいけません。

階層には parent-child を、実際の前提条件には blocks を使います。独立した兄弟タスクは並列のままにします。すべての実装子タスクは、ライフサイクルの spec-reconcile ステップに依存させ、仕様レビュー前に実装可能な状態にならないようにします。ツリービュー以外でも内容が分かるよう、範囲限定タスクに名前を付けます。

<feature-slug> <task-key> — <concrete outcome>

すべてのライフサイクルタスクと実装タスクに feature_slug と feature_name を保存します。機能エピックを唯一の親／コンテナーとします。実装コーディネーターは、その下に範囲限定タスクを持つタスクゲートであり、2 つ目の機能エピックやマイルストーンではありません。

グラフを完成させる前に、TBD、未解決の選択肢、「決定する」「選択する」、または必須の製品動作を決める調査を含むネイティブタスクは、却下するか書き換えます。調査タスクで実装上の事実を収集できるのは、どのような結果になっても、すでに決定済みの契約に適合する場合に限ります。

9. 計画状態を完成させる

設計案と実装グラフができたら、ライフサイクルの設計ステップを完了します。

bd close <design-step-id> --reason "Planning Q&A complete; draft design and implementation graph created"

分離された 4 つのレビュー手順は、/start-feature で開始できる状態のままにします。

docs/src/planned-features.md を更新し、簡潔なロードマップの説明、正規の <slug> 機能参照、監査可能性のための Beads ルート ID、依存関係、設計へのリンク、順序付けの根拠、ステータスのスナップショットを記載します。詳細な意図は design.md に、最新の状態は Beads に記録します。

後続作業のワークツリーで必要になる場合は、計画ドキュメントをコミットします。コミットメッセージに機能ルート ID を含めます。

完了基準

ロードマップに一貫性があり、各機能が人間に分かりやすい名前の Beads エピック 1 つと、その下のライフサイクル／タスクで構成され、近い将来に着手する機能に安定したスラッグと設計があり、実装が範囲限定の作業に分解され、ドキュメントの正確な変更内容と検証が割り当てられ、すべてのネイティブ実装タスクが新たなユーザー判断なしに実行可能であれば、計画は完了です。未解決の判断によるブロッカーが許されるのは、/migrate-workflow で取り込んだ作業のみです。その場合、明示的な調整の出所を記録する必要があります。

ハッシュを手動でコピーせず、Beads から推奨機能を選択します。

uv run <core-dir>/scripts/resolve-feature.py --next --json

ヘルパーの recommended_command（例：/start-feature conduit-rest-list-response-validation）を、人間向けの機能名およびルート ID とともに返します。Beads ID に文字を追加してはいけません。また、正規のスラッグまたは正確な機能名が利用できる場合、判読できない ID を推奨してはいけません。