@jakkrichm/create-nexus-devflow 2.0.24 → 2.0.27

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

@@ -1,175 +1,256 @@
 ---
 name: autopilot
-description: "[Devflow] Optional explicit mode for one bounded spec/plan/implement/verify/report pass with checkpoint commits and review packet."
+description: "[devflow][B] Optional explicit Blueprint mode for one bounded spec/build/check/audit pass. It can pick or resume the current feature, write the spec when needed, create or reuse the branch, implement small steps, run build/tests/checks, create checkpoint commits after passing steps, audit changed code, repair confirmed high-severity findings, and stop with a review packet. It never completes, merges, pushes, deploys, publishes, sends, or performs destructive actions without explicit approval. Use only when the user explicitly runs /autopilot, invokes $autopilot, or directly asks for Autopilot."
 ---
 
-# autopilot - Autonomous Bounded DevFlow Loop
+# autopilot - optional Blueprint loop
 
 Where this sits in the workflow:
 
-```text
-devflow  ->  [autopilot]  ->  review packet  ->  70-release
-(where        (spec, plan,     (human review,     (package, PR,
- are we?)      build, verify,   walkthrough)       merge with approval)
-               report)
-```
+    /status  ->  [autopilot]  ->  review packet  ->  /complete
+    (where       (spec, build,      (human review,    (log, commit,
+     are we?)     check, audit)      fixes if needed)  merge with approval)
 
-Autopilot is an explicit opt-in execution skill for Nexus-DevFlow 2.0. It runs a single bounded loop across the delivery lifecycle (**`20-spec` -> `30-plan` -> `40-execute` -> `50-verify` -> `60-report`**) without requiring human confirmation between every sub-step.
+Autopilot is an explicit opt-in path. It uses the same Blueprint files and the
+same quality gates, but it does not stop after every normal review point. A
+single user request is permission to run one bounded loop until the feature is
+ready for review, blocked, or unsafe to continue.
 
-It does **not** replace the normal step-by-step workflow. Mainline commands (`20-spec`, `30-plan`, `40-execute`, `50-verify`, `60-report`, `70-release`) remain the conservative default.
+It does **not** replace the normal workflow. `/feature`, `/implement`, `/check`,
+and `/complete` remain the conservative default.
 
-Do not suggest Autopilot as the default next action. Use it only when the user explicitly asks for it.
+Do not suggest Autopilot as the default next action. Use it only when the user
+explicitly asks for it.
 
-The explicit Autopilot request is permission to create checkpoint commits on the feature or fix branch after passing implementation steps. It is **not** permission to merge into `main`, push to remote, deploy, publish, delete data, or run destructive actions.
+The explicit Autopilot request is permission to create checkpoint commits on the
+feature or fix branch after passing implementation steps. It is not permission to
+merge, push, deploy, publish, send, delete data, or run destructive actions.
 
 ## Input
 
 Common forms:
 
-- **No argument**: resume the active run in `devflow/context/current-stage.md`, or target the next planned run/feature in `devflow/context/project-overview.md`.
-- **Running ID or feature name**: target that run, e.g. `autopilot RUN-004` or `autopilot "add user authentication"`.
-- **`fix "<issue>"`**: write and execute an ad-hoc fix run.
-- **`resume`**: continue the current active run on its existing branch.
+- No argument: resume the current feature if one exists, otherwise target the next
+  unchecked build-plan item.
+- A number or name: target that build-plan feature, for example `/autopilot 3` or
+  `$autopilot "directory listing"`.
+- `fix "<issue>"`: write and build an ad-hoc fix spec.
+- `resume`: continue the current feature on its existing branch.
 
-If the requested target conflicts with a run already in progress, stop and ask which one should win. Do not overwrite active stage artifacts silently.
+If the requested target conflicts with a feature already in progress, stop and
+ask which one should win. Do not overwrite `devflow/context/current-feature.md`
+silently.
 
-> [!IMPORTANT]
-> Rollback is intentionally excluded from Autopilot. If the request is a rollback or the stage is marked Rollback, stop and direct the user to `rollback` and reviewed `40-execute`. Reversing completed work requires explicit dependency and human review gates.
+Rollback is intentionally excluded from Autopilot. If the request is a rollback
+or `current-feature.md` is marked `Type: Rollback`, stop and direct the user to
+the reviewed `/implement` path. Reversing completed work requires the explicit
+dependency and conflict gates in `/rollback` and `/implement`.
 
----
-
-## Step 1 - Preflight & Safety Check
+## Step 1 - preflight like /status
 
-Read the project state:
+Read the same state `/status` reads:
 
-- `AGENTS.md` & `CLAUDE.md`
+- `AGENTS.md`
+- `devflow/project-plan.md`
+- `devflow/build-plan.md`
 - `devflow/context/project-overview.md`
-- `devflow/context/current-stage.md`
+- `devflow/context/current-feature.md`
+- `devflow/context/findings.md`
 - `devflow/context/coding-standards.md`
 - `devflow/context/ai-interaction.md`
-- `devflow/context/findings.md`
 - git branch, status, and recent log
 
-Stop before changing files when:
-
-1. The repo is not a git repository.
-2. The working tree is dirty with uncommitted changes unrelated to this run.
-3. `current-stage.md` has an active run and the user requested a different target without resolving conflict.
-4. The task requires architectural, financial, auth, billing, or destructive decisions not documented in the context.
-
----
-
-## Step 2 - Choose or Write Specification (`20-spec`)
-
-1. If `devflow/runs/{running-id}-{slug}20-spec.md` already exists, resume it.
-2. If no spec exists:
-   - Ensure `10-define.md` exists with locked scope and allocated Running ID.
-   - Write `20-spec.md` following the DevFlow specification schema.
-   - Critique and red-team the spec (edge cases, unhappy paths, testable criteria).
-   - Apply fixes to the spec.
-
----
-
-## Step 3 - Branch Setup & Implementation Plan (`30-plan`)
-
-1. **Branch Management**:
-   - Feature: `feature/{slug}-{running-id}`
-   - Fix: `fix/{slug}-{running-id}`
-   - Switch to or create the working branch. Never run Autopilot directly on `main` or `master`.
-2. **Planning**:
-   - Write `devflow/runs/{running-id}-{slug}30-plan.md`.
-   - Seed `checklists/implementation-checklist.md` and `checklists/verification-checklist.md`.
-
----
-
-## Step 4 - Implement in Small Increments (`40-execute`)
-
-Work through the implementation checklist in order. Each step must remain reviewable.
-
-For every subtask:
-
-1. Implement only that scoped unit.
-2. Run relevant verification (unit tests, typecheck, lint, build).
-3. If UI is involved, inspect behavior, verify console errors and network calls.
-4. Self-review diff against `coding-standards.md`.
-5. Fix issues and rerun failed checks.
-6. Mark the task checked `[x]` in `checklists/implementation-checklist.md`.
-7. **Create a Checkpoint Commit** on the feature/fix branch for the passing step:
-   ```bash
-   git add <modified-files> devflow/runs/{running-id}-{slug}/checklists/implementation-checklist.md
-   git commit -m "feat({running-id}): checkpoint <concise step description>"
-   ```
-8. Write `devflow/runs/{running-id}-{slug}40-execute.md`.
-
----
-
-## Step 5 - Senior QA Verification (`50-verify`)
+Then decide whether it is safe to run.
 
-1. Execute full project verification commands:
-   - Framework integrity (`npm run check` or equivalent)
-   - Static contracts (`npm run check:static` when applicable)
-   - Project test suite (Unit tests, integration tests)
-   - Build / Package smoke tests
-2. Update `checklists/verification-checklist.md` with concrete evidence.
-3. Write `devflow/runs/{running-id}-{slug}50-verify.md` with QA verdict (`PASS` / `FAIL`).
-
----
-
-## Step 6 - Targeted Quality Audit & Repair
-
-Review diffs and inspect `devflow/context/findings.md`:
-
-1. **Repair confirmed P0 and P1 findings** within the current run scope.
-2. Update finding status in `devflow/context/findings.md`.
-3. Rerun verification tests after repairs.
-4. Create a checkpoint commit for the fix.
-5. If a P0/P1 finding cannot be repaired within scope or fails twice consecutively, stop immediately and report.
-
----
-
-## Step 7 - Delivery Digest & Review Packet (`60-report`)
-
-1. Write `devflow/runs/{running-id}-{slug}60-report.md`.
-2. Render standalone HTML dashboard `devflow/runs/{running-id}-{slug}60-report.html` (via `md2html` or report generator).
-3. Update `devflow/context/current-stage.md` to indicate ready for `70-release`.
-4. Stop with a concise **Review Packet Dashboard** for human approval.
-
----
-
-## 🛑 Strict Hard Stops (Never Exceed)
-
-Stop immediately and report to the user instead of continuing when Autopilot would need to:
-
-- Commit directly to `main` or `master`, merge branches, delete branches, or force push.
-- Run `git push` to remote repositories.
-- Deploy to staging/production or publish packages to npm/registries.
-- Delete data, drop databases, or run irreversible destructive migrations.
-- Make product, business, or architecture decisions not specified in the context.
-- Continue after two failed attempts to fix the same issue (Two-attempt hard stop).
-
----
-
-## Output Review Packet Format
-
-When Autopilot finishes successfully, output a scannable review packet:
-
-```markdown
-### 🛸 Autopilot Execution Summary: [{running-id}]
-
-- **Branch**: `{branch-name}`
-- **Target Run**: `{running-id} - {title}`
-- **Artifacts Generated**:
-  - Spec: `devflow/runs/{id}20-spec.md`
-  - Plan: `devflow/runs/{id}30-plan.md`
-  - Implement Evidence: `devflow/runs/{id}40-execute.md`
-  - QA Verify Report: `devflow/runs/{id}50-verify.md`
-  - Digest Report: `devflow/runs/{id}60-report.md`
-  - HTML Dashboard: `devflow/runs/{id}60-report.html`
-- **Validation & Tests**: `All Passed (Green)`
-- **Checkpoint Commits**: `{count} commits created on {branch-name}`
-- **Manual QA Walkthrough**: Run `try {running-id}` for human review guide
+Stop before changing files when:
 
----
-👉 **Next Recommended Action**:
-Inspect diffs and `try` walkthrough, then run `70-release {running-id}` to package, merge, or create PR.
-```
+- The repo is not a git repo.
+- The working tree is dirty and there is no current feature tying those changes
+  to this run.
+- `current-feature.md` has real work and the user requested a different target.
+- `project-overview.md` is missing or stale and the planning docs are not clear
+  enough to regenerate it.
+- The next feature is visual or replication-heavy and no design reference exists.
+- The task needs product, data, auth, billing, or destructive decisions the docs
+  do not answer.
+
+If the only issue is that `project-overview.md` is stale and the plans are clear,
+regenerate it using the `/overview` behavior and continue. Include that in the
+final packet.
+
+## Step 2 - choose or write the spec
+
+If `devflow/context/current-feature.md` already contains an active spec,
+resume it. Read checked steps and continue from the first unchecked step.
+
+If there is no active spec:
+
+1. Use the `/feature` behavior for a planned feature, or `/fix` behavior for a
+   requested fix.
+2. Write `devflow/context/current-feature.md`.
+3. Red-team the spec before building:
+   - missing unhappy paths
+   - oversized steps
+   - undefined contracts
+   - missing design reference
+   - scope creep
+   - vague done-whens
+   - missing testing plan when `AGENTS.md` declares a test command
+4. Apply the spec fixes.
+
+Autopilot may continue past this spec gate because the user explicitly invoked
+Autopilot. Still report what the critique changed in the final packet.
+
+## Step 3 - create or reuse the branch
+
+Use the same branch rules as `/implement`:
+
+- Feature: `feature/<name>`
+- Fix: `fix/<name>`
+
+If the branch already exists, switch to it only if it matches the active spec.
+If switching branches would strand unrelated dirty work, stop and report the
+problem.
+
+## Step 4 - implement in small steps
+
+Work through the spec's build steps in order. Each step must remain reviewable.
+Unlike `/implement`, do not pause for user approval after each passing step. The
+review happens at the final packet unless a hard stop is hit.
+
+For every step:
+
+1. Implement only that step.
+2. Run the relevant verification:
+   - the exact `Verify` command from `AGENTS.md`, when declared
+   - otherwise the build, relevant test, lint, and typecheck commands already
+     documented by the project
+   - browser, CLI, API, or app-level evidence for behavioral done-whens
+3. If UI is involved, inspect the running app when possible. Prefer Playwright if
+   it is already installed or declared. Capture screenshots when they add useful
+   evidence. Check for console errors and failed requests.
+4. Self-review the diff for the step:
+   - does it match the spec?
+   - did it add scope?
+   - is the error path handled?
+   - did it follow `coding-standards.md`?
+   - are tests present for new in-scope logic when the test gate is on?
+5. Fix obvious issues and rerun the failed checks.
+6. Mark the step checked in `current-feature.md` only after the step passes.
+7. Create a checkpoint commit on the feature or fix branch for the passing step.
+   Include the code, tests, and the updated `current-feature.md` checkbox. Use a
+   conventional message such as `feat: checkpoint mock snapshot route` or
+   `fix: checkpoint stale service filter`. Keep the message about the step, not
+   about Autopilot.
+
+Do not batch the whole feature into one large diff. If a step gets too large,
+split the step in `current-feature.md` and continue with the first smaller step.
+
+## Step 5 - acceptance check
+
+After all implementation steps are checked, run the `/check` behavior for the
+feature when any done-when is behavioral, visual, or integration-facing.
+
+For pure library or CLI work, build plus tests and representative command output
+may be enough. Be explicit about the evidence used.
+
+## Step 6 - targeted quality audit and repair
+
+After the acceptance check, apply the `/audit current` behavior to the active
+feature, its diff, and the nearby code affected by the change. This is a targeted
+feature audit, not a repository-wide cleanup pass. Findings are recorded in
+`devflow/context/findings.md` with durable IDs and statuses, as `/audit`
+defines; the ledger reports status and never scopes what the audit examines.
+
+For every finding:
+
+1. Validate it against the actual code, spec, tests, `coding-standards.md`, and
+   local project patterns. An audit finding is evidence to investigate, not an
+   automatic instruction to edit.
+2. Repair confirmed P0 and P1 findings when the fix stays inside the approved
+   feature scope and does not require a product or architecture decision. Set
+   the repaired finding to `fixed` in the ledger, never `closed`.
+3. Report P2 and P3 findings in the final packet. Fix them only when the change
+   is small, directly caused by the current feature, and clearly required by the
+   project standards.
+4. If a confirmed P0 or P1 finding cannot be repaired safely within scope, stop
+   and report it. Do not present the feature as ready for `/complete`.
+
+After any audit repair:
+
+1. Rerun the documented `Verify` command when present; otherwise rerun the
+   affected build, lint, typecheck, and test commands.
+2. Rerun the acceptance evidence affected by the repair.
+3. Recheck the repaired area using the same targeted audit criteria. When that
+   recheck confirms the original defect is gone and the repair introduced no
+   new one, move the `fixed` finding to `closed` under the `/audit` close
+   conditions and name it in the packet. An unrelated new finding gets its own
+   ledger entry and does not keep the repaired one open.
+4. Create a checkpoint commit only after the repair and its checks pass.
+
+Use the existing two-attempt hard stop for repeated repair failures. Do not widen
+the feature into a general refactor, silently suppress a finding, or turn this
+step into a full-project hardening pass. A broader cleanup remains a separate
+`/audit` followed by planned `/fix` work.
+
+## Step 7 - final review packet
+
+Stop with a concise review packet. Keep it useful enough for `/complete` but not
+a full audit report:
+
+- branch name
+- target feature or fix
+- whether the spec was created or resumed
+- what the spec critique changed
+- changed files and why each changed
+- build/test/check commands run, with pass or fail
+- screenshots or output paths, when relevant
+- how to try it manually, or a pointer to `/try` for the full walkthrough
+- checkpoint commits created
+- self-review findings
+- targeted audit scope and findings
+- audit repairs made and checks rerun
+- P0/P1 findings still `open` or `fixed` in `devflow/context/findings.md`,
+  which block `/complete`
+- unresolved risks or skipped checks
+- exact next action
+
+If everything is green, the next action is usually: review the diff, then run
+`/try` if you want a manual walkthrough, then `/complete`.
+
+If something failed, name the failing check and the next fix target.
+
+## Hard Stops
+
+Stop immediately and report instead of continuing when Autopilot would need to:
+
+- commit on `main`, merge, delete a branch, push, deploy, publish, or send
+  anything
+- delete data, reset a database, run irreversible migrations, kill processes, or
+  change system settings
+- install dependencies or use network access without the current tool's approval
+  flow
+- make a product decision not covered by the docs
+- continue after two failed fix attempts on the same issue
+- hide, skip, or hand-wave a failing check
+
+## Rules
+
+- One Autopilot run handles one feature or one fix.
+- Autopilot creates checkpoint commits on the feature or fix branch after passing
+  steps.
+- Autopilot audits the active feature and affected code, not the entire project.
+- A P0 or P1 finding left `open` or `fixed` in `devflow/context/findings.md`
+  blocks readiness for `/complete`. The ledger is what makes this enforceable.
+- Autopilot stops before `/complete`. It never merges.
+- The Blueprint files remain the state machine. Keep
+  `current-feature.md` accurate as steps complete.
+- Follow `coding-standards.md`, `ai-interaction.md`, and `AGENTS.md`.
+- Prefer fewer, higher-quality changes over broad coverage.
+- Report uncertainty plainly. A blocked run is useful if it tells the truth.
+
+## 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/brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorm
-description: "[Devflow] Companion skill for structured divergent and convergent ideation, generating 2-3 viable options with trade-off analysis before committing to delivery."
+description: "[devflow][B] Companion skill for structured divergent and convergent ideation, generating 2-3 viable options with trade-off analysis before committing to delivery."
 argument-hint: "{topic, feature, or discovery-id}"
 ---
 
@@ -58,5 +58,5 @@ Construct a structured evaluation table:
 
 ## Next Workflow Recommendation
 
-- **Primary**: `00-discover {discovery_id}` (if resuming discovery) or `10-define` / `feature` (if ready to specify)
-- **Inbox**: `idea` to record into `devflow/ideas.md`
+- **Primary**: `00-explore {discovery_id}` (if resuming discovery) or `10-define` / `feature` (if ready to specify)
+- **Inbox**: `idea` to record into `devflow/ideas.md`

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

@@ -1,77 +1,100 @@
 ---
 name: brief
-description: "[Devflow] Read-only scope, dependency, and risk pre-briefing before speccing a run."
+description: "[devflow][B] Read-only briefing on an upcoming build-plan feature before you spec it. With no argument, briefs the next unchecked item; given a number or name, briefs that one. Reads build-plan.md and project-overview.md and explains what the feature is, what it depends on, what it will touch, how big it is, and whether it will split - without writing anything. Use when the user runs /brief, asks what the next feature involves, wants to understand or preview a feature before /feature, or is deciding what to build or reorder next."
 ---
 
-# brief - Scope, Dependency & Risk Pre-Check
+# brief - understand a feature before you spec it
 
 Where this sits in the workflow:
 
-```text
-10-define or project-overview.md  ->  [brief]  ->  20-spec  ->  30-plan  ->  40-execute
-(proposed scope & context)            (read-only   (write        (break down)  (build it)
-                                      explainer)    contract)
-```
+    build-plan + overview  ->  [brief]  ->  /feature  ->  /implement
+    (what exists)              (read-only    (spec it)     (build it)
+                                explainer)
 
-This skill answers one essential question: ***"What does this upcoming feature or run actually involve before I commit to writing a full specification?"***
+This skill answers one question: *what does this feature actually involve, before
+I commit to spec'ing it?* It reads the two files that describe the work and prints
+a short briefing so you can decide whether to spec it now, reorder it, split it,
+or clear a blocker first. It is the read-only precursor to `/feature`.
 
-It inspects the relevant context files and provides a concise briefing so the team can decide whether to spec it now, split it into smaller runs, reorder priorities, or clear an architectural blocker first.
+It never writes anything: no spec, no edits to `build-plan.md`, no branch, no
+commit. `/feature` is the mutating step that turns a briefing into a spec; this
+one just explains.
 
-It is **strictly read-only 100%**. It never writes specs, creates directories, branches, or commits code.
+How it differs from its neighbors:
 
-## Input
-
-- **no argument**: briefs the active run in `devflow/context/current-stage.md` (or the first planned feature in `devflow/context/project-overview.md`).
-- **running ID or feature name**: e.g. `brief RUN-003`, `brief "OAuth Login"`.
-- **topic / concern**: e.g. `brief "database migration"`.
+- `/status` reports the *whole project*: progress, current work, git, next action.
+  `/brief` zooms into *one feature* and explains it in depth.
+- `/feature` *writes* the spec (and may split the item in `build-plan.md`).
+  `/brief` previews what `/feature` would tackle, changing nothing.
 
-If there is no active run and the overview does not list planned features, plainly report that context is needed and recommend `00-discover` or `10-define`.
+## Input
 
-## Step 1 - Read Context (Read-Only)
+A feature from `build-plan.md`, by number or name - e.g. `/brief 4` or
+`/brief "validator"`.
 
-Gather and synthesize:
+**With no argument, brief the next one** - the first unchecked leaf in
+`build-plan.md`, the same target `/feature` would pick.
 
-1. **Active/Target Scope**: Target Running ID, `10-define.md`, or roadmap feature item.
-2. **Project Context**: `devflow/context/project-overview.md` (Data models, architecture layout, primary stack, existing shipped capabilities).
-3. **Existing Codebase State**: Inspect existing directory structures, schemas, and routes touching this feature.
-4. **Dependencies**: What previously completed runs (`devflow/runs/`) or modules must be in place first.
+If `build-plan.md` is still a placeholder stub or the overview is missing, say so
+plainly and point at `/overview` (or filling the plans) rather than inventing a
+briefing.
 
-## Step 2 - Analyze & Assess
+## What it reads
 
-Evaluate:
+Gather these, then synthesize. Don't dump file contents; explain.
 
-- **What It Is**: Core capability and user-visible or system-visible outcome.
-- **Depends On**: Required upstream models, tables, APIs, environment variables, or sibling runs.
-- **Unblocks**: Downstream features or workflows that this run enables.
-- **Touches**: Files, modules, API routes, database tables, or UI components likely to change.
-- **Estimated Size**: Small (S), Medium (M), Large (L), or Extra-Large (XL - recommend splitting in `10-define`).
-- **Open Questions & Risks**: Ambiguous requirements, missing external APIs, or complex migrations.
+1. **The target** - the feature's line in `devflow/build-plan.md`, plus whether
+   a parent was already split into sub-items (`4a`, `4b`, ...).
+2. **Full context** - `devflow/context/project-overview.md`: the data model,
+   routes/endpoints, stack, UI/UX, conventions, and open questions that touch this
+   feature.
+3. **What already exists** - earlier checked build-plan items and, if useful, git
+   history, to ground the dependency read (what must be in place first, what this
+   unblocks later).
+4. **Design reference** - if `prototypes/` exists and the feature is UI-facing,
+   note which mockups apply (that `/feature` will link them and port `theme.css`).
 
-## Step 3 - Output Structured Briefing
+## Output
 
-Produce a short, scannable briefing:
+A short, scannable briefing, not a wall of text. Aim for something like:
 
-```markdown
-### 📋 Feature Briefing: [Feature / Run Name]
+    Feature 5 - Submission draft flow
+    What: maintainers submit a skill by GitHub URL (primary) or zip (fallback);
+      drafts are saved before validation runs.
+    Depends on: apps/api must be stood up first (this is the first feature that
+      needs the backend); builds on the Skill / SkillVersion shapes from feature 3.
+    Unblocks: queue-backed validation (6) and the publishable flow (7).
+    Touches: new User, Submission, SkillVersion tables (Drizzle); GitHub OAuth;
+      POST /submissions; R2 snapshot upload; a React upload island (client).
+    Size: large - likely splits into 5a (OAuth + maintainer profile), 5b
+      (GitHub-URL submission + draft record), 5c (zip upload + R2).
+    Reference: no prototype for this flow; upload.html covers the later validation
+      panel, not this form.
+    Open questions: apps/api (Hono) is not scaffolded yet - resolve before spec'ing.
 
-- **What**: Brief summary of the core outcome.
-- **Depends On**: Prerequisite modules, runs, or infrastructure.
-- **Unblocks**: Downstream capabilities enabled by this feature.
-- **Touches**: Anticipated files, schemas, endpoints, and UI views.
-- **Estimated Scope & Size**: `[S / M / L / XL]` (and split recommendation if XL).
-- **Key Risks & Open Questions**: Technical or product unknowns that must be settled in `20-spec`.
+    Next: run /feature 5 to spec 5a, or clear the apps/api blocker first.
 
----
-👉 **Next Recommended Action**: `20-spec {running-id}` (or resolve prerequisite blocker first).
-```
+Adapt the lines to the feature; drop any that don't apply. Always end with a
+single **Next** action - usually `/feature N` to spec it, but `/overview` if the
+plans aren't ready, `/prototype` if it's UI-facing and the look isn't locked, or
+"clear X first" when a dependency blocks it.
 
 ## Rules
 
-- **Always Read-Only**: Never edit any workspace file, never allocate running IDs, never commit or execute scripts.
-- **Explain, Don't Spec**: Focus on scope, architectural dependencies, and size estimation. The formal delivery contract is the responsibility of `20-spec`.
-- **Ground In Reality**: Trace all assertions back to `project-overview.md` or actual codebase facts. Do not invent non-existent packages or fictional architecture.
-- **Highlight Blockers Early**: Flagging a missing prerequisite before speccing is the primary value of this command.
-
-## Output Formatting
-
-Follow the project conventions in `devflow/context/ai-interaction.md`: concise, scannable markdown with bold labels and actionable bullet points.
+- **Read-only, always.** Never write a file, never edit `build-plan.md` or
+  `current-feature.md`, never branch, commit, install, or build. To act on the
+  briefing, the user runs `/feature` next.
+- **Explain, don't spec.** Size, dependencies, and a likely sub-split are the
+  value here; the actual build steps are `/feature`'s job. Don't write step lists.
+- **Trace to the plans.** Everything in the briefing comes from `build-plan.md`
+  and `project-overview.md`. Don't invent scope; if something is underspecified,
+  say so and flag it as a question for `/feature` or `/overview`.
+- **Be honest about gaps.** If the plans are a stub, the overview is stale, or a
+  dependency isn't built yet, say that plainly - catching a blocker before
+  spec'ing is half the value.
+
+## 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.