spec-writer

仕様書作成者

バンドル済みランタイム

以下の CLI 行を実行する前に、先頭の SSF を node "<plugin-root>/scripts/spec-superflow.mjs" に置き換えてください。<plugin-root> は、このファイルの 2 階層上にある絶対ディレクトリです。SSF を文字どおり実行したり、PATH 上の ssf を呼び出したりしないでください。

変更が探索段階を超えたら、計画アーティファクトを作成またはブラッシュアップしてください。

新しい計画済み変更

新しいリクエスト（状態もワークフローも自動設定されていない場合）、または workflow_variant planned の場合は、個々のアーティファクトの間で一時停止せず、proposal.md と tasks.md を続けて作成してください。提案には目標、対象範囲と対象外の範囲、受け入れ条件、リスクを記載し、タスクには順序付けした成果物と証明コマンドを記載します。永続的なシナリオが必要な動作に限り仕様を追加し、未解決のアーキテクチャ上の決定がある場合に限り設計を追加してください。execution-contract.md は作成せず、別の計画にタスクリストを重複して記載しないでください。

共有インターフェースを実際のソースと一度照合してから、問題、対象範囲、依存関係、証明方法を自己点検してください。この具体的な計画に承認がない場合に限り、承認を 1 回だけ求めてください。承認後、SSF workflow start <dir> --path planned --confirm --reason "<user decision>" を実行して実装を続けてください。途中の計画・橋渡し遷移や、独立したリーダーエージェントは使用しないでください。意味に関わる修正では、承認後に同じコマンドを使用してください。意味に関わらない修正では、実行の再同期を行い、失敗したレビューの履歴を保持してください。以降のセクションは、既存のレガシー変更にのみ適用されます。

必須入力

.spec-superflow.yaml（特に dp_0_decisions、dp_0_confirmed）と、既存の計画アーティファクトを読み込んでください。dp_0_confirmed が true でない場合は停止し、DP-0 のために workflow-start に戻してください。

設定の確認

実行します：SSF runtime config --get artifacts.order — 設定された順序（既定値：proposal → specs → design → tasks）で生成してください。artifacts.skip を指定して実行し、一覧に含まれるアーティファクトをスキップしてください。

アーティファクトの役割

• proposal.md：理由と対象範囲
• specs/：必須の動作（テスト可能）
• design.md：アーキテクチャ上の決定とトレードオフ（行単位ではない）
• tasks.md：依存関係を考慮した実装手順

作業ルール

DP-0 を順守する：dp_0_decisions を読み、確認済みの制約を尊重し、黙って対象範囲を広げないでください。未確認の決定があれば一時停止してください。

proposal.md

次の内容を必ず記載してください：確認された問題、変更内容、対象範囲と対象外の範囲、影響を受ける領域、完了の証明方法。「より良い」「堅牢」「効率的」などの中身のない形容詞より、具体的な事実を優先してください。

specs/

すべての要件はテスト可能でなければなりません。SHALL または MUST を使用してください。すべての要件に、WHEN/THEN を含む #### Scenario: を少なくとも 1 つ設けてください。ADDED/MODIFIED/REMOVED Requirements ヘッダーの下にまとめてください。

design.md

関連する事実と制約、目標と対象外、決定事項（Choice + Rationale + Alternatives + Consequences）、検証の証拠を伴うリスクを必ず記載してください。決定に影響しない関係者、移行手順、未解決の質問を作り上げないでください。

tasks.md

成果物／証明の対応表と、依存関係を考慮したタスクを含めてください。各タスクには、影響を受けるパスまたは限定された領域、観測可能な成果、証拠となるコマンドを記載してください。RED/GREEN の詳細、レビューの記録、ディスパッチの仕組みは、実行契約／タスクブリーフに記載してください。読者向けタスクを、儀式的な 5 つの小ステップに膨らませないでください。

アーティファクトの生成

計画アーティファクトを作成または編集する前に、specifying に入ります。まだ specifying でない場合に限り、SSF state transition <change-dir> specifying を実行してください。再開時は未完了のアーティファクトから続け、状態遷移を自分自身に対して行わないでください。完全な計画では、明示的に変更しない動作に限り仕様を省略でき、設定によって設計を省略できます。タスクは完全な計画から省略できません。パックを生成する前に、この設定を修正してください。

DP-0 によってスコープが明確になったら、設定された計画パック（proposal、templates/spec.md を基にした差分仕様、設計、タスク）を、個々のアーティファクトの間で中断せず順番に生成します。パックを検証してから、DP-2 レビューを一度だけ依頼してください。未決事項によってユーザーに見える動作、互換性、セキュリティ、提供範囲、または選択された設計が変わる可能性がある場合、あるいはアーティファクトに互いに矛盾するスコープが記載されている場合に限り、それより前に一時停止してください。

検証チェックリスト

proposal.md

• ## Why は 50 文字を超えること、## What Changes、## Scope（In/Out）、## Impact があること、TBD/TODO がないこと。主張には、観測された問題と完了を証明する方法を明記すること

specs/

• 必須の動作には SHALL/MUST を使用し、各要件に #### Scenario: と WHEN/THEN を含め、差分ヘッダーの下にまとめ、矛盾がないこと

design.md

• 事実と制約、目標と非目標、## Decisions（1 件以上。Choice、Rationale、Alternatives、Consequences を含む）、リスクと検証があること

tasks.md

• 提供内容と証明の対応表、番号付きタスク、影響を受けるパスまたは範囲を限定した領域、観測可能な結果、プレースホルダーがないこと、すべての要件への対応付け、明示的な依存関係
• テンプレートのチェックボックス形式（各タスクを独立した行に - [ ] で記載）を使用すること。実行に移る際、この形式がガードによって強制されます

いずれかのアーティファクトが検証に失敗した場合は、contract-builder に引き渡す前に修正してください。

DP-2：アーティファクトのレビューチェックポイント

設定されたアーティファクトの概要を簡潔に提示します。問題、コマンドの境界、無効化の境界、継続の境界、ドキュメントの流れという 5 つの質問で一度だけ自己チェックします。ユーザーが明示的に委任を依頼していない限り、ブラインドリーダーのサブエージェントを呼び出さないでください。これらのアーティファクトをすでに対象としている承認を再利用し、新たな重要な決定または未承認のアーティファクトがある場合にのみ、質問を一つにまとめて確認してください。継続について別途質問を追加しないでください。承認後：

SSF state set <change-dir> dp_2_result "approved: <summary>"
SSF state set <change-dir> dp_2_timestamp now

DP-2 を記録した後も specifying のままにし、contract-builder に進みます。

引き継ぎルール

計画アーティファクトを作成した後、実装を開始しないでください。内容が安定し、検証され、DP-2 が記録されたら、contract-builder に引き継ぎます。

例外処理

• 解析失敗：該当するファイルとエラーを具体的に報告し、破損したテンプレートから生成しないでください
• テンプレートの不足：このスキルで定義されているアーティファクト構造を代わりに使用してください
• ユーザーによる中断：ディスク上のアーティファクトを復旧チェックポイントとして扱い、最初の未作成または未完了のものから再開してください
• 検証失敗：引き継ぐ前に修正し、問題のあるアーティファクトを引き継がないでください