@jakkrichm/create-nexus-devflow 2.0.24 → 2.0.27

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

@@ -1,95 +1,158 @@
 ---
 name: adopt
-description: "[Devflow] Survey existing brownfield codebase and bootstrap DevFlow context files."
+description: "[devflow][B] Bring the blueprint into an existing (brownfield) codebase. Surveys the real repo, interviews for intent, generates the owned plans and coding standards, documents existing verification and CI, and points to the optional standalone CI setup. Use when the user runs /adopt, is overlaying the blueprint onto an app that already has meaningful code, or asks to adopt or bootstrap the workflow into an existing project. For freshly scaffolded or early projects, use onboard instead."
 ---
 
-# adopt - Bootstrap Nexus-DevFlow from an Existing Codebase
+# adopt - bootstrap the blueprint from an existing codebase
 
 Where this sits in the workflow:
 
-```text
-existing codebase  ->  [adopt]  ->  project-overview + coding-standards  ->  00-discover or 10-define
-(already has code)     (survey +    (seeded from the real code;               (first feature / refactoring
-                        interview)   shipped architecture documented)          delivery lifecycle)
-```
+    existing codebase  ->  [adopt]  ->  project-plan + build-plan + coding-standards  ->  /overview  ->  normal loop
+    (already has code)     (survey +     (seeded from the real code; shipped               (project-       (/feature,
+                            interview)     features already checked off)                    overview.md)     /implement, ...)
 
-Standard onboarding assumes a freshly scaffolded, near-empty app. That does not fit a codebase that already has thousands of lines of working code.
+The standard onboarding assumes a freshly scaffolded, near-empty app: you write
+the two plans from scratch and build forward. That doesn't fit a project that
+already has thousands of lines of working code. `/adopt` is the brownfield
+on-ramp: it reads what's already there, asks you only for what the code can't tell
+it (the *why* and the *roadmap*), and produces the same input files the rest of
+the workflow expects - so an existing project joins the loop without you
+hand-writing everything.
 
-`adopt` is the brownfield on-ramp for Nexus-DevFlow: it reads what is already there, asks only for what the code cannot reveal (the *intent*, the *why*, and the *upcoming roadmap*), and produces the exact context files the rest of the DevFlow lifecycle expects (`project-overview.md`, `coding-standards.md`, `AGENTS.md` commands).
-
----
+It generates the inputs; it does not generate `project-overview.md`. That stays
+`/overview`'s job. `/adopt` ends by telling you to run `/overview`.
 
 ## Input
 
-A description of what the project is, if provided. Otherwise, inspect the repository directly. No argument is required.
-
----
-
-## Step 0 - Confirm Brownfield Safety
-
-Inspect `devflow/context/project-overview.md` and `devflow/context/coding-standards.md`:
-
-- If they contain default placeholders or empty templates, proceed.
-- If they already hold rich, user-owned content, stop and inform the user; offer to refresh specific sections rather than overwriting existing context without confirmation.
-
-Never run a framework scaffolder (DevFlow is an overlay, never a generator).
-
----
-
-## Step 1 - Survey the Codebase (Read-Only)
+A description of what the project is, if the user offers one. Otherwise just the
+repository itself. No argument is required.
+
+## Step 0 - confirm it's brownfield and safe
+
+Look at `devflow/project-plan.md` and `devflow/build-plan.md`.
+
+- If they're missing or still the empty worksheet/placeholder, proceed.
+- If they already hold real content, this project is already adopted. Stop and say
+  so; offer to refresh a specific file instead of overwriting work the user owns.
+
+Never overwrite a filled-in plan without explicit confirmation. Never run a
+framework scaffolder (the blueprint is an overlay, never a generator).
+
+Protect the project README:
+
+- If the root `README.md` already looks like a real project README, leave it
+  alone.
+- If the root `README.md` is the copied Blueprint workflow doc (for example it
+  starts with `# AI Coding Blueprint`), report it as obsolete overlay content
+  and ask before replacing or removing it. Do not move it into `blueprint/`.
+- Do not create or overwrite a root project README for a brownfield app unless
+  the user explicitly asks. The existing project face belongs to the app, not the
+  workflow.
+
+## Step 1 - survey the codebase (read-only)
+
+Read the repo to establish the facts. Change nothing in this step. Establish:
+
+- **Stack and tooling** - language(s), framework(s), and versions, from the real
+  manifest (`package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`,
+  `Gemfile`, `Cargo.toml`, etc.). Note the package manager actually in use (lockfile).
+- **Commands** - the real dev / build / test / lint scripts. These feed the
+  Commands section of `AGENTS.md` and, per the testing opt-in switch, decide
+  whether a testing gate even applies.
+- **Conventions in practice** - directory layout, component/file naming, styling
+  approach, state management, data-fetching pattern, error handling. Read what the
+  code *does*, not what a default template prescribes.
+- **Testing reality** - is a runner configured and are there tests, or none? Be
+  honest; don't describe a gate the project doesn't have.
+- **Verification and CI** - note any combined verification command, GitHub
+  remote, `.github/workflows/`, or external CI. Preserve what already exists.
+- **What the app already does** - the shipped features, inferred from routes,
+  pages, entry points, and modules. This becomes the *checked* part of the build plan.
+
+Keep notes; you'll turn them into the files in Step 3.
+
+## Step 2 - interview for intent
+
+The code reveals *what* and *how*, never *why* or *what next*. Ask the user a short
+set of questions (aim for three to five, not an interrogation) to fill the gaps:
+
+- What is this project for, and who uses it? (the problem and the users)
+- Is the stack and structure you found intentional, or are there parts they'd call
+  legacy / want to change?
+- What do you want to build next? (the unchecked items in the build plan)
+- Anything the survey got wrong or missed?
+
+If the user already gave intent up front, skip what they've answered. Don't ask
+what you can read from the code.
+
+## Step 3 - generate the inputs
+
+Write these, drawn from the survey (facts) and the interview (intent). Mark every
+inference you're unsure of with a clear `> TODO (confirm)` so the user can correct
+it rather than inherit a wrong guess.
+
+- **`devflow/project-plan.md`** - the what & why, following the existing
+  worksheet structure (problem, users, features, data, tech, monetization, UI/UX).
+  The "features" and "tech" sections describe what *already exists*; the rest comes
+  from the interview.
+- **`devflow/build-plan.md`** - the ordered feature list as a checklist. **Mark
+  shipped features `- [x]`** (this is the brownfield difference: the build plan
+  reflects reality, so most of an existing app starts checked) and the roadmap
+  items from the interview as `- [ ]`. This makes `/status` and `/feature` work
+  immediately - the next unchecked item is genuinely what's next.
+- **`devflow/context/coding-standards.md`** - rewrite the default to match the
+  project's *actual* conventions from Step 1, not the shipped Next.js/Prisma
+  defaults. Keep the Writing and Comments sections; replace the stack-specific ones
+  with what the code really does. Its Testing section must reflect the real testing
+  state (the opt-in switch is a `test` command in `AGENTS.md`).
+- **`AGENTS.md` Commands section** - fill in the real dev / build / test / lint
+  commands you found, so the rest of the workflow (and the testing gate) uses the
+  project's actual scripts. Include `Verify` when a real combined command exists.
+
+Do not write `project-overview.md`; that's `/overview`'s job, downstream of these.
+
+## Step 4 - point to optional CI setup
+
+Do not create or change Verify commands or GitHub workflows during adoption.
+Report any verification command or CI already present. When equivalent automatic
+pull-request checks are absent, mention the optional standalone setup:
 
-Read the repository to establish the facts. Change nothing in this step:
-
-- **Stack & Tooling**: Languages, frameworks, and versions from manifest files (`package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc.). Note the active package manager from lockfiles.
-- **Commands**: Real dev, build, test, lint, and verify scripts.
-- **Conventions in Practice**: Directory layout, component naming, state management, styling, data-fetching, error handling, validation. Read what the code *actually does*.
-- **Testing Reality**: Inspect existing test suites, runners, and coverage. Be honest about test status.
-- **Shipped Capabilities & Architecture**: Inferred from routes, pages, controllers, database schemas, and entry points.
-
-Keep structured notes for generation in Step 3.
-
----
-
-## Step 2 - Interview for Intent
-
-The code reveals *what* and *how*, but not *why* or *what next*. Ask a short set of 3-4 questions to fill the gaps:
-
-1. **Purpose & Users**: What is the core problem this project solves, and who are the target users?
-2. **Architecture Status**: Is the current structure and stack intentional, or are there legacy parts/technical debt the team wants to change or refactor?
-3. **Upcoming Roadmap**: What are the top priorities to build, fix, or refactor next?
-4. **Clarifications**: Anything the survey got wrong or missed?
-
-*(If the user already provided this context in the prompt, skip questions that are already answered).*
-
----
+```text
+Run /ci or $ci when you want automatic GitHub checks.
+```
 
-## Step 3 - Generate the Context Artifacts
+Explain that CI is not required to finish adoption. The `/ci` skill owns
+project-specific Verify and GitHub workflow setup.
 
-Write the baseline context files drawn from the survey (facts) and interview (intent):
+## Step 5 - review gate, then hand off
 
-1. **`devflow/context/project-overview.md`**:
-   - Project Name, Purpose, and Target Users
-   - Architecture summary and directory layout
-   - Shipped capabilities and existing major modules
-   - Key technical stack components and verified commands
-   - Known technical debt or architectural focus areas
+Stop and show the user what you generated, calling out:
 
-2. **`devflow/context/coding-standards.md`**:
-   - Rewrite defaults to reflect the project's *actual* conventions discovered in Step 1
-   - Framework patterns, state management, error handling, styling, and test rules based on real code
+- the **build-plan split** - what you marked shipped vs not, since that's the
+  judgment most worth their eyes,
+- every `> TODO (confirm)` you left,
+- anything the survey and the interview disagreed on,
+- verification command and GitHub checks status.
 
-3. **`AGENTS.md` Commands Section**:
-   - Fill in the real dev, build, test, lint, and verify commands found during survey.
+These files are the ones the user *owns*. Have them review and adjust, then tell
+them to run `/overview` to distill the plans into `project-overview.md` and start
+the normal loop.
 
----
+## Rules
 
-## Step 4 - Review Gate and Handoff
+- **Read-only until Step 3.** The survey changes nothing; only generation writes.
+- **Reflect reality, don't prescribe.** `coding-standards.md` must match the code
+  that exists. A project using Zustand and REST routes should not be handed
+  standards about Server Actions and Prisma just because that's the default.
+- **Never invent intent.** Ask for the why and the roadmap; mark anything inferred
+  with `> TODO (confirm)`. Silent guesses about purpose are the main failure mode.
+- **Don't clobber owned work.** If the plans already have real content, confirm
+  before touching them. Never run a scaffolder.
+- **Be honest about testing.** If there's no runner, say testing is opt-in and not
+  yet set up; don't describe a gate the project hasn't adopted.
 
-Present the adoption summary for review:
+## Formatting
 
-- Shipped features and architectural baseline recorded
-- Inferred conventions and coding standards
-- Available verified commands in `AGENTS.md`
-- Recommended next step:
-  - Run `00-discover` (or `00-discover`, `$00-discover`) to explore the next major initiative or feature
-  - Run `10-define` (or `10-define`, `$10-define`) to immediately scope a delivery run for known roadmap items
+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/audit/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: audit
+description: "[devflow][B] Read-only code audit for a Blueprint project, except for the findings ledger it maintains at devflow/context/findings.md. Reviews the active feature, changed files, a selected path, or the full project through all concerns or a focused quality, security, performance, or tests lens. Use when the user runs /audit, invokes $audit, asks for a code or quality audit, security review, performance review, test quality review, dead-code or duplication check, vibe-coded project cleanup, or standards review."
+---
+
+# audit - review code quality against the project standards
+
+Where this sits in the workflow:
+
+    /implement or /autopilot  ->  [audit]  ->  fixes or /complete
+    (code exists)                 (review +    (repair quality issues
+                                   ledger)      or close the feature)
+
+`/check` proves behavior against the spec. `/doctor` checks Blueprint setup and
+workflow health. This skill checks the code itself through either a broad review
+or one focused lens: quality, security, performance, or tests.
+
+It reviews code without changing it: it never edits source files, installs
+dependencies, commits, merges, pushes, or starts product work. Its one write is
+the findings ledger at `devflow/context/findings.md` (Step 4), the durable
+record of findings and their status.
+
+## Input
+
+Treat scope and lens as separate controls. Arguments may appear in either order,
+such as `/audit security current` or `/audit src/auth tests`.
+
+Optional scope:
+
+- no scope argument: use `current` when an active feature exists, otherwise use
+  `changed` when local changes exist, otherwise use `full`
+- `current`: audit the active `current-feature.md`, every committed feature-branch
+  change from its merge base through `HEAD`, staged and unstaged changes,
+  untracked source files, and nearby code affected by the feature
+- `changed`: audit staged, unstaged, and untracked source files plus nearby code
+- `full`: audit all project-owned source, tests, and configuration while excluding
+  dependencies, generated files, build output, coverage output, caches, vendored
+  code, and minified assets unless the user explicitly includes them
+- path or directory: audit that area and the tests or callers needed to understand it
+
+Optional lens:
+
+- no lens: review all four lenses
+- `quality`: maintainability, duplication, dead code, consistency, complexity,
+  and standards drift
+- `security`: authorization, input trust, injection, data exposure, secret
+  handling, and unsafe configuration
+- `performance`: query, network, rendering, memory, payload, concurrency, and
+  unbounded-work risks
+- `tests`: missing coverage for important logic, weak assertions, skipped or
+  focused tests, poor isolation, brittle mocks, and likely flakiness
+
+`full` is always the full-project scope, not a lens. `/audit full` therefore runs
+all lenses across the full project. When only a lens is supplied, select scope
+with the normal no-scope rules. A focused pass may name one or more lenses. If
+the request names multiple lenses, review their union and report them separately.
+
+If the requested scope is unclear, pick the smallest useful scope and state it.
+If the lens is unclear, use all lenses and state that choice.
+
+## Step 1 - gather context
+
+Read:
+
+- `AGENTS.md`
+- `devflow/context/project-overview.md`
+- `devflow/context/coding-standards.md`
+- `devflow/context/current-feature.md`
+- `devflow/context/findings.md`, for existing IDs and statuses
+- `devflow/context/ai-interaction.md`
+- `devflow/build-plan.md`, when feature order matters
+- git branch and working tree status
+- relevant source files, tests, and configs for the chosen scope
+
+For `current`, resolve the comparison base without network access:
+
+1. Use a base branch declared by the active spec or project instructions.
+2. Otherwise use the locally recorded remote default branch when available.
+3. Otherwise use an existing local `main`, then `master`.
+4. Find the merge base and inspect the committed delta through `HEAD`, then add
+   staged, unstaged, and untracked work.
+5. If no reliable base exists, say so and use the active spec plus local changes.
+   Never claim that committed feature work was fully covered in that case.
+
+Do not fetch or pull to discover the base. For `full`, state the excluded paths
+before reviewing so generated or third-party code does not consume the audit.
+
+Prefer `rg` and targeted file reads. Do not dump large files into the response.
+
+## Step 2 - run available signals
+
+Use existing commands only. Do not install tools.
+
+Run or inspect only the signals relevant to the selected lens and scope:
+
+- lint and typecheck commands when declared and relevant
+- test command for the tests lens or when it directly validates a suspected risk
+- build command when the selected lens needs compilation or bundle evidence
+- existing security command for the security lens, when declared and locally runnable
+- existing performance command for the performance lens, when declared and locally runnable
+- targeted lightweight searches for the chosen lens, such as unused exports and
+  copied logic for quality, unsafe trust boundaries for security, repeated or
+  unbounded work for performance, and skipped or weak tests for tests
+
+Do not run broad checks unrelated to a focused lens. If a useful command is
+missing, report that as a gap. Do not invent a pass or claim that a focused
+review covered the other lenses.
+
+## Step 3 - review the code
+
+For all lenses, ground findings in reachable code and project-specific
+expectations. Apply only the selected lens or lenses:
+
+- **Quality:** duplicated logic, dead or unused code, unreachable paths,
+  oversized modules, abstractions that do not pay for themselves, risky missing
+  abstractions, inconsistent patterns, and drift from the standards or spec.
+- **Security:** missing authentication or authorization, client-controlled
+  ownership, injection, unsafe parsing or deserialization, sensitive-data
+  exposure, secret handling, insecure defaults, and trust-boundary mistakes.
+  Inspect existing dependency or scanner output when available, but never imply
+  that local manifest inspection is a current vulnerability scan.
+- **Performance:** N+1 queries, repeated network or database work, unnecessary
+  rendering, blocking work on hot paths, unbounded loops or collections, memory
+  growth, oversized payloads, missing pagination, and unsafe concurrency. Mark
+  hypotheses as unverified when runtime or profiling evidence is missing.
+- **Tests:** important logic without coverage when a test command exists, weak
+  assertions, tests that only mirror implementation, excessive mocking, shared
+  state, time or order dependence, skipped or focused tests, placeholder tests,
+  swallowed failures, and missing browser or integration evidence where behavior
+  crosses a real boundary. Never invent a coverage percentage.
+
+Do not nitpick harmless style differences unless they signal drift from the local
+patterns. Prefer a short list of real findings over a broad list of guesses.
+
+Do not broaden a focused pass because another category might be interesting.
+Do not report or call out non-critical concerns from omitted lenses, even as
+suggestions for a later audit. If an obvious P0 is directly encountered outside
+the selected lens, report and record it as an out-of-lens critical risk, but do
+not continue searching that other lens.
+
+If a possible secret is found, never quote its value, paste the matching source
+line, or include raw command output containing it. Report only the redacted secret
+category, file, line, risk, and remediation. Redact sensitive values from all
+audit evidence before responding.
+
+## Step 4 - update the findings ledger
+
+`devflow/context/findings.md` is the durable record of findings. Chat reports
+do not survive a context clear; the ledger does. It is the only file this skill
+writes. If it is missing (an older install), create it with a `# Findings`
+heading first.
+
+**The ledger never scopes the review.** Review the code fresh in Step 3, then
+record what the review found. Working from the open findings as a checklist and
+verifying only those is the exact failure this file exists to prevent: a repair
+can introduce a new defect that no existing entry points at.
+
+One block per finding. The header line is the machine-readable contract and must
+keep this exact shape; the prose below it is for humans and may vary:
+
+    ### F-03 [P0] open - Retained auth volumes carry the run label
+
+    **File:** ops/agent-proof/compose.yaml:86
+    **Found:** 2026-07-21 by /audit (scope: current; lens: security)
+    **Why it matters:** ...
+    **Suggested fix:** ...
+    **Resolution:**
+
+IDs are sequential within the ledger (`F-01`, `F-02`, ...), never reused and
+never renumbered while their entries live here, even after a finding closes.
+Bare IDs are scoped to the live ledger: `/complete` archives resolved entries
+under a work-item prefix (feature 12's `F-03` becomes `12/F-03`), and that
+prefixed form is the permanent reference. A later ledger that has emptied and
+reset starts at `F-01` again without colliding. Severity reuses the P0-P3
+scheme from Step 5; only P0 and P1 block `/complete`. Status is one of:
+
+| Status | Meaning | Blocks P0/P1 at /complete |
+|---|---|---|
+| `unverified` | Suspected, no confirming evidence yet | No |
+| `open` | Confirmed, not yet repaired | Yes |
+| `fixed` | Repaired, not yet re-reviewed | Yes |
+| `closed` | Repaired and re-reviewed against the new code | No |
+| `accepted` | Not fixing, by the user's explicit decision; reason recorded in Resolution | No |
+| `invalid` | Re-examination proved the finding wrong; evidence recorded in Resolution | No |
+
+After the review:
+
+- Append each new confirmed finding as `open` with the next sequential ID, one
+  past the highest ID present in the ledger (entries carried forward from
+  earlier work count; a fresh ledger starts at `F-01`).
+- Record an unverified risk worth tracking as `unverified`. It is a lead, not a
+  defect, and never gates a merge.
+- Update the entries this pass re-examined: correct the status or severity and
+  note the evidence in **Resolution**.
+- Move a `fixed` finding to `closed` only when all three hold: this pass's
+  reviewed set included the finding's file, re-examining the repaired code
+  confirmed the original defect is gone and the repair introduced no new one,
+  and the report names the finding as closed. An unrelated new finding in the
+  same file gets its own entry and does not keep the repaired one open. Never
+  close a finding implicitly.
+- Set `accepted` only on the user's explicit decision in the current session,
+  and record their reason. Never accept a finding on their behalf.
+- Set `invalid` only when re-examination shows the finding was wrong, and
+  record that evidence in **Resolution**. It is a review verdict (or the
+  user's explicit call), never a shortcut past the gate for blocked work.
+
+`fixed` blocking `/complete` is deliberate: a repair is not done when the code
+changes, it is done when a review has looked at the result. `/implement` marks
+repairs `fixed`; only a review pass moves them to `closed`.
+
+## Step 5 - report findings
+
+Lead with findings, ordered by severity, using the IDs the ledger assigned:
+
+    F-04 [P1] Title
+    File: path:line
+    Why it matters: ...
+    Suggested fix: ...
+
+Severity:
+
+- `P0` - data loss, security break, or code that cannot ship
+- `P1` - likely bug, broken contract, missing guard, or high-risk duplication
+- `P2` - maintainability issue worth fixing before the feature closes
+- `P3` - small cleanup, consistency issue, or follow-up candidate
+
+Use P0 or P1 only when a concrete code path, violated contract or security
+boundary, failing command or test, or reproducible behavior confirms the risk. If
+the evidence is incomplete, list it under `Unverified risks` with the missing
+validation instead of presenting it as a confirmed high-severity finding.
+
+If there are no findings, say that clearly for the selected lens and name any
+remaining risk or missing signal, such as "no test command declared" or
+"browser flow not audited."
+
+Then include:
+
+- ledger changes: findings added, updated, or closed this pass, by ID
+- commands run and results
+- selected scope
+- selected lens or lenses
+- base branch, merge base, and commit range for `current`, when available
+- files or directories reviewed
+- generated, third-party, or otherwise excluded paths
+- applicable standards checked
+- browser or runtime evidence inspected, when relevant
+- skipped, focused, or placeholder tests found, when the tests lens was selected
+- checks that were unavailable or could not run
+- suggested repair order
+
+For `full`, say whether coverage was complete or partial. Never label a partial
+review as a full-project audit.
+
+## Rules
+
+- The findings ledger is the only file this skill writes. Never edit, format,
+  install, commit, merge, push, or delete anything else.
+- A focused lens is not a broad audit. State what was not reviewed and never
+  imply that omitted lenses passed.
+- The ledger reports status; it never defines what the review looks at. Do not
+  turn open findings into the review checklist.
+- Never fetch, pull, or run network-backed audit tools without explicit approval.
+- Never reproduce secrets or sensitive values in findings or command output.
+- Findings first. Keep summaries short.
+- Ground every finding in a file path and line number when possible.
+- Avoid speculative rewrites. Recommend the smallest fix that removes the risk.
+- Respect existing project patterns over generic advice.
+- Do not require perfection. The goal is code that is understandable, consistent,
+  testable where it matters, and safe to keep building on.
+
+## 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.