@jakkrichm/create-nexus-devflow 2.1.0 → 2.2.0

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

@@ -1,109 +1,155 @@
 ---
 name: rollback
-description: "[Devflow] Plan safe feature or run reversal with dependency and commit risk analysis."
+description: "[devflow][B] Plan a safe reversal of a completed Blueprint feature using its archived spec and squashed git commit. Finds the exact feature commit, reviews later commits for dependency risk, writes a Type: Rollback spec to devflow/context/current-feature.md, and stops for review before /implement applies any code change. Use when the user runs /rollback, asks to remove or undo a completed feature, or wants to return the app to its pre-feature behavior without erasing Blueprint history."
 ---
 
-# rollback - Safe Feature Reversal & Rollback Planner
+# rollback - safely reverse a completed feature
 
 Where this sits in the workflow:
 
-```text
-completed run + git history  ->  [rollback]  ->  40-execute (or fix run)  ->  50-verify  ->  70-deliver
-(run archive + commits)          (risk review    (reverse product diff)          (prove)      (log & finalize)
-                                  + plan)
-```
+    completed feature + git history  ->  [rollback]  ->  /implement  ->  /check  ->  /complete
+    (archive + squashed commit)           (risk review     (reverse       (prove)     (log + merge)
+                                           + spec)          product diff)
 
-This skill **plans a rollback**. It does not silently alter product code, reset branches destructively, force-push, or mutate repository history. It identifies the completed run and its exact git commit, analyzes what changed afterward, drafts a guarded rollback specification, and stops for human review before execution.
+This skill plans a rollback. It does not change product code, create a branch,
+commit, merge, or push. It identifies the completed feature and its exact git
+commit, checks what changed afterward, writes a guarded rollback spec, then stops
+for review. `/implement` performs the reversal only after the user approves that
+spec.
 
 ## Input
 
-A completed run by Running ID, name, or run path, plus an optional reason. Examples:
+A completed feature by build-plan number, name, or archive path, plus an optional
+reason. Examples:
 
-```text
-rollback RUN-002-add-onboard-adopt-doctor-skills
-rollback "auth login" because OAuth provider changed
-rollback devflow/runs/RUN-001-align-devflow-blueprint
-```
+    /rollback 4 because the new export flow is corrupting files
+    /rollback "PDF export"
+    /rollback devflow/history/features/04-pdf-export.md
 
-With no target, list recent completed runs from `devflow/runs/` and `devflow/context/current-stage.md` and ask the user to choose. Never silently guess the target. If the reason is missing, ask for one before finalizing the rollback plan.
+With no target, list a short set of recent completed feature archives and ask the
+user to choose. Never silently pick the latest feature. If the reason is missing,
+ask for one before writing the spec because the rollback archive must explain why
+the feature was removed.
 
-## Step 0 - Preflight Check
+## Step 0 - preflight
 
-Read `AGENTS.md`, `devflow/context/current-stage.md`, `devflow/context/project-overview.md`, completed run archives under `devflow/runs/`, and git state.
+Read `AGENTS.md`, `devflow/build-plan.md`,
+`devflow/context/current-feature.md`, the completed feature archives, and git
+state.
 
-Stop before planning when:
+Stop before writing when:
 
-- The directory is not a git repository.
-- There is uncommitted active work in the working tree (unless the user asks to inspect it).
-- The target run cannot be identified unambiguously in `devflow/runs/` or Git history.
+- the directory is not a git repository
+- `current-feature.md` already holds active work
+- the working tree is dirty, including unrelated untracked work
+- the current branch is not the local main or default branch
+- the target is not a checked build-plan feature with a matching archive
+- the archive or its introducing commit cannot be identified unambiguously
 
-Do not discard, force-reset, switch branches, or destroy untracked files automatically.
+Do not stash, discard, fetch, pull, switch branches, or clean the tree from this
+skill.
 
-## Step 1 - Resolve Target Run & Commits
+## Step 1 - resolve the exact feature
 
-Match the requested ID or name against `devflow/runs/` and git commit history:
+Match the requested number or name against both the checked build-plan items and
+`devflow/history/features/*.md`. Exclude the directory README.
 
-```bash
-git log --grep="RUN-002" --oneline
-```
+Use the archive path to locate the commit that added it:
 
-Identify:
+    git log --diff-filter=A --format="%H %s" HEAD -- <archive-path>
 
-- Exact commit SHA(s) introducing the feature.
-- Parent commit before the feature was introduced.
-- Associated stage artifacts (`20-spec.md`, `40-execute.md`, `70-deliver.md`).
+Use the newest matching commit reachable from the current branch. Confirm the
+archive was added by that commit, the commit has exactly one parent, and its
+subject and diff are consistent with the requested feature. A merge commit needs
+mainline selection, so stop rather than guessing. If the archive was never
+committed, explain that git cannot reconstruct a safe rollback from it.
 
-## Step 2 - Separate Product Changes From DevFlow History
+## Step 2 - separate product changes from Blueprint history
 
-Inspect the files touched by the target commit(s).
+Inspect the target commit and build the product-path set from the files it
+changed. Exclude these protected workflow paths:
 
-**Protected Workflow Paths (Never Revert Automatically):**
 - `.agents/**`
 - `.claude/**`
-- `devflow/**` (preserve run records, schemas, and historical reports)
-- `AGENTS.md` / `CLAUDE.md` (unless explicitly intended to update commands)
-- `.nexus/**`
+- `devflow/**`
+- `AGENTS.md`
+- `CLAUDE.md`
+- `prototypes/**`
+
+The rollback must preserve the original feature archive, later planning changes,
+the active rollback spec, adapter skills, and throwaway prototype history. Root
+`README.md` and ordinary app docs are product files unless the project says
+otherwise.
+
+If no product paths remain, stop. Do not create an empty rollback that only
+rewrites Blueprint records.
+
+## Step 3 - review later-change risk
+
+Inspect every commit after the target through `HEAD` that touches one of the
+product paths. Also read later completed feature specs when they mention the
+target, its contracts, routes, data, or files.
+
+Classify the result:
+
+- **No overlap** - no later commit touched the target product paths.
+- **Overlap, likely compatible** - later edits touched the same paths, but the
+  target change can be reversed without removing their behavior.
+- **Dependency risk** - later work appears to require the target's API, schema,
+  route, component, or data.
+- **Blocked** - safe behavior after reversal is unclear, data migration would be
+  destructive, or a cascading rollback would be required.
+
+Path overlap is a warning signal, not proof of dependency. Explain the concrete
+later commit and contract involved. Never silently cascade into reverting other
+features. For a blocked case, stop and ask the user to choose a narrower
+remediation or explicitly plan the dependent rollbacks.
+
+## Step 4 - write the rollback spec
+
+Write `devflow/context/current-feature.md` using
+`reference/rollback-spec-template.md`. Fill in:
+
+- target feature, archive, exact commit, and parent commit
+- user's reason
+- product paths introduced or changed by the target
+- protected workflow paths
+- later commits reviewed and the risk classification
+- compatibility work that is allowed, if any
+- exact verification commands and observable removal criteria
+
+The first build step must apply the target commit's product diff in reverse using
+the guarded Type: Rollback behavior in `/implement`. Later steps may repair only
+the specific downstream compatibility issues named in the spec. Do not use a
+rollback as permission for unrelated cleanup.
+
+Older installations may not have `devflow/history/rollbacks/` yet because
+updates preserve user history. That is not a planning blocker; `/complete`
+creates the directory when it archives the approved rollback.
+
+Red-team the draft before presenting it:
+
+- does it preserve all Blueprint history and later plan changes?
+- could it remove data or require a destructive migration?
+- does later code import or call something the target introduced?
+- are the removal criteria observable rather than phrased as "feature gone"?
+- can each compatibility edit be reviewed separately?
+
+Tighten the spec, then stop. Summarize the target commit, affected product paths,
+later-change risk, and what the critique changed. Tell the user to review the
+spec, then run `/implement` to create the rollback branch and apply it.
 
-The rollback must preserve DevFlow's durable history while isolating the **Product Code Diff** (application code, UI components, backend APIs, configuration).
-
-## Step 3 - Review Later-Commit Risk (Dependency Risk Analysis)
-
-Inspect every commit after the target commit through `HEAD` that touches any of the product files.
-
-Classify the risk into one of 4 standard categories:
-
-| Risk Level | Meaning | Action |
-| :--- | :--- | :--- |
-| **No Overlap** | No subsequent commits touched these product files. | Clean reversal is safe and straightforward. |
-| **Overlap, Compatible** | Later edits touched the same files, but the target code can be cleanly extracted without breaking newer behavior. | Plan selective reverse-patching. |
-| **Dependency Risk** | Subsequent features or bugfixes directly depend on types, APIs, tables, or exports introduced by the target. | Explicitly warn that dependent features will be affected; plan compatibility shims. |
-| **Blocked** | Reversing the target would cause data loss, break database schema, or require a cascading rollback of multiple runs. | Stop and present the blocker to the user for explicit architectural guidance. |
-
-## Step 4 - Produce The Guarded Rollback Plan
-
-Draft the rollback plan containing:
-
-1. **Target Run & Rationale**: Running ID, original commit SHA, author, and reason for reversal.
-2. **Product Files to Revert**: Exact list of application files to modify/delete/restore.
-3. **Protected Paths**: Explicit declaration of preserved history files.
-4. **Risk Classification**: Dependency analysis findings and required compatibility repairs.
-5. **Step-by-Step Reversal Steps**:
-   - Step 1: Apply reverse product diff.
-   - Step 2: Apply compatibility fixes for downstream dependencies.
-   - Step 3: Run project verify command (`npm test`, `npm run check`).
-6. **Acceptance & Verification Criteria**: How to prove the removed behavior is truly gone without breaking existing unaffected features.
-
-## Step 5 - Stop For Human Confirmation
-
-Present the rollback plan to the user:
+## Rules
 
-- Summarize affected files and dependency risks.
-- If approved, route to `40-execute` (or allocate a dedicated Fixrollback Run) to safely execute the reversal steps behind review gates.
+- Preserve history. Never delete or rewrite the original feature archive.
+- Plan only. This skill writes the rollback spec and nothing else.
+- One completed feature per rollback.
+- Never use `git reset --hard`, force-push, history rewriting, or broad file
+  restoration.
+- Never infer permission to cascade into later features or destroy stored data.
+- A rollback still uses `/implement`, `/check`, and `/complete` review gates.
 
-## Rules
+## Formatting
 
-- **Preserve History**: Never delete run folders under `devflow/runs/`. Historical reports must remain intact.
-- **Update History Ledger**: When the rollback is completed and verified, update the target entry's status in `devflow/history/HISTORY.md` to `Rolled Back` with reference to the reversal commit.
-- **No Destructive Git Commands**: Never execute `git reset --hard HEAD~N` or `git push --force`. All reversals must be applied as forward commits.
-- **One Target Per Rollback**: Avoid bundling multiple unrelated rollbacks into one pass.
-- **Explicit Human Gate**: Always wait for user approval before applying any reverse diffs to code.
+Format the output to match `devflow/context/ai-interaction.md`: concise,
+scannable markdown with a small risk table when later commits overlap.

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

@@ -0,0 +1,109 @@
+---
+name: status
+description: "[devflow][B] Show where the project stands: build-plan progress, the current feature's checked and unchecked steps, git state, drift warnings, and the exact next action. Read-only. Use when the user runs /status, asks where things stand, what's next, what's in progress, or is picking work back up after a break or a context clear."
+---
+
+# status - where the project stands right now
+
+Where this sits in the workflow:
+
+    any time  ->  [status]  ->  reads build-plan + current-feature + git
+                  (read-only)   prints a short "you are here"
+
+This skill answers one question: *where am I?* It reads the files that already
+track progress and prints a short orientation. It is the fast way back in after a
+break, a context clear, or a day away. It never changes anything: no edits, no
+commits, no installs, no builds, no branch changes.
+
+Progress in this workflow lives in files, not the chat, so everything this skill
+reports comes from disk and git. That is the point: a fresh session can run
+`/status` and know exactly as much as the last one did.
+
+For setup problems, missing files, placeholder plans, adapter drift, or questions
+about whether the Blueprint is installed correctly, run `/doctor` instead.
+
+## Input
+
+None. `/status` takes no argument.
+
+## What it reads
+
+Gather these, then summarize. Don't dump file contents; report the distilled
+state.
+
+1. **Build plan** - `devflow/build-plan.md`. Count checked vs unchecked leaf
+   items. Name the next unchecked leaf, the same target `/feature` would pick,
+   and note if a parent item was split into sub-items (`4a`, `4b`, ...).
+2. **Current work** - `devflow/context/current-feature.md`. Is something in
+   progress, or is it the reset stub? If a feature, fix, or rollback spec is
+   present, report its type and name, which build steps are checked, and the
+   first unchecked step where `/implement` resumes.
+3. **Findings** - `devflow/context/findings.md`. Count findings by status and
+   report open and fixed counts next to build-plan progress. Call out any P0 or
+   P1 still `open` or `fixed` by ID, since those block `/complete`. A missing
+   file means no findings.
+4. **Overview freshness** - if `devflow/context/project-overview.md` is missing,
+   or if `project-plan.md` or `build-plan.md` appears newer than it by filesystem
+   time, mention that `/overview` should run before new feature work.
+5. **Git** - current branch, whether the working tree is clean or has uncommitted
+   changes, roughly how many files changed, last commit subject, and whether the
+   branch is ahead of its remote. If the directory is not a git repo, say so and
+   skip this part rather than failing.
+6. **Progress drift** - flag active spec on `main`, a spec in progress but no
+   matching `feature/`, `fix/`, or `rollback/` branch, all spec steps checked but
+   not completed, or disagreement between `build-plan.md` and
+   `current-feature.md`. A rollback legitimately targets a checked build-plan
+   item until `/complete` unchecks it, so do not compare it to the next unchecked
+   feature.
+
+## Output
+
+A short, scannable summary, not a wall of text. Aim for something like:
+
+    Status: Building feature 4 - PDF export
+    Plans: Overview current. Build plan 3 of 9 complete.
+    Current work: Step 2 of 3 done. Next step: Download PDF button.
+    Findings: 1 open P2 (F-04), 1 fixed P1 awaiting re-review (F-02).
+    Git: branch feature/pdf-export, 3 uncommitted files, last commit "feat: widen export helper".
+    Watch: F-02 is fixed but not re-reviewed; it blocks /complete until /audit closes it.
+
+    Next action: run /implement for Step 3.
+
+End with a single suggested next action, chosen in this order:
+
+- The overview is missing or stale and no feature is in progress -> `/overview`.
+- A spec is in progress with unchecked steps -> `/implement` and name the step.
+- A spec is in progress and all implementation steps are checked -> `/check` if
+  proof is not recorded, `/try` if the user wants a manual review path,
+  `/implement` when a P0 or P1 finding is still `open` (the repair is an extra
+  reviewed step), `/audit` when one is `fixed` and awaiting re-review (both
+  block `/complete`), otherwise `/complete`.
+- `current-feature.md` is the reset stub and a P0 or P1 finding is `open` ->
+  `/fix <finding id>`; when one is `fixed`, `/audit` to re-review and close it.
+- `current-feature.md` is the reset stub and unchecked build-plan items remain ->
+  `/feature` and name the next build-plan item.
+- All build-plan items are checked -> say the current milestone is complete;
+  suggest hardening, release, or docs when appropriate, or
+  `/feature "new capability"` to propose an addition to the living build plan.
+  Do not suggest creating a second build plan.
+
+If something is off, include a `Watch:` line before the next action. Catching
+drift is half the value of the command.
+
+## Rules
+
+- **Read-only, always.** This skill never writes a file, never commits, never runs
+  installs, never runs builds or tests, and never switches branches. If the user
+  wants to act on what it reports, they run the relevant skill next.
+- **Prefer exact next actions.** Do not end with vague advice like "continue the
+  workflow". Name the command and, when useful, the file or step.
+- **Distill, don't dump.** Report the state in a few lines. Do not paste file
+  contents back unless the user asks for them.
+- **Be honest about gaps.** If a file is missing or the repo is not initialized,
+  say that plainly instead of guessing.
+
+## 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/test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test
-description: "[Devflow] Test execution, missing test generation, and coverage analysis across unit, integration, and smoke test suites."
+description: "[devflow][B] Test execution, missing test generation, and coverage analysis across unit, integration, and smoke test suites."
 ---
 
 # Test-Driven Development, Generation & Execution
@@ -91,4 +91,4 @@ When generating or logging test runs during `40-execute` or `50-verify`:
 
 - **Classification**: Companion command & Engineering standard
 - **Mainline stages**: `30-plan` (TDD decisions), `40-execute` (TDD execution), `50-verify` (QA gate)
-- **Handoff**: `50-verify`, `Debug`, `autopilot`
+- **Handoff**: `50-verify`, `Debug`, `autopilot`

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

@@ -0,0 +1,126 @@
+---
+name: tests
+description: "[devflow][B] Add or normalize unit testing for a Blueprint project. Detects the stack, reuses an existing test runner when present, or installs the stack-native unit test runner when missing, then adds one small example test, updates AGENTS.md commands, runs build and tests, and reports the diff. Use when the user runs /tests, invokes $tests, asks to add unit tests, set up unit testing, configure tests, or make tests part of the Blueprint workflow."
+---
+
+# tests - add unit testing to the project
+
+Where this sits in the workflow:
+
+    any time  ->  [tests]  ->  test command in AGENTS.md  ->  /feature + /implement use it
+                  (setup)     (the opt-in testing gate)      (logic steps get tests)
+
+Testing is optional in the Blueprint until the project declares a real test
+command in `AGENTS.md`. This skill is the explicit setup path. It adds or
+normalizes **unit testing** only; browser automation and end-to-end testing are
+separate setup work.
+
+## Input
+
+No argument is required. If the user names a runner or stack preference, treat it
+as a preference and verify it against the project files.
+
+## Step 1 - inspect the project
+
+Read enough files to identify the real setup:
+
+- `AGENTS.md` Commands section
+- package or language manifest (`package.json`, `pyproject.toml`, `go.mod`,
+  `Cargo.toml`, and similar)
+- existing test config (`vitest.config.*`, `jest.config.*`, `pytest.ini`,
+  `phpunit.xml`, language-native config, and similar)
+- existing test files
+- package manager lockfile
+- an existing `Verify` command and `.github/workflows/verify.yml`, when present
+- `devflow/context/coding-standards.md`
+
+Do not assume Next.js. Detect the stack from files.
+
+## Step 2 - choose the smallest test setup
+
+Prefer the existing runner if one is already present. If none exists, choose the
+stack-native unit test runner:
+
+- TypeScript or JavaScript app: Vitest by default, unless the project already
+  clearly uses Jest or another runner.
+- Python: pytest.
+- Go: built-in `go test`.
+- Rust: built-in `cargo test`.
+- Ruby: the runner already implied by the project, or Minitest when nothing else
+  is present.
+- PHP: PHPUnit when the project is Composer-based.
+
+If the stack is unclear, stop and ask what runner to use instead of guessing.
+
+Keep the setup minimal. Do not add coverage, browser testing, CI, snapshots,
+mock-service layers, or a large test architecture unless the user explicitly asks.
+
+## Step 3 - make the setup changes
+
+Apply the smallest practical diff:
+
+1. Add missing test dependencies or config.
+2. Add or normalize package/script commands.
+3. Add one small example test for real project logic if a suitable function
+   exists; otherwise add a tiny helper and test that proves the runner works.
+4. Update the Commands section of `AGENTS.md` with the real test command and,
+   when available, the test watch command.
+5. If a `Verify` command already exists, add the real test command to it between
+   typecheck and build while preserving any established project checks. Do not
+   create verification or CI only because `/tests` was invoked.
+6. Update `devflow/context/coding-standards.md` only if the project needs a
+   stack-specific testing note different from the default.
+
+Do not write a broad test suite for existing app code. This skill proves the
+testing path and turns on the gate; feature work adds focused tests later.
+
+If adding dependencies requires network access, ask for the needed install command
+through the current tool's approval flow. Use the project's package manager.
+
+## Step 4 - verify
+
+If `AGENTS.md` documents a `Verify` command, run the focused test command and
+then run `Verify` as the final gate. The combined command should now exercise the
+new tests along with its existing typecheck and build checks.
+
+If no `Verify` command exists, run the relevant commands from `AGENTS.md`:
+
+- the test command
+- the build command, when one exists
+- lint or typecheck only if they are already standard commands and the diff
+  touches config or types that should satisfy them
+
+An empty suite must not be treated as a pass. If the runner reports no tests, add
+or fix the example test.
+
+## Step 5 - report
+
+Stop with a concise report:
+
+- runner chosen or reused
+- commands added or updated
+- existing verification command updated, or confirmation that none exists
+- example test added
+- verification commands run and whether they passed
+- any follow-up the user should consider
+
+Show the diff summary. Do not commit, merge, push, or start product feature work.
+
+## Rules
+
+- Unit testing only. Do not set up Playwright, Cypress, browser E2E, CI, or
+  coverage unless the user explicitly asks.
+- Reuse existing project conventions before adding new tools.
+- Preserve existing CI. This skill may update an existing verification command,
+  but it never creates a GitHub workflow on its own.
+- Keep the first test boring and small. It exists to prove the workflow.
+- Once `AGENTS.md` has a test command, later `/feature` and `/implement` runs
+  treat tests as the gate for logic-bearing changes.
+- Do not hide install or verification failures. Report exactly what failed and
+  what to fix next.
+
+## 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.