@jakkrichm/create-nexus-devflow 2.2.0 → 2.2.2

package/template/.agents/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/.agents/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/.agents/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/.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/10-define/SKILL.md

@@ -43,7 +43,7 @@ using:
 Require:
 - `Decision: Proceed`
 - `Approval Status: Approved`
-- A resolvable Discovery ID and `00-explore.md`
+- A resolvable Discovery ID and `discovery.md` (or legacy `00-explore.md`)
 
 ### 3. Allocate Sequential ID
 - Inspect `devflow/history/HISTORY.md` and allocate sequential ID without prefix (e.g. `022-{slug}`).

package/template/.claude/skills/30-plan/SKILL.md

@@ -83,12 +83,12 @@ Record important findings in `30-plan.md`. Use legacy context updates only when
 
 ### 4. Build The Plan
 
-Use the old planner discipline, but keep `30-plan.md` as the main contract:
+Use strict planning discipline, keeping `30-plan.md` as the main contract:
 
+- **Atomic Micro-Task Sizing (2–5 Minutes)**: Every subtask must be a small, verifiable unit that can be implemented and reviewed cleanly without context sprawl.
 - record the planning loop evidence: context read, observations, adjustments made, stop condition, and handoff notes
 - add phases in dependency order
-- add subtasks that are small, verifiable units
-- include explicit files to modify or create
+- include explicit files to modify or create (exact file paths)
 - include patterns to follow
 - include verification command or manual check
 - include a test decision for every subtask
@@ -97,18 +97,24 @@ Use the old planner discipline, but keep `30-plan.md` as the main contract:
 Each subtask should answer:
 
 - what to change
-- where to change it
+- where to change it (exact path)
 - which pattern to follow
 - how to verify it
 - whether automated tests are required, manual, or not required
 
-### 4.1 Test Decision Gate
+### 4.1 Strict TDD Task Breakdown & Test Decision Gate
 
-**STRICT MANDATE (กฎเหล็ก Unit Test)**: สำหรับทุก subtask ที่มีการเพิ่ม แก้ไข หรือเปลี่ยนแปลงการทำงานของโค้ด (Behavior Change) **ต้องระบุเป็น `Required` เสมอ** ห้ามละเว้นเด็ดขาด ยกเว้นงานประเภทเอกสารหรือแก้ไข Configuration เท่านั้น
+**STRICT MANDATE (กฎเหล็ก Unit Test & TDD)**: สำหรับทุก subtask ที่มีการเพิ่ม แก้ไข หรือเปลี่ยนแปลงการทำงานของโค้ด (Behavior Change) **ต้องระบุเป็น `Required` เสมอ** และต้องย่อยงานเป็น **TDD Triplet Sub-tasks** ดังนี้:
+
+```markdown
+- [ ] Task 1.1 [TDD-Red]: Write failing test for {feature/behavior} in {test_file} and verify failure
+- [ ] Task 1.2 [TDD-Green]: Implement minimal code in {src_file} to satisfy Task 1.1 test
+- [ ] Task 1.3 [TDD-Refactor]: Refactor logic, eliminate duplication, and verify zero regression
+```
 
 For every subtask, decide one of:
 
-- `Required`: automated tests must be created or updated (Mandatory for all behavior changes)
+- `Required`: automated tests must be created or updated (Mandatory for all behavior changes, formatted as TDD Triplet)
 - `Manual/Command Only`: verification is non-test but still explicit (Only for configuration/infrastructure tasks)
 - `Not Required`: no new automated test is needed because there is no meaningful behavior surface (Only for documentation/comments)
 

package/template/.claude/skills/40-execute/SKILL.md

@@ -59,27 +59,24 @@ Confirm the current Git branch with `git branch --show-current` and use that bra
 
 Select one scoped unit of work at a time. Do not implement the whole plan as one blob.
 
-### 2. Execute One Scoped Unit
+### 2. Execute One Scoped Unit (Strict TDD Red-Green-Refactor)
 
-Use the original coder discipline, adapted to 2.0:
+Use the strict coder discipline:
 
-- **STRICT MANDATE (กฎเหล็ก Unit Test)**: ต้องสร้าง/แก้ไข Unit Test ควบคู่กับการแก้ไขโค้ดเสมอ โดยห้ามแก้ไขเฉพาะไฟล์โค้ดหลัก (Production Code) โดยไม่แก้ไขหรือสร้างไฟล์เทสต์ควบคู่กัน
+- **STRICT MANDATE (กฎเหล็ก Unit Test & TDD)**: สำหรับทุกงานที่มีการแก้ไข logic การทำงาน ต้องสร้างหรือแก้ไข Unit Test ควบคู่กับการแก้ไขโค้ดเสมอ โดยห้ามเขียนเฉพาะ Production Code โดยไม่มีเทสต์
+- **🔴 RED (Test First)**: ออกแบบและเขียน Test Case ในไฟล์เทสต์ก่อนเสมอ แล้วรันคำสั่งเทสต์เพื่อพิสูจน์ว่า **Test ล้มเหลว (FAIL)** ตามที่คาดหวัง
+- **🟢 GREEN (Minimal Implementation)**: เขียน Production Code เท่าที่จำเป็นเพื่อให้เทสต์ผ่าน แล้วรันคำสั่งเทสต์เพื่อพิสูจน์ว่า **Test ผ่าน 100% (PASS)**
+- **🔵 REFACTOR (Clean Code)**: ปรับปรุงโครงสร้างโค้ดให้อ่านง่าย กำจัดความซ้ำซ้อน (DRY) โดยที่เทสต์ยังคงเขียว 100%
+- **Code Deletion / Reversion Rule**: หากเผลอเขียน Production Code ก่อนมีเทสต์ ให้ Revert หรือลบโค้ดส่วนนั้น แล้วเริ่มวงจร RED ก่อนเสมอ
 - start each scoped unit by naming its intent, context, expected observation, adjustment route, and stop condition
 - read referenced pattern files before editing
 - read the test decision from `30-plan.md`
 - confirm assumptions, target files, and success criteria before editing
-- make the smallest useful code change
 - preserve project style
-- run the planned verification
+- run the planned verification and capture concrete terminal outputs
 - record observation, adjustment, stop condition status, and the result in `40-execute.md`
 - update checklist item status, timestamps, and evidence links as work progresses
 
-If tests are `Required`:
-
-1. **TDD Cycle (RED)**: ออกแบบและเขียนตัวเทสต์ให้พังก่อน (หรือเขียนโครงสร้างเทสต์ที่คาดหวังผลลัพธ์ที่ถูกต้อง) ตามแนวทางใน [coding-standards.md](file:///devflow/context/coding-standards.md)
-2. **GREEN**: เขียนโค้ดระบบจริงให้สอดคล้องเพื่อให้เทสต์ผ่าน
-3. **REFACTOR**: ปรับปรุงโครงสร้างโค้ดโดยยังคงรันเทสต์ผ่านอย่างต่อเนื่อง
-
 ### 3. Recovery
 
 Use the old recovery discipline when blocked:

package/template/.claude/skills/50-verify/SKILL.md

@@ -18,15 +18,21 @@ Review implementation quality, run multi-lane validation, produce a verification
 Use `50-verify.md` as the primary verification artifact.
 Use `50-verify-impact.md` as an optional companion artifact when the run changes behavior, touches core logic, crosses integration boundaries, or needs explicit rollback and client impact analysis.
 
-## Process & Quality Gates
+## Process & Quality Gates (Two-Stage Review Pattern)
 
-### 1. Senior QA Review & Multi-Lane Verification
+### Stage 1: Spec Fidelity & Acceptance Criteria Gate
+Before evaluating technical code metrics, verify that the implementation faithfully delivers what was specified:
+1. **Acceptance Criteria Validation**: Cross-check each Acceptance Criterion (AC-1, AC-2, ...) in `20-spec.md` or `current-feature.md` and verify concrete evidence of completion.
+2. **Done-When Observable Verification**: Check that all observable conditions ("Done when...") are satisfied in the running application or test suite.
+3. **Scope Discipline**: Ensure zero scope creep (no unrequested features added) and no unfulfilled functional requirements.
+4. **Boundary & Negative Scenarios**: Verify unhappy paths, empty inputs, and error states defined in the specification.
 
-Execute verification across all essential quality dimensions:
+### Stage 2: Code Quality, Security & Architecture Gate
+Execute multi-lane technical verification across all essential quality dimensions:
 
 1. **Lane 1: Typecheck & Static Code Quality**:
    - Run typecheck and static analysis (`tsc --noEmit`, `npm run lint`).
-2. **Lane 2: Automated Test Suites (TDD Gate)**:
+2. **Lane 2: Automated Test Suites (Strict TDD Gate)**:
    - Run automated unit and integration tests (`npm test`).
    - Confirm 100% test pass rate with zero disabled or skipped tests.
 3. **Lane 3: Scrutinize QA & Edge Cases Review**:
@@ -44,12 +50,13 @@ Execute verification across all essential quality dimensions:
 
 ### 2. Decision & Route
 
-- **Pass**: Route to `60-report {ID}`.
-- **Fail**: Route back to `40-execute {ID}` with exact failure evidence and remediation steps.
+- **Pass**: Both Stage 1 and Stage 2 pass with 0 blockers -> Route to `60-report {ID}`.
+- **Fail**: Either Stage 1 or Stage 2 fails -> Route back to `40-execute {ID}` with exact failure evidence and remediation steps.
 
 ## Output
 
 Report:
-- QA verdict across all verification lanes
+- **Stage 1 Verdict**: Spec Fidelity & Acceptance Criteria status
+- **Stage 2 Verdict**: Technical Multi-lane quality & security matrix
 - Evidence commands and outputs
 - Next command: `60-report {ID}` (if pass) or `40-execute {ID}` (if fail)

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

@@ -58,5 +58,5 @@ Construct a structured evaluation table:
 
 ## Next Workflow Recommendation
 
-- **Primary**: `00-explore {discovery_id}` (if resuming discovery) or `10-define` / `feature` (if ready to specify)
+- **Primary**: `discovery {discovery_id}` (if resuming discovery) or `10-define` / `feature` (if ready to specify)
 - **Inbox**: `idea` to record into `devflow/ideas.md`

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/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