@jakkrichm/create-nexus-devflow 2.1.0 → 2.2.0

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

@@ -1,197 +1,256 @@
 ---
 name: autopilot
-description: "[Devflow] Optional explicit mode for one bounded Fast-Track or Deep-Track delivery 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  ->  /complete (fast) / 70-deliver (deep)
-(where        (fast or deep      (human review,        (package, PR,
- are we?)      track loop)        walkthrough)           merge with approval)
-```
+    /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 one bounded loop without requiring human confirmation between every sub-step, in either track:
+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.
 
-- Fast-Track: `feature` / `fix` -> `implement` -> `check`.
-- Deep-Track: `20-spec` -> `30-plan` -> `40-execute` -> `50-verify` -> `60-report`.
+It does **not** replace the normal workflow. `/feature`, `/implement`, `/check`,
+and `/complete` remain the conservative default.
 
-It does **not** replace the normal step-by-step workflow. Mainline commands (`feature`, `fix`, `implement`, `check`, `complete`, `20-spec`, `30-plan`, `40-execute`, `50-verify`, `60-report`, `70-deliver`) 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/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`.
-- **`fast`**: force Fast-Track mode. Example: `autopilot fast "add auth header"`
-- **`deep`**: force Deep-Track mode. Example: `autopilot deep "data migration"`
-- **Running ID or feature name**: target that run, e.g. `autopilot RUN-004` or `autopilot "add user authentication"` (mode auto-selected from context).
-- **`fix "<issue>"`**: write and execute an ad-hoc fast-mode 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/current-run/` artifacts
+- `devflow/context/findings.md`
 - `devflow/context/coding-standards.md`
 - `devflow/context/ai-interaction.md`
-- `devflow/context/findings.md`
 - git branch, status, and recent log
 
-Track mode selection:
-
-1. Use explicit `fast` or `deep` if provided.
-2. If `devflow/context/current-feature.md` is active and `current-run/` has no deep stage files, default to **fast**.
-3. If `devflow/context/current-run/` has deep stage files (`10-define.md`, `20-spec.md`, `30-plan.md`, etc.), default to **deep**.
-4. If both tracks are active, stop and ask which track should win.
+Then decide whether it is safe to run.
 
 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
-
-### Fast-Track
-
-1. If `devflow/context/current-feature.md` already exists and is active, resume it.
-2. If no spec exists:
-   - Write or refresh the spec in `devflow/context/current-feature.md`.
-   - Lock scope, acceptance criteria, and implementation checklist.
-   - Add feasibility checks and test hooks.
-3. Critique and red-team the spec (edge cases, unhappy paths, testable criteria), then apply fixes.
-
-### Deep-Track
-
-1. If `devflow/context/current-run/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), then apply fixes.
-
-## 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**:
-   - **Fast-Track**: maintain the implementation and verification checklist sections in `devflow/context/current-feature.md`.
-   - **Deep-Track**: write `devflow/context/current-run/30-plan.md` and 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]`.
-7. **Create a Checkpoint Commit** on the feature/fix branch for the passing step:
-   ```bash
-   # Fast-Track
-   git add <modified-files> devflow/context/current-feature.md
-   git commit -m "feat({running-id}): checkpoint <concise step description>"
-
-   # Deep-Track
-   git add <modified-files> devflow/context/current-run/{running-id}-{slug}/checklists/implementation-checklist.md
-   git commit -m "feat({running-id}): checkpoint <concise step description>"
-   ```
-8. **Fast-Track**: write implementation status to `devflow/context/current-feature.md`.
-9. **Deep-Track**: write `devflow/context/current-run/{running-id}-{slug}40-execute.md`.
-
-## Step 5 - Senior QA Verification (`50-verify`)
-
-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 verification evidence with concrete evidence in the active track artifact:
-   - **Fast-Track**: `devflow/context/current-feature.md`
-   - **Deep-Track**: `checklists/verification-checklist.md`
-3. **Deep-Track**: write `devflow/context/current-run/{running-id}-{slug}50-verify.md` with QA verdict (`PASS` / `FAIL`).
-4. **Fast-Track**: confirm check stage transition and verification state in `devflow/context/current-feature.md`.
-
-## 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 - Review Packet & Track Handoff
-
-1. **Deep-Track**: write `devflow/context/current-run/{running-id}-{slug}60-report.md`, render standalone HTML dashboard `devflow/context/current-run/{running-id}-{slug}60-report.html` (via `md2html` or report generator), and set `devflow/context/current-stage.md` to ready for `70-deliver`.
-2. **Fast-Track**: keep final checkpoint and evidence in `devflow/context/current-feature.md`.
-3. Stop with a concise **Review Packet Dashboard** for human approval, including:
-   - Track used (`fast` or `deep`)
-   - Evidence summary
-   - Commit count
-   - Manual next action (`/complete` for fast, `/70-deliver` for deep)
-
-## 🛑 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}] ({track})
-
-- **Branch**: `{branch-name}`
-- **Target Run**: `{running-id} - {title}`
-- **Artifacts Generated**:
-  - **Fast-Track**:
-    - Spec/Build/Verify evidence: `devflow/context/current-feature.md`
-  - **Deep-Track**:
-    - Spec: `devflow/context/current-run/{id}20-spec.md`
-    - Plan: `devflow/context/current-run/{id}30-plan.md`
-    - Implement Evidence: `devflow/context/current-run/{id}40-execute.md`
-    - QA Verify Report: `devflow/context/current-run/{id}50-verify.md`
-    - Digest Report: `devflow/context/current-run/{id}60-report.md`
-    - HTML Dashboard: `devflow/context/current-run/{id}60-report.html`
-- **Validation & Tests**: track-aware PASS/FAIL evidence
-- **Checkpoint Commits**: `{count} commits created on {branch-name}`
-- **Manual QA Walkthrough**: Run `try {running-id}` for human review guide
-
----
-👉 **Next Recommended Action**:
-Inspect diffs and `try` walkthrough.
-- Fast-Track: run `/complete {running-id}` for final safety and merge flow.
-- Deep-Track: run `70-deliver {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/.claude/skills/brainstorm/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: brainstorm
+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}"
+---
+
+# Brainstorming & Option Analysis
+
+$ARGUMENTS
+
+Explore a vague request, architectural choice, or feature direction without allocating a Running ID. Formulate 2-3 materially different options, analyze trade-offs, and recommend the optimal path.
+
+## Usage
+
+```text
+brainstorm {topic or request}
+brainstorm {discovery-id}
+```
+
+Use this when:
+- A request has multiple viable implementation paths
+- The team needs to compare options before locking delivery scope
+- Discovering or defining a complex technical feature
+
+## Process & Execution Lenses
+
+### 1. Ground the Problem
+- Restate the core goal and target user/stakeholder value.
+- Identify technical, business, or timeline constraints.
+
+### 2. Option Formulation (Divergent Phase)
+Provide at least 2-3 materially distinct approaches:
+- **Option A (Standard / Conservative)**: Low risk, proven pattern, minimal changes.
+- **Option B (Modern / Optimized)**: Best-practice architecture, balanced trade-off, scalable.
+- **Option C (Alternative / Unconventional)**: High innovation, simplified scope, or creative alternative.
+
+### 3. Trade-off Comparison Matrix
+Construct a structured evaluation table:
+
+| Option | Pros (ข้อดี) | Cons (ข้อเสีย) | Effort & Complexity | Verdict / Status |
+| :--- | :--- | :--- | :--- | :--- |
+| **Option A** | ... | ... | Low / Med / High | ... |
+| **Option B** | ... | ... | Low / Med / High | **Recommended** |
+| **Option C** | ... | ... | Low / Med / High | ... |
+
+### 4. Codebase & Feasibility Check
+- Use `grep_search` to inspect existing patterns in the project.
+- Verify library suitability or external API contracts before recommending.
+
+### 5. Recommendation & Next Steps (Convergent Phase)
+- Select the best option and explain the core rationale.
+- Define actionable next steps without writing prematurely detailed code.
+
+## Output
+
+1. Render the comparison matrix and recommended path directly in the conversation.
+2. (Optional) Save persistent artifact to `devflow/research/brainstorm-{slug}.md` when attached to a discovery run.
+
+## Next Workflow Recommendation
+
+- **Primary**: `00-explore {discovery_id}` (if resuming discovery) or `10-define` / `feature` (if ready to specify)
+- **Inbox**: `idea` to record into `devflow/ideas.md`