@careerchain/stdd 0.1.1 → 0.1.2

package/assets/.claude/hooks/spec-first-check.sh

@@ -0,0 +1,201 @@
+#!/bin/bash
+# PreToolUse Hook: 実装ファイルの編集前に STDD の「Spec → テスト → 実装」順序を促す。
+# Edit / Write / MultiEdit にマッチさせて使う（settings.json で登録）。
+#
+# 役割（Poka-Yoke）:
+#   ad-hoc な「この実装を直して」等の指示でスキルを介さず実装ファイルを編集しようと
+#   したとき、まず Spec / テストの更新を検討するようリマインドする。既定は非ブロッキング。
+#
+# このフックは下流プロジェクト固有の値をハードコードせず、リポジトリルートの
+# .stdd.config.yml を実行時に読み取って動作する（設定駆動）。
+#   - apps[].path                  : 実装ファイルとみなすディレクトリ（"." はリポジトリ全体）
+#   - docs.layout.requirements     : Spec の配置（{{ より前の固定 prefix を Spec 領域とみなす）
+#   - workflow.enforce_spec_first  : off | warn(既定) | block
+#   - project.primary_branch       : block 判定でブランチ差分を比較する基準
+#
+# 分類で Spec / テスト / docs / .claude / 設定・ロックファイルは免除（無言で許可）する。
+# 設定が無い / フックが失敗する場合はブロックせずスキップする（フェイルオープン）。
+# 詳細な記述規約は docs/config-driven-authoring.md を参照。
+
+hook_input=$(cat)
+FILE_RAW=$(printf '%s' "$hook_input" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE_RAW" ] && exit 0
+
+ROOT_DIR=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+CONFIG="$ROOT_DIR/.stdd.config.yml"
+[ -f "$CONFIG" ] || exit 0
+
+# 編集対象パスをリポジトリルート相対へ正規化
+case "$FILE_RAW" in
+    "$ROOT_DIR"/*) REL="${FILE_RAW#"$ROOT_DIR"/}" ;;
+    ./*)           REL="${FILE_RAW#./}" ;;
+    *)             REL="$FILE_RAW" ;;
+esac
+
+# --- .stdd.config.yml パーサ（外部依存なし。pre-push-check.sh と同じ流儀） ---
+
+# 指定セクション直下のスカラー値を取得: $1=section, $2=key
+yaml_scalar() {
+    awk -v sec="$1:" -v k="$2:" '
+        /^[^[:space:]]/ { insec = ($1 == sec) }
+        insec && $1 == k {
+            sub(/^[[:space:]]*[^:]*:[[:space:]]*/, "", $0)
+            print $0
+            exit
+        }
+    ' "$CONFIG"
+}
+
+# apps[] の path を 1 行ずつ取得
+yaml_apps_paths() {
+    awk '
+        /^[^[:space:]]/ { inapps = ($1 == "apps:") }
+        inapps && $1 == "path:" {
+            sub(/^[[:space:]]*path:[[:space:]]*/, "", $0)
+            print $0
+        }
+    ' "$CONFIG"
+}
+
+# docs.layout.requirements の値（ネストキー。最初の requirements: 行を採用）
+yaml_requirements() {
+    awk '$1 == "requirements:" {
+        sub(/^[[:space:]]*requirements:[[:space:]]*/, "", $0)
+        print $0
+        exit
+    }' "$CONFIG"
+}
+
+strip_quotes() {
+    local v="$1"
+    v="${v%\"}"; v="${v#\"}"
+    v="${v%\'}"; v="${v#\'}"
+    printf '%s' "$v"
+}
+
+# docs.layout.requirements の {{ より前の固定 prefix を Spec 領域として導出
+REQ_TPL=$(strip_quotes "$(yaml_requirements)")
+SPEC_PREFIX="${REQ_TPL%%\{\{*}"
+
+# --- パス分類 ---
+
+is_spec() {
+    local rel="$1" base
+    base=$(basename "$rel")
+    case "$base" in
+        REQUIREMENTS.md|TECH_DESIGN.md|TEST_PLAN.md|ARCHITECTURE.md|TABLE_DEFINITION.md|API_SPEC.md|DESIGN.md) return 0 ;;
+    esac
+    case "$rel" in
+        docs/*|*/docs/*) return 0 ;;
+    esac
+    if [ -n "$SPEC_PREFIX" ] && [ "$SPEC_PREFIX" != "$REQ_TPL" ]; then
+        case "$rel" in
+            "$SPEC_PREFIX"*) return 0 ;;
+        esac
+    fi
+    return 1
+}
+
+is_test() {
+    local rel="$1" base
+    base=$(basename "$rel")
+    case "$base" in
+        *.test.*|*.spec.*|*_test.*|*_spec.*) return 0 ;;
+    esac
+    case "/$rel/" in
+        */__tests__/*|*/__mocks__/*|*/tests/*|*/test/*|*/e2e/*|*/spec/*) return 0 ;;
+    esac
+    return 1
+}
+
+is_excluded() {
+    local rel="$1" base
+    base=$(basename "$rel")
+    case "$rel" in
+        .claude/*|*/.claude/*|.git/*|*/.git/*|node_modules/*|*/node_modules/*) return 0 ;;
+        dist/*|*/dist/*|build/*|*/build/*|coverage/*|*/coverage/*|.next/*|*/.next/*) return 0 ;;
+    esac
+    case "$base" in
+        .env*|*.lock) return 0 ;;
+        *.md|*.txt|*.json|*.yml|*.yaml|*.toml|*.ini) return 0 ;;
+        *.css|*.scss|*.sass|*.less|*.svg|*.png|*.jpg|*.jpeg|*.gif|*.ico|*.webp) return 0 ;;
+    esac
+    return 1
+}
+
+APPS_PATHS=$(yaml_apps_paths)
+[ -z "$APPS_PATHS" ] && APPS_PATHS="."
+
+in_apps() {
+    local rel="$1" p
+    while IFS= read -r raw; do
+        [ -z "$raw" ] && continue
+        p=$(strip_quotes "$raw")
+        [ -z "$p" ] && continue
+        [ "$p" = "." ] && return 0
+        p="${p%/}"
+        case "$rel" in
+            "$p"/*) return 0 ;;
+        esac
+    done <<EOF
+$APPS_PATHS
+EOF
+    return 1
+}
+
+# Spec / テスト / 除外対象 / apps 外 はいずれも無言で許可
+is_spec "$REL" && exit 0
+is_test "$REL" && exit 0
+is_excluded "$REL" && exit 0
+in_apps "$REL" || exit 0
+
+# --- 実装ファイル編集と判定。enforce_spec_first に従う ---
+
+MODE=$(strip_quotes "$(yaml_scalar workflow enforce_spec_first)")
+MODE=${MODE:-warn}
+
+[ "$MODE" = "off" ] && exit 0
+
+REMINDER="STDD リマインダ: 実装ファイル ($REL) を編集しようとしています。\
+この変更が仕様の振る舞いを変えるなら、いきなり実装を直さず、先に Spec\
+（.stdd.config.yml の docs.layout）とテストを更新してください（Spec → テスト → 実装）。\
+振る舞いを変えないリファクタ・整形・設定変更ならこのまま進めて構いません。\
+本格的な機能実装は auto-implement、仕様更新は documenting-specifications スキルに委譲できます。"
+
+if [ "$MODE" = "block" ]; then
+    PRIMARY_BRANCH=$(strip_quotes "$(yaml_scalar project primary_branch)")
+    PRIMARY_BRANCH=${PRIMARY_BRANCH:-main}
+
+    branch_has_spec_or_test() {
+        local base files f
+        base=$(git merge-base HEAD "origin/$PRIMARY_BRANCH" 2>/dev/null || true)
+        files=""
+        [ -n "$base" ] && files=$(git diff --name-only "$base"...HEAD 2>/dev/null)
+        files="$files
+$(git diff --name-only 2>/dev/null)
+$(git diff --name-only --cached 2>/dev/null)"
+        while IFS= read -r f; do
+            [ -z "$f" ] && continue
+            if is_spec "$f" || is_test "$f"; then return 0; fi
+        done <<EOF
+$files
+EOF
+        return 1
+    }
+
+    # ブランチに既に Spec / テストの変更があれば spec-first 充足とみなして許可
+    if branch_has_spec_or_test; then
+        exit 0
+    fi
+
+    DENY="STDD enforce_spec_first=block: このブランチにはまだ Spec / テストの変更がありません。\
+$REMINDER"
+    jq -n --arg r "$DENY" \
+        '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$r}}'
+    exit 0
+fi
+
+# warn（既定）: 非ブロッキングのリマインドを文脈に注入
+jq -n --arg r "$REMINDER" \
+    '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$r}}'
+exit 0

package/assets/.claude/rules/stdd-spec-first.md

@@ -0,0 +1,36 @@
+# STDD: Spec-First の原則（最優先・常時適用）
+
+このプロジェクトは **STDD (Spec & Test Driven Development)** で運用されている。
+唯一の真実源 (SSoT) は **Spec ドキュメント**であり、コード変更は必ず
+**「Spec → テスト → 実装」** の順で行う。Spec から始まらない実装は STDD 違反。
+
+## 必ず守ること
+
+ユーザーから「修正して / 直して / 変更して / fix / 〜を追加して / 実装して」等、
+**コードに手を入れる依頼**を受けたら（スキルを介さない ad-hoc な一言依頼でも）、
+いきなり実装ファイルを編集せず、まず次の順で判断・実行する。
+
+1. **Spec 確認**: この変更で対象機能の `REQUIREMENTS.md` / `TECH_DESIGN.md`
+   （配置は `.stdd.config.yml` の `docs.layout`）の記述が変わるか確認する。
+   仕様（What / 振る舞い）が変わるなら、**先に Spec を更新**する。
+2. **テスト更新 (Red)**: Spec の変更または新しい振る舞いを検証するテストを
+   先に追加 / 更新し、失敗する（Red）ことを確認する。
+3. **実装 (Green)**: テストを通す最小限の実装を行う。
+4. **整合性**: Spec ⇔ テスト ⇔ 実装が一致した状態でコミットする。
+
+「実装だけ」を直すと Spec と実装が乖離し、SSoT 性が壊れる。実装側で先に直したく
+なっても、Spec を飛ばさない。
+
+## 例外（Spec 更新が不要なケース）
+
+**仕様の振る舞いを変えない**変更は Spec 更新をスキップしてよい:
+リファクタリング / 命名・整形 / コメント / 設定値 / ビルド・CI / タイポ修正。
+ただし**テストが緑のまま**であることは必ず確認する。
+
+## 迷ったら
+
+「これは仕様変更か、それとも振る舞いを変えない変更か」を一言ユーザーに確認する。
+
+本格的な機能実装は `auto-implement` スキル、仕様の作成・更新は
+`documenting-specifications` スキル、Spec ⇔ テスト ⇔ 実装 の整合性確認は
+`verifying-consistency` スキルに委譲できる。

package/assets/.claude/settings.json

@@ -47,7 +47,8 @@
       "Bash(shasum:*)",
       "Bash(xargs:*)",
       "Bash(awk:*)",
-      "Bash(PGPASSWORD=postgres psql:*)"
+      "Bash(PGPASSWORD=postgres psql:*)",
+      "mcp__playwright__*"
     ]
   },
   "hooks": {
@@ -61,7 +62,20 @@
             "timeout": 600
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/spec-first-check.sh",
+            "timeout": 30
+          }
+        ]
       }
     ]
-  }
+  },
+  "enabledMcpjsonServers": [
+    "playwright"
+  ]
 }

package/assets/.claude/skills/auto-implement/SKILL.md

@@ -93,7 +93,7 @@ GitHub Projectのステータス更新の手順は [references/github-project.md
 
 ```
 Team Lead（オーケストレーター）      ← このスキル自身
- ├→ Spec Writer          : REQUIREMENTS.md + TECH_DESIGN.md 作成
+ ├→ Spec Writer          : REQUIREMENTS.md + TECH_DESIGN.md + TEST_PLAN.md 作成
  ├→ Spec Reviewer        : Spec の品質・整合性・漏れをレビュー
  ├→ Plan Writer          : タスク分解・実装計画（PLANドキュメント）を作成
  ├→ Implementer          : テスト作成 → 実装（STDDフロー）

package/assets/.claude/skills/auto-implement/references/phases.md

@@ -17,18 +17,18 @@
 
 1. `docs/` 配下に該当機能のディレクトリを作成（存在しない場合）
 2. `REQUIREMENTS.md` を作成:
-   - ビジネス要件の整理
-   - ユーザージャーニーの定義
-   - 受入基準の明確化
+   - 業務要件（解決する問題・対象ユーザー・ビジネス目標）の整理
+   - 機能要件：ユースケースごとに 振る舞い（番号付き手順・主語明示）＋ 受入基準（EARS）＋ Priority を定義
+   - 非機能要件（機能固有のもの。共通は common 準拠）の明確化
 3. ワイヤーフレーム（WF）を生成（UI を持つ機能の場合）:
    - `generating-wireframes` スキルに従い `docs/<app>/<feature-path>/wireframes/` に HTML WF を生成
-   - REQUIREMENTS.md「3. UI/UX デザイン」から `./wireframes/index.html` にリンク
+   - REQUIREMENTS.md「2.4 UI/UX・画面」から `./wireframes/index.html` にリンク
    - UI を持たない機能（バッチ・API のみ等）はスキップ
 4. `TECH_DESIGN.md` を作成:
-   - 技術設計方針
-   - ファイル構成
-   - テスト戦略（テストケース一覧）
-5. 必要に応じて `SCREEN_ITEMS_DEFINITION.md` を作成
+   - 技術設計方針（概要 / 主要な設計判断 / ロジック設計 / エラーハンドリング戦略）
+   - 画面 feature では「画面項目定義」セクションを含める（非画面 feature は省略）
+   - データ構造は common `TABLE_DEFINITION.md`、API は common `API_SPEC.md` を参照
+5. `TEST_PLAN.md` を作成（テスト戦略・テストケース一覧。feature 単位の独立ドキュメント）
 
 作成したSpecをコミット。
 
@@ -55,8 +55,8 @@ HIGH/MEDIUM の指摘がある場合は Hard Threshold とは別に判断する
 
 **Plan Writerに依頼**して、Specドキュメントに基づきPLANドキュメントを作成する。
 
-1. REQUIREMENTS.mdのUser JourneyとPriorityを確認
-2. TECH_DESIGN.mdのTest Strategyに基づきタスクを分解
+1. REQUIREMENTS.mdのユースケース（振る舞い＋受入基準）とPriorityを確認
+2. TEST_PLAN.mdのテスト戦略に基づきタスクを分解
 3. テスト→実装の順序でタスクリストを作成
 4. ファイル構成（新規/既存修正/既存維持）を明記
 5. PLANドキュメントをコミット
@@ -107,14 +107,14 @@ HIGH/MEDIUM の指摘がある場合は Hard Threshold とは別に判断する
 
 レビュー観点:
 
-1. **Spec準拠**: TECH_DESIGN.mdのテスト戦略（ジャーニー別テストレベル分類・テスト総数・内訳）に作成テストが則っているか
+1. **Spec準拠**: TEST_PLAN.mdのテスト戦略（ユースケース別テストレベル分類・テスト総数・内訳）に作成テストが則っているか
 2. **形骸的テストの検出**: トートロジー、モック戻り値のassert、内容を検証しないアサーション等、意味のないテストがないか
    - ただしE2EテストでUI要素（role, aria-label, data-testid, 可視テキスト等）に依拠した検証は許容
 3. **一般的なテスト品質**: AAA構造、独立性、命名、Flaky耐性、アサーションの具体性
 
 ### 判定結果の扱い
 
-Test Reviewer の **Hard Threshold**（HIGH 0件 / MEDIUM ≤2件 / 形骸的テスト 0件 / TECH_DESIGN.md整合 / P0 E2E完全カバー / 受入基準テスト網羅）を1項目でも下回った場合は必ず NEEDS CHANGES 以下となる。
+Test Reviewer の **Hard Threshold**（HIGH 0件 / MEDIUM ≤2件 / 形骸的テスト 0件 / TEST_PLAN.md整合 / P0 E2E完全カバー / 受入基準テスト網羅）を1項目でも下回った場合は必ず NEEDS CHANGES 以下となる。
 
 - **PASS**: Phase 2のステップ2（実装）に戻って作業を継続。
 - **NEEDS CHANGES**: Test Reviewer 出力末尾の「Generator への差し戻し指示」をそのまま implementer に渡してテストを修正させる → テストを再コミット → Test Reviewer に再レビュー依頼。**最大3回**ループ。
@@ -143,6 +143,8 @@ Test Reviewer の **Hard Threshold**（HIGH 0件 / MEDIUM ≤2件 / 形骸的テ
 
 4. **コード品質チェック**: `simplify` skill と同等のレビューを実施
 
+5. **動作確認（Playwright MCP）**: `commands.dev` が定義され UI を持つ場合、dev サーバを起動し Playwright MCP（`mcp__playwright__*`）で主要ユースケースのハッピーパスをブラウザ操作で確認する（主要要素の存在・console エラーなし・画面遷移）。`commands.dev` 未定義 / UIなし / Playwright MCP 利用不可ならスキップする。詳細は QA Engineer の Phase 6 を参照。
+
 問題がある場合:
 
 - **ビルド・型エラー**: Build Error Resolverに修正を依頼

package/assets/.claude/skills/documenting-plans/SKILL.md

@@ -150,9 +150,9 @@ PLANドキュメントには以下のセクションを含める:
 ```
 「REQUIREMENTS.mdを確認しました。今回のセッションでは以下のどの範囲を実装しますか？
 
-A) 全てのUser Journey（P0〜P2）
+A) 全てのユースケース（P0〜P2）
 B) P0のCritical Pathsのみ
-C) 特定のJourneyのみ（指定してください）
+C) 特定のユースケースのみ（指定してください）
 
 また、既存のPLANドキュメントがある場合は、そちらを継続しますか？」
 ```