| name | start-teams-doc |
| argument-hint | [team/project/feature] |
| description | Unified entry point for generating feature documentation in the teams/ directory. Automatically detects the current phase (Discovery, Design, QA, Operations) and delegates to the appropriate skill. Use when creating new feature docs, continuing existing feature docs, or when user says /start-teams-doc. |
start-teams-doc スキル
トリガー条件
/start-teams-doc スキルが呼ばれたとき- ユーザーが「teams のドキュメントを作りたい」「どこから始めればいい？」「フィーチャードキュメントを作りたい」と言ったとき
Step 0: 既存フィーチャーの検出と再開フロー
パラメータ収集の前に、既存フィーチャーを検出して再開オプションを提示する。
docs_root の解決（実行手順 0）を先に行ってから本ステップを実行すること。
パス A: 引数による直接指定
/start-teams-doc {team}/{project}/{feature} の形式で引数が渡された場合、パスを解析して即再開する。
- 引数を
/ で分割し team, project, feature を取得
{docs_root}/teams/{team}/{project}/{feature}/ の存在を確認- 以下の分岐表に従いパラメータを取得し、バッチ wizard をスキップして実行手順 1 へ進む
パス B: 既存フィーチャー一覧から選択
引数なしで実行された場合:
{docs_root}/teams/ 配下を 3 階層（{team}/{project}/{feature}/）までスキャンする- フェーズディレクトリ（discovery, design, qa, operation）は除外し、フィーチャーディレクトリのみ収集する
- 既存フィーチャーが 0 件 の場合はこのステップをスキップし、バッチ 1 から開始する
- 既存フィーチャーが 1 件以上 の場合、以下の形式で 1 回の
AskUserQuestion で提示する:
既存のフィーチャーが見つかりました。続きから再開するか、新規作成を選んでください:
1. {feature_name} ({team}/{project}) {status_hint}
2. {feature_name} ({team}/{project}) {status_hint}
...
0. 新しいフィーチャーを作成する
番号を入力してください:
status_hint の決定:
_approval-status.yaml が存在する場合: フェーズ進捗アイコンを表示（例: [✅Discovery → ⏳Design]）_approval-status.yaml が存在しない場合: 既存サブディレクトリ名を表示（例: [design/operation]）
- フィーチャーが 15 件を超える場合は、最終更新日が新しい順に 15 件を表示し、残りは「他に {N} 件あります。チーム名を入力すると絞り込めます」と表示する
ユーザーが 0 を選択した場合は従来のバッチ 1 → バッチ 2 wizard を実行する。
既存フィーチャーを選択した場合は以下の分岐表に従う。
選択後の分岐表（パス A・B 共通）
| 条件 | バッチ 1 | バッチ 2 |
|---|
_approval-status.yaml あり + _interview-notes.yaml あり | スキップ（yaml から読み取り） | スキップ |
_approval-status.yaml あり + _interview-notes.yaml なし | スキップ（yaml から読み取り） | 実行 |
_approval-status.yaml なし + _interview-notes.yaml あり | スキップ（パスから推定、feature_id 自動生成） | スキップ |
_approval-status.yaml なし + _interview-notes.yaml なし | スキップ（パスから推定、feature_id 自動生成） | 実行 |
パスから推定する場合: ディレクトリパスの各階層から team（第1階層）、project（第2階層）、feature（第3階層）を取得し、feature_id は既存の自動生成ルールで生成する。
入力パラメータ収集（バッチ wizard 形式）
Step 0 で既存フィーチャーが選択された場合は、上記の分岐表に従いスキップ可能なバッチを省略する。
新規フィーチャーが選択された場合、または Step 0 がスキップされた場合（既存フィーチャー 0 件）は、以下をバッチ形式で収集する。
パラメータ一覧
| パラメータ | 説明 | 必須 |
|---|
team | チーム名。.sdd-config.yaml に teams: があればその中から選択、なければ任意 | ✅ |
project | プロジェクト名（日本語可） | ✅ |
feature | フィーチャー名（日本語可） | ✅ |
feature_id | feature 名から自動生成（kebab-case） | 自動 |
goal | このフィーチャーで達成したい価値 | ✅ |
scope_in | スコープ内の事項 | ✅ |
scope_out | スコープ外の事項 | ✅ |
constraints | 期限・法令・予算・技術的制約 | 任意 |
収集方法（バッチ提示）
AskUserQuestion の呼び出しは 2回（バッチ1 + バッチ2）に収める。
各バッチは 1回の AskUserQuestion で全項目をまとめて提示すること。項目ごとに個別の AskUserQuestion を発行してはならない。
バッチ1: 基本情報（1回の AskUserQuestion で以下を全て聞く）
以下の基本情報を教えてください:
1. チーム名: （`.sdd-config.yaml` に `teams:` が定義されている場合はその中から選択、なければ任意）
2. プロジェクト名: （日本語可）
3. フィーチャー名: （日本語可）
feature_id 自動生成ルール:
バッチ1でフィーチャー名を受け取った後、以下のルールで feature_id を自動生成する:
- フィーチャー名が英語の場合: そのまま kebab-case に変換（例:
Product Search → product-search）
- フィーチャー名が日本語の場合: ローマ字に変換して kebab-case（例:
商品検索 → shohin-kensaku）
- スペース・記号はハイフンに置換、小文字化
バッチ2: スコープ・制約（1回の AskUserQuestion で以下を全て聞く）
フィーチャーの詳細を教えてください（番号に対応する形で回答してください）:
1. 達成したい価値（goal）: このフィーチャーで実現したいこと
2. スコープ内の事項: このフィーチャーに含まれる機能・対応範囲
3. スコープ外の事項: 今回のスコープに含めないもの
4. 制約事項（任意）: 期限・法令・予算・技術的制約があれば
未回答の必須項目がある場合のみ、不足分をまとめて1回の AskUserQuestion で再確認する。
実行手順
0. docs_root の解決（サブモジュール対応）と設定ファイルの読み込み
ドキュメントリポジトリがサブモジュールとして利用されている場合、ドキュメントの生成先はサブモジュール内の teams/ ディレクトリになる。以下のロジックで docs_root を自動検出する:
- ワークスペースルートに
sdd-docs/teams/ ディレクトリが存在するか確認
- 存在する場合 →
docs_root = sdd-docs（サブモジュールモード）
- 存在しない場合 →
docs_root = .（スタンドアロンモード — 本リポジトリ単体で利用）
サブモジュールのディレクトリ名は sdd-docs を既定とする。別名を使っている場合は、その名前に読み替えること。
以降の全てのパスは {docs_root}/teams/... の形式で解決する。docs_root は全てのスキル・エージェントへの委譲時にパラメータとして引き渡す。
続いて {docs_root}/.sdd-config.yaml の存在を確認する:
- 存在する場合 →
teams: に列挙されたチーム名を読み込み、バッチ1のチーム名質問ではその中から選択させる
- 存在しない場合 → チーム名は自由入力とする
1. フィーチャーパスの特定
{docs_root}/teams/{team}/{project}/{feature}/_approval-status.yaml
2. 現在のフェーズ状態を読み込む
_approval-status.yaml が存在する場合は読み込み、存在しない場合は全フェーズ pending として扱う。
3. 進捗インジケーターを表示する
フェーズ開始前に必ず以下の形式で現在の進捗を表示する:
📋 start-teams-doc: {feature}
[✅ Discovery] → [✅ Design] → [⏳ QA] → [⬜ Operations]
凡例:
✅ — status: approved⏳ — 実行中（これから着手するフェーズ）⬜ — 未着手👀 — status: in_review（レビュー待ち）🔄 — status: changes_requested（修正待ち）
3.5. インタビュー実行
次に実行するフェーズを特定した後、フェーズスキルへ委譲する前にインタビューを実施する。
| 条件 | アクション |
|---|
_interview-notes.yaml が存在しない | interviewer スキルを mode: initial で呼び出す（共通質問 + フェーズ固有質問） |
_interview-notes.yaml が存在する | interviewer スキルを mode: phase-followup で呼び出す（フェーズ固有質問のみ） |
インタビュー呼び出し時のパラメータ:
target_skill: teams-docs-{次のフェーズ名}
output_dir: {docs_root}/teams/{team}/{project}/{feature}
mode: initial または phase-followup
existing_notes: （存在する場合）_interview-notes.yaml の内容
context_params: { team, project, feature, feature_id, goal, scope_in, scope_out, constraints, docs_root }
インタビュー結果（_interview-notes.yaml）はフェーズスキルへのコンテキストとして引き渡す。フェーズスキルは _interview-notes.yaml が存在する場合、その内容を参照してドキュメントの質を向上させる。
4. 次に実行すべきフェーズを自動判定して委譲する
| 条件 | 実行するスキル |
|---|
discovery.status が pending または yaml なし | teams-docs-discovery |
discovery.status == approved かつ design.status != approved | teams-docs-design |
design.status == approved かつ qa.status != approved | teams-docs-qa |
qa.status == approved かつ operation.status != approved | teams-docs-operations |
全フェーズ approved | 完了メッセージを表示して終了 |
優先順位（上が最優先）:
changes_requested のフェーズがある場合は、そのフェーズを最優先で修正モードで実行するin_review のフェーズがある場合は、インタビュー・ドキュメント生成をスキップし、構造バリデーション（手順5）のみ実行して承認確認に直接進む- 上記テーブルに従い、次の
pending フェーズを実行する
5. 構造バリデーション（フェーズ実行前）
フェーズスキルへ委譲する前に、構造バリデーションスクリプトを実行する。
新規フィーチャー（ディレクトリ未作成）の場合はスキップしてよい。
python <this_skill_dir>/scripts/validate-structure.py <feature_dir>
<this_skill_dir> は、この SKILL.md が配置されているディレクトリの実際のパスに解決すること。
既存のディレクトリ構成・ファイル命名・ID採番・_approval-status.yaml の整合性をチェックし、問題があれば修正してからフェーズを開始する。
承認ルール・トレーサビリティルールの詳細は references/rules.md を参照。
ID整合ルールについても references/rules.md を参照。
6. スキルへの委譲
決定したスキルを読み込み、収集済みのパラメータ（docs_root を含む）をそのまま引き渡して実行する。
委譲先スキルで再度パラメータの入力を求めない。
6.5. ソースコード参照ガイダンス
サブモジュールモード（docs_root = sdd-docs）の場合、ワークスペースルートにはメインリポジトリのソースコードが存在する。各フェーズスキルは必要に応じてソースコードを参照し、ドキュメントの精度を高めること:
- Design: 既存のコードベース構造・DB スキーマ・API 定義を参照してモデリング・spec を作成
- QA: 既存テストコードのパターン・テストフレームワーク設定を参照してテスト計画を作成
- Operations: インフラ構成（Dockerfile, k8s manifests 等）・CI/CD 設定・監視設定を参照して運用ドキュメントを作成
7. 構造バリデーション（フェーズ実行後）
フェーズスキル完了後・承認確認前に、再度構造バリデーションスクリプトを実行する。
python <this_skill_dir>/scripts/validate-structure.py <feature_dir>
バリデーションエラーがある場合は承認前に修正を行う。
全フェーズ完了時のメッセージ
🎉 {feature} のドキュメントが全フェーズ完了しました。
生成されたドキュメント:
{docs_root}/teams/{team}/{project}/{feature}/
├── _approval-status.yaml
├── discovery/
│ ├── prd.md
│ └── ユーザーストーリー/
├── design/
│ ├── 非機能要件.md
│ ├── モデリング.md
│ ├── spec/
│ └── adr/（該当する場合）
├── qa/
│ ├── テスト計画書.md
│ ├── 非機能要件のテスト.md
│ └── ユーザーストーリー/*.feature
└── operation/
├── slo-sla.md
└── ...
Troubleshooting
_approval-status.yaml が見つからない → 新規フィーチャーとして扱い、Discovery フェーズから開始する。_approval-status.yaml は Discovery フェーズ実行時に自動生成される。- フェーズ自動判定が正しくない → ユーザーに確認し、手動でフェーズを指定する。
_approval-status.yaml の各フェーズの status 値を確認する。
- validate-structure.py がエラーを返す → エラーメッセージに従いディレクトリ構造・必須ファイル・ID 採番を修正する。詳細は references/rules.md を参照。
- サブモジュールモードで
docs_root が解決できない → sdd-docs ディレクトリの存在を確認する。存在しない場合は docs_root = . として実行する。
参照スキル・エージェント
