@jakkrichm/create-nexus-devflow 2.18.2 → 2.19.0

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

@@ -1,126 +1,36 @@
 ---
 name: check
-description: "[devflow] Check the running app, CLI, or server against the active spec's done-when criteria and capture observable pass or fail evidence without editing code. Use for /check, proving behavior before completion beyond builds and tests."
-argument-hint: "[{run-id, number, or name}]"
+description: "[devflow] Check the running app, CLI, or server against the active spec's done-when criteria and capture observable pass or fail evidence without editing source. Use /check to verify real feature behavior, or /check guide [latest|scope] for a read-only manual walkthrough: how to test manually, where to click, expected and incorrect results, or a human review path."
+argument-hint: "[guide] [latest | <step> | <path> | <route>]"
 ---
 
-# check - Dual-Axis Independent Verification Engine
+# check - verify behavior or explain how to try it
 
-$ARGUMENTS
+**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`.
-
-Where this sits in the workflow:
-
-    /implement  ->  [check]  ->  /complete
-    (built a       (dual-axis       (only once both
-     step or        review with      axes pass with
-     the feature)   empirical proof) evidence)
-
-`/implement` builds and does a quick build-plus-screenshot check inline. `/check` is the rigorous, repeatable gate for when a feature or step needs **empirical proof** on the running app and **two-axis code review** before merging.
-
-It changes no source and commits nothing — it executes, inspects, and reports observed facts.
-
----
-
-## Input
-
-- **Given an ID or name** (e.g. `/check 12`, `/check 012`) -> targets `devflow/context/{xxx-slug}/` and records audit ledger to `{xxx-slug}/findings.md`.
-- **With no argument** (`/check`) -> verifies the active run matching current git branch or single active spec.
-
----
-
-## Hybrid Browser Verification Engine
-
-Nexus-DevFlow uses a **Dual-Layer Browser Verification Hierarchy**:
-
-```text
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                    🌐 Hybrid Browser Verification Engine                    │
-├──────────────────────────────────────┬──────────────────────────────────────┤
-│ 1. Code-Driven Test Automation (CI)  │ 2. Interactive AI Visual QA (MCP)    │
-│    • Framework: Playwright           │    • Server: MCP browseros-neo       │
-│    • Command: npm run test:browser   │    • URL: http://127.0.0.1:9010/mcp  │
-│    • Purpose: Assertions, Headless,  │    • Purpose: Live DOM Inspection,   │
-│      Regression Suite & Pre-commit   │      Real Screenshot Proofs, /try    │
-└──────────────────────────────────────┴──────────────────────────────────────┘
-```
-
-1. **Layer 1: Code-Driven Repeatable Tests (Playwright)**:
-   - If `AGENTS.md` declares `Browser tests: <command>`, run that exact command as repeatable automated evidence.
-2. **Layer 2: Interactive AI Visual QA (MCP browseros-neo)**:
-   - When the `browseros-neo` MCP server (`http://127.0.0.1:9010/mcp`) is active, use it to inspect the live running app, verify rendered CSS/layout, test click flows, and capture actual screenshot proofs.
-
----
-
-## Step 1 - Build the Dual-Axis Review Matrix
+## Select the mode before any tool call
 
-Read the target spec from `devflow/context/{xxx-slug}/spec.md` and `devflow/context/coding-standards.md`. Prepare the inspection criteria across two independent axes:
+- `/check guide` or `$check guide`: generate a read-only manual walkthrough.
+  Pass remaining arguments such as `latest`, a step, a path, route, or command
+  to `reference/guide.md`. Read and follow that reference only. Do not write
+  activity state, run checks or the app, edit files, update spec status, or
+  produce verification receipts.
+- A natural-language request for instructions on how the user can manually test
+  or review a change also selects guide mode. If the request mixes a guide with
+  agent verification, clarify which mode to run first before any activity.
+- `/check` or `$check`, optionally with a verification scope: verify observed
+  behavior against the spec. Follow verification startup below, then read and
+  follow `reference/verify.md` only.
 
-1. **Axis 1 (Standards & Architecture Criteria)**:
-   - Coding conventions in `coding-standards.md`
-   - Deep Modules discipline (Small interface, deep implementation, clean seams, no leaky abstractions)
-   - Baseline 12 Fowler Code Smells (Primitive obsession, Feature envy, Shotgun surgery, Speculative generality, etc.)
-   - Multi-lane technical gates (Typecheck, test suites, zero secrets, zero P0/P1 findings)
-2. **Axis 2 (Spec Fidelity & Behavioral Observables)**:
-   - Line-by-line Acceptance Criteria (ACs) and "Done When" observables from `devflow/context/{xxx-slug}/spec.md`
-   - Scope Creep detection (Unrequested behavior in the diff)
-   - Missing Requirements detection (Unimplemented edge cases)
+Load only the selected reference. Do not read both references preemptively.
+Guide generation never satisfies a verification gate. The existing
+`qualityGates.regular.tryGuide` and `qualityGates.continuous.tryGuide` keys now
+select `/check guide`; their policy values and automatic invocation rules are
+unchanged. The separate `check` gates continue to select verification mode.
 
----
-
-## Step 2 - Get the App Running & Exercise Live Proof
-
-Use the project's real commands (from `AGENTS.md`):
-
-- **Web app**: Start (or reuse) the local dev server. Drive a real browser to relevant routes. If `Browser tests: <command>` is declared, run it. When MCP `browseros-neo` is active, connect to inspect live visual state.
-- **CLI**: Execute commands with representative input fixtures, asserting exit codes and output snapshots.
-- **Server / API**: Hit endpoints with real payloads and assert on HTTP response status and bodies.
-- **Library**: Exercise public interfaces through integration tests or sample scripts.
-
-> [!IMPORTANT]
-> **Evidence or it didn't happen**: Every verdict must be backed by empirical evidence (screenshot, command output, status code, response time). Never assume a pass from reading source code alone.
-
----
-
-## Step 3 - Dual-Axis Independent Report & State Update
-
-Format the report into two distinct, un-merged review axes:
-
-```markdown
-# 🔍 Verification Report: [Feature Name]
+## Verification startup (verification mode only)
 
-## ⚖️ Axis 1: Standards, Architecture & Quality Gate
-
-- **Technical Lanes**:
-  - [pass] Type Safety: `tsc --noEmit` (0 errors)
-  - [pass] Automated Tests: `npm test` (All tests green)
-  - [pass] Browser Tests: `npm run test:browser` (Playwright passed)
-  - [pass] Visual Inspection: MCP browseros-neo verified UI layout & zero console errors
-  - [pass] Security & Hygiene: Zero secrets, sanitized inputs
-  - [pass] Findings Ledger: 0 blocking P0/P1 in `devflow/context/{xxx-slug}/findings.md`
-- **Deep Modules & Architecture**:
-  - [pass] Seam Integrity: Public interfaces remain small, implementation details hidden.
-  - [pass] The Deletion Test: Complexity is concentrated inside the module, not scattered across callers.
-- **Code Smells Assessment**:
-  - [clean] 12 Fowler Code Smells evaluated across git diff: No critical smells detected.
-
-## 🎯 Axis 2: Spec Fidelity & Behavioral Acceptance Gate
-
-Line-by-line verification against `devflow/context/{xxx-slug}/spec.md`:
-- [pass] **AC-1 (<title>)**: <Observed empirical evidence / screenshot path>
-- [pass] **AC-2 (<title>)**: <Observed empirical evidence / terminal output>
-- [fail] **AC-3 (<title>)**: <Exact observed failure with reproduction command>
-- [clean] **Scope Creep Check**: No unrequested features or unnecessary abstractions introduced.
-- [clean] **Completeness Check**: 100% of spec requirements addressed.
-
----
-
-## 🚦 Final Routing & Verdict
-
-- **ALL PASSED**: Both axes green. Update `stage.md` (Passed -> Ready for `/complete`).
-- **ANY FAILURE**: Hand back to `/implement` with exact failure evidence and reproduction steps.
-- **UNVERIFIABLE**: Clearly document the gap and residual risk. Never fabricate a pass.
-```
+**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`, with command `check`. This precedes reading the
+verification reference. Guide mode must skip this startup entirely.

package/template/.agents/skills/check/reference/guide.md

@@ -17,15 +17,16 @@ produce verification receipts. Reading files and git status is allowed. A guide
 never counts as acceptance evidence or proof that any check passed.
 
 The quality-gate config controls when another workflow generates this guide
-automatically. An explicit `/check guide` or `/try` request always runs.
+automatically. An explicit `/check guide`, `$check guide`, or `/try` request always runs.
 A generated guide never counts as evidence that the user performed the walkthrough.
 
 ## Input
 
 Optional scope:
 
-- no argument: use the active feature, fix, or rollback in `devflow/context/{xxx-slug}/spec.md`
-- `latest`: use the most recent archive under `devflow/history/features/`, `devflow/history/fixes/`, or `devflow/history/rollbacks/`
+- no argument: use the active task spec in `devflow/context/{xxx-slug}/spec.md`
+- `latest`: use the most recent archive under `devflow/history/features/`,
+  `devflow/history/fixes/`, or `devflow/history/rollbacks/`
 - a step name or number: focus the guide on that current task step
 - a path, route, or command: include it as the main thing to try
 
@@ -42,8 +43,14 @@ Read:
 - `devflow/context/project-overview.md`
 - `devflow/context/coding-standards.md`
 - `devflow/build-plan.md`
+- latest files under `devflow/history/features/`, `devflow/history/fixes/`, and `devflow/history/rollbacks/`, if the current feature is reset
 - Git branch and working tree status
 
+For `latest`, use the most recent archive even when an active spec exists.
+Otherwise prefer the active spec. If the active spec is missing, use
+the most recent archived feature, fix, or rollback by filename or modification time and
+say that is what you used.
+
 Do not dump the spec. Pull out the routes, commands, UI surfaces, CLI commands,
 API endpoints, data states, and done-whens that matter for a human trying it.
 For a rollback, lead with the path that proves the removed behavior is gone, then
@@ -72,7 +79,15 @@ Produce a concise guide with these 5 sections (respond in Thai per project conve
 4. **Expect** - visible result, output, response, state change, file, or lack of error.
 5. **Watch For** - common wrong outcomes, console or network errors, stale data, missing fields, bad empty states, layout issues, or safety warnings.
 
-Keep it concrete.
+Keep it concrete. Prefer:
+
+    Open http://127.0.0.1:7788/api/snapshot
+    Expect a JSON object with `generated_at`, `services`, `projects`, and
+    `conflicts`.
+
+Avoid:
+
+    Check that the snapshot works.
 
 ## Step 4 - include confidence and gaps
 
@@ -85,6 +100,23 @@ End with:
 If the feature is not user-visible, say so and provide the closest manual signal,
 such as an API response, CLI output, log line, or unit test command.
 
+## Rules
+
+- Read-only only. Do not edit, commit, merge, push, install, or delete.
+- Do not run the app or verification commands in guide mode. If the user asks
+  you to try it for them, leave guide mode and explicitly route to `/check`
+  verification, following its activity and authorization rules.
+- Do not pretend a path is known when the spec does not say it. Give the best
+  likely path and label uncertainty.
+- Keep the guide short enough to follow while the app is open.
+- Match the project's commands from `AGENTS.md`.
+
 ## Dual Compatibility with `/try`
 
 In Nexus-DevFlow, `/try` and `/check guide` serve the same user purpose and can be used interchangeably.
+
+## Formatting
+
+Format the output to match the project's conventions in
+`devflow/context/ai-interaction.md`: concise, scannable markdown, with numbered
+steps for the manual path and short bullets for warnings.

package/template/.agents/skills/check/reference/verify.md

@@ -0,0 +1,129 @@
+# Check verification
+
+**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.
+
+Verification activity was started by the dispatcher before loading this reference.
+
+Where this sits in the workflow:
+
+    /implement  ->  [check]  ->  /complete
+    (built a       (run the app,    (only once the
+     step or        prove each       done-whens are
+     the feature)   done-when)       proven)
+
+`/implement` builds and does a quick build-plus-screenshot check inline. `/check`
+is the deeper, repeatable gate for when a "done when" needs the *real running app*,
+not just a green build: a click that triggers a download, a route that returns a
+file, a flow across screens. Run it on a single step whose done-when is
+behavioral, or on the whole feature as the acceptance check before `/complete`.
+
+The point is evidence. A passing build proves the code compiles; `/check` proves
+the thing the spec promised actually happens. It changes no source and commits
+nothing - it runs the app and reports what it saw.
+
+## Input
+
+Optional: a specific thing to check (a step, a flow, a URL). With no argument,
+verify the whole current feature against every "done when" in
+`devflow/context/{xxx-slug}/spec.md`.
+
+## Step 1 - build the checklist
+
+Read `devflow/config.json` first. A missing file means the built-in defaults
+apply. If the file exists but is invalid, stop and point the user to `/doctor`.
+Configuration never grants permission to start a server or take any other action
+that the project instructions or user have not authorized.
+The quality-gate config controls automatic invocation only. An explicit `/check`
+or `$check` request always runs.
+
+Read `devflow/context/{xxx-slug}/spec.md`. Pull the observable "done when"
+criteria from the build steps (and any acceptance notes in the Testing section).
+Turn them into a concrete checklist of claims to prove - each one a specific,
+observable behavior, not "it works". If the user named one thing, scope to that.
+
+If there's no active feature spec, ask what to verify rather than guessing.
+
+## Step 2 - get the app running
+
+Use the project's real commands (see Commands in `AGENTS.md`). Match the project
+type:
+
+- **Web app** - start (or reuse) the dev/preview server, then drive a real browser
+  to the relevant routes. Prefer reusing an already-running server over starting a
+  duplicate. If `AGENTS.md` declares `Browser tests: <command>`, run that exact
+  command as repeatable evidence and use its harness for covered interactions.
+  Reuse runner-owned server lifecycle instead of starting a duplicate. A green
+  suite is one evidence source, not proof of claims it does not observe. If no
+  command is declared but Playwright is already installed, prefer it for browser
+  driving, screenshots, console errors, and failed request checks. Never install
+  it from `/check`; use another real-browser evidence path and report what you
+  used, or point to `/browser-tests` for later optional setup.
+- **CLI** - run the actual command(s) with representative inputs.
+- **Server/API** - start it and hit the endpoints.
+- **Library** - exercise the public API through an example or the test command.
+
+If a `test` command is declared in `AGENTS.md`, you may run it as *one* input, but
+`/check` is broader than unit tests: it checks real behavior, which is exactly the
+evidence UI and integration steps ride on instead of unit tests.
+
+## Step 3 - exercise each claim
+
+Drive the app to each checklist item and capture evidence as you go:
+
+- Navigate and interact for real (click, type, submit, download) - don't assert
+  from the code what the running app would do.
+- Capture **screenshots** for visual/UI claims, **output** for CLI/API claims.
+- Watch for **console errors and failed network requests**; a clean-looking screen
+  with errors in the console is not a pass.
+
+With `verification.uiEvidence: "required"`, every UI claim needs direct browser
+evidence, including a screenshot and the relevant console and network check. If
+that evidence path is unavailable, mark the claim unverifiable instead of
+passing it from build output. With `when-available`, use the strongest available
+evidence and report any gap plainly.
+
+### AC-to-Test Traceability Verification:
+Cross-reference each Acceptance Criterion (`- [ ] **AC-N**`) in `spec.md` against the test suite's executed assertions and observable evidence:
+- Match tagged test cases (e.g. `it('AC-1: ...')`) to their respective criteria.
+- Ensure 100% of defined acceptance criteria have empirical proof before issuing a `verified` status.
+
+
+## Step 4 - report
+
+Give a short, honest verdict, one line per checklist item:
+
+    [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)
+
+Then state the bottom line: are all the feature's done-whens proven, or not yet.
+
+- All proven -> update only the `**Status:**` line in
+  `devflow/context/{xxx-slug}/spec.md` to `verified`, then say it is ready for
+  `/complete`.
+- Anything failed -> update only that status line to `verification failed`, then
+  hand back to `/implement`; name what to fix. Do not fix it here.
+- Anything unverifiable -> update only that status line to `verification
+  incomplete`, then say why; never report it as a pass.
+
+The status-line update is generated workflow state, not a product-source edit.
+Do not change the spec, checkboxes, findings, or product files from `/check`.
+
+## Rules
+
+- **Observe product behavior, don't repair it.** `/check` changes only the
+  current spec's status line as described above. It never edits product source,
+  commits, or merges. Fixing is `/implement`'s job.
+- **Evidence or it didn't happen.** Every `pass` is backed by something observed -
+  a screenshot, output, a response. No assumed passes from reading the code.
+- **Honest over green.** "Couldn't verify" and "failed" are valid, useful results.
+  Faking a pass defeats the entire gate.
+- **Check the spec, not vibes.** Verify against the done-whens in
+  `spec.md`, so "works" means what the spec said it would do.
+
+## Formatting
+
+Format the output to match the project's conventions in
+`devflow/context/ai-interaction.md`: concise, scannable markdown, with lists for
+enumerations and tables for matrices rather than dense paragraphs.

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