@jakkrichm/create-nexus-devflow 2.18.1 → 2.19.0

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

@@ -1,10 +1,13 @@
 ---
 name: ci
-description: "[devflow] Set up or normalize one project Verify command and matching GitHub Actions checks while preserving existing CI. Use for /ci, GitHub Actions setup, pull-request checks, automatic checks, or aligning verification."
+description: "[devflow] Set up or normalize one project Verify command and matching GitHub Actions checks while preserving existing CI, with an optional local pre-push hook. Use for /ci, GitHub Actions setup, pull-request checks, automatic checks, pre-push hooks, or aligning verification."
+argument-hint: "[--hook | --no-hook]"
 ---
 
 # ci - set up automatic GitHub checks
 
+**Context reuse:** Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed.
+
 **First action:** Before project inspection, preflight, or any other tool call,
 publish `running` to `devflow/.state/run.json` using the dashboard activity
 contract in `AGENTS.md`.
@@ -15,7 +18,7 @@ Where this sits in the workflow:
     (project commands)     (setup)    (same recipe)      (pull requests)
 
 This skill gives local work and GitHub one shared automated command. It is an
-optional setup task, not a requirement for using the Blueprint.
+optional setup task, not a requirement for using DevFlow.
 
 Keep the beginner explanation simple:
 
@@ -23,9 +26,12 @@ Keep the beginner explanation simple:
 - **GitHub Actions is the worker.** It runs the same recipe automatically.
 - **A GitHub ruleset is the lock.** That optional remote setting can require the
   worker to report green before merge.
+- **A pre-push hook is the early warning.** That optional local setting runs the
+  recipe before a push leaves the machine. It is a convenience, not the lock:
+  `git push --no-verify` skips it.
 
-This skill configures the recipe and worker. It never changes the remote ruleset,
-pushes, publishes, deploys, or adds local git hooks.
+This skill configures the recipe and worker, and adds the hook only when the
+user opts in. It never changes the remote ruleset, pushes, publishes, or deploys.
 
 ## Input
 
@@ -47,7 +53,7 @@ Read enough to identify the real project setup:
 - `.github/workflows/` and any documented external CI
 - git's current branch, configured default branch, and remotes when available
 
-Do not assume npm, Node.js, `main`, or GitHub from the Blueprint template. Do not
+Do not assume npm, Node.js, `main`, or GitHub from the DevFlow template. Do not
 run installs or edit files during inspection.
 
 If an existing workflow already provides equivalent pull-request checks, explain
@@ -113,11 +119,26 @@ After the workflow exists, ask one question and default to no:
 
     Also add a local pre-push hook that runs Verify before every push? [y/N]
 
-Skip the question when the request already answered it (for example "/ci with hook" or "no hook"). When the answer is no, write nothing and move on. When it is yes:
-
-1. Use `npx nexus-devflow hook install pre-push` or configure `.githooks/pre-push` running the exact `Verify` command with `git config core.hooksPath .githooks`.
-2. Run the hook once to verify it passes cleanly. If it fails, revert the hook setup and report the failure. Never leave a hook the project cannot pass.
-3. Note that `git push --no-verify` bypasses the hook if an emergency push is ever needed.
+Skip the question when the request already answered it (for example "/ci with
+hook" or "no hook"). When the answer is no, write nothing and move on. When it
+is yes:
+
+1. Use `npx nexus-devflow hook install pre-push` or manually write `.githooks/pre-push`
+   (mode 755) that announces itself and runs the exact `Verify` command from `AGENTS.md`
+   with `exec`, so the command's exit code is the hook's exit code.
+2. Point git at the folder: `git config core.hooksPath .githooks`.
+3. For JavaScript and TypeScript projects, add a `prepare` script,
+   `git config core.hooksPath .githooks 2>/dev/null || true`, so a fresh
+   install wires the hook without a manual step. The `|| true` keeps installs
+   working where no git checkout exists, such as a deploy build. For other
+   stacks, document the `git config` line in the README instead.
+4. Run the hook once (`.githooks/pre-push`). If it fails, remove what this
+   step added and report the failing subcommand. Never leave a hook the
+   project cannot pass.
+
+The hook and the workflow run the same `Verify` command; if one changes, the
+other changes with it. Say in the report that `--no-verify` bypasses the hook,
+so the GitHub ruleset remains the lock.
 
 ## Step 4 - prove the setup locally
 
@@ -146,6 +167,7 @@ Finish with a concise setup report:
 - checks included and checks omitted
 - test gate status
 - workflow path and triggers
+- whether a pre-push hook was added, and that `--no-verify` bypasses it
 - local Verify result and whether CI is only prepared locally or confirmed by a
   successful GitHub run
 - files changed
@@ -157,7 +179,7 @@ part of this skill.
 
 ## Interaction with other skills
 
-- `/tests` adds the real test command to an existing Verify command, but never
+- `/setup-tests` or `/test` adds the real test command to an existing Verify command, but never
   creates CI by itself.
 - `/implement`, `/complete`, and `/autopilot` run Verify when it is documented,
   with their existing fallback behavior when it is absent.
@@ -168,8 +190,8 @@ part of this skill.
 
 - Preserve existing CI and custom checks.
 - Never invent tests or install a runner as part of CI setup.
-- Never add git hooks, coverage, browser tests, security scans, or matrices by
-  default.
+- Never add coverage, browser tests, security scans, or matrices by default.
+- Add a git hook only through the Step 3b opt-in, never silently.
 - Never push or change a remote ruleset without separate explicit approval.
 - Keep one exact Verify command shared by local work and GitHub.
 

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

@@ -106,6 +106,8 @@ Before logging or committing, run a short safety pass and report blockers only:
 - no P0 or P1 finding in `devflow/context/{xxx-slug}/findings.md` is `open` or `fixed`.
   `fixed` still blocks on purpose: the repair exists but no review has looked at
   it - run `/audit` to close it. The only waivers are `accepted` or `invalid`.
+- any `Status: Assumed` ADR in `devflow/decisions/` has been surfaced with its ratification plan noted.
+
 
 Do not claim "passed", "verified", or "working" without naming the command,
 route, screenshot, or output that proves it. Stop before Step 1 if required

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

@@ -36,7 +36,8 @@ When invoked without an argument (or when determining the next step), inspect:
 
 ### 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 the user requests a bugfix plan -> Recommend `/fix <bug>`.
+- If the user requests a completed fix -> preserve the implementation and verification scope; draft the required spec internally and continue to `/implement` using existing authorization.
 - 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`.
@@ -48,7 +49,7 @@ When invoked without an argument (or when determining the next step), inspect:
 | User Intent / Request Type | Recommended Skill | Normal Name / Alias | Lifecycle Path |
 | :--- | :--- | :--- | :--- |
 | **"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` |
+| **"Draft a bugfix / small-change plan"** | `fix` | `/fix` | **Unified**: `/fix` -> `/implement` -> `/check` -> `/complete` |
 | **"Capture quick idea / thought"** | `idea` | `/idea` | **Companion**: Enriches & saves to `devflow/ideas.md` |
 | **"Pre-delivery exploration / research"**| `discovery`| `/discovery` | **Pre-Flight**: `discovery` -> `/feature` |
 | **"Socratic alignment / ADR / glossary"**| `grill` | `/grill` / `/align` | **Pre-Flight**: `grill` -> `/feature` |

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

@@ -81,6 +81,15 @@ devflow/discoveries/{DISCOVERY_ID}-{slug}/discovery.md
    - **For interactive system architecture, dataflows, state transitions, and sequence traces**: Use `archify` (`.agents/skills/archify/SKILL.md`) to compile validated interactive HTML artifacts with dark/light themes, motion, and route probes.
    - **For editorial, business, quadrant, or broad diagram types**: Use `diagram-design` (`.agents/skills/diagram-design/SKILL.md`).
    - Save diagram artifacts to `devflow/discoveries/{DISCOVERY_ID}-{slug}/diagrams/{name}.html` and reference them directly in `discovery.md`.
+7. **🧩 Slicing & Decomposition Lens (4 Slicing Archetypes)**:
+   - When breaking down a large initiative into sub-features or milestones, evaluate against [`devflow/reference/slicing-archetypes.md`](file:///d:/Projects/devtools/nexus-devflow/devflow/reference/slicing-archetypes.md):
+     - **Skateboard**: Minimal functional loop (prove core logic end-to-end with minimal UI).
+     - **Facade**: Rich UI/DX with mock backend (validate user flow & interaction first).
+     - **Tracer Bullet**: Deep vertical slice across all layers (DB -> API -> UI) for 1 happy path.
+     - **Journey**: Slice along natural user workflow milestones.
+   - Recommend the primary Archetype for each proposed sub-feature in `discovery.md`.
+
+
 
 ### Decision & Approval Gate:
 Set one visible decision:

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

@@ -166,6 +166,8 @@ Gather these, then summarize. Do not dump file contents.
      last commit subject, and whether the branch is ahead of upstream.
    - If the directory is not a git repo, report that as a setup issue and keep
      going.
+9. **Token Economics & Session Cost Audit**
+   - When session transcript is available, report token efficiency, cache hit rate, and estimated model costs using `npm run analyze:tokens` or `scripts/analyze-token-usage.ts`.
 
 ## Output
 

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

@@ -1,6 +1,7 @@
 ---
 name: explore
 description: "[devflow] Explore an idea against the actual codebase without changing files. Investigate whether a change would help, compare alternatives and tradeoffs, and discuss uncertainty before deciding whether to plan anything. Use for /explore, considering an idea, or weighing options without writing a spec."
+argument-hint: "[<idea or question>]"
 ---
 
 # explore - investigate an idea before deciding to build (Read-Only)
@@ -79,4 +80,4 @@ let the discussion continue as long as useful.
   Suggest the appropriate command only when the user is ready to proceed.
 
 Do not force a handoff at the end of every response. Keep discussing the idea
-when that is what the user wants, and leave the project unchanged.
+until the user decides what to do next.

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

@@ -102,6 +102,8 @@ the data model, stack, and conventions. Decide how big the feature is:
   those sub-items back under the parent in `build-plan.md` as an indented
   checklist (`4a`, `4b`, `4c` ...). Spec only the **first** sub-feature now; the
   rest get picked up on later `/feature` runs.
+  *Use the **4 Slicing Archetypes** ([`devflow/reference/slicing-archetypes.md`](file:///d:/Projects/devtools/nexus-devflow/devflow/reference/slicing-archetypes.md)) to guide the split: 🛹 Skateboard (core logic first), 🎭 Facade (UI/DX mock first), 🎯 Tracer Bullet (end-to-end slice), or 🧭 Journey (workflow steps).*
+
 
 Two levels of breakdown - don't confuse them:
 
@@ -198,7 +200,7 @@ Before the user reads it, turn on the spec yourself and try to break it. The
 cheapest place to catch a scope problem or an oversized step is here, before any
 code exists. Run the draft against these questions:
 
-- **Coverage.** What does this feature need that no step delivers? Push on the
+- **Coverage & Input Mapping.** What does this feature need that no step delivers? Run a mechanical **Input Coverage Test**: does every value this build produces, displays, or computes have a named source (input, DB column, formula, or settled decision) in the spec? Push on the
   unhappy paths the happy-path spec skipped: empty / missing / malformed input,
   the error / loading / empty states, the first-run case, failure of anything
   external it calls.
@@ -218,6 +220,7 @@ code exists. Run the draft against these questions:
   anything pushed to "out of scope" that this feature actually can't ship without?
 - **Done-whens.** Is each one observable and checkable by `/check`, or is it a
   vague "it works"? Make it concrete.
+- **Proportionality.** Does any proposed abstraction, dependency, service, config surface, or security mechanism lack a current requirement, or duplicate existing code/platform features? If so, remove it.
 - **Testing.** Does the predicted coverage match the gate - in-scope logic gets a
   test when a `test` command is declared in `AGENTS.md`, UI/integration rides on
   screenshot + build?

package/template/.agents/skills/feature/reference/feature-spec-template.md

@@ -14,18 +14,18 @@
 ## 1. Specification & Scope
 
 ### 1.1 Problem Statement
-{คำอธิบายปัญหาและที่มาของความจำเป็นในการพัฒนาฟีเจอร์นี้}
+{Description of the problem, background, and rationale for developing this feature}
 
 ### 1.2 In-Scope
-1. {ขอบเขตการทำงานข้อที่ 1}
-2. {ขอบเขตการทำงานข้อที่ 2}
+1. {In-scope item 1}
+2. {In-scope item 2}
 
 ### 1.3 Out-of-Scope
-- {สิ่งที่อยู่นอกเหนือขอบเขตหรือไม่ทำในรอบนี้}
+- {Items deliberately excluded or deferred to future features}
 
-### 1.4 Acceptance Criteria (เกณฑ์การยอมรับ)
-- [ ] **AC-1**: {เกณฑ์การตรวจรับข้อที่ 1}
-- [ ] **AC-2**: {เกณฑ์การตรวจรับข้อที่ 2}
+### 1.4 Acceptance Criteria
+- [ ] **AC-1**: {Acceptance criterion 1}
+- [ ] **AC-2**: {Acceptance criterion 2}
 
 ---
 
@@ -40,18 +40,18 @@
 - **Review Strategy**: One feature-level review packet at completion
 
 ### 2.3 Test Decision: Required (TDD) | Optional
-- **Rationale**: {เหตุผลความจำเป็นในการเขียน Unit Tests / TDD}
+- **Rationale**: {Reason for requiring Unit Tests / TDD}
 
 ---
 
 ## 3. Implementation Checklist (Strict TDD)
 
-- [ ] **Task 1: {หัวข้องานที่ 1}**
-  - [ ] 1.1 `[TDD-Red]`: {เขียน Test เคสล้มเหลว}
-  - [ ] 1.2 `[TDD-Green]`: {เขียนโค้ดขั้นต่ำเพื่อให้ Test ผ่าน}
-  - [ ] 1.3 `[TDD-Refactor]`: {Refactor และตรวจให้ 100% Tests Green}
+- [ ] **Task 1: {Task 1 title}**
+  - [ ] 1.1 `[TDD-Red]`: {Write failing unit or behavioral test}
+  - [ ] 1.2 `[TDD-Green]`: {Write minimal implementation to pass test}
+  - [ ] 1.3 `[TDD-Refactor]`: {Refactor and ensure 100% tests green}
 
-- [ ] **Task 2: {หัวข้องานที่ 2}**
+- [ ] **Task 2: {Task 2 title}**
   - [ ] 2.1 `[TDD-Red]`: ...
   - [ ] 2.2 `[TDD-Green]`: ...
   - [ ] 2.3 `[TDD-Refactor]`: ...
@@ -65,11 +65,11 @@
 - **Automated Test Matrix**: TBD
 - **Static Contract Verification**: TBD
 - **Package Smoke Test**: TBD
-- **Findings Ledger**: ตรวจสอบ `findings.md` สะอาด 100%
+- **Findings Ledger**: Verify `findings.md` is 100% clean
 
 ### 🎯 Axis 2: Spec Fidelity & Behavioral Acceptance Gate
-- [ ] **AC-1**: {หลักฐานการผ่านเกณฑ์ข้อที่ 1}
-- [ ] **AC-2**: {หลักฐานการผ่านเกณฑ์ข้อที่ 2}
+- [ ] **AC-1**: {Empirical proof for AC-1}
+- [ ] **AC-2**: {Empirical proof for AC-2}
 
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 name: fix
-description: "[devflow] Write a task-isolated spec (devflow/context/{xxx-slug}/spec.md) for an ad-hoc bug fix or small unplanned change, then stop before implementation. Use for /fix, confirmed bugs, or small changes outside the build plan."
+description: "[devflow] Draft a task-isolated spec for a bug or small change. Use when invoking /fix or requesting a fix plan."
 argument-hint: "[{title or issue-description}]"
 ---
 
@@ -23,7 +23,7 @@ it creates a dedicated run folder at `devflow/context/{xxx-slug}/` (e.g. `059-fi
 ## Input
 
 A description of the bug or change, for example `/fix "password reset email never
-sends"`. If the user just reported the problem in chat, use that.
+sends"`. Use the reported problem as input when the user asks for a fix plan. A request to diagnose a problem belongs to `/debug`; a request to fix and verify it retains its full delivery scope.
 
 The input may also be a finding ID from `devflow/context/{xxx-slug}/findings.md` (or previous findings), alone
 or with a description, for example `/fix F-03`.
@@ -46,7 +46,7 @@ then write a short spec to `devflow/context/{xxx-slug}/spec.md`. Also initialize
   big to read. Each ends with an observable "done when".
 - **Verify** - how to confirm it's fixed (what to click or test).
 
-Then stop. Tell the user to review the fix spec, then run `/implement` to build it.
+For an explicit `/fix` or a planning-only request, present the spec as the completed deliverable and identify `/implement` as the next command. For an existing request to implement and verify the fix, preserve that authorization: use this spec as the internal handoff and continue through `/implement` without an extra approval pause. Ask only for unresolved material scope, design, or permission decisions.
 
 ## Rules
 

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

@@ -70,10 +70,14 @@ Allocate the next sequential ID (`ADR-001`, `ADR-002`, ...) and create `devflow/
 ```markdown
 # ADR-xxx: {Title}
 
-- **Status**: Accepted
+- **Status**: Accepted | Assumed (Fast-tracked Assumption)
 - **Date**: {YYYY-MM-DD}
 - **Context**: {Why was this decision needed? What problem does it solve?}
 - **Decision**: {What did we decide to do?}
+- **Assumption Metadata** *(Required when Status is Assumed)*:
+  - **Assumption**: {What was assumed to unblock progress}
+  - **Risk Level & Blast Radius**: {Risk if assumption fails}
+  - **Ratification Plan**: {Trigger, date, or test to ratify as Accepted or Rejected}
 - **Alternatives Considered**:
   - *Option 1*: {Pros / Cons}
   - *Option 2*: {Pros / Cons}
@@ -82,6 +86,7 @@ Allocate the next sequential ID (`ADR-001`, `ADR-002`, ...) and create `devflow/
   - *Trade-offs / Risks*: {Costs, constraints, or follow-ups}
 ```
 
+
 ---
 
 ## 4. Closing & Handoff

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

@@ -26,7 +26,7 @@ When invoked:
 3. Allocate the next sequential ID (e.g. `IDEA-001`, `IDEA-002`).
 
 ### 2. AI Feasibility & Value Analysis
-Evaluate the user's raw idea and generate an enriched entry in Thai (`th` per user communication rules):
+Evaluate the user's raw idea and generate an enriched entry:
 - **Raw Idea**: The user's input description
 - **AI Feasibility & Tech**: Feasibility rating (Easy / Medium / Complex) along with recommended libraries, APIs, or architectural approaches
 - **Value & Potential**: Business value, user benefits, and strategic impact
@@ -37,17 +37,17 @@ Insert the new idea block directly under `## 📌 Pending Ideas` in `devflow/ide
 
 ```markdown
 ### [IDEA-001] {Brief idea title}
-- **บันทึกเมื่อ**: {YYYY-MM-DD}
-- **ไอเดียตั้งต้น**: {User's raw idea text}
+- **Recorded Date**: {YYYY-MM-DD}
+- **Original Idea**: {User's raw idea text}
 - **AI Feasibility & Tech**: {Feasibility and tooling analysis}
 - **Value & Potential**: {Value and impact analysis}
-- **Quick Seed (กันลืม)**:
+- **Quick Seed**:
   1. {Key point 1}
   2. {Key point 2}
-- **สถานะ**: `Pending` (Ready for pickup via `/feature IDEA-001` or `/discovery IDEA-001`)
+- **Status**: `Pending` (Ready for pickup via `/feature IDEA-001` or `/discovery IDEA-001`)
 ```
 
-*(If placeholder `*(ยังไม่มีไอเดียค้างอยู่...)*` exists, remove it upon recording the first idea)*
+*(If placeholder `*(No pending ideas...)*` exists, remove it upon recording the first idea)*
 
 ### 4. Output Summary
 Report to the user:

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

@@ -1,10 +1,10 @@
 ---
 name: implement
-description: "[devflow] Implement or start coding the active task-isolated spec on its branch in small steps, running tests after each step and presenting the configured review handoff. Use for /implement or requests to build or resume an approved spec."
+description: "[devflow] Build and verify a task-isolated spec. Use for /implement or requests to implement an approved plan."
 argument-hint: "[{run-id, number, or name}] [--ticket <NN | path>]"
 ---
 
-# implement - build the target spec, one reviewed step at a time
+# implement - build and verify the target spec
 
 **Context reuse:** Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed.
 
@@ -20,17 +20,23 @@ Where this sits in the workflow:
 
 `/feature`, `/fix`, or `/rollback` wrote the spec to
 `devflow/context/{xxx-slug}/spec.md` and stopped.
-This skill turns that spec into code, following the build loop in
-`devflow/context/ai-interaction.md`, without vibe coding: small steps, a visible diff plus
-a plain-English explanation for each, testing, and iteration until it works, all
-behind your approval. It builds on a branch and offers an optional commit
-checkpoint after each step; the work-level commit, merging, and logging are
-`/complete`'s job.
+Build the selected spec through its acceptance criteria and required verification, then present the configured review handoff. Preserve authorization already given for this work. Read only relevant conventions and reuse loaded context.
+
+## Review cadence and checkpoints
+
+Read `workflow.stepReview` and `workflow.checkpointCommits` from `devflow/config.json` independently; defaults are `feature` and `disabled`.
+
+- `stepReview: "feature"`: continue through all authorized steps without asking Continue after each step. Record evidence as work proceeds and present one final review packet.
+- `stepReview: "every"`: after a working step, show its diff and evidence, then wait for approval before the next step. A walkthrough is available on request.
+- `checkpointCommits: "disabled"`: omit ordinary checkpoint offers.
+- `checkpointCommits: "enabled"`: offer an optional checkpoint at the configured review boundary (per-step for `every`, final packet for `feature`). Show the exact candidate and obtain commit authorization before committing. The setting itself is not authorization.
+
+Independent-review checkpoints follow their separate contract below. Review cadence never authorizes commit, merge, push, or deployment.
 
 ## Multi-Run Target & Ticket-Driven Target Resolution
 
-- **Given an ID or name** (e.g. `/implement 12`, `/implement 012`, `/implement kanban`) -> locates the matching run folder `devflow/context/{xxx-slug}/`, checks out `feature/{xxx-slug}`, and loads only that run's `spec.md`.
-- **With no argument** (`/implement`) -> checks current git branch matching `feature/{xxx-slug}`, or auto-picks if only 1 spec is active in `devflow/context/`, or prompts the user if multiple specs are queued.
+- **Given an ID or name** (e.g. `/implement 12`, `/implement 012`, `/implement kanban`) -> locates the matching run folder `devflow/context/{xxx-slug}/`, selects the branch matching the run type and configured prefix, and loads only that run's `spec.md`.
+- **With no argument** (`/implement`) -> checks the current feature, fix, or rollback branch against the configured prefixes, or auto-picks if only 1 spec is active in `devflow/context/`, or prompts the user if multiple specs are queued.
 - **Ticket Input (`--ticket <NN | path>`)**: Targets a specific tracer-bullet ticket directly (e.g. `/implement 12 --ticket 01`, `/implement --ticket 02`, `/implement --ticket issues/01-auth.md`, or `/implement 01` when run-id is not ambiguous).
 
 ### Ticket Discovery Hierarchy
@@ -80,23 +86,23 @@ receipt. After the final Verify pass, an active gate routes to
 `current` freshness may proceed toward `/complete`. This skill never approves
 its own work or rewrites receipt evidence.
 
-For a browser-facing step, run `npm run test:browser` when the script exists and
-record the result in the step evidence. Use `browseros-neo` for the interactive
-handoff when it is available and the done-when is visual or behavioral. When the
-script or MCP is absent, report that exact limitation; do not silently install a
-runner or claim browser evidence.
+For browser-facing changes, run focused browser tests during iteration when available. Run the required `npm run test:browser` gate once before handoff if the spec or project requires it. Use `browseros-neo` for visual or behavioral evidence when available and relevant. Record missing tooling accurately; install a runner only when setup is in the authorized scope.
 
 **Resuming?** If the spec already has some build steps checked off (`- [x]`), this
 feature was started earlier and interrupted (often a cleared context). The spec and
 its ticked steps are files, so pick up where it left off: read which steps are done,
 check the git branch and `git status`/log to see what is committed and what is still
 in the working tree, then continue from the **first unchecked step** instead of
-starting over.
+### Step 0 - Mechanical Input Coverage Pre-flight Gate
+
+Before touching code or executing build tasks, perform a positive **Input Coverage Test** against the active Living Spec:
+- Enumerate every value, state, or data field this implementation must produce, compute, or display (from the acceptance criteria and spec design).
+- For each required value, verify that the spec explicitly names where it comes from (e.g. database schema/column, API request parameter, calculated derivation from a named source, or explicit prior architectural decision).
+- **Anti-Hallucination Guard**: Any required value with no named source is an **Owed Decision**. Do NOT rationalize it as "just wiring" and do NOT silently invent an ad-hoc provider, schema field, or business rule. Stop and route to `/grill` or request user clarification before proceeding.
 
 ## Step 1 - branch
 
-Create and check out a branch named from the spec: `feature/{xxx-slug}` for a feature,
-`fix/{xxx-slug}` for a fix, or `rollback/{xxx-slug}` for a Type: Rollback spec. If the
+Create or select the branch for the spec using `git.featureBranchPrefix`, `git.fixBranchPrefix`, or `git.rollbackBranchPrefix` from config (defaults: `feature/`, `fix/`, `rollback/`). Preserve unrelated working-tree changes before switching. If the
 project isn't a git repo yet, say so and ask the user to run `git init` first;
 the loop needs branches. On resume, the branch already exists - check it out
 instead of creating a new one.
@@ -105,99 +111,23 @@ instead of creating a new one.
 
 When implementing a rollback task, follow the exact safety procedure in `reference/rollback-implementation.md`.
 
-## 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. **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.
-
-   **⚖️ The Iron Law**: `NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST` — Apply to behavior changes according to the spec's test decision. If code came first, revert only your own work for that step and restart from the test, preserving the user's existing work.
-
-   **Red-Phase Verification (confirm all three before GREEN):**
-   - The test actually fails, rather than encountering a syntax error
-   - The error message identifies missing behavior, rather than invalid configuration
-   - The failure reflects the behavior under test, rather than a bug in the test itself
-
-   **Green-Phase Discipline**: Write the minimum code needed to pass the test; add only the options/features it requires (YAGNI constraint).
-
-   > 📖 For anti-patterns and Bad vs Good examples, read [`tdd-anti-patterns.md`](tdd-anti-patterns.md).
-
-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 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.
-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
-   when the project declares one. A step that adds logic must ship a passing test
-   in the same diff when the test gate is on, and the suite must be green before
-   the step is approved (see the Testing gate in `coding-standards.md`). UI and
-   integration-only steps ride on screenshot plus build evidence. Run a focused
-   test separately when it gives faster feedback, then use `Verify` as the final
-   automated gate. For UI or integration done-whens, prefer Playwright when it is
-   already installed or declared in `AGENTS.md`; do not add it silently for an
-   unrelated feature. Create focused test files next to the source they cover,
-   per `coding-standards.md`. Never install a runner mid-step unless the current
-   spec is explicitly the unit-testing setup itself (for example `/fix "add unit
-   testing"`). If a step surfaces non-trivial logic the spec did not foresee, add
-   a focused test then, or note why not. When a step's done-when is behavioral (a
-   click, a download, or a flow across screens), run `/check` to prove it against
-   the running app rather than eyeballing it.
-5. **Iterate until it works.** If it fails or the user wants changes, revise the
-   step (re-prompt or hand-edit the code), show the updated diff, and re-test.
-   Repeat until it works and the user approves. Nothing is committed until the
-   user is happy with the step.
-6. **Mark it done, then prompt to move on.** Once the step is approved, check that
-   step off (`- [x]`) in `devflow/context/{xxx-slug}/spec.md` so progress survives a context
-   clear. If the step repaired a finding tracked in
-   `devflow/context/{xxx-slug}/findings.md`, set that finding's status to `fixed` now too
-   and note the repair in its **Resolution** line. Never set `closed`: a repair
-   is re-reviewed by `/audit` before it clears, because a fix can introduce a
-   worse defect than the one it removed. Then offer a short choice, noting that checkpoints are optional since
-   `/complete` makes the real feature-level commit. Use the current tool's short
-   user-input prompt when available; when you've just produced a long block to
-   read (a deep explanation, a big
-   walk-through), ask in plain text instead, so the prompt doesn't cover what the
-   user is still reading:
-   - **Continue** (default) - roll into the next step without committing.
-   - **Commit checkpoint** - commit just this step on the branch with a
-     conventional message (a cheap rollback point).
-   - **Walk me through it** - give a deeper, line-level explanation of the new or
-     changed code (why this approach, what each part does, any gotchas), then
-     re-ask this checkpoint prompt. A loop-back, not a terminal choice.
-   - **Stop here** - pause the loop so the user can review or come back later.
-
-   On **Continue** or after **Commit checkpoint**, go to the next step. On **Walk
-   me through it**, explain in depth and then re-ask this prompt in plain text (the
-   explanation is long, so a modal would cover it). On **Stop here**, stop and say
-   where things stand: the branch is intact; run `/implement` again to resume, or
-   `/complete` to wrap up what's built so far.
-
-### Ticket-Driven TDD Execution (when working from a Ticket)
-
-When executing a tracer-bullet ticket (via `--ticket` or auto-frontier):
-1. **Extract Scope**: Read *What to build* and *Acceptance criteria* checklist (`- [ ]`) from the active ticket file.
-2. **Strict TDD Cycle per Criterion**:
-   - **🔴 RED**: Write the unit/integration test for the criterion first at the agreed seam. Execute the test command and verify the expected failing assertion.
-   - **🟢 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.
-3. **Verify Gate**: Run the project's Verify command (`npm run check` or documented test suite) to ensure whole-system health before concluding the ticket.
-4. **Bidirectional State Sync**:
-   - Mark each completed criterion `- [x]` in the ticket file.
-   - Once all criteria in the ticket pass, update the ticket status to `**Status:** done` (or `Status: done`).
-   - Mirror the completed work, status, and diff evidence into `devflow/context/{xxx-slug}/spec.md` (under `## 📋 3. Execution Plan & TDD Checklist` and `## ⚡ 4. Implementation Log & Evidence`) so the Living Spec remains the authoritative single source of truth for `/check`, `/audit`, and `/complete`.
-
-Never batch the whole thing into one diff. If a step's diff is too big to read,
-split it. The documented `Verify` command, or the fallback build and tests, must
-pass before any commit.
+## Step 2 - implement and verify
+
+Work in small reviewable diffs, keeping progress in the selected spec.
+
+1. For logic or behavior changes with the test gate on, use Red-Green-Refactor: write a focused failing test, confirm the assertion fails for the missing behavior, implement the smallest change, then refactor with affected tests green. Preserve the user's existing work. Consult [TDD anti-patterns](tdd-anti-patterns.md) when test design needs it.
+   - **Proportional Engineering**: Add an abstraction, dependency, service, configuration surface, compatibility layer, or security mechanism only when the approved spec or an established repository requirement needs it now. Prefer existing code, standard library, and native platform features.
+2. Match the step's done-when and run focused checks. Documentation or formatting-only edits use structural checks and review; they do not require artificial unit tests. Capture relevant runtime or browser proof for behavioral criteria, following the selected Check policy.
+3. Fix failures caused by the change and rerun affected checks without requesting authorization again. Broaden verification when dependencies, failures, or risk justify it.
+4. Record the diff summary and evidence. Mark a step complete once its done-when passes and any configured per-step review has been approved. A repaired finding becomes `fixed` with resolution evidence; only a subsequent audit can close it. Apply the review cadence above before proceeding.
+
+Run a proportionality check before final verification: every new abstraction, dependency, service, configuration surface, compatibility layer, and security mechanism must trace to the approved spec or an established repository requirement. Remove speculative machinery this work added without weakening real trust-boundary validation, data-loss prevention, accessibility, or configured verification.
+
+At the final handoff, run the exact documented Verify command and all required gates. If there is no Verify command, use the project's declared build and test commands. Reuse a passing result for unchanged inputs within this pass; rerun affected gates after subsequent edits. Do not add tests or tools just to inflate the verification matrix.
+
+### Ticket execution
+
+When a ticket is selected, use its acceptance criteria as the steps above. Mark completed criteria in the ticket, mark it `done` after its criteria and required verification pass, and mirror status and evidence into the run's spec. A ticket handoff runs required gates once; criteria within the ticket use focused checks. A request to finish the whole run continues through the dependency frontier until the authorized scope is verified.
 
 After final Verify and required Check pass, set the active spec to `verified`
 with every completed box checked. Then resolve independent review before the
@@ -270,23 +200,19 @@ named area. If the feature spans too many distinct areas for one useful pass,
 name the sections first and let the user choose where to begin. Remain read-only
 unless the user separately requests changes.
 
-Never create an ordinary step, product, or work-level commit from this skill.
-The sole exception is exactly one immutable independent-review checkpoint after
-showing its exact candidate and receiving current explicit commit approval.
-Configuration never supplies that approval. Never merge, push, deploy, publish,
+Ordinary checkpoint commits are available only through the configured review boundary and explicit candidate approval above. The immutable independent-review checkpoint also requires explicit candidate approval. Work-level completion commits belong to `/complete`. Configuration never supplies commit approval. Never merge, push, deploy, publish,
 or start unrelated work from this skill.
 
 ## Rules
 
-- One small step per diff; the user reviews and approves each before any commit.
+- Keep diffs small and apply the configured review cadence.
 - Explain every change in plain English. Understanding the code is the point.
 - Iterate on the branch until each step works; never commit code the user hasn't
   approved.
 - Follow `devflow/context/coding-standards.md` (server vs client, scope user-owned queries
   by the authenticated user id, validate inputs, and so on).
-- Build only what the spec says. If the spec is wrong or thin, stop and fix the
-  spec first, do not improvise.
-- Per-step commits are optional checkpoints. The work-level commit, the merge,
+- Keep the spec aligned with the authorized scope. Correct routine omissions with evidence; ask only when a material scope or design decision is unresolved.
+- Configured checkpoint offers are optional. The work-level commit, the merge,
   and any push are `/complete`'s job.
 - For Type: Rollback, reverse only the approved product diff and preserve all
   protected Blueprint paths.

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

@@ -87,6 +87,32 @@ When generating or logging test runs during `/implement` or `/check`:
 
 ---
 
+## 7. 5-Tier Test File Classification Strategy
+
+Do not write identical test patterns for all file types. Classify files into 5 distinct tiers:
+
+| Tier | Category / File Paths | Recommended Test Strategy | What NOT to do |
+| :--- | :--- | :--- | :--- |
+| 🧠 **Tier 1** | **Pure Logic & Algorithms**<br>`src/utils/`, `src/services/`, `lib/` | Fast in-memory Unit Tests with 100% boundary & edge cases coverage. Use TDD (Red-Green-Refactor). | Do not over-mock pure mathematical or transformation functions. |
+| 🎨 **Tier 2** | **UI Components**<br>`src/components/`, `src/pages/` | Component rendering, event dispatching, visual verification via Playwright / BrowserOS Neo. | **Prohibited**: Do not write trivial unit tests that merely assert static HTML tags exist. |
+| 🔌 **Tier 3** | **API & Data Integration**<br>`src/api/`, route handlers, DB models | Contract tests, schema validation (Zod), HTTP status codes, error payload shapes. | Do not test external third-party network APIs without isolated fakes. |
+| ⚙️ **Tier 4** | **Config & Build Tooling**<br>`*.json`, `*.yaml`, `scripts/` | Static contract validation (`npm run check:static`), budget linters (`npm run check:budgets`), smoke tests. | Do not skip static validation on build tool modifications. |
+| 📝 **Tier 5** | **Documentation & Prose**<br>`*.md`, `devflow/docs/` | Structural checks, markdown contract scans, and link integrity verification. | Do not write artificial unit test suites for documentation files. |
+
+---
+
+## 8. Acceptance Criteria (`AC-N`) Traceability Protocol
+
+To guarantee 100% spec fidelity, every automated test suite must trace back to the active Living Spec:
+- **Test Title Tagging**: Prefix test titles or describe blocks with the target Acceptance Criterion:
+  ```typescript
+  it('AC-1: enforces 32KB byte budget on SKILL.md files', async () => { ... });
+  it('AC-2: returns exit code 1 when budget violation occurs', async () => { ... });
+  ```
+- **Traceability Verification**: During `/check`, cross-reference every `- [ ] AC-N` against the passing test assertion name to ensure zero untracked requirements.
+
+---
+
 ## Relationship To DevFlow 2.6.x
 
 - **Classification**: Companion command & Engineering standard