@jakkrichm/create-nexus-devflow 2.2.0 → 2.2.2

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

@@ -23,7 +23,7 @@ Use this skill to guide the user on what to do next, inspect current workspace s
 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)**: `00-explore` ➔ `10-define` ➔ `20-spec` ➔ `30-plan` ➔ `40-execute` ➔ `50-verify` ➔ `60-report` ➔ `70-deliver`  
+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.*
 
 ---
@@ -45,14 +45,14 @@ When invoked without an argument (or when determining the next step), inspect:
      - 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}`.
 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`.
+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`.
 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 fix a bug -> Recommend `/fix <bug>`.
-- If no run is active and user has pending ideas in `devflow/ideas.md` -> Highlight `/spec IDEA-xxx`.
-- If no run is active and user wants deep architectural exploration -> Recommend `00-explore`.
+- 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 user asks to check system health -> Recommend `doctor`.
 
 ---
@@ -71,7 +71,7 @@ When invoked without an argument (or when determining the next step), inspect:
 | "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` |
 | "Check setup health & diagnostics" | `doctor` | `doctor` / `health` | `doctor` |
-| "Explore a new request / deep idea" | `00-explore` | `discover` | **Deep-Track**: `00` -> `10` -> `20` -> ... |
+| "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` |
@@ -84,6 +84,7 @@ When invoked without an argument (or when determining the next step), inspect:
 | "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 |
 
 ---
@@ -97,7 +98,7 @@ When invoked without an argument (or when determining the next step), inspect:
 - `complete` (`/complete`, `$complete`) - Safety pass, release digest, git merge, close run
 
 ### 2. Deep-Track (Architect Mode - 8 Steps)
-- `00-explore` - Explore request and decide Proceed/Defer/Reject
+- `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
@@ -109,6 +110,8 @@ When invoked without an argument (or when determining the next step), inspect:
 ### 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
@@ -118,6 +121,5 @@ When invoked without an argument (or when determining the next step), inspect:
 - `ci` - Automatic GitHub Actions workflow setup
 - `brief` - Read-only scope and risk pre-briefing
 - `autopilot` - Autonomous bounded delivery loop
-- `brainstorm` - Ideate without allocating running IDs
 - `debug` - Root cause investigation before or during implementation
 - `overview` - Living context synchronization into project-overview.md

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

@@ -1,166 +1,91 @@
 ---
 name: discovery
-description: "[devflow][B] Optional deep, multi-turn project discovery that helps the user develop detailed Blueprint project-plan.md and build-plan.md files through an adaptive conversation, then drafts them only after the user says they are ready. Use when the user explicitly runs /discovery or $discovery, asks for a guided planning interview, wants to think through a new product before writing the plans, or wants help deepening existing plans. Do not use merely because planning files are empty, after /onboard, or before /overview; users may always write the plans directly or create them through any conversation they prefer."
+description: "[devflow][D] Unified discovery and exploration stage in DevFlow 2.0 - conducts project-level roadmap discovery (project-plan.md/build-plan.md) or feature-level exploration (Stage 00) before delivery commitment."
+argument-hint: "[{title, request, IDEA-xxx, or discovery-id}]"
 ---
 
-# discovery - develop the plans through a deep conversation
+# discovery - Unified Discovery & Pre-Delivery Exploration
 
-Where this can sit in the workflow:
+$ARGUMENTS
 
-    /onboard  ->  write the plans directly  ->  /overview
-              \
-               ->  [discovery]  ->  review and approve plan drafts  ->  /overview
+`/discovery` is the central discovery entry point in Nexus-DevFlow. It operates in two adaptive modes based on input scope:
+1. **🗺️ Macro Project Discovery**: Develops high-level product and build roadmap plans (`devflow/project-plan.md` & `devflow/build-plan.md`) through an adaptive conversation before `/overview`.
+2. **🔍 Micro Feature Exploration (Stage 00)**: Explores a specific feature, request, or idea before committing to delivery, routes through supporting lenses, and finishes with a visible `Proceed`, `Defer`, or `Reject` decision before `10-define`.
 
-`/discovery` is an optional planning partner, not a required workflow gate and
-not a quick questionnaire. It can span as many turns as the project needs. Its
-job is to help the user think through the product, preserve the depth and nuance
-of that conversation, and draft the two user-owned planning files only when the
-user asks for drafts.
+---
+
+## Invocations & Usage
 
-Running `/onboard` never starts this skill. Empty plans never require it. A user
-who writes detailed plans manually, has another AI conversation, or arrives with
-finished plans continues directly to `/overview` exactly as before.
+```text
+# 1. Macro Project Planning Mode (No arguments or project scope)
+/discovery
+/discovery --project
 
-## Step 1 - establish the starting point
+# 2. Micro Feature Exploration Mode (Stage 00 of Deep-Track)
+/discovery {title or request}
+/discovery IDEA-xxx
+/discovery {discovery-id}
+```
 
-Read only the planning and project facts needed for the conversation:
+---
 
-- `devflow/project-plan.md`
-- `devflow/build-plan.md`
-- the root project manifest, README, and framework configuration when they
-  already contain relevant facts
-- `devflow/context/project-overview.md` only when the user is revisiting an
-  established project's direction
+## Mode 1: Macro Project Discovery (Roadmap & System Planning)
 
-Classify each planning file as a template, partial draft, or substantive plan.
-Never treat existing user content as disposable. When either plan has real
-content, summarize what it already establishes and ask whether the user wants to
-deepen it, revise a specific direction, or use it unchanged as conversation
-context. Do not replace it with a fresh generic plan.
+Use when:
+- Starting a new product or shaping high-level architecture across the entire repository.
+- Revisiting the overall project vision, major milestones, or tech stack before generating `/overview`.
 
-Start with a short working hypothesis about the project and name the most
-important unknown. Then ask one focused question. Do not draft either plan yet.
+### Process:
+1. **Establish Baseline**: Read `devflow/project-plan.md` and `devflow/build-plan.md` (if present).
+2. **Adaptive Conversation**: Ask 1-2 focused questions at a time covering problem space, user workflows, MVP boundaries, non-goals, data models, and stack constraints.
+3. **Periodic Snapshots**: Provide compact summaries of confirmed decisions, working assumptions, and open TODOs.
+4. **Draft Plans Behind Approval Gate**: Draft proposed `project-plan.md` and `build-plan.md` only when the user explicitly requests drafts.
+5. **Write on Approval**: Write approved files and recommend `/overview` as the next step.
 
-## Step 2 - run adaptive discovery
+---
+
+## Mode 2: Micro Feature Exploration (Stage 00 of Deep-Track)
+
+Use when:
+- Exploring a specific feature, complex architectural change, or pending idea (`/discovery IDEA-xxx`).
+- The team needs to evaluate feasibility, options, domain glossary, or root causes before locking delivery scope.
+
+### Markdown-First Contract:
+Write the primary discovery artifact to:
+```text
+devflow/discoveries/{DISCOVERY_ID}-{slug}/discovery.md
+```
+*(A Discovery ID uses the namespace `DISC-YYYYMMDD-NNN`. It is not a Running ID and does not reserve a numeric delivery run.)*
+
+### 5 Supporting Routes & Built-in Lenses:
+
+1. **Brainstorming Lens (Divergent & Convergent)**:
+   - Formulate 2-3 viable options with trade-offs.
+   - Construct a **Trade-off Comparison Table** (Pros, Cons, Recommendation).
+2. **Research & Empirical Proof Lens**:
+   - Inspect existing codebase patterns with search tools (`grep_search`, `rg`).
+   - Conduct external web search if library feasibility or API contracts are uncertain.
+3. **PRD & Scoping Lens**:
+   - Problem Statement, Target Persona, Core User Stories, and In-Scope vs. Out-of-Scope boundaries.
+4. **Issue & Bug Triage Lens**:
+   - Classify severity (`Critical/Blocker`, `Major`, `Minor`) and determine whether root-cause analysis (`debug`) is required.
+5. **Socratic Grilling & Domain Alignment Lens (`grill`)**:
+   - Codebase-grounded interactive inquiry to clarify entity boundaries, data flows, and edge cases.
+   - Record agreed terminology in `devflow/context/glossary.md` and major architecture decisions in `devflow/decisions/ADR-xxx-{slug}.md`.
+
+### Decision & Approval Gate:
+Set one visible decision:
+- `Proceed`: Enough value and evidence exist to define delivery work:
+  - **🏎️ Fast-Track (Recommended for 85% of standard features/fixes)**: Handoff to `/feature {discovery_id}` or `/fix {discovery_id}` (writes `devflow/context/current-feature.md`).
+  - **🏗️ Deep-Track (For large architectural epics/migrations)**: Handoff to `10-define {discovery_id}` (writes `devflow/context/current-run/10-define.md`).
+- `Defer`: The idea remains relevant but timing or evidence is not ready.
+- `Reject`: The idea should not proceed under current framing.
+
+---
 
-Ask one meaningful question at a time and let each answer shape the next one.
-Prefer a likely interpretation the user can correct over a vague request for
-more detail. Explain a tradeoff when the answer would materially change scope,
-architecture, cost, or build order.
+## Next Workflow Recommendations
 
-Cover the areas that matter to this project, not a fixed questionnaire:
-
-- problem, desired outcome, and why the project should exist
-- target users, their context, and their primary workflows
-- MVP capabilities, explicit non-goals, and later possibilities
-- business rules, data, integrations, permissions, and important edge cases
-- stack choices, constraints, dependencies, and technical unknowns
-- UI/UX direction, accessibility needs, and useful references
-- monetization or business model when relevant
-- deployment shape, environments, background work, storage, and operations
-- risks, assumptions, unresolved decisions, and how success will be judged
-- feature boundaries, dependencies, and a sensible build order
-
-Depth is the goal. Follow a consequential answer until its implications are
-clear instead of racing to the next category. Do not ask the user to repeat facts
-already established in the conversation or repository. Do not force irrelevant
-topics merely to complete a checklist.
-
-Periodically return a compact discovery snapshot with:
-
-- confirmed decisions
-- working assumptions that still need confirmation
-- open questions or conflicts
-- ideas explicitly deferred or excluded
-
-The snapshot keeps a long conversation coherent. It is not permission to write
-the plans.
-
-## Step 3 - decide whether the plans are ready
-
-Do not end discovery because a preset number of questions has been reached. It
-is ready to draft when:
-
-- the problem, users, and core workflows are concrete
-- MVP scope and non-goals are distinguishable
-- data and technical choices are detailed enough to expose major dependencies
-- the build order can be expressed as feature-sized outcomes
-- important contradictions are resolved
-- remaining unknowns are either safe to defer or explicitly accepted as TODOs
-- the user says they are ready for the plans to be drafted
-
-If the user asks for drafts while a material gap remains, name the gap and ask
-whether to continue discovery or preserve it as an explicit TODO. Respect the
-choice. The user may also stop at any time and write the plans manually.
-
-## Step 4 - draft both planning files
-
-When the user asks for drafts, produce complete proposed contents for both files
-without writing them yet.
-
-For `devflow/project-plan.md`:
-
-- keep the template's main subject areas, adding useful sections when the
-  conversation requires them
-- preserve rationale, examples, tradeoffs, constraints, edge cases, and
-  exclusions that will matter during later feature work
-- be as detailed as the project needs; never compress a rich discovery into a
-  line or two per section
-- distinguish confirmed decisions from assumptions and TODOs
-
-For `devflow/build-plan.md`:
-
-- use numbered checkboxes and optional milestone headings
-- keep each item a high-level, feature-sized outcome with a concise description
-- order items by dependency and the earliest useful vertical slice
-- keep implementation detail in later `/feature` specs rather than turning the
-  roadmap into a task dump
-- include only agreed scope; place deferred ideas outside the MVP or omit them as
-  the user directed
-
-If substantive plans already exist, preserve their information and completed
-build-plan numbering. Clearly identify proposed additions, removals, or changed
-decisions.
-
-End by asking the user to review the full drafts. Do not write either file in the
-same response that first presents them.
-
-## Step 5 - write only after approval
-
-Write the approved drafts only after the user explicitly approves them. If the
-user requests changes, revise the drafts and show the affected sections again
-before writing.
-
-After writing:
-
-- report which files changed
-- list any retained TODOs or unresolved decisions
-- remind the user that both files remain theirs to edit and deepen directly
-- stop before generating `devflow/context/project-overview.md`
-- point to `/overview` or `$overview` as the next optional command when the user
-  is satisfied with the plans
-
-## Rules
-
-- This skill is always optional. Never make it a prerequisite for `/overview`,
-  `/feature`, or any other Blueprint command.
-- Never start it automatically from `/onboard`, because planning files are
-  empty, or because a project is new.
-- Never imply that plans created manually or through another conversation are
-  inferior or incomplete merely because this skill was not used.
-- Never overwrite substantive planning content without showing the replacement
-  and receiving explicit approval.
-- Never write plans during the interview or after a vague signal such as "looks
-  good." The user must explicitly approve the proposed file contents.
-- Never scaffold the app, edit product code, generate the overview, create a
-  feature spec, commit, merge, push, or deploy.
-- Preserve detailed project reasoning in `project-plan.md`, while keeping
-  `build-plan.md` high-level and trackable.
-- Keep the conversation adaptive. Depth comes from relevant follow-up questions,
-  not from mechanically asking every possible question.
-
-## Formatting
-
-Follow `devflow/context/ai-interaction.md`. During discovery, ask one focused
-question per turn. For snapshots and draft reviews, use concise headings and
-lists so confirmed decisions and remaining gaps are easy to inspect.
+- **From Macro Project Mode**: Run `/overview` to compile context into `devflow/context/project-overview.md`.
+- **From Micro Stage 00 (Approved Proceed ➔ Fast-Track)**: Run `/feature {discovery_id}` to start lean living spec.
+- **From Micro Stage 00 (Approved Proceed ➔ Deep-Track)**: Run `10-define {discovery_id}` to allocate a Running ID.
+- **From Micro Stage 00 (Defer / Reject)**: No next command needed.

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

@@ -32,6 +32,7 @@ big item has been split into sub-items, the next unchecked sub-item is the targe
 
 ## Step 1 - pick the target
 
+- Given a Discovery ID or Idea ID (e.g. `/feature DISC-20260824-001` or `/feature IDEA-001`) -> import problem context, research, trade-offs, and ADRs from `devflow/discoveries/{DISC-ID}/discovery.md` or `devflow/ideas.md` into the living spec.
 - Given a number or name that matches a build-plan item -> use it.
 - Given a request that clearly describes a new feature with no reasonable match
   in the build plan -> follow **New-feature intake** below.
@@ -112,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/grill/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: grill
+description: "[devflow][B] Interactive Socratic alignment & domain modeling - stress-test plans, extract domain glossary, and record architecture decision records (ADRs) before delivery."
+argument-hint: "{topic, plan, or question}"
+---
+
+# grill - Socratic Alignment & Domain Modeling
+
+$ARGUMENTS
+
+Use this skill to conduct a codebase-grounded, interactive Socratic interview with the user. It clarifies domain vocabulary, resolves architectural ambiguities, and prevents misalignment before writing specifications or code.
+
+## Invocations & Aliases
+
+- `/grill {topic or plan}`: Standard slash command in Claude Code, Google Antigravity, and Gemini CLI
+- `grill {topic or plan}`: Plain text invocation
+- `$grill {topic or plan}`: Codex CLI invocation
+- `/align {topic}`: Alias for domain alignment
+
+## Core Philosophy: Align Before You Build
+
+1. **Codebase-Grounded**: Read existing code and context first. Never ask questions the codebase can already answer.
+2. **One Round at a Time**: Ask 1-2 focused, high-leverage questions per round with clear recommended defaults. Never dump a wall of 10 questions.
+3. **Lazy Inline Persistence**:
+   - Write agreed domain terminology to `devflow/context/glossary.md` the moment each term resolves.
+   - Record significant, hard-to-reverse technical decisions as ADRs in `devflow/decisions/ADR-xxx-{slug}.md`.
+4. **Zero Assumptions**: Challenge ambiguities, contradictory requirements, and naming inconsistencies upfront.
+
+---
+
+## Process & Execution Loop
+
+### 1. Grounding Phase (Silent Inspection)
+Before asking the first question:
+- Read `devflow/context/project-overview.md` and `devflow/context/coding-standards.md`.
+- Inspect existing domain terms in `devflow/context/glossary.md` (if present).
+- Search codebase patterns (`grep_search` / `rg`) related to the topic to ground technical reality.
+
+### 2. Interactive Socratic Interview Loop
+In each turn:
+- Identify the most critical unresolved branch in the design tree:
+  - **Domain Language & Boundaries**: "What exactly is an Entity X versus Entity Y in this context?"
+  - **Data Flow & Contracts**: "Who owns state X? Synchronous vs. asynchronous?"
+  - **Edge Cases & Failure Modes**: "What happens on network failure, concurrent mutation, or invalid input?"
+  - **Irreversible Trade-offs**: "Database schema change vs. application-layer adapter?"
+- Ask **1-2 questions maximum** per turn.
+- Always provide a recommended default with concise technical rationale.
+- Wait for the user's answer.
+
+### 3. Immediate State Persistence
+
+#### A. Domain Glossary (`devflow/context/glossary.md`)
+When a domain term or conceptual definition crystallizes, immediately create or append to `devflow/context/glossary.md`:
+
+```markdown
+### [Term / Concept]
+- **Definition**: Clear, unambiguous definition within this project.
+- **Constraints**: Invariants, boundaries, or lifecycle rules.
+- **Aliases / Related**: Related terms or common misnomers.
+```
+
+#### B. Architecture Decision Records (`devflow/decisions/ADR-xxx-{slug}.md`)
+When a decision meets the 3 ADR criteria:
+1. **Significant Impact**: Affects architecture, data schema, security, or public API.
+2. **Hard to Reverse**: Changing it later requires painful migration or refactoring.
+3. **Multiple Viable Alternatives**: There were real trade-offs between 2+ options.
+
+Allocate the next sequential ID (`ADR-001`, `ADR-002`, ...) and create `devflow/decisions/ADR-xxx-{slug}.md`:
+
+```markdown
+# ADR-xxx: {Title}
+
+- **Status**: Accepted
+- **Date**: {YYYY-MM-DD}
+- **Context**: {Why was this decision needed? What problem does it solve?}
+- **Decision**: {What did we decide to do?}
+- **Alternatives Considered**:
+  - *Option 1*: {Pros / Cons}
+  - *Option 2*: {Pros / Cons}
+- **Consequences**:
+  - *Positive*: {Benefits gained}
+  - *Trade-offs / Risks*: {Costs, constraints, or follow-ups}
+```
+
+---
+
+## 4. Closing & Handoff
+
+When all design branches are resolved:
+1. Summarize settled domain terms and created ADRs.
+2. Provide explicit next command recommendations:
+   - **Fast-Track (Standard Features/Fixes)**: Run `/feature {topic}` or `/fix {topic}` to immediately start the living spec.
+   - **Deep-Track (Large Architectural Epics)**: Run `10-define` or `/discovery` with the discovery context.

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

@@ -31,10 +31,10 @@ 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`, `00-explore`, `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`, `discovery`, `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`, `40-execute`, `devflow`).
-   - **Slash Prefix (`/`)**: For tools supporting slash commands (Claude Code, Google Antigravity, Gemini CLI), e.g., `/feature`, `/fix`, `/implement`, `/40-execute`, `/devflow`.
-   - **Dollar Prefix (`$`)**: For OpenAI Codex CLI or skill-invocation tools, e.g., `$feature`, `$fix`, `$40-execute`, `$devflow`.
+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`.
 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/`.
@@ -67,10 +67,10 @@ Recommended for 85% of daily work (features, bug fixes, UI improvements, iterati
 Recommended for large architectural epics, database migrations, and multi-agent coordination:
 
 ```text
-00-explore ──▶ 10-define ──▶ 20-spec ──▶ 30-plan ──▶ 40-execute ──▶ 50-verify ──▶ 60-report ──▶ 70-deliver
+discovery ──▶ 10-define ──▶ 20-spec ──▶ 30-plan ──▶ 40-execute ──▶ 50-verify ──▶ 60-report ──▶ 70-deliver
 ```
 
-1. `00-explore`: Explore request before delivery commitment without allocating running ID (`00-explore.md`).
+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).

package/template/devflow/build-plan.md

@@ -68,3 +68,13 @@
   - *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
+
+
+

package/template/devflow/context/ai-interaction.md

@@ -65,21 +65,37 @@ The entire lifecycle is driven by the **Single Living Spec (`devflow/context/cur
 *Recommended for large architectural epics, database migrations, security audits, and multi-agent coordination.*
 
 ```text
-00-explore ➔ 10-define ➔ 20-spec ➔ 30-plan ➔ 40-execute ➔ 50-verify ➔ 60-report ➔ 70-deliver
+discovery ➔ 10-define ➔ 20-spec ➔ 30-plan ➔ 40-execute ➔ 50-verify ➔ 60-report ➔ 70-deliver
 ```
 
-1. `00-explore`: Explore request before delivery commitment (`DISC-YYYYMMDD-NNN`).
+1. `discovery`: Unified pre-delivery discovery & Socratic alignment (`DISC-YYYYMMDD-NNN` or project roadmap).
 2. `10-define`: Turn approved discovery into bounded delivery run in `devflow/context/current-run/10-define.md`.
 3. `20-spec`: Formalize markdown 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`).
+4. `30-plan`: Breakdown spec into atomic 2-5 min tasks with explicit TDD decisions (`30-plan.md` + checklists).
+5. `40-execute`: Strict Red-Green-Refactor task execution behind review gates (`40-execute.md`).
+6. `50-verify`: Senior QA Two-Stage Review (Spec Fidelity + Quality/Security Gate) (`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/{features|fixes|rollbacks}/{xxx-slug}/`, and closes the run.
+8. `70-deliver`: Release packaging, git merge, archives `devflow/context/current-run/` ➔ `devflow/history/{category}/{xxx-slug}/`, and closes the run.
 
 ---
 
-## 4. Standalone HTML Reporting Policy
+## 4. Strict TDD & Two-Stage Review Interaction Rules
+
+### 🔴🟢 Strict TDD Execution Discipline
+During implementation in `/implement` and `40-execute`:
+- **Show Red Phase**: First execute tests to demonstrate expected failure *before* adding production code.
+- **Show Green Phase**: Add minimal production code, re-run tests, and report pass rate.
+- **Show Refactor Phase**: Polish and clean up with zero test regression.
+- **Forbidden**: Never present functional code changes without matching test execution evidence.
+
+### 🛡️ Two-Stage Verification Reporting
+During `/check` and `50-verify`:
+- **Stage 1 (Spec Fidelity Gate)**: Report each Acceptance Criterion and "Done When" status.
+- **Stage 2 (Code Quality & Security Gate)**: Report Typecheck, Lint, Test Suites, Security checks, and Findings Ledger (0 blockers).
+
+---
+
+## 5. Standalone HTML Reporting Policy
 
 > [!IMPORTANT]
 > **No Auto-Generated HTML**: Mainline stages (`/complete` and `60-report`) strictly output Markdown only.
@@ -120,3 +136,14 @@ Progress lives in persistent files, not in transient chat history:
 - `autopilot` is an explicit opt-in command (`/autopilot`). Never suggest it as the default next action.
 - When invoked, it runs one bounded spec/plan/implement/verify pass.
 - Autopilot **MUST stop** before `/complete`, merge, push, deploy, or any destructive action.
+
+---
+
+## 9. Socratic Alignment & Grilling Discipline (`/grill`)
+
+- **Align Before You Build**: When plans, domain language, or architectural boundaries are fuzzy, invoke `/grill` (or use the Grilling Lens in `00-explore`) to conduct a structured interview before creating specifications.
+- **Codebase-Grounded Inquiry**: Inspect existing context and code before asking questions. Never ask questions the codebase already answers.
+- **Turn Discipline**: Ask only 1–2 high-leverage questions per turn with clear recommended defaults. Never dump a wall of questions.
+- **Lazy Inline Persistence**:
+  - Immediately append resolved terms to `devflow/context/glossary.md`.
+  - Immediately record major, hard-to-reverse architectural decisions as Architecture Decision Records in `devflow/decisions/ADR-xxx-{slug}.md`.