project-onboard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

project-onboard

Reads the current project's file system and determines which of 6 onboarding cases applies, then recommends the exact command sequence.

Triggers:

/project-onboard

, onboard project, diagnose project state, what do I run first, project setup help

读取当前项目的文件系统，判断适用6种项目初始化场景中的哪一种，然后推荐精准的命令序列。

触发词：/project-onboard、onboard project、diagnose project state、what do I run first、project setup help

Process

流程

I run a 5-check waterfall in strict priority order. I read real files — I never ask the user questions. The first failing check determines the primary case assignment. Check 4 is non-blocking: a project can simultaneously be Case 6 (healthy) and have local skill issues.

我会按照严格的优先级顺序执行5项检查。我会读取真实文件——绝不会向用户提问。首次未通过的检查将确定主要场景分配。检查4为非阻塞项：项目可同时属于场景6（健康状态）并存在本地skill问题。

Check 1 — CLAUDE.md exists

检查1 — CLAUDE.md是否存在

Read

.claude/CLAUDE.md

(also accept

CLAUDE.md

at project root for global-config repos).

If absent → Case 1: Brand-new project

undefined

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

若不存在 → 场景1：全新项目

undefined

Diagnosis

Project state: Case 1 — Brand-New Project

Detected:

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

Warnings:

None

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

/project-setup — creates .claude/CLAUDE.md, ai-context/ skeleton, persists context to engram
/memory-init — generates ai-context/ files from real project content
/project-audit — produces audit-report.md with score and findings
/project-fix — applies all corrections from the audit report

/project-setup — creates .claude/CLAUDE.md, ai-context/ skeleton, persists context to engram
/memory-init — generates ai-context/ files from real project content
/project-audit — produces audit-report.md with score and findings
/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.


Stop here if Case 1.

---

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，流程到此结束。

---

Check 2 — Engram MCP reachable

检查2 — Engram MCP是否可达

Check if Engram MCP is reachable (call

mem_context

If Engram is reachable → SDD infrastructure lives in Engram. Treat the project as healthy for this check and continue to Check 3.
If Engram is NOT reachable → Case 2 (below).

If Engram not reachable → Case 2: CLAUDE.md present but no SDD persistence

undefined

检查Engram MCP是否可达（调用

mem_context

）。

若Engram可达 → SDD基础设施存储于Engram中。本次检查判定项目健康，继续执行检查3。
若Engram不可达 → 场景2（如下）。

若Engram不可达 → 场景2：存在CLAUDE.md但无SDD持久化

undefined

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]

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

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

Ensure Engram MCP server is running and configured
/project-audit — diagnose the full scope of what is missing
/project-fix — adds SDD section to CLAUDE.md
/memory-init — if ai-context/ is empty or absent
/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.


Stop here if Case 2.

---

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，流程到此结束。

---

Check 3 — ai-context/ has ≥ 3 populated files

检查3 — ai-context/包含≥3个已填充内容的文件

Read

ai-context/

directory. Count files that exist AND have more than 10 lines. Expected files:

stack.md

architecture.md

conventions.md

known-issues.md

changelog-ai.md

If fewer than 3 populated files → Case 3: Partial SDD, sparse memory layer

undefined

读取

ai-context/

目录。统计存在且内容超过10行的文件数量。预期文件包括：

stack.md

、

architecture.md

、

conventions.md

、

known-issues.md

、

changelog-ai.md

。

若已填充内容的文件少于3个 → 场景3：SDD不完整，内存层稀疏

undefined

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]

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

/memory-init — regenerates all ai-context/ files from real project state
/project-audit — verify D2 score improved
/project-fix — address any remaining findings

/memory-init — regenerates all ai-context/ files from real project state
/project-audit — verify D2 score improved
/project-fix — address any remaining findings

Notes

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


Stop here if Case 3.

---

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


若为场景3，流程到此结束。

---

Check 4 — Local skills review (non-blocking)

检查4 — 本地skill检查（非阻塞）

Read

.claude/skills/

directory. If it exists and has any subdirectories, record a warning for the diagnosis output. Do not stop — continue to Check 5.

Local skills warning (append to any case diagnosis):

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.

读取

.claude/skills/

目录。若该目录存在且包含子目录，在诊断输出中记录警告。不要停止流程——继续执行检查5。

本地skill警告（追加至任意场景诊断结果）：

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.

Check 5 — Orphaned SDD changes

检查5 — 孤立的SDD变更

Search engram for active SDD changes:

mem_search(query: "sdd/", project: "{project}")

. Filter for changes that have a state artifact but no archive-report, and check if they have tasks and verify-report artifacts.

If any change is missing
tasks
OR
verify-report
artifacts → Case 5: Orphaned or stale changes

undefined

在engram中搜索活跃的SDD变更：

mem_search(query: "sdd/", project: "{project}")

。筛选存在状态工件但无归档报告的变更，并检查它们是否包含任务和验证报告工件。

若任意变更缺少
tasks
或
verify-report
工件 → 场景5：孤立或过期变更

undefined

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]

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

/sdd-status — see all active changes and their current phase
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
/project-audit — verify D3 shows no orphaned changes

/sdd-status — see all active changes and their current phase
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
/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.


Stop here if Case 5.

---

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，流程到此结束。

---

Check 6 — All healthy (default)

检查6 — 全部健康（默认场景）

All checks passed. The project is fully configured.

undefined

所有检查均通过。项目已完全配置。

undefined

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: "Run /project-update to refresh user docs"]

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: "Run /project-update to refresh user docs"]

Recommended Command Sequence

For a well-understood change:

/sdd-propose <change-name> — create proposal (orchestrator fast-forwards planning automatically)
/sdd-apply <change-name> — implement the task plan

For a complex or vague change:

/sdd-explore <topic> — investigate the area before committing to a change
/sdd-propose <change-name> — create proposal from exploration findings
/sdd-apply <change-name> — implement the task plan

For a well-understood change:

/sdd-propose <change-name> — create proposal (orchestrator fast-forwards planning automatically)
/sdd-apply <change-name> — implement the task plan

For a complex or vague change:

/sdd-explore <topic> — investigate the area before committing to a change
/sdd-propose <change-name> — create proposal from exploration findings
/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.

---

---

Check 7 — Runtime sync hint (non-blocking, global-config mode only)

检查7 — 运行时同步提示（非阻塞，仅全局配置模式）

install.sh

AND

skills/

exist at the project root (i.e., the cwd is the

agent-config

meta-repo), append the following line to the

Warnings:

section of the case diagnosis output — regardless of which case was assigned:

- Run /claude-folder-audit to verify ~/.claude/ is in sync with this repo (installation drift check).

This check MUST NOT change the case assignment, alter the Recommended Command Sequence, or interrupt the existing 6-check waterfall. It is a hint only.

若项目根目录同时存在

install.sh

和

skills/

（即当前工作目录为

agent-config

元仓库），则在场景诊断结果的

Warnings:

部分追加以下内容——无论分配的是哪个场景：

- Run /claude-folder-audit to verify ~/.claude/ is in sync with this repo (installation drift check).

本检查不得更改场景分配、修改推荐命令序列或中断现有6项检查的流程。它仅作为提示信息。

Stale docs warning logic

过期文档警告逻辑

After determining the primary case, check

ai-context/onboarding.md

ai-context/scenarios.md

, and

ai-context/quick-reference.md

for the

> Last verified:

field. If any file's date is more than 90 days from today, append to the Warnings section:

- [filename] is stale ([N] days since last verification). Run /project-update to refresh.

确定主场景后，检查

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). Run /project-update to refresh.

Rules

规则

Do not ask the user any questions — detection is fully automatic from file-system state
Detection is derived from real file presence/absence — no hardcoded case IDs or lookup tables
Priority order is strict: once a case is assigned at check N, do not also assign a lower-priority case (exception: Check 4 local skill flag is always surfaced as a warning, non-blocking)
Emit structured output only — no raw directory listings, no stack traces, no internal file dumps
Make no file-system changes — this skill is 100% read-only
Always include a
```
## Notes
```
section pointing to the relevant case in
```
ai-context/scenarios.md
```
for failure modes

不得向用户提问——完全通过文件系统状态自动检测
检测基于真实文件的存在/缺失——无硬编码场景ID或查找表
优先级顺序严格：一旦在检查N分配了场景，不得同时分配低优先级场景（例外：检查4的本地skill标记始终作为警告显示，非阻塞）
仅输出结构化内容——无原始目录列表、无堆栈跟踪、无内部文件转储
不得修改文件系统——本skill为100%只读
始终包含
```
## Notes
```
部分，指向
```
ai-context/scenarios.md
```
中相关场景的故障模式说明