project-onboard

project-onboard

读取当前项目的文件系统，判断适用的 6 种入门场景之一，然后推荐准确的命令序列。

触发方式：/project-onboard、项目入门、诊断项目状态、我应该先运行什么、项目设置帮助

---

流程

我会严格按优先级顺序执行 5 项检查。我会读取实际文件，而不会向用户提问。第一个未通过的检查决定主要场景分配。检查 4 不会阻断流程：项目可以同时属于 Case 6（健康）并存在本地技能问题。

检查 1 — CLAUDE.md 是否存在

读取 .claude/CLAUDE.md（对于全局配置仓库，也接受项目根目录下的 CLAUDE.md）。

如果不存在 → Case 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.

如果属于 Case 1，在此停止。

---

检查 2 — Engram MCP 是否可访问

检查 Engram MCP 是否可访问（调用 mem_context）。

• 如果 Engram 可访问 → SDD 基础设施位于 Engram 中。此项检查视为项目健康，然后继续检查 3。
• 如果 Engram 不可访问 → Case 2（如下）。

如果 Engram 不可访问 → Case 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.

如果属于 Case 2，在此停止。

---

检查 3 — ai-context/ 中是否有 ≥ 3 个已填充文件

读取 ai-context/ 目录。统计存在且行数超过 10 行的文件。 预期文件：stack.md、architecture.md、conventions.md、known-issues.md、changelog-ai.md。

如果已填充文件少于 3 个 → Case 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.

如果属于 Case 3，在此停止。

---

检查 4 — 本地技能审查（不阻断流程）

读取 .claude/skills/ 目录。如果目录存在且包含任何子目录，则在诊断输出中记录一条警告。不要停止 — 继续检查 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}")。筛选出有状态产物但没有归档报告的变更，并检查是否有任务和验证报告产物。

如果任何变更缺少 tasks 或 verify-report 产物 → Case 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.

如果属于 Case 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 的本地技能标记始终作为警告显示，不阻断流程）
• 仅输出结构化内容 — 不输出原始目录列表、堆栈跟踪或内部文件转储
• 不做任何文件系统更改 — 此技能完全只读
• 始终包含 ## Notes 部分，指向 ai-context/scenarios.md 中与故障模式相关的条目