@jakkrichm/create-nexus-devflow 2.2.1 → 2.5.0

package/template/.agents/skills/implement/SKILL.md

@@ -88,19 +88,23 @@ broad checkout. Ask whether to resolve only the conflict allowed by the approved
 spec or abandon the attempt. A cascade into another completed feature needs a
 new rollback plan.
 
-## Step 2 - build one step, review, iterate, checkpoint
+## Step 2 - build one step, review, iterate, checkpoint (Strict TDD)
 
 Work through the spec's build steps in order, one at a time. For each step:
 
-1. Implement just that step: the smallest change that satisfies its "done when."
-2. Show the **diff**, not whole files.
-3. **Explain it, and prove it.** Give a short summary: what the step delivered,
+1. **Strict TDD Cycle (for logic & behavior changes)**:
+   - **🔴 RED**: Write the unit test first in the relevant test file. Execute the test command and show the failing assertion output.
+   - **🟢 GREEN**: Implement only the minimal code in the source file necessary to make the test pass. Re-run test and show passing output.
+   - **🔵 REFACTOR**: Refactor and format cleanly, verifying that 100% of tests remain green.
+   - *Code Reversion Rule*: If production code is written without a prior test for behavior changes, revert it and write the test first.
+2. Implement just that step: the smallest change that satisfies its "done when."
+3. Show the **diff**, not whole files.
+4. **Explain it, and prove it.** Give a short summary: what the step delivered,
    one line per changed file on what it does and why, then confirm the step's
-   "done when" is met with evidence (build output, a screenshot, a passing
-   assertion). This summary is the comprehension gate, so keep it concrete, not
-   ceremonial. Include a short **How to try it** note when the step has a manual
+   "done when" is met with empirical evidence (test pass output, build output, or screenshot). This summary is the comprehension gate, so keep it concrete, not
+   vague. Include a short **How to try it** note when the step has a manual
    path: the command, URL, click, endpoint, or output the user can check.
-4. **Verify the step.** If `AGENTS.md` declares a `Verify` command, run that exact
+5. **Verify the step.** If `AGENTS.md` declares a `Verify` command, run that exact
    command as the automated gate. It is only an umbrella for checks the project
    actually has, so do not invent tests or other checks to satisfy it. If no
    `Verify` command exists, run the documented build command and the test command

package/template/.claude/skills/check/SKILL.md

@@ -66,21 +66,29 @@ Drive the app to each checklist item and capture evidence as you go:
 - Watch for **console errors and failed network requests**; a clean-looking screen
   with errors in the console is not a pass.
 
-## Step 4 - report
+## Step 4 - report (Two-Stage Review Pattern)
 
-Give a short, honest verdict, one line per checklist item:
+Format the verification report into two explicit review stages:
 
-    [pass] Download PDF saves certificate-<slug>.pdf - file downloaded, opened to the cert
-    [pass] Both buttons show a loading state - screenshot: loading-state.png
-    [fail] PDF border missing - printBackground not set; screenshot: pdf-no-border.png
-    [skip] Vercel render - can't verify locally (feature 9)
+### Stage 1: Spec Fidelity & Acceptance Gate
+Give a line-by-line verdict for each Acceptance Criterion and "done when" item:
 
-Then state the bottom line: are all the feature's done-whens proven, or not yet.
+    [pass] AC-1: Download PDF saves certificate-<slug>.pdf - file downloaded, opened to cert
+    [pass] AC-2: Both buttons show a loading state - screenshot: loading-state.png
+    [fail] AC-3: PDF border missing - printBackground not set; screenshot: pdf-no-border.png
+    [skip] AC-4: Vercel deploy smoke test - can't verify locally (pending staging)
 
-- All proven -> say it's ready for `/complete`.
-- Anything failed -> hand back to `/implement` to fix; name what to fix. Don't fix
-  it here.
-- Anything unverifiable -> say so plainly and why; never report it as a pass.
+### Stage 2: Code Quality, Security & Architecture Gate
+Report the multi-lane technical verification results:
+- **Type & Syntax**: `tsc --noEmit` (0 errors)
+- **Automated Tests**: Unit & integration tests (100% pass)
+- **Security & Hygiene**: Zero secrets, sanitized inputs
+- **Findings Ledger**: 0 blockers (P0/P1) in `devflow/context/findings.md`
+
+### Final Verdict & Route
+- **All Passed**: State that the feature is verified and ready for `/complete`.
+- **Any Failure**: Hand back to `/implement` with exact failure evidence and reproduction steps. Never fix issues inside `/check`.
+- **Unverifiable**: Clearly state reasons and residual risk. Never fabricate a pass.
 
 ## Rules
 

package/template/.claude/skills/complete/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: complete
-description: "[devflow][F] Wrap up a finished feature, fix, or rollback. Runs a final safety pass, archives its spec to devflow/history/features/, devflow/history/fixes/, or devflow/history/rollbacks/, updates the build plan for features and rollbacks, resets devflow/context/current-feature.md to its stub, makes one work-level commit, then squash-merges the branch to main and deletes it. Merges only with explicit approval, then asks separately before pushing main. Use when the user runs /complete, or asks to finish, wrap up, merge, or close out the current feature, fix, or rollback after it is built and reviewed."
+description: "[devflow][F] Wrap up a finished feature, fix, or rollback. Runs a final safety pass, archives its spec to devflow/history/features/, devflow/history/fixes/, or devflow/history/rollbacks/, updates the build plan for features and rollbacks, resets devflow/context/current-feature.md to its stub, and makes the work commit. Enforces a mandatory user gate: asks whether to squash-merge to main/master OR pull latest main/master into the feature/dev branch and push to remote for Merge Request (MR / PR) creation. Never merges into main/master without explicit user instruction."
 ---
 
-# complete - log the finished work, make the work commit, and merge
+# complete - log the finished work, make the work commit, and deliver
 
 Where this sits in the workflow:
 
     /feature, /fix, or /rollback  ->  /implement  ->  [complete]  ->  next
-    (the spec)                         (build it)      (commit + merge + log)
+    (the spec)                         (build it)      (commit + delivery gate)
 
 `/implement` built the feature, fix, or rollback on its branch, with optional per-step commit
 checkpoints. This skill closes it out: it logs the work, makes the single
-work-level commit, and squash-merges. Run it only when the work is done,
+work-level commit, and guides the delivery through a **Mandatory User Delivery Gate**. Run it only when the work is done,
 reviewed, and the documented `Verify` command, or the fallback build and tests,
 passes.
 
@@ -22,7 +22,7 @@ Confirm the work is actually finished: `devflow/context/current-feature.md`
 holds a real spec, its steps are built on a branch, and `Verify`, or the fallback
 build and tests, passes. If any of the
 spec's done-whens are behavioral, `/check` should have proven them against the
-running app first - don't merge on an unverified claim. Uncommitted step work is
+running app first - don't merge or complete on an unverified claim. Uncommitted step work is
 expected (per-step checkpoints are optional); this skill commits it. Don't require
 the steps to be pre-committed.
 
@@ -30,7 +30,7 @@ the steps to be pre-committed.
 
 Before logging or committing, run a short safety pass and report blockers only:
 
-- active spec exists and the work is not being completed from `main` or `master`
+- active spec exists and the work is not being completed directly from `main` or `master`
 - changed files are tied to the active spec, with no unrelated dirty work mixed
   in (a dirty `devflow/context/findings.md` is expected, since `/audit` writes it)
 - the exact `Verify` command from `AGENTS.md` passed in this session, when one is
@@ -107,25 +107,47 @@ into the app - delete the `prototypes/` folder now. The tokens live in the real
 stylesheet and the HTML mockups were always throwaway; fold the deletion into this
 feature's commit. Skip this if the feature didn't consume prototypes.
 
-## Step 2 - make the work commit
+## Step 2 - make the work commit on feature branch
 
 Stage everything on the branch (any uncommitted step work plus the Step 1 logging
-changes) and make one conventional work commit (for example `feat: <feature>`,
+changes) and make one conventional work commit on the active branch (for example `feat: <feature>`,
 `fix: <name>`, or `revert: roll back <feature>`). `Verify`, or the fallback build
 and tests, must pass first.
 
-## Step 3 - merge
+## Step 3 - Mandatory Delivery Gate (Ask User First)
+
+> [!IMPORTANT]
+> **MANDATORY USER SELECTION**: In real-world engineering teams, developers often do NOT have direct merge/push access to `main` or `master` (protected branches).
+> Therefore, you **MUST STOP AND ASK** the user to choose their desired delivery flow. **NEVER automatically merge into `main` or `master` without explicit user choice.**
+
+Present the user with two clear delivery options:
+
+### 🔀 Option 1: Team MR / PR Flow (Pull latest main/master & Push dev branch) [Default for Teams]
+- **When to choose**: When working in a team where code reviews happen via GitLab Merge Request (MR) or GitHub Pull Request (PR), or where developers lack direct write access to protected `main`/`master` branches.
+- **Execution Actions**:
+  1. Detect default base branch name (`main` or `master`).
+  2. Run `git pull origin <main/master>` (or `git fetch origin <main/master> && git merge origin/<main/master>`) to bring the latest upstream changes into the active feature/dev branch.
+  3. If merge conflicts occur, highlight them clearly and help the user resolve them.
+  4. Run `Verify` (or build & tests) to ensure integrity after the merge.
+  5. Run `git push origin <current-feature-branch>` to push the up-to-date branch to the remote repository.
+  6. Stop and inform the user that the branch is synchronized and pushed, ready for them to open a Merge Request (MR / PR) on GitLab/GitHub.
+  7. **Do NOT merge into local `main`/`master` and do NOT delete the branch.**
+
+### 🔀 Option 2: Direct Local Squash-Merge (Solo / Direct Access Mode)
+- **When to choose**: Only when the user explicitly instructs that they want to merge directly into `main` or `master` locally now (e.g. solo projects or Tech Leads with merge privileges).
+- **Execution Actions**:
+  1. Switch to `main` or `master`: `git checkout <main/master>`.
+  2. Squash-merge the branch: `git merge --squash <feature-branch>`.
+  3. Commit the squash-merge.
+  4. Delete the local feature branch only with the user's explicit consent.
+  5. **Stop and ask separately** before pushing local `main`/`master` to remote upstream. The merge approval does NOT count as push approval.
+  6. Run `git push origin <main/master>` only after separate explicit confirmation.
 
-1. Squash-merge the branch into main, only with the user's explicit go-ahead, so
-   the feature lands as one clean commit regardless of how many checkpoints the
-   branch carried.
-2. Delete the branch after a clean merge.
-3. Stop and ask whether to push local `main` to its upstream. The merge approval
-   does not count as push approval.
-4. Push main only after a separate explicit yes to push main in the current chat.
-   If the repo has no remote or upstream, say so instead of guessing.
+---
+
+## Step 4 - Finish & Try Path
 
-Then point the user at `/feature`, `/fix`, or `/rollback` for the next thing.
+Point the user at `/feature`, `/fix`, or `/rollback` for the next task.
 
 Finish with a concise **How to try it** note for the completed work. For a
 rollback, explain how to confirm the removed behavior is gone and name one
@@ -135,26 +157,15 @@ that command can read the archived feature after `current-feature.md` is reset.
 
 ## Rules
 
+- **Mandatory User Confirmation Gate**: Always ask before choosing between Team MR/PR Push vs Direct Squash-Merge.
+- **Never auto-merge into main/master**: The decision to merge into `main` or `master` belongs strictly to the user.
 - The work item is the unit of history: one squashed feature, fix, or rollback
-  commit on main, even if the branch carried several checkpoint commits.
+  commit, even if the branch carried several checkpoint commits.
 - A rollback preserves the original feature archive and adds a separate rollback
   archive. Never rewrite history to make the feature look as if it never existed.
-- Don't merge unfinished or failing work. The documented `Verify` command, or
+- Don't merge or push unfinished or failing work. The documented `Verify` command, or
   the fallback build and tests, must pass first.
-- Never merge while a P0 or P1 finding is `open` or `fixed` in the ledger. The
-  recorded ways past the gate without code are `accepted` (only by the user's
-  explicit decision, with their reason) or `invalid` (only from re-examination
-  evidence or the user's explicit call); both travel into the archive, never a
-  silent drop.
-- Merging and pushing are the user's calls: get an explicit yes for the merge,
-  then ask whether to push main. Do not treat merge approval, `/complete`, or
-  "looks good" as permission to push.
-- Push main only after a separate explicit yes to push main in the current chat.
+- Never merge or push while a P0 or P1 finding is `open` or `fixed` in the ledger.
+- Pushing to remote is always explicit: confirm before running `git push`.
 - One item per completion. If a parent feature still has unchecked sub-features,
-  leave the parent unchecked.
-
-## Formatting
-
-Format the output to match the project's conventions in
-`devflow/context/ai-interaction.md`: concise, scannable markdown, with lists for
-enumerations and tables for matrices rather than dense paragraphs.
+  leave the parent unchecked.

package/template/.claude/skills/debug/SKILL.md

@@ -117,14 +117,10 @@ Give a concise debug report:
 
 Choose the next action without writing files:
 
-- Active feature or fix caused the failure -> return the diagnosis to
-  `/implement`.
-- No active work item and the bug is confirmed -> recommend
-  `/fix "<concise bug and confirmed cause>"`.
-- Cause is only likely or blocked -> recommend the next diagnostic evidence, not
-  a speculative repair.
-- The issue is planned product work rather than a defect -> point to
-  `/feature`.
+- Active feature or fix caused the failure -> return the diagnosis to `/implement` with instructions to write a failing reproduction test ([TDD-Red]) first.
+- No active work item and the bug is confirmed -> recommend `/fix "<concise bug and confirmed cause>"` (which will write a failing test first before fixing).
+- Cause is only likely or blocked -> recommend the next diagnostic evidence, not a speculative repair.
+- The issue is planned product work rather than a defect -> point to `/feature`.
 
 ## Rules
 

package/template/.claude/skills/devflow/SKILL.md

@@ -5,26 +5,19 @@ description: "[devflow][B] Flagship interactive guide, state inspector, and inte
 
 # devflow - Interactive Workflow Guide & Intent Router for Nexus-DevFlow
 
-## Command Track Policy
-- [F] Fast-Track only
-- [D] Deep-Track only
-- [B] Available in both tracks (Track-agnostic)
-
-
-Use this skill to guide the user on what to do next, inspect current workspace state, map their natural language intent to the right Nexus-DevFlow track (Fast-Track or Deep-Track) or companion command, or display a sitemap of available DevFlow skills.
+Use this skill to guide the user on what to do next, inspect current workspace state, map their natural language intent to the matching Nexus-DevFlow stage or companion command, or display a sitemap of available DevFlow skills.
 
 ## Input
 
-- **No argument (`devflow`, `devflow`, `$devflow`, or `status`)**: Inspect current workspace state (active run in `devflow/runs/` or `devflow/context/current-stage.md`, active discovery in `devflow/discoveries/`, pending ideas in `devflow/ideas.md`, open findings in `devflow/context/findings.md`, and project overview in `devflow/context/project-overview.md`) and recommend the exact next action.
-- **With user request (`devflow "<request>"`)**: Classify the user's intent and guide them to the matching DevFlow workflow track or companion command path.
+- **No argument (`devflow`, `/devflow`, `$devflow`, or `status`)**: Inspect current workspace state (active run in `devflow/context/current-stage.md`, active living spec in `devflow/context/current-feature.md`, active discovery in `devflow/discoveries/`, pending ideas in `devflow/ideas.md`, open findings in `devflow/context/findings.md`, and project overview in `devflow/context/project-overview.md`) and recommend the exact next action.
+- **With user request (`devflow "<request>"`)**: Classify the user's intent and guide them to the matching DevFlow workflow stage or companion command path.
 
-## Dual-Track Architecture
+## The Unified Living Spec Architecture (DevFlow 2.5.0)
 
-Nexus-DevFlow supports two seamless workflow tracks:
-1. **🏎️ Fast-Track (Blueprint Mode - 4 Steps)**: `/spec` ➔ `/implement` ➔ `/check` ➔ `/complete`  
-   *Driven by a **Single Living Spec (`current-feature.md`)** for fast, high-velocity daily development and bugfixes (85% of tasks).*
-2. **🏗️ Deep-Track (Architect Mode - 8 Steps)**: `discovery` ➔ `10-define` ➔ `20-spec` ➔ `30-plan` ➔ `40-execute` ➔ `50-verify` ➔ `60-report` ➔ `70-deliver`  
-   *Driven by modular separate stage files for large, high-stakes architectural epics and multi-agent coordination.*
+Nexus-DevFlow uses a **Single Unified Living Spec Model**:
+- **The 4-Stage Lifecycle**: `/feature` (or `/fix`) ➔ `/implement` ➔ `/check` ➔ `/complete`
+- Driven by a **Single Living Spec (`devflow/context/current-feature.md`)** that integrates architectural depth (Define, Spec, Plan, Execution Log, Multi-Lane QA, and Release Digest) into one clear living document.
+- **Pre-Flight Inception Engine**: Companion skills (`/discovery`, `/idea`, `/grill`, `/brainstorm`) feed directly into `/feature`.
 
 ---
 
@@ -33,93 +26,72 @@ Nexus-DevFlow supports two seamless workflow tracks:
 When invoked without an argument (or when determining the next step), inspect:
 
 1. **Project Setup Baseline**: Read `devflow/context/project-overview.md` and `devflow/context/coding-standards.md`. If empty or default placeholders, recommend `onboard` (for fresh projects) or `adopt` (for existing codebases).
-2. **Active Delivery Run**: Read `devflow/context/current-stage.md` and check `devflow/runs/{RUNNING_ID}/`.
-   - **If Fast-Track (`current-feature.md`, `spec.md`, or `blueprint.md` present)**:
-     - If `current-feature.md` (or `spec.md`) has incomplete checklist items -> Recommend `/implement` (or `implement {RUNNING_ID}`).
-     - If all tasks done but no passing verification evidence -> Recommend `/check` (or `check {RUNNING_ID}`).
-     - If verification evidence passed -> Recommend `/complete` (or `complete {RUNNING_ID}`).
-   - **If Deep-Track (numbered stage files present)**:
-     - If at `10-define.md` -> Recommend `20-spec {RUNNING_ID}`.
-     - If at `20-spec.md` -> Recommend `30-plan {RUNNING_ID}`.
-     - If at `30-plan.md` -> Recommend `40-execute {RUNNING_ID}`.
-     - If at `40-execute.md` with all tasks done -> Recommend `50-verify {RUNNING_ID}`.
-     - If passed `50-verify.md` -> Recommend `60-report {RUNNING_ID}` then `70-deliver {RUNNING_ID}`.
+2. **Active Delivery Run**: Read `devflow/context/current-stage.md` and `devflow/context/current-feature.md`.
+   - If `current-feature.md` has incomplete checklist tasks (`- [ ]`) -> Recommend `/implement`.
+   - If all tasks are completed (`- [x]`) but no passing verification evidence in Section 5 -> Recommend `/check`.
+   - If verification evidence passed in Section 5 -> Recommend `/complete`.
 3. **Active Discovery**: Check `devflow/discoveries/` for open discovery notes.
-4. **Pending Ideas Inbox**: Check `devflow/ideas.md`. If items exist under `## 📌 Pending Ideas`, summarize them in a **💡 Pending Ideas (Inbox)** list with their IDs (`[IDEA-xxx]`), feasibility, and mention that they can be started with `/spec IDEA-xxx` or `/discovery IDEA-xxx`.
+4. **Pending Ideas Inbox**: Check `devflow/ideas.md`. If items exist under `## 📌 Pending Ideas`, summarize them in a **💡 Pending Ideas (Inbox)** list with their IDs (`[IDEA-xxx]`), feasibility, and mention that they can be started with `/feature IDEA-xxx` or `/discovery IDEA-xxx`.
 5. **Audit Findings Ledger**: Check `devflow/context/findings.md` for open high-severity findings.
 
 ### Default State Recommendations
-- if no run is active and user wants to start a feature -> Recommend `/feature <name>`.
+- If no run is active and user wants to start a feature -> Recommend `/feature <name>`.
 - If no run is active and user wants to fix a bug -> Recommend `/fix <bug>`.
-- If no run is active and user has pending ideas in `devflow/ideas.md` -> Highlight `/spec IDEA-xxx` or `/discovery IDEA-xxx`.
-- If no run is active and user wants deep architectural exploration -> Recommend `discovery`.
+- If no run is active and user has pending ideas in `devflow/ideas.md` -> Highlight `/feature IDEA-xxx` or `/discovery IDEA-xxx`.
+- If no run is active and user wants deep architectural exploration -> Recommend `/discovery`.
 - If user asks to check system health -> Recommend `doctor`.
 
 ---
 
 ## Intent Classification & Skill Routing
 
-| User Intent / Request Type | Recommended Skill | Normal Name / Alias | Track / Lifecycle Path |
+| User Intent / Request Type | Recommended Skill | Normal Name / Alias | Lifecycle Path |
 | :--- | :--- | :--- | :--- |
-| **"Spec new feature / lean workflow"** | `spec` | `/spec` / `/feature` | **Fast-Track**: `/spec` -> `/implement` -> `/check` -> `/complete` |
-| **"Quick bugfix / ad-hoc change"** | `spec` | `/fix` | **Fast-Track**: `/fix` -> `/implement` -> `/check` -> `/complete` |
+| **"Spec new feature / living spec"** | `feature` | `/feature` / `/spec` | **Unified**: `/feature` -> `/implement` -> `/check` -> `/complete` |
+| **"Quick bugfix / ad-hoc change"** | `fix` | `/fix` | **Unified**: `/fix` -> `/implement` -> `/check` -> `/complete` |
 | **"Capture quick idea / thought"** | `idea` | `/idea` | **Companion**: Enriches & saves to `devflow/ideas.md` |
-| **"Execute implementation tasks"** | `implement` | `/implement` | **Fast-Track**: `/implement` -> `/check` |
-| **"Run QA verification & check"** | `check` | `/check` | **Fast-Track**: `/check` -> `/complete` |
-| **"Complete run & git merge"** | `complete` | `/complete` | **Fast-Track**: `/complete` |
-| **"Generate HTML dashboard report"**| `report-html` | `/report:html` | **Standalone**: Converts `current-feature.md` / `60-report.md` to HTML |
-| "Setup DevFlow on fresh/new project" | `onboard` | `onboard` / `setup` | `onboard` -> `/spec` or `10-define` |
-| "Adopt DevFlow on existing codebase" | `adopt` | `adopt` / `bootstrap` | `adopt` -> `/spec` or `10-define` |
+| **"Pre-delivery exploration / research"**| `discovery`| `/discovery` | **Pre-Flight**: `discovery` -> `/feature` |
+| **"Socratic alignment / ADR / glossary"**| `grill` | `/grill` / `/align` | **Pre-Flight**: `grill` -> `/feature` |
+| **"Execute implementation tasks"** | `implement` | `/implement` | **Core Loop**: `/implement` -> `/check` |
+| **"Run QA verification & check"** | `check` | `/check` | **Core Loop**: `/check` -> `/complete` |
+| **"Complete run & git merge"** | `complete` | `/complete` | **Core Loop**: `/complete` |
+| **"Generate HTML dashboard report"**| `report-html` | `/report:html` | **Standalone**: Converts `current-feature.md` or archive to HTML |
+| "Setup DevFlow on fresh/new project" | `onboard` | `onboard` / `setup` | `onboard` -> `/feature` |
+| "Adopt DevFlow on existing codebase" | `adopt` | `adopt` / `bootstrap` | `adopt` -> `/feature` |
 | "Check setup health & diagnostics" | `doctor` | `doctor` / `health` | `doctor` |
-| "Explore a new request / deep idea" | `discovery` | `discovery` / `/discovery` | **Deep-Track**: `discovery` -> `10` -> `20` -> ... |
-| "Define delivery boundaries and ID" | `10-define` | `define` | **Deep-Track**: `10` -> `20` -> `30` |
-| "Break down spec into plan (Deep)" | `30-plan` | `plan` | **Deep-Track**: `30` -> `40` -> `50` |
-| "Deep code implementation" | `40-execute` | `implement` | **Deep-Track**: `40` -> `50` |
-| "Deep QA verification" | `50-verify` | `verify` | **Deep-Track**: `50` -> `60` -> `70` |
-| "Deep markdown digest report" | `60-report` | `report` | **Deep-Track**: `60` -> `70` |
-| "Deep release packaging & merge" | `70-deliver` | `release` | **Deep-Track**: `70-deliver` |
 | "Human manual QA walkthrough guide" | `try` | `try` | Companion (after implement or check) |
-| "Safely plan feature or run reversal" | `rollback` | `rollback` | Companion |
+| "Safely plan feature or run reversal"| `rollback` | `rollback` | Companion |
 | "Set up automatic GitHub Actions CI" | `ci` | `ci` | Companion |
-| "Pre-check scope & risks before spec" | `brief` | `brief` | Companion |
+| "Pre-check scope & risks before spec"| `brief` | `brief` | Companion |
 | "Run autonomous bounded delivery loop"| `autopilot` | `autopilot` | Companion |
 | "Brainstorm ideas without ID" | `brainstorm` | `brainstorm` | Companion |
-| "Socratic alignment / ADR / glossary" | `grill` | `/grill` / `align` | Companion (pre-spec / domain modeling) |
 | "Investigate failure or root cause" | `debug` | `debug` | Companion |
 
 ---
 
 ## Available Skills Sitemap
 
-### 1. Fast-Track (Blueprint Mode - 4 Steps)
-- `spec` (`/spec`, `/feature`, `/fix`, `$spec`) - Define, spec, plan, and create `current-feature.md`
-- `implement` (`/implement`, `$implement`) - Execute planned checklist tasks with TDD
-- `check` (`/check`, `$check`) - Senior QA review, multi-lane verification, record evidence
-- `complete` (`/complete`, `$complete`) - Safety pass, release digest, git merge, close run
+### 1. Mainline Living Spec Loop (4 Steps)
+- `feature` (`/feature`, `/spec`) - Define, spec, and plan in `current-feature.md`
+- `fix` (`/fix`) - Document an ad-hoc bug or change in `current-feature.md`
+- `implement` (`/implement`) - Execute planned checklist tasks with TDD
+- `check` (`/check`) - Senior QA review, multi-lane verification, record evidence
+- `complete` (`/complete`) - Safety pass, release digest, git merge, close run
 
-### 2. Deep-Track (Architect Mode - 8 Steps)
+### 2. Pre-Flight Discovery Engine
 - `discovery` - Project roadmap planning or feature exploration before delivery commitment
-- `10-define` - Lock delivery boundaries and allocate Running ID
-- `20-spec` - Formalize markdown delivery contract
-- `30-plan` - Breakdown spec into phased tasks with test decisions
-- `40-execute` - Incremental task implementation
-- `50-verify` - Senior QA review and multi-lane validation
-- `60-report` - Generate standardized markdown digest report
-- `70-deliver` - Release packaging, release notes, and merge
-
-### 3. Public Companion Commands
-- `devflow` (`status`, `/devflow`) - Interactive guide, state inspector, and router
-- `idea` (`/idea`) - Quick idea capture and AI feasibility enrichment into `devflow/ideas.md`
-- `grill` (`/grill`, `align`) - Codebase-grounded Socratic alignment, domain glossary, and ADR recorder
-- `brainstorm` - Ideate and compare trade-off options without allocating running IDs
-- `report-html` (`/report:html`) - Standalone interactive HTML report dashboard generator
-- `onboard` - Baseline stack setup for freshly scaffolded projects
-- `adopt` - Bootstrap DevFlow into existing brownfield projects
-- `doctor` - Read-only health check for setup and drift
-- `try` - Step-by-step human manual QA review guide
-- `rollback` - Safe feature/run reversal planner
-- `ci` - Automatic GitHub Actions workflow setup
-- `brief` - Read-only scope and risk pre-briefing
-- `autopilot` - Autonomous bounded delivery loop
-- `debug` - Root cause investigation before or during implementation
-- `overview` - Living context synchronization into project-overview.md
+- `idea` - Quick idea capture with AI feasibility scoring
+- `grill` (or `align`) - Socratic alignment, domain modeling, and ADR recording
+- `brainstorm` - Multi-option ideation with trade-off analysis
+
+### 3. Verification & Diagnostic Companions
+- `doctor` - Health check for setup, adapters, and workspace state
+- `audit` - Branch-aware or full-project code, security, and quality review
+- `test` / `tests` - Test suite runner and unit test scaffolding
+- `ci` - Set up or normalize GitHub Actions checks
+- `status` - Read-only progress summary and next action suggestion
+- `try` - Human manual QA walkthrough guide
+- `report-html` - Standalone interactive HTML report dashboard
+- `debug` - Root-cause investigation without editing code
+- `rollback` - Safe reversal of completed features
+- `release` - Deployment readiness check

package/template/.claude/skills/feature/SKILL.md

@@ -113,10 +113,14 @@ build plan starts high-level.
 
 For the one (sub-)feature being built now, write a full spec to
 `devflow/context/current-feature.md` (create `devflow/context/` if needed), following
-`reference/feature-spec-template.md`. Fill every section: goal, in/out of scope,
-the build loop, small build steps as a checklist (`- [ ]`, each with an observable
-"done when" - `/implement` ticks them off and resumes from the first unchecked
-one), files/areas, data/contracts, testing, and notes for the AI.
+`reference/feature-spec-template.md`. Fill every section:
+- Goal, Problem Statement, and In/Out of scope
+- Acceptance Criteria (AC-1, AC-2, ...)
+- Small build steps as atomic 2-5 min checklist items (`- [ ]`, supporting `[TDD-Red]`, `[TDD-Green]`, `[TDD-Refactor]` triplets for functional logic)
+- Two-Stage Verification Strategy:
+  - **Stage 1**: Spec Fidelity & Acceptance Criteria Gate
+  - **Stage 2**: Technical Multi-lane quality, tests, security, and findings ledger
+- Files/areas to modify, data/contracts, and notes for the AI.
 
 **Visual or replication features need a reference image.** If the feature is
 "make it look like X" - recreating an existing design, matching a mockup, or

package/template/.claude/skills/implement/SKILL.md

@@ -88,19 +88,23 @@ broad checkout. Ask whether to resolve only the conflict allowed by the approved
 spec or abandon the attempt. A cascade into another completed feature needs a
 new rollback plan.
 
-## Step 2 - build one step, review, iterate, checkpoint
+## Step 2 - build one step, review, iterate, checkpoint (Strict TDD)
 
 Work through the spec's build steps in order, one at a time. For each step:
 
-1. Implement just that step: the smallest change that satisfies its "done when."
-2. Show the **diff**, not whole files.
-3. **Explain it, and prove it.** Give a short summary: what the step delivered,
+1. **Strict TDD Cycle (for logic & behavior changes)**:
+   - **🔴 RED**: Write the unit test first in the relevant test file. Execute the test command and show the failing assertion output.
+   - **🟢 GREEN**: Implement only the minimal code in the source file necessary to make the test pass. Re-run test and show passing output.
+   - **🔵 REFACTOR**: Refactor and format cleanly, verifying that 100% of tests remain green.
+   - *Code Reversion Rule*: If production code is written without a prior test for behavior changes, revert it and write the test first.
+2. Implement just that step: the smallest change that satisfies its "done when."
+3. Show the **diff**, not whole files.
+4. **Explain it, and prove it.** Give a short summary: what the step delivered,
    one line per changed file on what it does and why, then confirm the step's
-   "done when" is met with evidence (build output, a screenshot, a passing
-   assertion). This summary is the comprehension gate, so keep it concrete, not
-   ceremonial. Include a short **How to try it** note when the step has a manual
+   "done when" is met with empirical evidence (test pass output, build output, or screenshot). This summary is the comprehension gate, so keep it concrete, not
+   vague. Include a short **How to try it** note when the step has a manual
    path: the command, URL, click, endpoint, or output the user can check.
-4. **Verify the step.** If `AGENTS.md` declares a `Verify` command, run that exact
+5. **Verify the step.** If `AGENTS.md` declares a `Verify` command, run that exact
    command as the automated gate. It is only an umbrella for checks the project
    actually has, so do not invent tests or other checks to satisfy it. If no
    `Verify` command exists, run the documented build command and the test command

package/template/AGENTS.md

@@ -1,12 +1,12 @@
-# Nexus-DevFlow 2.0 (The 3-Pillars & Dual-Track Model)
+# Nexus-DevFlow 2.5.0 (The 3-Pillars & Single Living Spec Model)
 
 Instructions for AI coding agents working in this project. This is the cross-tool entry point: Codex, Google Antigravity, Cursor, GitHub Copilot, Gemini CLI, Aider, Zed, Windsurf, and others read `AGENTS.md`. Claude Code reads `CLAUDE.md`, which imports this file (`@AGENTS.md`), so there is a single source of truth.
 
 ## What this is
 
-This project uses **Nexus-DevFlow**, an agentic workflow layer supporting **The 3-Pillars Workspace Architecture & Dual-Track Delivery**:
+This project uses **Nexus-DevFlow**, an agentic workflow layer supporting **The 3-Pillars Workspace Architecture & Single Living Spec Model**:
 1. **🔮 Future (Backlog)**: `devflow/ideas.md` — Centralized Idea Inbox with AI scoring.
-2. **⚡ Present (Active Context)**: `devflow/context/` — Living Source of Truth & Active Work (`current-feature.md` for Fast-Track, `current-run/` for Deep-Track).
+2. **⚡ Present (Active Context)**: `devflow/context/` — Living Source of Truth & Active Work (`current-feature.md` Single Living Spec).
 3. **📦 Past (History Archive)**: `devflow/history/` — Categorized delivery archives (`features/`, `fixes/`, `rollbacks/`, and `HISTORY.md`).
 
 To start a new project, scaffold the application first in an empty folder, then run `npx @jakkrichm/create-nexus-devflow` to overlay DevFlow onto your codebase.
@@ -18,6 +18,7 @@ To start a new project, scaffold the application first in an empty folder, then
 - `devflow/context/ai-interaction.md` - how to interact with the user on this project
 - `devflow/context/current-stage.md` - active discovery or running delivery state
 - `devflow/context/findings.md` - quality, security, and verification ledger
+- `devflow/context/glossary.md` - domain terms & architecture definitions
 
 ## Tool-Specific Adapters & Execution Rules
 
@@ -31,60 +32,50 @@ Unused adapter families can be removed. Codex, Antigravity, GitHub Copilot, and
 
 ### Universal Invocation & Agent Directives:
 
-1. **Canonical Command Names & AI Provider Invocation**: Each workflow stage and companion tool has exactly **one Canonical Name** (e.g. `feature`, `fix`, `implement`, `check`, `complete`, `discovery`, `10-define`, `20-spec`, `30-plan`, `40-execute`, `50-verify`, `60-report`, `70-deliver`, `devflow`, `doctor`, `overview`, `debug`, `onboard`, `adopt`, `try`, `rollback`, `idea`, `ci`, `test`, `autopilot`, `prototype`, `report-html`, `brief`, `audit`, `release`, `brainstorm`, `grill`). The way you invoke commands depends on your AI Provider / Tool:
-   - **Canonical Name (Plain text)**: Directly invoke or prompt the command by its standard name (e.g., `feature`, `40-execute`, `devflow`, `discovery`).
-   - **Slash Prefix (`/`)**: For tools supporting slash commands (Claude Code, Google Antigravity, Gemini CLI), e.g., `/feature`, `/fix`, `/implement`, `/40-execute`, `/devflow`, `/discovery`.
-   - **Dollar Prefix (`$`)**: For OpenAI Codex CLI or skill-invocation tools, e.g., `$feature`, `$fix`, `$40-execute`, `$devflow`, `$discovery`.
+1. **Canonical Command Names & AI Provider Invocation**: Each workflow stage and companion tool has exactly **one Canonical Name** (e.g. `feature`, `fix`, `implement`, `check`, `complete`, `discovery`, `idea`, `grill`, `brainstorm`, `devflow`, `doctor`, `overview`, `debug`, `onboard`, `adopt`, `try`, `rollback`, `ci`, `test`, `tests`, `autopilot`, `prototype`, `report-html`, `brief`, `audit`, `release`). The way you invoke commands depends on your AI Provider / Tool:
+   - **Canonical Name (Plain text)**: Directly invoke or prompt the command by its standard name (e.g., `feature`, `implement`, `devflow`, `discovery`).
+   - **Slash Prefix (`/`)**: For tools supporting slash commands (Claude Code, Google Antigravity, Gemini CLI), e.g., `/feature`, `/fix`, `/implement`, `/devflow`, `/discovery`.
+   - **Dollar Prefix (`$`)**: For OpenAI Codex CLI or skill-invocation tools, e.g., `$feature`, `$fix`, `$devflow`, `$discovery`.
 2. **OpenAI Codex & Non-Native CLI Tools**: In environments without automatic background skill discovery (such as OpenAI Codex CLI, Aider, or generic terminals), **you MUST use your file reading tool to inspect `.agents/skills/<skill>/SKILL.md` before executing the stage** to strictly follow its schema, artifact contract, and quality gates.
 3. **Google Antigravity & Claude Code**: Native skill engines automatically discover and surface `.agents/skills/` and `.claude/skills/`.
 4. **State-Aware Inspection**: When unsure what to do next, invoke `devflow` to automatically inspect `devflow/context/current-stage.md` and active context in `devflow/context/`.
-5. **Default Artifact & Communication Language (Thai)**: All generated markdown stage artifacts (`current-feature.md`, `00-explore.md`...`70-deliver.md`) and user communication MUST default to **Thai (`th`)**, while code, technical terms, file paths, and identifiers remain in English.
+5. **Default Artifact & Communication Language (Thai)**: All generated markdown stage artifacts (`current-feature.md`, `discovery.md`, etc.) and user communication MUST default to **Thai (`th`)**, while code, technical terms, file paths, and identifiers remain in English.
 
 ---
 
-## 🏎️ Track 1: Fast-Track (Blueprint Mode - 4 Steps)
+## ⚡ The Unified 4-Stage Living Spec Lifecycle
 
-Recommended for 85% of daily work (features, bug fixes, UI improvements, iterative tasks):
+All development tasks (from lean UI fixes to deep architectural epics) execute through the 4-step progressive lifecycle:
 
 ```text
 /feature (หรือ /fix) ──▶ /implement ──▶ /check ──▶ /complete
 ```
 
 1. **`feature` / `fix` (`/feature`, `/fix`, `/spec`)**:
-   - **Purpose**: Combines Discover, Define, Spec, and Plan into one unified step. Checks Single Active Run Guardrail, allocates sequential ID (`xxx-slug`), and creates the **Single Living Spec (`devflow/context/current-feature.md`)**.
+   - **Purpose**: Combines Discover, Define, Spec, and Plan into one unified step. Checks Single Active Run Guardrail, allocates sequential ID (`xxx-slug`), and creates the **Single Living Spec (`devflow/context/current-feature.md`)** with 6 structured sections.
    - **Artifact**: `devflow/context/current-feature.md`
 2. **`implement` (`/implement`)**:
-   - **Purpose**: Incrementally executes checklist tasks with TDD discipline and appends progress to `devflow/context/current-feature.md`.
+   - **Purpose**: Incrementally executes checklist tasks with TDD discipline (Red-Green-Refactor) and appends diff evidence to `current-feature.md`.
 3. **`check` (`/check`)**:
-   - **Purpose**: Senior QA review, multi-lane verification matrix (Typecheck, Lint, Test suites, manual proof), and records evidence into `devflow/context/current-feature.md`.
+   - **Purpose**: Senior QA review, multi-lane verification matrix (Typecheck, Lint, Test suites, manual proof), and records empirical proof into `current-feature.md`.
 4. **`complete` (`/complete`)**:
-   - **Purpose**: Final safety pass, records Release Digest, automatically archives to `devflow/history/{features|fixes|rollbacks}/{xxx-slug}.md`, resets the stub, performs git merge, and closes the run without auto HTML generation.
+   - **Purpose**: Final safety pass, records Release Digest, automatically archives to `devflow/history/{features|fixes|rollbacks}/{xxx-slug}.md`, resets the stub, and performs git squash-merge.
 
 ---
 
-## 🏗️ Track 2: Deep-Track (Architect Mode - 8 Steps)
+## 🔮 Pre-Flight Discovery & Architectural Alignment (Companions)
 
-Recommended for large architectural epics, database migrations, and multi-agent coordination:
-
-```text
-discovery ──▶ 10-define ──▶ 20-spec ──▶ 30-plan ──▶ 40-execute ──▶ 50-verify ──▶ 60-report ──▶ 70-deliver
-```
-
-1. `discovery`: Unified pre-delivery discovery & exploration (project-level roadmap planning or feature-level exploration with 5 lenses: Brainstorm, Research, PRD, Bug Triage, Grill) before delivery commitment (`devflow/discoveries/{DISC-ID}/discovery.md`).
-2. `10-define`: Turn approved discovery into bounded delivery run in `devflow/context/current-run/10-define.md`.
-3. `20-spec`: Formalize markdown-first delivery contract & acceptance criteria (`20-spec.md`).
-4. `30-plan`: Breakdown spec into executable tasks with test decisions (`30-plan.md` + checklists).
-5. `40-execute`: Incremental task execution behind review gates (`40-execute.md`).
-6. `50-verify`: Senior QA review & multi-lane verification checks (`50-verify.md`).
-7. `60-report`: Standardized markdown delivery digest (`60-report.md`).
-8. `70-deliver`: Release packaging, git merge, archives `devflow/context/current-run/` ➔ `devflow/history/{category}/{xxx-slug}/`, and closes run.
+- `discovery`: Unified pre-delivery discovery & exploration (`devflow/discoveries/{DISC-ID}/discovery.md`).
+- `idea`: Quick idea capture and AI feasibility scoring (`devflow/ideas.md`).
+- `grill` (or `align`): Socratic alignment, domain modeling, and ADR recording (`devflow/decisions/`).
+- `brainstorm`: Divergent/convergent ideation with trade-off analysis.
 
 ---
 
 ## 🌐 Standalone HTML Reporting Policy
 
 > [!IMPORTANT]
-> **No Auto-Generated HTML**: Mainline flows (`/complete` and `60-report`) strictly output Markdown only.
+> **No Auto-Generated HTML**: Mainline flows (`/complete`) strictly output Markdown only.
 > When an interactive web dashboard is desired for presentation or sharing, invoke the standalone companion command:
 > `/report:html` (or `npm run report:html -- {ID}`).
 

package/template/devflow/build-plan.md

@@ -68,3 +68,22 @@
   - *Dependencies*: None
   - *Scope*: ผสานความสามารถ Adopt Workflow Visibility (Commit vs Local-only), การรองรับ OpenCode และ Multi-Adapter Checkbox Prompt ใน CLI พร้อมอัปเดต Doctor checks และซิงก์ Baseline SHA เป็น v0.13.0 (`0b65166`)
 
+---
+
+## 🧪 Phase 9: Strict TDD Sub-Tasks & Two-Stage Review Guardrails
+
+- [x] **9. Strict TDD Sub-Tasks & Two-Stage Review Guardrails** `[Size: M]`
+  - *Dependencies*: None
+  - *Scope*: นำ Strict TDD (Red-Green-Refactor) Sub-Tasks และ Two-Stage Review Pattern (Stage 1: Spec Fidelity, Stage 2: Quality & Security Gate) ผสานเข้าสู่ Prompt Rules, Coding Standards, AI Interaction และ Stage Skills (`30-plan`, `40-execute`, `50-verify`, `feature`, `implement`, `check`, `debug`) พร้อมอัปเดต Template และ Unit Tests
+
+---
+
+## ⚡ Phase 10: Nexus-DevFlow 2.5.0 (Unified Living Spec Model)
+
+- [x] **10. Unify Deep-Track and Fast-Track into Single Living Spec Model** `[Size: L]`
+  - *Dependencies*: ADR-001
+  - *Scope*: รวมความสามารถเชิงสถาปัตยกรรมระดับลึกของ Deep-Track เข้าสู่ 4 ขั้นตอนหลักของ Fast-Track บนเอกสาร Single Living Spec (`current-feature.md`) จัดเก็บประวัติแบบ Single Archive (`.md`), ปลดระวาง stage skills 10-70 ที่ซ้ำซ้อน, และปรับปรุงเอกสาร & Schemas ทั้งหมด
+
+
+
+