KLR-Pattern · allmonday · Jul 1, 2026
diff --git a/presets/nexusx/commands/speckit.plan.md b/presets/nexusx/commands/speckit.plan.md
@@ -0,0 +1,143 @@
+---
+description: nexusx preset — plan with DB 选型 / alembic / TS SDK 决策访谈.
+handoffs:
+  - label: Create Tasks
+    agent: speckit.tasks
+    prompt: Break the plan into nexusx phase-tagged tasks (Schema → Methods → Service → optional SDK)
+    send: true
+  - label: Create Checklist
+    agent: speckit.checklist
+    prompt: Create a checklist for the following nexusx domain...
+scripts:
+  sh: scripts/bash/setup-plan.sh --json
+  ps: scripts/powershell/setup-plan.ps1 -Json
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before planning)**:
+- Check `.specify/extensions.yml` for `hooks.before_plan` entries
+- Standard handling: parse YAML, skip if invalid, filter by `enabled`, output per `optional` flag (Automatic → `EXECUTE_COMMAND:`; Optional → prompt display)
+- If no `before_plan` hooks, skip silently
+
+## Outline
+
+1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: `'I'\''m Groot'` (or double-quote if possible: `"I'm Groot"`).
+
+2. **Load context**: Read FEATURE_SPEC + `/memory/constitution.md`（nexusx preset 版本，含 8 条硬规则 + V 型验收治理）+ IMPL_PLAN template.
+
+3. **Verify Phase 0 completeness** *(nexusx preset)*:
+   - 检查 FEATURE_SPEC 中 `## Phase 0 需求确认纪要` 八步全部填写
+   - 特别确认 Step 0-4 Service 切分由用户明确选择（不是 `[NEEDS CLARIFICATION]`）
+   - 特别确认 Step 0-7 DB 选型由用户明确选定
+   - 任一缺失 → ERROR："Phase 0 不完整，请重新运行 `__SPECKIT_COMMAND_SPECIFY__` 补全访谈"
+
+4. **Execute plan workflow** *(nexusx preset)*:
+   - Fill `## Technical Context`（nexusx 字段：Language/Version、Primary Dependencies、DB 选型、async/sync DATABASE_URL、Async DB Driver、是否引入 alembic、Testing、Target Platform）
+   - Fill `## Phase 决策记录`：从 spec 复制 Service 切分最终方案 + 与用户确认是否生成 TS SDK + 第三方库确认清单
+   - Fill `## Constitution Check`：逐条对照 8 条原则
+   - Evaluate gates（任何 ❌ 或 ⚠️ 必须在 Complexity Tracking 给理由，否则 ERROR）
+   - Phase 0: Generate `research.md`（解决 Technical Context 中所有 NEEDS CLARIFICATION；研究 alembic 配置、async driver 选型、跨层数据流 ExposeAs/SendTo/Collector 适用性）
+   - Phase 1: Generate `data-model.md`（实体定义，含 docstring + Field description）、`contracts/`（REST endpoints + GraphQL SDL）、`quickstart.md`
+   - Phase 1: Update agent context by running the agent script
+   - Re-evaluate Constitution Check post-design
+
+## Mandatory Post-Execution Hooks
+
+**You MUST complete this section before reporting completion to the user.**
+
+Check `.specify/extensions.yml` for `hooks.after_plan` entries. Same handling as Pre-Execution:
+- Mandatory → emit `EXECUTE_COMMAND: {command}`
+- Optional → prompt display
+
+If no `after_plan` hooks or `.specify/extensions.yml` missing, skip to Completion Report.
+
+## Completion Report
+
+Report branch, IMPL_PLAN path, generated artifacts (research.md / data-model.md / contracts/ / quickstart.md), and **nexusx Phase 决策摘要**（Service 切分 / DB 选型 / 是否 TS SDK）.
+
+## Phases
+
+### Phase 0: DB 选型 + alembic + 第三方库 + TS SDK 决策研究
+
+1. **从 spec.md 复制决策**（已在 Phase 0 访谈中由用户裁定）：
+   - DB 选型（in-memory / file sqlite / docker pg / docker mysql / external）
+   - Service 切分最终方案
+   - 第三方库候选
+
+2. **填充 plan.md Technical Context 的待定字段**：
+   - async DATABASE_URL：根据 DB 选型填具体值
+   - sync DATABASE_URL_SYNC：持久化场景必填（alembic + load_seed 用）；in-memory 留空
+   - Async DB Driver：sqlite→aiosqlite、pg→asyncpg、mysql→aiomysql
+   - 是否 alembic：in-memory 否；其他是
+   - Testing：pytest + pytest-asyncio（项目级 `tests/`）
+
+3. **TS SDK 决策访谈**：
+
+   向用户提问："本特性是否需要生成 TypeScript SDK？"
+   - **是** → plan.md 标记为"是"；Phase 4 触发，需 `fe/` 子目录 + `@hey-api/openapi-ts`；前提是 Phase 3 用 `create_use_case_router()`
+   - **否**（默认）→ plan.md 标记为"否"，跳过 Phase 4
+
+   决策结果写入 plan.md `## Phase 决策记录 > 是否生成 TS SDK` 区块。
+
+4. **alembic 配置研究**（仅持久化场景）：参考 `presets/nexusx/reference/phase1.md` 的 alembic 配置部分，记录：
+   - `alembic/env.py` 必须加 `import src.models  # noqa: F401`（否则 autogenerate 空）
+   - `script.py.mako` 必须加 `import sqlmodel`（否则 NameError）
+   - SQLite 必须 `render_as_batch=True`
+   - `alembic.ini` `sqlalchemy.url =` 留空，env.py 覆盖
+
+5. **Generate research.md** with format:
+   - Decision: [选了什么]
+   - Rationale: [为什么]
+   - Alternatives considered: [还看了什么]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+### Phase 1: Design & Contracts
+
+**Prerequisites**: `research.md` complete
+
+1. **Extract entities from feature spec + spec.md Phase 0 Step 0-1** → `data-model.md`:
+   - Entity name + docstring + fields (with description)
+   - Relationships（全部带 `sa_relationship_kwargs={"lazy": "noload"}`）
+   - Validation rules from requirements
+   - State transitions if applicable
+
+2. **Define interface contracts** → `/contracts/`:
+   - REST endpoints（每个 service 的方法 → 一个 POST 路由，由 `create_use_case_router()` 自动生成）
+   - GraphQL SDL（基于 SQLModel 实体 + Phase 2 挂载的 methods）
+   - MCP tools 4 层（list_apps → describe_compose_schema → describe_compose_method → compose_query）
+   - 跨层数据流标注（如有 ExposeAs / SendTo / Collector 用法）
+
+3. **Create quickstart validation guide** → `quickstart.md`:
+   - 端到端可运行验证场景
+   - 包含：prerequisites、setup commands、test/run commands、expected outcomes
+   - 用链接引用 contracts/ 和 data-model.md，不复制内容
+   - 不含完整实现代码、迁移文件、完整测试套件
+
+4. **Agent context update**: 更新 `__CONTEXT_FILE__` 中 `<!-- SPECKIT START -->` 与 `<!-- SPECKIT END -->` 之间的 plan 引用
+
+**Output**: data-model.md, /contracts/*, quickstart.md, updated agent context
+
+## Key rules
+
+- Use absolute paths for filesystem operations; use project-relative paths for references in docs
+- ERROR on Constitution gate failures or unresolved clarifications
+- nexusx preset 强制：plan.md 的 Technical Context 必须填 nexusx 字段，不能保留 spec-kit 通用字段
+
+## Done When
+
+- [ ] Phase 0 (spec.md) 完整性验证通过
+- [ ] Plan workflow executed：Technical Context 填 nexusx 字段、Phase 决策记录完整、Constitution Check 全 ✅ 或 Complexity Tracking 给理由
+- [ ] research.md 生成且所有 NEEDS CLARIFICATION 解决
+- [ ] data-model.md / contracts/ / quickstart.md 生成
+- [ ] Extension hooks dispatched or skipped per rules above
+- [ ] Completion reported with branch / plan path / artifacts / nexusx Phase 决策摘要
diff --git a/presets/nexusx/commands/speckit.specify.md b/presets/nexusx/commands/speckit.specify.md
@@ -0,0 +1,228 @@
+---
+description: nexusx preset — specify with Phase 0 八步访谈 (entities/关系/聚合根/Service切分/DB选型).
+handoffs:
+  - label: Build Technical Plan
+    agent: speckit.plan
+    prompt: Create a plan for the spec. I am building with nexusx (SQLModel + FastAPI + MCP).
+  - label: Clarify Spec Requirements
+    agent: speckit.clarify
+    prompt: Clarify specification requirements
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before specification)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_specify` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, output based on its `optional` flag per the standard spec-kit format (Automatic Pre-Hook emits `EXECUTE_COMMAND:`; Optional Pre-Hook shows the prompt)
+- If no hooks are registered, skip silently
+
+## Outline
+
+The text after `__SPECKIT_COMMAND_SPECIFY__` in the triggering message **is** the feature description.
+
+### 1. Short-name & directory setup
+
+1. **Generate a concise short name** (2-4 words) for the feature (action-noun format when possible; preserve technical acronyms like OAuth2/JWT)
+2. **Branch creation** (optional, via `before_specify` hook): if a hook ran successfully it will have output JSON with `BRANCH_NAME` and `FEATURE_NUM`. Note these for reference
+3. **Create the spec feature directory** under `specs/`:
+   - Resolution order: user-provided `SPECIFY_FEATURE_DIRECTORY` > auto-generated `specs/<NNN>-<short-name>` (check `.specify/init-options.json` for `feature_numbering`: `timestamp` → `YYYYMMDD-HHMMSS-<name>`; `sequential` (default) → next 3-digit number)
+   - `mkdir -p SPECIFY_FEATURE_DIRECTORY`
+   - Resolve active `spec-template` through the preset stack (equivalent to `specify preset resolve spec-template` — nexusx preset provides this)
+   - Copy resolved template to `SPECIFY_FEATURE_DIRECTORY/spec.md`
+   - Set `SPEC_FILE` to `SPECIFY_FEATURE_DIRECTORY/spec.md`
+   - Persist path to `.specify/feature.json`: `{ "feature_directory": "<resolved path>" }`
+   - **One feature per invocation**; spec dir name and git branch name are independent
+
+### 2. Load context
+
+4. Load the resolved `spec-template` (nexusx preset version) to understand required sections
+5. **IF EXISTS**: Load `/memory/constitution.md` for project principles (nexusx preset constitution defines 8 hard rules)
+
+### 3. Phase 0 八步访谈 *(nexusx preset — interactive)*
+
+<!--
+  ⚠️ Constitution Principle IV 强制门：必须在向用户提出 Service 切分候选方案并取得明确选择后才能继续。
+  禁止模型自行决定 Service 切分。
+-->
+
+按 `spec.md` 模板的 `## Phase 0 需求确认纪要` 区块逐项与用户访谈。**每步等待用户回复后才继续**。
+
+#### Step 0-1 术语与实体定义
+
+从 feature description 提取候选取实体，**表格化呈现**给用户逐行确认：
+
+| 实体 | 业务含义（一句话） | 核心字段（名称+类型+语义） | 字段约束 |
+|------|----------|----------|----------|
+| [候选 1] | ... | ... | ... |
+
+询问：补充、修改、删除哪些？
+
+#### Step 0-2 实体关系
+
+基于 Step 0-1 实体，绘制文本 ER 图：
+
+```
+User ──1:N──→ Post
+Post ──N:M──→ Tag (中间表: PostTag)
+```
+
+每条关系标方向（1:N / N:1 / M:N）+ 业务含义 + 是否需要中间实体。**与用户确认关系方向和基数**。
+
+#### Step 0-3 聚合根 + 根类型
+
+明确每个聚合根是 **SQLModel 实体**还是 **虚拟实体**（普通 `pydantic.BaseModel`）：
+
+| 聚合根 | 类型 | 选用理由 |
+|--------|------|----------|
+| [候选] | SQLModel 实体 / 虚拟实体 | [判断依据] |
+
+**判断依据**：根字段全部来自 DB → SQLModel；来自请求上下文（JWT、headers）或聚合多源 → 虚拟。
+
+#### Step 0-4 Service 切分候选方案 ⚠️ 强制门
+
+**禁止模型自行决定**。必须向用户提出**至少一种候选方案**：
+
+```
+方案 A：按业务功能域
+  auth/    → register, login
+  chat/    → create_conversation, list_messages, send_message
+  优势：业务内聚
+  劣势：chat 域可能过大
+
+方案 B：按聚合根
+  user/         → register, login
+  conversation/ → create_conversation, list_messages
+  message/      → send_message
+  优势：每 service 粒度均匀
+  劣势：conversation/message 强耦合被拆开
+
+方案 C：混合
+  ...
+```
+
+**强制门**：如果未向用户提出候选方案并取得明确选择（A / B / C / 用户的修正），**立即标记 `SPEC_PHASE0_BLOCKED`** 并停在此处输出：
+
+```
+⚠️ SPEC_PHASE0_BLOCKED
+等待用户从 A/B/C 选择 Service 切分方案，或提出修正。
+```
+
+收到用户回复后才继续 Step 0-5。
+
+#### Step 0-5 GraphQL 定位
+
+告知用户：GraphQL 在 nexusx 中是**辅助开发测试**接口（不是正式 API）。业务方法定义在 `service/<domain>/methods.py`，挂载到 Entity（GraphQL 辅助）+ UseCaseService（REST/MCP 正式）。无需用户确认。
+
+#### Step 0-6 第三方库确认
+
+列出 feature 涉及的非业务功能领域（认证、实时推送、文件存储、数据迁移等）。对每个：
+- 候选方案（成熟第三方库 vs 手写）
+- 推荐理由
+- **必须调查用户提到的库的当前维护状态**（避免停更库）
+
+| 功能领域 | 推荐方案 | 维护状态 | 备注 |
+|----------|----------|----------|------|
+| 认证 | ... | 活跃/维护中/已停更 | ... |
+
+#### Step 0-7 DB 选型 + 迁移策略 ⚠️ 强制门
+
+向用户呈现 5 选项决策表：
+
+| 选项 | async URL | 持久化 | Alembic | 适用 |
+|------|----------|--------|---------|------|
+| in-memory sqlite | `sqlite+aiosqlite://` | ❌ | ❌ | Demo |
+| file sqlite | `sqlite+aiosqlite:///./var/X.db` | ✅ 文件 | ✅ | 本地开发 |
+| docker pg | `postgresql+asyncpg://...` | ✅ 卷 | ✅ | 团队 |
+| docker mysql | `mysql+aiomysql://...` | ✅ 卷 | ✅ | MySQL 偏好 |
+| external | 视驱动 | ✅ | ✅ | 已有 DB |
+
+**强制门**：用户未明确选定（含 async URL + sync URL + 是否 alembic + 是否 docker-compose）前，标记 `SPEC_PHASE0_BLOCKED` 等待。
+
+#### Step 0-8 检查清单汇总
+
+向用户展示 8 项 checklist 全部 ✅ 后才进入下一步：
+
+- [ ] 实体和字段完整，约束清晰
+- [ ] 实体关系方向和基数正确
+- [ ] 聚合根明确，每个类型已确认
+- [ ] **Service 切分由用户明确选择**（IV）
+- [ ] 核心用例覆盖，逻辑自洽
+- [ ] 第三方库选型确认
+- [ ] **DB 选型 + 迁移策略明确**（影响 Phase 1 alembic）
+- [ ] 无遗漏或未讨论的边界
+
+### 4. Fill spec.md using Phase 0 answers
+
+6. Write the specification to `SPEC_FILE`:
+   - 用 Phase 0 八步访谈的答案填充 `## Phase 0 需求确认纪要` 区块
+   - 用 spec-kit core 流程填充 `## User Scenarios & Testing` / `## Requirements` / `## Success Criteria` / `## Assumptions`
+   - 解析用户描述中的 actors / actions / data / constraints
+   - 不明确的标记 `[NEEDS CLARIFICATION: specific question]`，**全局最多 3 个**
+   - 优先级：scope > security/privacy > UX > technical details
+   - 合理默认：标准 web/mobile 性能、用户友好错误、标准认证模式、项目合适的集成模式
+
+### 5. Specification Quality Validation
+
+7. 创建 `SPECIFY_FEATURE_DIRECTORY/checklists/requirements.md` 验证 checklist，包含：
+   - **Content Quality**: 无实现细节、聚焦用户价值、面向非技术干系人
+   - **Requirement Completeness**: 无残留 `[NEEDS CLARIFICATION]`、需求可测、success criteria 可衡量且与实现无关、边界用例识别
+   - **Feature Readiness**: 所有 FR 有清晰验收、用户场景覆盖主流程
+
+8. 验证流程：
+   - **全部通过** → 标记完成，进入 Mandatory Post-Execution Hooks
+   - **非 NEEDS CLARIFICATION 失败** → 列出问题、更新 spec、重验证（最多 3 轮）
+   - **残留 NEEDS CLARIFICATION** → 提取每个标记（最多 3 个），用表格向用户提问（Q1/Q2/Q3 同时呈现），等用户回复后替换标记，重新验证
+
+## Mandatory Post-Execution Hooks
+
+**You MUST complete this section before reporting completion to the user.**
+
+Check `.specify/extensions.yml` for `hooks.after_specify` entries. Apply same logic as Pre-Execution Checks:
+- Mandatory hook → emit `EXECUTE_COMMAND: {command}`
+- Optional hook → show prompt and command path
+
+If no `after_specify` hooks or `.specify/extensions.yml` missing, skip to Completion Report.
+
+## Completion Report
+
+Report to user:
+- `SPECIFY_FEATURE_DIRECTORY` — feature 目录路径
+- `SPEC_FILE` — spec 文件路径
+- Phase 0 八步访谈全部完成（特别提示 Service 切分 + DB 选型已由用户裁定）
+- Checklist 验证结果摘要
+- Readiness for next phase (`__SPECKIT_COMMAND_CLARIFY__` 或 `__SPECKIT_COMMAND_PLAN__`)
+
+**NOTE**: Branch creation 由 `before_specify` hook 处理；spec 目录和文件创建由本命令处理。
+
+## Quick Guidelines
+
+- **Phase 0 访谈阶段**：聚焦业务实体、关系、聚合根、Service 边界、DB 选型——这些决定后续 phase 走向。可以包含 nexusx 技术栈名（SQLModel / FastAPI / MCP），因为本项目就用 nexusx
+- **User Scenarios / Requirements / Success Criteria 阶段**：聚焦 WHAT 和 WHY，避免 HOW（具体代码结构、字段名）
+- **NEEDS CLARIFICATION** 上限 3 个，仅在多重合理解读且影响范围时使用
+
+### Section Requirements
+
+- **Phase 0 需求确认纪要**：nexusx preset 必填，未完成禁止进入 plan
+- **User Scenarios**：必填，每个故事可独立测试
+- **Requirements / Success Criteria / Assumptions**：必填
+- 不适用的 section 整段删除，不留 "N/A"
+
+## Done When
+
+- [ ] Phase 0 八步访谈完成（Service 切分 + DB 选型由用户明确裁定）
+- [ ] Specification written to `SPEC_FILE`，包含 nexusx Phase 0 区块 + spec-kit core 区块
+- [ ] Validated against quality checklist
+- [ ] Extension hooks dispatched or skipped per rules above
+- [ ] Completion reported with feature dir / spec path / Phase 0 interview summary