project-onboard

project-onboard

現在のプロジェクトのファイルシステムを読み取り、6 つのオンボーディングケースのどれに該当するかを判断し、正確なコマンドの実行順序を推奨します。

トリガー：/project-onboard、プロジェクトのオンボーディング、プロジェクトの状態を診断する、最初に何を実行すればよいか、プロジェクトのセットアップに関するヘルプ

---

プロセス

厳密な優先順位に従って、5 つのチェックを順に実行します。実際のファイルを読み取り、ユーザーに質問することはありません。最初に失敗したチェックによって、主なケースの割り当てが決まります。チェック 4 はブロッキングではありません。プロジェクトはケース 6（正常）に該当しながら、ローカルスキルに問題がある場合があります。

チェック 1 — CLAUDE.md が存在するか

.claude/CLAUDE.md を読み取ります（グローバル設定リポジトリでは、プロジェクトルートにある CLAUDE.md も対象とします）。

存在しない場合 → ケース 1：新規プロジェクト

## Diagnosis

Project state: Case 1 — Brand-New Project

Detected:
- .claude/CLAUDE.md: NOT FOUND
- No Claude configuration present in this project

Warnings:
- None

## Recommended Command Sequence

1. /project-setup     — creates .claude/CLAUDE.md, ai-context/ skeleton, persists context to engram
2. /memory-update     — generates ai-context/ files from real project content (skeleton already created by /project-setup)
3. /project-audit     — produces audit-report.md with score and findings
4. /project-fix       — applies all corrections from the audit report

## Notes
After /project-fix, re-run /project-audit to verify score ≥ 75 and SDD Readiness = FULL or PARTIAL.
See ai-context/scenarios.md → Case 1 for failure modes and recovery steps.

ケース 1 の場合、ここで終了します。

---

チェック 2 — Engram MCP に接続できるか

Engram MCP に接続できるか確認します（mem_context を呼び出します）。

• Engram に接続できる場合 → SDD インフラストラクチャは Engram にあります。このチェックではプロジェクトを正常とみなし、チェック 3 に進みます。
• Engram に接続できない場合 → ケース 2（以下）。

Engram に接続できない場合 → ケース 2：CLAUDE.md は存在するが、SDD の永続化機能がない

## Diagnosis

Project state: Case 2 — CLAUDE.md Without SDD Persistence

Detected:
- .claude/CLAUDE.md: FOUND
- Engram MCP: NOT REACHABLE
- SDD cannot persist artifacts without Engram

Warnings:
- [list any ai-context/ files found or note if ai-context/ is absent]

## Recommended Command Sequence

1. Ensure Engram MCP server is running and configured
2. /project-audit     — diagnose the full scope of what is missing
3. /project-fix       — adds SDD section to CLAUDE.md
4. /memory-init       — if ai-context/ is empty or absent
5. /project-audit     — verify score improved

## Notes
project-fix will ask before every change — review each proposed action carefully.
See ai-context/scenarios.md → Case 2 for failure modes and recovery steps.

ケース 2 の場合、ここで終了します。

---

チェック 3 — ai-context/ に内容のあるファイルが 3 つ以上あるか

ai-context/ ディレクトリを読み取ります。存在し、かつ 10 行を超えるファイルの数を数えます。 想定されるファイル：stack.md、architecture.md、conventions.md、known-issues.md、changelog-ai.md。

内容のあるファイルが 3 つ未満の場合 → ケース 3：SDD が部分的に設定されており、メモリレイヤーが不十分

## Diagnosis

Project state: Case 3 — Partial SDD (ai-context/ is sparse)

Detected:
- .claude/CLAUDE.md: FOUND
- Engram MCP: REACHABLE
- ai-context/ populated files: [N] of 5 (minimum needed: 3)
- Missing or empty: [list each absent/stub file]

Warnings:
- [list any other issues found, e.g. stale onboarding.md]

## Recommended Command Sequence

1. /memory-update     — regenerates all ai-context/ files from real project state
2. /project-audit     — verify D2 score improved
3. /project-fix       — address any remaining findings

## Notes
/memory-update does not overwrite files that already have substantial content.
See ai-context/scenarios.md → Case 3 for failure modes and recovery steps.

ケース 3 の場合、ここで終了します。

---

チェック 4 — ローカルスキルの確認（ブロッキングではない）

.claude/skills/ ディレクトリを読み取ります。ディレクトリが存在し、サブディレクトリが 1 つ以上ある場合は、診断結果に警告を記録します。終了せず、チェック 5 に進んでください。

ローカルスキルに関する警告（どのケースの診断にも追記）：

Warnings:
- .claude/skills/ found with [N] local skill(s): [list names]
  Run /project-audit to see Dimension 9 findings (duplicate detection, structural completeness, language compliance).
  Run /project-fix Phase 5 to apply corrections after auditing.

---

チェック 5 — 孤立した SDD 変更

Engram でアクティブな SDD 変更を検索します：mem_search(query: "sdd/", project: "{project}")。state アーティファクトはあるが archive-report がない変更を絞り込み、tasks および verify-report アーティファクトがあるか確認します。

tasks または verify-report アーティファクトがない変更がある場合 → ケース 5：孤立または古い変更

## Diagnosis

Project state: Case 5 — Orphaned SDD Changes

Detected:
- .claude/CLAUDE.md: FOUND
- Engram MCP: REACHABLE
- ai-context/: adequate ([N] populated files)
- Orphaned changes:
  - [change-name]: missing [tasks | verify-report]
  - [change-name]: missing [tasks | verify-report]

Warnings:
- [local skills warning if Check 4 triggered]

## Recommended Command Sequence

1. /sdd-status        — see all active changes and their current phase
2. For each orphaned change, one of:
   /sdd-apply <name>  — if tasks.md is missing (change never implemented)
   /sdd-verify <name> — if implemented but never verified
   /sdd-archive <name> — if complete but never archived
3. /project-audit    — verify D3 shows no orphaned changes

## Notes
To discard a dead-end change: run /sdd-archive <name> to close it in engram.
See ai-context/scenarios.md → Case 5 for failure modes and recovery steps.

ケース 5 の場合、ここで終了します。

---

チェック 6 — すべて正常（デフォルト）

すべてのチェックに合格しました。プロジェクトは完全に設定されています。

## Diagnosis

Project state: Case 6 — Fully Configured

Detected:
- .claude/CLAUDE.md: FOUND
- Engram MCP: REACHABLE
- ai-context/: adequate ([N] populated files)
- Engram: no orphaned SDD changes

Warnings:
- [local skills warning if Check 4 triggered]
- [stale onboarding.md warning if Last verified > 90 days: "onboarding docs are stale — refresh them manually"]

## Recommended Command Sequence

For a well-understood change:
  1. /sdd-propose <change-name>  — create proposal (orchestrator fast-forwards planning automatically)
  2. /sdd-apply <change-name>    — implement the task plan

For a complex or vague change:
  1. /sdd-explore <topic>        — investigate the area before committing to a change
  2. /sdd-propose <change-name>  — create proposal from exploration findings
  3. /sdd-apply <change-name>    — implement the task plan

## Notes
Multi-phase flows (propose → spec+design → tasks in one shot, or full cycles with exploration) are handled
by the orchestrator as meta-commands typed directly in conversation — not invoked as skills.
See ai-context/quick-reference.md for entry-point guidance.

---

チェック 7 — ランタイム同期のヒント（ブロッキングではない。グローバル設定モードのみ）

プロジェクトルートに install.sh と skills/ の両方が存在する場合（つまり、現在の作業ディレクトリが agent-config メタリポジトリである場合）、割り当てられたケースにかかわらず、診断結果の Warnings: セクションに次の行を追記します。

- Verify ~/.claude/ is in sync with this repo by re-running install.sh (installation drift check).

このチェックによってケースの割り当てを変更したり、Recommended Command Sequence を変更したり、既存の 6 チェックのウォーターフォールを中断したりしてはいけません。これはヒントにすぎません。

---

古いドキュメントに関する警告ロジック

主なケースを決定した後、ai-context/onboarding.md、ai-context/scenarios.md、ai-context/quick-reference.md の > Last verified: フィールドを確認します。いずれかのファイルの日付が今日から 90 日を超えて古い場合は、Warnings セクションに次を追記します。

- [filename] is stale ([N] days since last verification). Refresh it manually.

---

ルール

• ユーザーに質問しないでください。検出はファイルシステムの状態から完全に自動で行います。
• 検出は実際のファイルの有無に基づいて行います。ケース ID やルックアップテーブルをハードコードしないでください。
• 優先順位は厳守してください。チェック N でケースを割り当てたら、優先順位の低いケースも割り当てないでください（例外：チェック 4 のローカルスキルフラグは、ブロッキングではない警告として常に表示します）。
• 構造化された出力のみを出力してください。生のディレクトリ一覧、スタックトレース、内部ファイルのダンプは出力しないでください。
• ファイルシステムを変更しないでください。このスキルは完全な読み取り専用です。
• 失敗モードについては、ai-context/scenarios.md 内の該当ケースを示す ## Notes セクションを必ず含めてください。