feat(preset): nexusx spec-kit preset (4-phase SDD on spec-kit)

.specify/extensions.yml

@@ -1,8 +1,40 @@
 installed:
 - agent-context
+- nexusx
 settings:
   auto_execute_hooks: true
 hooks:
+  # nexusx prepend hooks — v0.2.0+ 设计：
+  # - optional: true → 用户可禁用、hook 失败不阻塞 spec-kit 主流程
+  # - 失败时 graceful degrade：spec-kit 原生命令继续执行，nexusx 增强内容留空或由用户手动填写
+  # - 移除 nexusx preset 后，hooks 自动消失（spec-kit 主流程完全不受影响）
+  before_specify:
+  - extension: nexusx
+    command: nexusx.phase0
+    enabled: true
+    optional: true
+    priority: 5
+    prompt: Run nexusx Phase 0 八步访谈?
+    description: nexusx Phase 0 八步访谈，结果写入 spec.md 顶部区块
+    condition: null
+  before_plan:
+  - extension: nexusx
+    command: nexusx.plan-decisions
+    enabled: true
+    optional: true
+    priority: 5
+    prompt: Run nexusx plan 决策访谈?
+    description: nexusx DB 选型 / alembic / 第三方库 / TS SDK 决策访谈
+    condition: null
+  before_tasks:
+  - extension: nexusx
+    command: nexusx.tasks-phase-tags
+    enabled: true
+    optional: true
+    priority: 5
+    prompt: Run nexusx tasks phase 标签规则提示?
+    description: nexusx phase-first 混合排序规则与 [P1]-[P4] 标签说明
+    condition: null
   after_specify:
   - extension: agent-context
     command: speckit.agent-context.update

presets/nexusx/commands/nexusx-phase0.md

@@ -0,0 +1,90 @@
+---
+description: "nexusx Phase 0 八步访谈——在 /speckit-specify 之前自动 prepend（before_specify hook），也可独立调用。访谈结果写入 spec.md 的 Phase 0 需求确认纪要区块。"
+---
+
+# nexusx Phase 0 八步访谈
+
+**用途**：在执行 `/speckit-specify` **之前**完成 nexusx Phase 0 八步访谈，把结论填入 spec.md 的 "Phase 0 需求确认纪要" 区块。
+
+**触发方式**：
+- **自动**：装了 nexusx preset 后，`/speckit-specify` 命令的 `before_specify` hook 会先跑本命令（参考 `.specify/extensions.yml`）
+- **手动**：直接调用 `/nexusx-phase0`——适合用户想先做访谈再写 spec、或 hook 被禁用时的 fallback
+
+**插拔安全**：
+- 本命令独立可调用，不依赖 spec-kit 命令
+- hook 失败 / 被禁用时，spec-kit 原生 `/speckit-specify` 流程仍正常工作（spec.md 内 Phase 0 区块作为占位提示，用户可手动填写或留空）
+- 移除 nexusx preset 后，本命令与 hook 都消失，spec-kit 主流程完全不受影响
+
+**输出位置**：`<spec-dir>/spec.md` 的 `## Phase 0 需求确认纪要` 区块（spec-template.md 顶部预留）。如果 spec.md 不存在，本命令仅产出访谈纪要供后续手动写入。
+
+---
+
+## 八步访谈流程
+
+### Step 0-1 术语与实体定义
+
+逐一列出本特性涉及的业务实体。每个实体说明业务含义、核心字段、字段约束。
+
+| 实体 | 业务含义 | 核心字段（名称+类型+语义） | 字段约束 |
+|------|----------|-----------------------------|----------|
+| [Entity 1] | [一句话业务含义] | [关键属性] | [唯一/非空/枚举/联合唯一] |
+
+### Step 0-2 实体关系
+
+用文本 ER 图展示实体间关系。
+
+```
+User ──1:N──→ Post
+Post ──N:M──→ Tag   (中间表: PostTag)
+```
+
+### Step 0-3 聚合根
+
+明确本特性的聚合根（业务入口实体）。每个聚合根必须明确是 SQLModel 实体还是虚拟实体。
+
+| 聚合根 | 类型 | 数据持久化 | 选用理由 |
+|--------|------|------------|----------|
+| [Aggregate 1] | SQLModel / 虚拟实体 | 落表 / 不落表 | [判断依据] |
+
+### Step 0-4 Service 切分候选方案 ⚠️ 用户裁定
+
+**Constitution Principle IV 强制门**：本节必须由用户从候选方案中选择，禁止模型自行决定。
+
+提出至少 2 个候选方案（按业务功能域 / 按聚合根 / 混合），列出优劣，等用户选择。
+
+### Step 0-5 GraphQL 定位
+
+GraphQL 在本项目中是辅助开发测试与 AI 测试接口，不是正式 API。
+
+### Step 0-6 第三方库确认
+
+| 功能领域 | 推荐方案 | 维护状态已调查 | 备注 |
+|----------|----------|----------------|------|
+| 认证 | [候选] | [是/否] | [兼容性说明] |
+
+### Step 0-7 DB 选型 + 迁移策略
+
+从 In-memory SQLite / File-backed SQLite / Docker PostgreSQL / Docker MySQL / External DB 中选择。
+
+**用户最终选择**: 等用户明确选定。
+
+### Step 0-8 检查清单
+
+进入 Phase 1（plan 阶段）之前，以下必须全部 ✅：
+
+- [ ] 所有实体和字段完整，约束清晰
+- [ ] 实体关系方向和基数正确
+- [ ] 聚合根明确，类型（SQLModel / 虚拟）已确认
+- [ ] **Service 切分方案由用户明确选择**
+- [ ] 核心用例覆盖主要业务场景
+- [ ] 第三方库选型确认
+- [ ] **DB 选型 + 迁移策略由用户明确选定**
+- [ ] 无明显遗漏或未讨论的边界情况
+
+---
+
+## 完成后
+
+把八步结论以 `### Session YYYY-MM-DD` 区块形式追加到 spec.md 的 `## Phase 0 需求确认纪要` 下，然后由 spec-kit 原生 `/speckit-specify` 接管剩余的 spec 撰写流程（用户故事、需求、成功标准等）。
+
+如果是从 hook 自动触发（before_specify），完成后控制权自动交回 spec-kit specify 命令。

presets/nexusx/commands/nexusx-plan-decisions.md

@@ -0,0 +1,85 @@
+---
+description: "nexusx Plan 决策访谈——在 /speckit-plan 之前自动 prepend（before_plan hook），承载 DB 选型 / alembic / 第三方库 / TS SDK 决策。也可独立调用。"
+---
+
+# nexusx Plan 决策访谈
+
+**用途**：在执行 `/speckit-plan` **之前**完成 nexusx 专属决策访谈，把结论填入 plan.md 的 Technical Context 区块。
+
+**触发方式**：
+- **自动**：装了 nexusx preset 后，`/speckit-plan` 命令的 `before_plan` hook 会先跑本命令
+- **手动**：直接调用 `/nexusx-plan-decisions`
+
+**前置条件**：spec.md 必须存在且 Phase 0 需求确认纪要已填写（参考 `/nexusx-phase0`）。本命令开始时会校验 Phase 0 完整性，缺失则提示用户先跑 `/nexusx-phase0`。
+
+**插拔安全**：
+- 本命令独立可调用
+- hook 失败 / 被禁用时，spec-kit 原生 `/speckit-plan` 流程仍正常工作（Technical Context 由用户手动填写或留 NEEDS CLARIFICATION 占位）
+- 移除 nexusx preset 后，本命令与 hook 都消失
+
+**输出位置**：`<spec-dir>/plan.md` 的 Technical Context 区块（plan-template.md 中预留）。
+
+---
+
+## 决策 1：DB 选型 + async driver
+
+从 spec Phase 0 Step 0-7 的用户选择中确认并细化：
+
+| 项 | 决策 |
+|----|------|
+| DB 类型 | In-memory SQLite / File-backed SQLite / Docker PostgreSQL / Docker MySQL / External DB |
+| async driver | aiosqlite / asyncpg / aiomysql |
+| async URL 形态 | `sqlite+aiosqlite://` / `sqlite+aiosqlite:///./var/<name>.db` / `postgresql+asyncpg://...` 等 |
+| 同步 URL（alembic 用） | 对应 sync driver（sqlite / psycopg2 / mysqlclient） |
+
+## 决策 2：alembic 迁移策略
+
+| 项 | 决策 |
+|----|------|
+| 是否引入 alembic | 是 / 否（仅 In-memory SQLite 跳过） |
+| 初始 migration 来源 | 自动从 SQLModel metadata 生成 / 手写 |
+| seed 数据策略 | `init_db()` 钩子 / migration hook / 手动 |
+
+## 决策 3：第三方库维护状态调查
+
+对每个第三方库（来自 Phase 0 Step 0-6）调查：
+
+- 最新 release 版本与日期
+- 是否仍活跃维护（最近 commit / release 时间）
+- 与本项目 Python 版本、SQLModel / FastAPI 版本的兼容性
+- 替代方案（如果维护状态不佳）
+
+发现废弃或兼容性问题需告知用户、提供替代方案。
+
+## 决策 4：Service 切分最终方案（基于 Phase 0 Step 0-4 用户选择）
+
+把 Phase 0 用户选择的 Service 切分候选方案落到具体目录结构与边界：
+
+```text
+src/<project>/service/
+├── <domain1>/
+│   ├── methods.py
+│   ├── dtos.py
+│   └── service.py
+└── <domain2>/
+    └── ...
+```
+
+## 决策 5：是否生成 TypeScript SDK（Phase 4）
+
+| 项 | 决策 |
+|----|------|
+| 是否生成 TS SDK | 是 / 否 |
+| SDK 输出位置 | `sdk/<project>-ts/` 或 `packages/<project>-sdk/` |
+| GraphQL schema 来源 | SDL 文件 / introspection |
+| 生成工具 | graphql-codegen / 自研 |
+
+如果选 "是"，tasks 阶段会条件生成 Phase 4 任务；如果选 "否"，tasks 阶段跳过 Phase 4。
+
+---
+
+## 完成后
+
+把 5 个决策结论写入 plan.md 的 Technical Context，然后由 spec-kit 原生 `/speckit-plan` 接管剩余的 plan 撰写流程（research.md / data-model.md / contracts/ / quickstart.md 生成）。
+
+如果是从 hook 自动触发（before_plan），完成后控制权自动交回 spec-kit plan 命令。

presets/nexusx/commands/nexusx-tasks-phase-tags.md

@@ -0,0 +1,72 @@
+---
+description: "nexusx Tasks phase 标签规则——在 /speckit-tasks 之前自动 prepend（before_tasks hook），说明 phase-first 混合排序与 [P1]-[P4] / [USx] 双标签规则。也可独立调用。"
+---
+
+# nexusx Tasks phase 标签规则
+
+**用途**：在执行 `/speckit-tasks` **之前**输出 phase 标签规则提示，让生成的 tasks.md 符合 nexusx phase-first 混合排序。
+
+**触发方式**：
+- **自动**：装了 nexusx preset 后，`/speckit-tasks` 命令的 `before_tasks` hook 会先跑本命令
+- **手动**：直接调用 `/nexusx-tasks-phase-tags`
+
+**插拔安全**：
+- 本命令是文档型提示，不修改文件
+- hook 失败 / 被禁用时，spec-kit 原生 `/speckit-tasks` 仍正常工作（生成的 tasks.md 按 spec-kit 默认 user-story-first 排序，不带 [P1]-[P4] 标签）
+- 移除 nexusx preset 后，本命令与 hook 都消失
+
+**输出位置**：仅打印到对话上下文（提示 spec-kit tasks 命令遵循以下规则）。
+
+---
+
+## nexusx phase-first 混合排序规则
+
+spec-kit 原生 tasks 命令默认按 **user-story-first** 排序（每个 user story 一个 phase）。nexusx 在此基础上叠加 **phase-first** 维度，形成"双层标签"：
+
+### 标签格式
+
+```text
+- [ ] [TaskID] [P?] [Pn] [USx] 描述含文件路径
+```
+
+| 标签 | 含义 | 来源 |
+|------|------|------|
+| `[P]` | spec-kit 原生并行标记（可并行任务） | spec-kit 默认 |
+| `[P1]` | nexusx Phase 1（Schema 阶段任务） | nexusx |
+| `[P2]` | nexusx Phase 2（Methods 阶段任务） | nexusx |
+| `[P3]` | nexusx Phase 3（Service 阶段任务） | nexusx |
+| `[P4]` | nexusx Phase 4（TS SDK 阶段任务，条件生成） | nexusx（仅当 plan 决策 5 = "是"） |
+| `[USx]` | spec-kit 原生 user story 标签 | spec-kit 默认 |
+
+### Phase 划分（每个任务必须落且仅落一个）
+
+- **[P1] Schema 阶段**：SQLModel 实体定义、字段约束、关系（Foreign key、Relationship）、`__tablename__`、表初始化
+- **[P2] Methods 阶段**：实体的 `@query` / `@mutation` 方法、DTO（输入/输出）、字段级 description
+- **[P3] Service 阶段**：Service 切分（按 Phase 0 用户裁定）、跨实体工作流、UseCase 编排、REST + MCP 端点
+- **[P4] TS SDK 阶段**（条件）：基于 plan 决策 5 是否生成；包含 graphql-codegen 配置、SDK 入口、类型导出
+
+### 排序规则
+
+1. **首先**按 Phase 排序：[P1] → [P2] → [P3] → [P4]（如有）
+2. **Phase 内**按 user story 聚合：同 user story 的任务相邻
+3. **跨 Phase 的依赖**：[P3] Service 任务可能依赖 [P1] Schema 与 [P2] Methods；[P4] TS SDK 依赖 [P3]
+4. **Setup / Foundational / Polish 任务**不带 phase 标签（与 spec-kit 默认一致）
+
+### Phase 4 条件生成
+
+读 plan.md 的 "决策 5：是否生成 TypeScript SDK"：
+- **是** → tasks.md 末尾生成 Phase 4 区块（含 [P4] 任务）
+- **否** → 跳过 Phase 4，tasks.md 末尾说明"未生成 Phase 4（plan 决策：不生成 TS SDK）"
+
+### reference 文档引用
+
+生成 tasks.md 时，对应 phase 的实现指南链接到：
+- Phase 1 → `presets/nexusx/reference/phase1.md`
+- Phase 2 → `presets/nexusx/reference/phase2.md`
+- Phase 3 → `presets/nexusx/reference/phase3.md`
+
+---
+
+## 完成后
+
+打印完规则提示后，控制权自动交回 spec-kit 原生 `/speckit-tasks` 命令——后者会按上述规则生成 tasks.md。

presets/nexusx/preset.yml

@@ -0,0 +1,54 @@
+schema_version: "1.0"
+
+preset:
+  id: "nexusx"
+  name: "nexusx 4-Phase Workflow"
+  version: "0.2.0"
+  description: "nexusx 4-phase methodology (Schema → Methods → Service → optional SDK) layered on spec-kit SDD via prepend hooks (插拔不影响主流程)"
+  author: "tangkikodo"
+  repository: "https://github.com/KLR-Pattern/nexusx"
+  license: "MIT"
+
+requires:
+  speckit_version: ">=0.6.0"
+
+# 插拔安全设计（v0.2.0+）：
+# - 只 replace template（4 个），不 replace command
+# - spec-kit 原生命令 speckit.specify / plan / tasks 始终可见、可独立调用
+# - nexusx 增强逻辑（Phase 0 访谈、DB 选型决策、phase 标签）通过 .specify/extensions.yml
+#   的 before_specify / before_plan / before_tasks hooks 自动 prepend
+# - hooks optional: true，禁用或失败时不阻塞 spec-kit 主流程
+# - 用户禁用 preset → spec-kit 默认 template 接管，nexusx 增强完全不可见
+provides:
+  templates:
+    - type: "template"
+      name: "constitution-template"
+      file: "templates/constitution-template.md"
+      description: "nexusx 8 条硬规则 + V 型验收治理"
+      replaces: "constitution-template"
+
+    - type: "template"
+      name: "spec-template"
+      file: "templates/spec-template.md"
+      description: "spec-kit 用户故事结构 + nexusx Phase 0 需求确认纪要（可由 /nexusx-phase0 自动填充，也可手动填写）"
+      replaces: "spec-template"
+
+    - type: "template"
+      name: "plan-template"
+      file: "templates/plan-template.md"
+      description: "nexusx Technical Context（DB 选型 / service 切分 / TS SDK 决策，可由 /nexusx-plan-decisions 自动填充）"
+      replaces: "plan-template"
+
+    - type: "template"
+      name: "tasks-template"
+      file: "templates/tasks-template.md"
+      description: "phase-first 混合：Schema → Methods → Service → 可选 SDK（phase 标签规则可由 /nexusx-tasks-phase-tags 提示）"
+      replaces: "tasks-template"
+
+tags:
+  - "nexusx"
+  - "sqlmodel"
+  - "fastapi"
+  - "mcp"
+  - "4phase"
+  - "prepend-hooks"