@jakkrichm/create-nexus-devflow 2.17.5 → 2.17.6

package/template/.claude/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/.claude/skills/check/reference/guide.md

@@ -0,0 +1,126 @@
+# Check guide - manual review guide
+
+**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.
+
+Where this sits in the workflow:
+
+    /implement or /complete  ->  [check guide]  ->  human review
+    (work exists)                (manual           (where to go,
+                                  path)             what to click)
+
+`/check` proves behavior from the agent side. `/check guide` gives the user a practical
+manual walkthrough: start this command, open this route, click these controls,
+expect this result, and watch for these failure signs.
+
+It is always read-only. Do not edit files, write activity state, update spec
+status, run checks or the app, install dependencies, commit, merge, push, or
+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 `$check guide` request always runs.
+A generated guide never counts as evidence that the user performed the walkthrough.
+
+## Input
+
+Optional scope:
+
+- 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
+
+If there is no active feature and no useful archive, ask what change the user
+wants to try instead of guessing.
+
+## Step 1 - find the work to explain
+
+Read:
+
+- `AGENTS.md`
+- `devflow/config.json`
+- `devflow/context/{xxx-slug}/spec.md`
+- `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
+include one unaffected regression path from the rollback spec.
+
+## Step 2 - identify how to run the app
+
+Use the Commands section in `AGENTS.md`. Match the project type:
+
+- **Web app** - dev server command, URL, and the route or screen to open.
+- **Server/API** - server command, base URL, endpoint, method, and expected
+  response shape.
+- **CLI** - exact command(s), arguments, and expected output.
+- **Library** - example command, test fixture, REPL snippet, or sample call.
+- **Hybrid app** - list the smallest set of commands needed, such as backend plus
+  web dev server.
+
+If the app may already be running, say how to reuse it. If a command is missing
+from `AGENTS.md`, report that as a gap rather than inventing certainty.
+
+## Step 3 - write the manual guide
+
+Produce a short guide with these sections:
+
+1. **Start** - commands to run and where to run them.
+2. **Open** - URLs, screens, tabs, API endpoints, or CLI commands.
+3. **Do** - clicks, inputs, selections, or command arguments.
+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. 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
+
+End with:
+
+- **Best signal** - the one thing the user should try first.
+- **Optional deeper checks** - only if useful.
+- **Gaps** - anything the guide cannot know from the docs, such as missing route
+  names, seed data, credentials, or external services.
+
+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`.
+
+## 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/.claude/skills/check/reference/verify.md

@@ -0,0 +1,123 @@
+# 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.
+
+## 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/.claude/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
@@ -107,6 +113,33 @@ before writing the push trigger instead of guessing. Preserve all other workflow
 files. When another workflow overlaps, report the overlap and ask whether to
 reuse, align, or leave it alone.
 
+## Step 3b - offer a local pre-push hook (opt-in)
+
+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. Write `.githooks/pre-push` (mode 755) that announces itself and then 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
 
 Run the exact documented `Verify` command locally. The individual build, test,
@@ -134,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
@@ -145,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.
@@ -156,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/.claude/skills/doctor/SKILL.md

@@ -100,6 +100,10 @@ Gather these, then summarize. Do not dump file contents.
      report it as an obsolete installer artifact. Its absence is healthy. An
      unchanged managed copy can be removed by the updater; a modified copy needs
      user review.
+   - Check whether `AGENTS.md` contains substantive proportional-engineering
+     guidance (`## Proportional engineering` or equivalent rules). Warn if
+     missing, explaining that updates preserve this file and provide manual repair
+     guidance.
    - Check whether `AGENTS.md` has a `## Commands` section with dev and build
      commands.
    - Report missing lint or test commands as informational unless the project has

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

@@ -0,0 +1,78 @@
+---
+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
+
+**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.
+
+Explore is a read-only conversation grounded in the actual project. It can help
+with questions such as whether caching would help a dashboard, whether teams
+belong in the product, or which upload approach fits existing code.
+
+No plans or active feature are required. Do not require `/overview`, invent a
+plan, or treat missing DevFlow context as a blocker to discussing the idea.
+This command never writes activity state, including `devflow/.state/run.json`.
+
+## Start from the question
+
+Use the supplied topic or relevant conversation context. With neither, ask what
+the user wants to investigate. For a vague idea, state a tentative interpretation
+and ask a focused question only when its answer changes the investigation.
+
+Reuse context already loaded in the session. Read relevant project instructions,
+code, tests as text, manifests, and existing plans when they help answer the
+question. Follow the actual implementation far enough to support your claims;
+point to concrete files or symbols. Avoid scanning unrelated parts of the repo.
+Read-only Git inspection can establish what exists or is already in progress.
+
+Authoritative documentation lookup is appropriate when technical uncertainty
+needs it. Distinguish documented facts from what this project actually uses.
+Missing code or evidence is an uncertainty to explain, not permission to execute
+an experiment or to invent current behavior.
+
+## Discuss the options
+
+Keep the conversation proportional to the question. Compare plausible options
+against the user's needs and existing project constraints. Include doing nothing
+when the current behavior may already be sufficient. Do not invent scale,
+security requirements, or new abstractions to justify a change.
+
+Explain the strongest case against your recommendation and how confident you
+are. Separate observed facts, assumptions, and unanswered questions. Say what
+evidence could change the recommendation without gathering it through execution.
+An unresolved question or a recommendation to leave the project alone is a valid
+outcome.
+
+Use a small diagram in the response when it makes a relationship or tradeoff
+clearer. Do not create diagram files. There is no mandatory output template,
+report, question count, or next-step checklist. Follow the user's responses and
+let the discussion continue as long as useful.
+
+## Keep the boundaries clear
+
+- Never create, edit, or delete files, including specs, plans, notes, generated
+  output, and activity state. Do not save the conversation into the project.
+- Never install dependencies, execute product code, run tests or builds, start
+  servers, perform browser interactions, or call state-changing tools. Read
+  source and existing evidence instead of testing a hypothesis by execution.
+- Never create or switch branches, commit, merge, push, publish, or deploy.
+- Never turn a request to discuss an idea into approval to plan or implement it.
+  If the user asks for changes, explain the appropriate handoff and keep this
+  Explore invocation read-only. Do not invoke another command automatically.
+
+## Neighbors and handoff
+
+- `/brief` explains an existing build-plan item, its scope, dependencies, and
+  size. Explore can discuss an unplanned idea or question a planned approach.
+- `/discovery` develops broader product direction and reviewed planning drafts.
+  Explore does not draft either planning file.
+- `/debug` reproduces and isolates an actual failure. Explore discusses options
+  without executing code to diagnose or verify them.
+- `/feature` writes a buildable spec; `/fix` specifies a confirmed small change.
+  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.

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

@@ -218,6 +218,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?