feat(preset): add nexusx-4phase speckit preset

speckit-preset/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nexusx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

speckit-preset/README.md

@@ -0,0 +1,90 @@
+# nexusx-4phase preset
+
+A spec-kit preset that layers the nexusx **4-phase V-model workflow** on top of
+the standard spec-kit pipeline (`specify → plan → tasks → implement`).
+
+## When to use
+
+Use this preset when the project follows the nexusx 4-phase methodology:
+
+| Phase | What happens | Output |
+|-------|-------------|--------|
+| **Phase 0** | Requirements confirmation (8 steps, with user) | `spec.md` (entities, relationships, aggregate roots, service split, DB choice) |
+| **Phase 1** | Schema + ER diagram + mock seed | `src/models.py`, `src/db.py`, `src/database.py`, Voyager, optional alembic |
+| **Phase 2** | Method implementation + Entity mount | `src/service/<domain>/methods.py`, `mount_method()` |
+| **Phase 3** | UseCase composition + MCP | `dtos.py`, `service.py`, `create_use_case_router`, MCP, CLI |
+| **Phase 4** | OpenAPI → TS SDK | `fe/src/sdk/*.gen.ts` |
+
+Each phase follows a **V-model**: write acceptance criteria → implement →
+verify each criterion with the user before moving on.
+
+## What it overrides
+
+### Templates (composition)
+
+| Template | Strategy | Effect |
+|----------|----------|--------|
+| `spec-template` | `append` | Adds Phase 0 sections (entities, relationships, service split, DB strategy) |
+| `plan-template` | `append` | Adds Phase 1 sections (SQLModel, Voyager, alembic decisions) |
+| `phase-template` | (new) | Per-phase V-model spec: V降 / implementation / V升 |
+| `checklist-template` | `replace` | V-model acceptance checklist + `spec/` directory completeness check |
+
+### Commands (composition)
+
+| Command | Strategy | Effect |
+|---------|----------|--------|
+| `speckit.specify` | `wrap` | Runs Phase 0's 8-step requirements confirmation |
+| `speckit.plan` | `wrap` | Runs Phase 1 schema/ER/DB decisions |
+| `speckit.tasks` | `wrap` | Partitions tasks by Phase (2/3/4) |
+| `speckit.implement` | `wrap` | Runs V-model loop per phase |
+| `speckit.nexusx.phase` | (new) | Enter a specific phase explicitly |
+
+### Scaffold
+
+`scaffold/` contains the code skeleton (`pyproject.toml` + `src/`) that
+`speckit.plan` references when bootstrapping a new project.
+
+## Install
+
+```bash
+# From local directory (development)
+specify preset add --dev ./speckit-preset
+
+# Verify resolution
+specify preset resolve spec-template
+specify preset resolve speckit.specify
+
+# Remove
+specify preset remove nexusx-4phase
+```
+
+## Workflow
+
+```bash
+# 1. Phase 0 — requirements confirmation
+/speckit-specify <feature description>
+# → spec.md with Phase 0 sections filled
+
+# 2. Phase 1 — schema decisions
+/speckit-plan
+# → plan.md with Phase 1 (SQLModel, ER, DB choice, alembic decision)
+
+# 3. Phase 2-4 — implementation
+/speckit-tasks
+# → tasks.md grouped by Phase 2/3/4
+
+/speckit-implement
+# → V-model loop per Phase: pause for user verification after each phase
+
+# Or enter a specific phase directly
+/speckit-nexusx-phase 3
+```
+
+## Status
+
+Work in progress — see `../skill/` for the canonical 4-phase methodology this
+preset is being migrated from.
+
+## License
+
+MIT

speckit-preset/commands/speckit.implement.md

@@ -0,0 +1,89 @@
+---
+description: Execute tasks.md — wrap nexusx V-model loop (acceptance → implement → verify) per Phase.
+---
+
+<!--
+  ============================================================================
+  nexusx-4phase preset — wrap of speckit.implement
+  ============================================================================
+  The core /speckit-implement runs every task in dependency order. The nexusx
+  overlay enforces the V-model at each phase boundary:
+
+    V降 — re-confirm acceptance criteria for the current Phase with the user
+    实现 — run tasks belonging to the current Phase
+    V升 — verify each criterion tick-by-tick with the user
+    Gate — pause for explicit user sign-off before next Phase
+
+  Phases in scope: 1 / 2 / 3 / 4 (Phase 0 is handled by /speckit-specify).
+  ============================================================================
+-->
+
+## nexusx V-Model Implementation Overlay
+
+You are running `/speckit-implement` with the **nexusx-4phase preset** active.
+Execution proceeds **phase by phase**, not task-by-task across the whole
+`tasks.md`.
+
+### Per-phase execution loop
+
+For each Phase (1 → 2 → 3 → 4):
+
+1. **V降** — open `specs/<feature>/phaseN.md`. If the V降 acceptance criteria
+   table is empty or has unchecked `[NEEDS CLARIFICATION]` rows, run the
+   criteria definition conversation with the user FIRST. Do not start coding.
+2. **Filter tasks** — pick only tasks labeled `[PN]` from `tasks.md`.
+3. **Implement** — execute tasks in dependency order. Use the phase-specific
+   reference docs:
+   - Phase 1: `plan.md` Phase 1 addendum (SQLModel, alembic, Voyager).
+   - Phase 2: tasks.md Phase 2 block + nexusx `mount_method()` pattern.
+   - Phase 3: tasks.md Phase 3 block + UseCaseService / create_use_case_router
+     / create_use_case_graphql_mcp_server patterns.
+   - Phase 4: tasks.md Phase 4 block + `@hey-api/openapi-ts` config.
+4. **V升** — for each row in `phaseN.md`'s V降 table, run the verification
+   method with the user. Tick the corresponding V升 box only after explicit
+   user confirmation.
+5. **Gate** — announce "Phase N complete, awaiting sign-off" and STOP. Do not
+   start Phase N+1 tasks until the user explicitly says so (e.g. "go ahead
+   with Phase 3" or `/speckit-nexusx-phase 3`).
+
+### Phase-specific verification cheatsheet
+
+| Phase | Typical verification |
+|-------|---------------------|
+| 1 | Open Voyager; check ER shape; verify mock seed row counts; (persistent) `alembic upgrade head` |
+| 2 | GraphiQL: run every mounted `@query` / `@mutation`; confirm seed data still queryable; `pytest tests/` |
+| 3 | `curl /api/<service>/<method>` returns DTO shape (no FK fields); Voyager shows service tree; MCP 4-layer tools: `list_apps` → `describe_compose_schema` → `describe_compose_method` → `compose_query`; missing-param returns 422 |
+| 4 | `fe/src/sdk/types.gen.ts` covers every DTO; field names are snake_case; nested relations produce correct TS types |
+
+### Phase 3 specifically — Service layer rules
+
+When implementing Phase 3 tasks:
+
+- `methods.py` returns ORM `Model` instances (pure business logic).
+- `service.py` calls `methods.py`, then converts: `[DtoType.model_validate(m) for m in models]` → `Resolver().resolve(dtos)`.
+- `service.py` MUST NOT touch the DB directly. If you need a custom SELECT,
+  use `build_dto_select(Entity, DtoType)` → `dict(row._mapping)` → DTO.
+- Every `UseCaseService` method that is exposed via `@query` / `@mutation`
+  MUST declare a return type annotation. Missing annotation →
+  `MissingReturnAnnotationError` at server build time.
+- MCP http_app: `transport="streamable-http"`, `stateless_http=True`, and
+  nest `mcp_http.lifespan(mcp_http)` inside the FastAPI lifespan.
+
+### Iteration handling
+
+If the user is iterating on an existing project (not a fresh 4-phase build):
+
+- Confirm only the delta with Phase 0 (spec.md changes).
+- Implementation MAY merge Phase 1-3 into a single coding pass, but the
+  `phaseN.md` spec files MUST still be back-filled with V降 + V升 before
+  reporting completion.
+- Before "done", verify `specs/<feature>/phase*.md` are all non-empty
+  (`wc -l specs/<feature>/phase*.md`).
+
+---
+
+## Core implement workflow
+
+Below this point, the core `/speckit-implement` content runs unchanged.
+
+{CORE_TEMPLATE}

speckit-preset/commands/speckit.nexusx.phase.md

@@ -0,0 +1,110 @@
+---
+description: Enter a specific nexusx phase (0/1/2/3/4) — load phase instructions and run the V-model cycle.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+The argument is a single phase number (`0` / `1` / `2` / `3` / `4`). Parse it
+and dispatch to the corresponding flow below. If empty, print a phase picker:
+
+```text
+Which phase?
+  0 — Requirements confirmation (entities / relationships / service split / DB)
+  1 — Schema + ER diagram + mock seed
+  2 — Method implementation + Entity mount
+  3 — UseCase composition + MCP + REST/CLI
+  4 — OpenAPI → TS SDK
+```
+
+## Setup
+
+1. Read `.specify/feature.json` to resolve `feature_directory`.
+   - If missing, ERROR: "Run /speckit-specify first."
+2. Read `specs/<feature>/spec.md` to confirm Phase 0 is complete.
+   - For phases 1-4: if any Phase 0 box is unticked, STOP and tell the user
+     to finish Phase 0 first.
+3. Ensure `specs/<feature>/phaseN.md` exists; create it from the
+   `phase-template` if not.
+
+## Phase 0 — Requirements confirmation
+
+If argument is `0`:
+
+1. Open `specs/<feature>/spec.md` Phase 0 addendum.
+2. Walk the 8 steps with the user in order:
+   - 0-1 Entities & Fields
+   - 0-2 Relationships
+   - 0-3 Aggregate Roots
+   - 0-4 Service Partitioning (propose candidates, let user pick)
+   - 0-5 GraphQL Positioning
+   - 0-6 Third-Party Libraries
+   - 0-7 DB Persistence & Migration (must be explicit)
+   - 0-8 Checklist
+3. Tick boxes in step 0-8 as the user confirms each item.
+4. When all 8 boxes are ticked, suggest `/speckit-plan`.
+
+## Phase 1 — Schema + ER + mock seed
+
+If argument is `1`:
+
+1. Read `specs/<feature>/plan.md` Phase 1 addendum (V降 acceptance criteria).
+2. If V降 table is empty, run the criteria definition conversation first.
+3. Implement: `db.py`, `models.py`, `database.py`, `main.py` (+ alembic +
+   `load_seed.py` for persistent branch).
+4. Run Voyager verification with the user.
+5. Tick every V升 box in `phase1.md`.
+6. Pause for sign-off. Do NOT start Phase 2 automatically.
+
+## Phase 2 — Methods + Entity mount
+
+If argument is `2`:
+
+1. Open `specs/<feature>/phase2.md` V降 table.
+2. For each service in spec.md Step 0-4:
+   - Create `src/service/<domain>/methods.py` with the service's async functions.
+   - Wire `mount_method()` in `src/models.py` (delayed import, `@functools.wraps`).
+3. Restart the server, run every `@query` / `@mutation` in GraphiQL with the user.
+4. Tick V升 boxes.
+5. Pause.
+
+## Phase 3 — UseCase composition + MCP
+
+If argument is `3`:
+
+1. Open `specs/<feature>/phase3.md` V降 table.
+2. For each service:
+   - Create `dtos.py` (DefineSubset DTOs, no `from __future__ import annotations`).
+   - Create `service.py` (UseCaseService, return annotations required).
+   - Create `service/<domain>/spec.md`.
+3. Wire `main.py`: `create_use_case_router` (or `create_jsonrpc_router`) +
+   `create_use_case_graphql_mcp_server` + `create_use_case_voyager` (+ optional
+   `create_use_case_cli`).
+4. Verify with the user:
+   - curl returns DTO-shaped responses (FK hidden).
+   - Voyager shows service tree.
+   - MCP 4-layer tools work end-to-end.
+   - Missing params → 422.
+5. Tick V升 boxes.
+6. Pause.
+
+## Phase 4 — OpenAPI → TS SDK
+
+If argument is `4`:
+
+1. Open `specs/<feature>/phase4.md` V降 table.
+2. Create `fe/openapi-ts.config.ts` and `fe/package.json`.
+3. `cd fe && npm install && npm run generate-client`.
+4. Verify with the user:
+   - Every DTO has a matching TS type in `fe/src/sdk/types.gen.ts`.
+   - Field names are snake_case (preserve backend names).
+   - Nested relations produce correct recursive TS types.
+5. Tick V升 boxes.
+
+## Completion Report
+
+Report the phase that ran, the count of V升 boxes ticked, and any unresolved
+acceptance criteria. Suggest the next phase if appropriate.

speckit-preset/commands/speckit.plan.md

@@ -0,0 +1,64 @@
+---
+description: Generate plan.md + Phase 1 design artifacts — wraps nexusx Phase 1 (SQLModel schema, ER diagram, mock seed, alembic decision).
+---
+
+<!--
+  ============================================================================
+  nexusx-4phase preset — wrap of speckit.plan
+  ============================================================================
+  Runs the core /speckit-plan flow, then drives Phase 1 design:
+  - Branch on the Step 0-7 DB choice (in-memory vs persistent)
+  - Produce SQLModel entity specs with the conventions
+  - Produce Voyager wiring and mock seed strategy
+  - Define Phase 1 V-model acceptance criteria with the user
+
+  {CORE_TEMPLATE} is replaced at install time with the core plan command.
+  ============================================================================
+-->
+
+## nexusx Phase 1 Overlay
+
+You are running `/speckit-plan` with the **nexusx-4phase preset** active.
+After the core plan workflow writes `plan.md` and the standard design artifacts
+(`research.md`, `data-model.md`, `contracts/`, `quickstart.md`), drive the
+**Phase 1 schema & DB decisions**.
+
+### Pre-check
+
+Read `specs/<feature>/spec.md` and confirm Step 0-7 is filled in. If any
+Phase 0 box is unticked or `[NEEDS CLARIFICATION]` markers remain, STOP and
+tell the user to finish Phase 0 first.
+
+### Phase 1 design tasks (write to plan.md, Phase 1 addendum section)
+
+1. **List concrete entities** derived from spec.md Step 0-1 / 0-2. For each:
+   - SQLModel class name + table name
+   - Fields with types and `Field(description=...)`
+   - `Relationship(...)` declarations with `sa_relationship_kwargs={"lazy": "noload"}`
+2. **Branch on DB choice**:
+   - In-memory → document `init_db()` create_all + mock seed flow.
+   - Persistent → document alembic init steps, env.py edits, script.py.mako edit, baseline migration, optional `load_seed.py`.
+3. **Document Voyager wiring**: `create_use_case_voyager(services=[], er_manager=er)` mounted at `/voyager`.
+4. **Phase 1 pitfalls**: surface the 6 pitfalls from the plan-template addendum as explicit risks to mitigate.
+5. **Define Phase 1 acceptance criteria** with the user (V降 — see plan-template addendum) and record in `specs/<feature>/phase1.md`.
+
+### Phase 1 acceptance gate
+
+Phase 1 implementation must NOT start until:
+
+- [ ] `plan.md` Phase 1 addendum is filled
+- [ ] `phase1.md` V-model acceptance criteria table is agreed with the user
+- [ ] Any alembic-related risk (persistent branch) is called out
+
+### Hand-off
+
+When done, suggest the user run `/speckit-tasks` to break Phase 1 (and later
+phases) into actionable tasks.
+
+---
+
+## Core plan workflow
+
+Below this point, the core `/speckit-plan` content runs unchanged.
+
+{CORE_TEMPLATE}