@jakkrichm/create-nexus-devflow 2.0.25 → 2.1.0

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

@@ -0,0 +1,166 @@
+---
+name: discovery
+description: "[devflow][B] Optional deep, multi-turn project discovery that helps the user develop detailed Blueprint project-plan.md and build-plan.md files through an adaptive conversation, then drafts them only after the user says they are ready. Use when the user explicitly runs /discovery or $discovery, asks for a guided planning interview, wants to think through a new product before writing the plans, or wants help deepening existing plans. Do not use merely because planning files are empty, after /onboard, or before /overview; users may always write the plans directly or create them through any conversation they prefer."
+---
+
+# discovery - develop the plans through a deep conversation
+
+Where this can sit in the workflow:
+
+    /onboard  ->  write the plans directly  ->  /overview
+              \
+               ->  [discovery]  ->  review and approve plan drafts  ->  /overview
+
+`/discovery` is an optional planning partner, not a required workflow gate and
+not a quick questionnaire. It can span as many turns as the project needs. Its
+job is to help the user think through the product, preserve the depth and nuance
+of that conversation, and draft the two user-owned planning files only when the
+user asks for drafts.
+
+Running `/onboard` never starts this skill. Empty plans never require it. A user
+who writes detailed plans manually, has another AI conversation, or arrives with
+finished plans continues directly to `/overview` exactly as before.
+
+## Step 1 - establish the starting point
+
+Read only the planning and project facts needed for the conversation:
+
+- `devflow/project-plan.md`
+- `devflow/build-plan.md`
+- the root project manifest, README, and framework configuration when they
+  already contain relevant facts
+- `devflow/context/project-overview.md` only when the user is revisiting an
+  established project's direction
+
+Classify each planning file as a template, partial draft, or substantive plan.
+Never treat existing user content as disposable. When either plan has real
+content, summarize what it already establishes and ask whether the user wants to
+deepen it, revise a specific direction, or use it unchanged as conversation
+context. Do not replace it with a fresh generic plan.
+
+Start with a short working hypothesis about the project and name the most
+important unknown. Then ask one focused question. Do not draft either plan yet.
+
+## Step 2 - run adaptive discovery
+
+Ask one meaningful question at a time and let each answer shape the next one.
+Prefer a likely interpretation the user can correct over a vague request for
+more detail. Explain a tradeoff when the answer would materially change scope,
+architecture, cost, or build order.
+
+Cover the areas that matter to this project, not a fixed questionnaire:
+
+- problem, desired outcome, and why the project should exist
+- target users, their context, and their primary workflows
+- MVP capabilities, explicit non-goals, and later possibilities
+- business rules, data, integrations, permissions, and important edge cases
+- stack choices, constraints, dependencies, and technical unknowns
+- UI/UX direction, accessibility needs, and useful references
+- monetization or business model when relevant
+- deployment shape, environments, background work, storage, and operations
+- risks, assumptions, unresolved decisions, and how success will be judged
+- feature boundaries, dependencies, and a sensible build order
+
+Depth is the goal. Follow a consequential answer until its implications are
+clear instead of racing to the next category. Do not ask the user to repeat facts
+already established in the conversation or repository. Do not force irrelevant
+topics merely to complete a checklist.
+
+Periodically return a compact discovery snapshot with:
+
+- confirmed decisions
+- working assumptions that still need confirmation
+- open questions or conflicts
+- ideas explicitly deferred or excluded
+
+The snapshot keeps a long conversation coherent. It is not permission to write
+the plans.
+
+## Step 3 - decide whether the plans are ready
+
+Do not end discovery because a preset number of questions has been reached. It
+is ready to draft when:
+
+- the problem, users, and core workflows are concrete
+- MVP scope and non-goals are distinguishable
+- data and technical choices are detailed enough to expose major dependencies
+- the build order can be expressed as feature-sized outcomes
+- important contradictions are resolved
+- remaining unknowns are either safe to defer or explicitly accepted as TODOs
+- the user says they are ready for the plans to be drafted
+
+If the user asks for drafts while a material gap remains, name the gap and ask
+whether to continue discovery or preserve it as an explicit TODO. Respect the
+choice. The user may also stop at any time and write the plans manually.
+
+## Step 4 - draft both planning files
+
+When the user asks for drafts, produce complete proposed contents for both files
+without writing them yet.
+
+For `devflow/project-plan.md`:
+
+- keep the template's main subject areas, adding useful sections when the
+  conversation requires them
+- preserve rationale, examples, tradeoffs, constraints, edge cases, and
+  exclusions that will matter during later feature work
+- be as detailed as the project needs; never compress a rich discovery into a
+  line or two per section
+- distinguish confirmed decisions from assumptions and TODOs
+
+For `devflow/build-plan.md`:
+
+- use numbered checkboxes and optional milestone headings
+- keep each item a high-level, feature-sized outcome with a concise description
+- order items by dependency and the earliest useful vertical slice
+- keep implementation detail in later `/feature` specs rather than turning the
+  roadmap into a task dump
+- include only agreed scope; place deferred ideas outside the MVP or omit them as
+  the user directed
+
+If substantive plans already exist, preserve their information and completed
+build-plan numbering. Clearly identify proposed additions, removals, or changed
+decisions.
+
+End by asking the user to review the full drafts. Do not write either file in the
+same response that first presents them.
+
+## Step 5 - write only after approval
+
+Write the approved drafts only after the user explicitly approves them. If the
+user requests changes, revise the drafts and show the affected sections again
+before writing.
+
+After writing:
+
+- report which files changed
+- list any retained TODOs or unresolved decisions
+- remind the user that both files remain theirs to edit and deepen directly
+- stop before generating `devflow/context/project-overview.md`
+- point to `/overview` or `$overview` as the next optional command when the user
+  is satisfied with the plans
+
+## Rules
+
+- This skill is always optional. Never make it a prerequisite for `/overview`,
+  `/feature`, or any other Blueprint command.
+- Never start it automatically from `/onboard`, because planning files are
+  empty, or because a project is new.
+- Never imply that plans created manually or through another conversation are
+  inferior or incomplete merely because this skill was not used.
+- Never overwrite substantive planning content without showing the replacement
+  and receiving explicit approval.
+- Never write plans during the interview or after a vague signal such as "looks
+  good." The user must explicitly approve the proposed file contents.
+- Never scaffold the app, edit product code, generate the overview, create a
+  feature spec, commit, merge, push, or deploy.
+- Preserve detailed project reasoning in `project-plan.md`, while keeping
+  `build-plan.md` high-level and trackable.
+- Keep the conversation adaptive. Depth comes from relevant follow-up questions,
+  not from mechanically asking every possible question.
+
+## Formatting
+
+Follow `devflow/context/ai-interaction.md`. During discovery, ask one focused
+question per turn. For snapshots and draft reviews, use concise headings and
+lists so confirmed decisions and remaining gaps are easy to inspect.

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

@@ -1,84 +1,200 @@
 ---
 name: doctor
-description: "[Devflow] Read-only DevFlow health check and diagnostics for context files, adapters, commands, and workflow drift."
+description: "[devflow][B] Run a read-only Blueprint health check for setup, onboarding, required files, tool adapters, commands, optional verification and CI, Blueprint visibility, ignore rules, planning readiness, overview freshness, and workflow drift. Use when the user runs /doctor, asks whether the Blueprint is installed correctly, wants a health check, setup check, doctor pass, or says something feels off before starting or resuming work."
 ---
 
-# doctor - Read-Only DevFlow Health Check & Diagnostics
+# doctor - Blueprint health check
 
 Where this sits in the workflow:
 
-```text
-Any time during development -> [doctor] -> Health Report & Actionable Fixes
-(read-only inspection)          (diagnostics)    (remediation recommendations)
-```
+    any time  ->  [doctor]  ->  reads setup + plans + workflow state + git
+                  (read-only)   prints health, warnings, and repair order
 
-`doctor` is a safe, read-only diagnostic skill that verifies whether your repository's Nexus-DevFlow configuration, context files, tool adapters, commands, and active runs are healthy and aligned.
+This skill answers one question: *is this Blueprint project ready to use?* It is
+the diagnostic pass for setup drift, incomplete onboarding, missing files,
+placeholder plans, stale generated context, Blueprint visibility, and confusing
+workflow state. It never changes anything: no edits, no commits, no installs, no
+builds, no branch changes.
 
----
+Use `/status` when the user mainly wants progress and the next build action. Use
+`/doctor` when the user wants to know whether the workflow itself is healthy.
 
 ## Input
 
-No argument is required.
-
----
-
-## Diagnostics Checklist
-
-Run through these 5 health checks:
-
-### Check 1: Core Framework & Context Files Integrity
-- Check if [AGENTS.md](AGENTS.md) and [CLAUDE.md](CLAUDE.md) exist and are populated.
-- Check required context files under `devflow/context/`:
-  - `project-overview.md` (Check if still empty/placeholder -> recommend `onboard` or `adopt`)
-  - `coding-standards.md` (Check if customized for stack)
-  - `ai-interaction.md` (Check if rules are configured)
-  - `current-stage.md` (Check if active run matches filesystem)
-  - `findings.md` (Check if ledger exists)
-
-### Check 2: Tool Adapters Parity
-- Check if `.agents/skills/` exists and contains core lifecycle skills (`00-discover` through `70-release`, `devflow`, `onboard`, `adopt`, `doctor`).
-- Check if `.claude/skills/` is in sync with `.agents/skills/`.
-
-### Check 3: Commands & Script Verification
-- Inspect the Commands section in `AGENTS.md`.
-- Cross-reference with project manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, etc.):
-  - Does the `Dev` command exist in scripts?
-  - Does the `Build` command exist in scripts?
-  - Does the `Test` command exist in scripts?
-  - Does the `Verify` command exist in scripts?
-
-### Check 4: Active Runs & Workflow Drift Detection
-- Inspect `devflow/runs/`:
-  - Are there active runs?
-  - Is `current-stage.md` consistent with the latest stage artifact in the active run?
-  - Are checklists (`checklists/implementation-checklist.md`, `checklists/verification-checklist.md`) properly tracked?
-  - Detect stage skips or workflow drift (e.g. jumping from `10-define` directly to `40-execute` without `20-spec` and `30-plan`).
-
-### Check 5: Findings Ledger Inspection
-- Inspect `devflow/context/findings.md`:
-  - Are there open P0 or P1 findings that block release?
-  - Are resolved findings properly closed?
-
----
-
-## Output Format
-
-Present a clean, scannable diagnostic report:
-
-```markdown
-# 🩺 Nexus-DevFlow Health Report
-
-## Overall Status: [HEALTHY | WARNING | ACTION REQUIRED]
-
-| Component | Status | Details |
-| :--- | :--- | :--- |
-| **Context Files** | [PASS / WARN] | project-overview.md, coding-standards.md status |
-| **Tool Adapters** | [PASS / WARN] | .agents and .claude parity |
-| **Configured Commands**| [PASS / WARN] | dev, build, test, verify alignment |
-| **Active Runs & Drift**| [PASS / WARN] | active run status, stage progression |
-| **Findings Ledger** | [PASS / WARN] | open P0/P1 issues count |
-
-### Recommended Remediation Actions:
-1. [Action item if any warning or failure detected]
-2. [Suggested next command, e.g. devflow, onboard, adopt, etc.]
-```
+None. `/doctor` takes no argument.
+
+## What it checks
+
+Gather these, then summarize. Do not dump file contents.
+
+1. **Required Blueprint files**
+   - Confirm `AGENTS.md`, `blueprint/`, `devflow/project-plan.md`,
+     `devflow/build-plan.md`, and `devflow/context/` exist.
+   - Confirm `devflow/context/coding-standards.md`,
+     `devflow/context/ai-interaction.md`,
+     `devflow/context/current-feature.md`, and
+     `devflow/context/project-overview.md` exist.
+   - Confirm `devflow/history/features/` and `devflow/history/fixes/` exist.
+     When the rollback skill is installed, also check
+     `devflow/history/rollbacks/`. A missing rollback folder on a legacy
+     installation is a warning, not a blocker; `/complete` creates it on the
+     first rollback.
+   - Check `devflow/context/findings.md`. Missing on a legacy installation is
+     a warning, not a blocker; `/audit` and `/complete` create it on first use.
+     When present, confirm its entry headers still match
+     `### <id> [<severity>] <status> - <title>` and warn on a malformed ledger.
+     Report any P0 or P1 finding still `open` or `fixed` by ID, since it will
+     block `/complete`. Never block on the ledger yourself.
+   - If `.gitignore` marks Blueprint workflow files as local-only, still require
+     the files to exist on disk. Ignored but present is healthy; ignored and
+     missing means the local workflow needs to be restored.
+2. **Tool adapters**
+   - Confirm at least one adapter exists: `.agents/skills/` for Codex or
+     `.claude/skills/` for Claude Code.
+   - If both adapters are present, say that is healthy when both tools are used.
+   - If both adapters are present, compare their skill folder names. Warn about
+     missing skills on either side.
+   - If git shows changes under `.agents/skills/` or `.claude/skills/`, check
+     the matching adapter file too. Warn when workflow behavior was updated in
+     one adapter but not the other.
+   - If only one tool is used, mention the unused adapter can be deleted. Do not
+     treat extra adapters as an error.
+   - If `CLAUDE.md` exists and still starts with `# Project Name`, flag that
+     `/onboard` probably has not finished.
+3. **Commands and project setup**
+   - Check whether root `README.md` is still the copied Blueprint workflow doc
+     by looking for `# AI Coding Blueprint` or opening text that describes the
+     Blueprint workflow instead of the app. If so, warn that `/onboard` should
+     replace it with a project README before publishing.
+   - If `devflow/README.md` clearly contains copied Blueprint workflow docs,
+     report it as an obsolete installer artifact. Its absence is healthy. An
+     unchanged managed copy can be removed by the updater; a modified copy needs
+     user review.
+   - Check whether `AGENTS.md` has a `## Commands` section with dev and build
+     commands.
+   - Report missing lint or test commands as informational unless the project has
+     real lint or test scripts elsewhere that are not reflected in `AGENTS.md`.
+   - If `package.json` exists, compare its scripts against `AGENTS.md` at a high
+     level. Do not require every script to be documented.
+   - If `AGENTS.md` declares a `Verify` command, confirm it resolves to real
+     project commands in the expected order: typecheck, tests when configured,
+     then build. Do not require checks the project does not have.
+   - If `.github/workflows/verify.yml` exists, confirm it runs the exact documented
+     `Verify` command for pull requests and pushes to the default branch, uses the
+     detected runtime and package manager, and starts with read-only contents
+     permission. Preserve other workflows and report overlap for review.
+   - A missing `Verify` command or GitHub workflow is informational. It means the
+     optional automatic-check setup was not selected, not that the Blueprint is
+     unhealthy.
+4. **Ignore rules**
+   - Check obvious ignore patterns for the detected stack. For Node or Astro,
+     look for `node_modules`, `.env`, `dist`, and framework cache folders such as
+     `.astro` or `.next` when relevant.
+   - Detect local-only Blueprint mode if `.gitignore` ignores `.agents/`,
+     `.claude/`, `blueprint/`, or `CLAUDE.md`. Report it as a visibility choice,
+     not a failure, when the local files exist.
+   - In local-only mode, check whether tracked `AGENTS.md` still describes the
+     Blueprint workflow, lists hidden adapter paths, or exposes the core skill
+     list. If so, warn that `/onboard` should make `AGENTS.md` public-safe.
+   - If local-only mode is active but those paths are already tracked by git,
+     warn that `.gitignore` does not hide tracked files and the user must approve
+     any `git rm --cached` cleanup separately.
+   - Keep this conservative. If uncertain, report "review" instead of failure.
+5. **Planning readiness**
+   - Check whether `devflow/project-plan.md` and `devflow/build-plan.md` look
+     filled in or still template-like. Treat obvious TODO, TBD, example-only text,
+     or empty required sections as not ready.
+   - Check whether `devflow/build-plan.md` is a numbered checkbox list. Raw
+     bullets are allowed as a first draft, but they should be normalized by
+     `/overview` before the build loop starts.
+   - Count checked and unchecked leaf items in `devflow/build-plan.md`.
+6. **Overview freshness**
+   - Check whether `devflow/context/project-overview.md` exists and looks
+     generated from the current plans.
+   - If either planning file appears newer than the overview by filesystem time,
+     call the overview possibly stale and suggest `/overview` before feature work.
+7. **Current workflow state**
+   - Check whether `devflow/context/current-feature.md` is the reset stub or an
+     active feature, fix, or rollback spec.
+   - If a spec is active, report checked and unchecked implementation steps.
+   - If `current-feature.md` is the reset stub but git has source or workflow
+     changes, warn that work is happening without an active spec.
+   - Flag active spec on `main`, all spec steps checked but no completion, or a
+     branch that does not match `feature/`, `fix/`, or `rollback/` for the spec
+     type. For a feature, also flag a mismatch with the next unchecked
+     build-plan item. For a rollback, confirm its target is a checked item and do
+     not compare it to the next unchecked item.
+8. **Git**
+   - Report current branch, clean vs dirty working tree, rough changed-file count,
+     last commit subject, and whether the branch is ahead of upstream.
+   - If the directory is not a git repo, report that as a setup issue and keep
+     going.
+
+## Output
+
+Print a compact health report with these labels:
+
+    Health: Pass | Needs attention | Blocked
+    Setup: ...
+    Verification: ...
+    Adapters: ...
+    Visibility: ...
+    Plans: ...
+    Workflow: ...
+    Git: ...
+    Watch: ...
+    Repair order: ...
+
+Use `Watch:` only when there are warnings. Use `Repair order:` for the exact next
+steps, in order. Keep it short and practical.
+
+Choose the repair order in this priority:
+
+- Required Blueprint files missing -> overlay the Blueprint again, or use
+  `/adopt` for a brownfield app.
+- No git repo -> initialize git before using the build loop.
+- No tool adapter -> restore `.agents/skills/` or `.claude/skills/` for the tool
+  being used.
+- Onboarding incomplete -> run `/onboard`.
+- Root README is still the Blueprint workflow doc -> run `/onboard` to replace
+  it with a project README before publishing.
+- Local-only visibility selected but ignored Blueprint files are missing ->
+  reinstall or restore the Blueprint files locally.
+- Local-only visibility selected but Blueprint paths are tracked -> ask whether
+  to untrack them with `git rm --cached` while keeping local files.
+- Local-only visibility selected but `AGENTS.md` still exposes the workflow ->
+  run `/onboard` to make `AGENTS.md` a lightweight public project guide.
+- A documented `Verify` command, project script, and GitHub workflow disagree ->
+  run `/ci` to review and align them. Missing optional CI alone does not need
+  repair.
+- Commands or ignore rules need review -> update the files or run `/onboard` if
+  this is an early project.
+- Plans are placeholders -> fill `devflow/project-plan.md` and
+  `devflow/build-plan.md`.
+- Overview missing or stale -> run `/overview`.
+- Active spec has unchecked steps -> run `/status` or `/implement`, depending on
+  whether the user wants orientation or action.
+- A P0 or P1 finding is `open` -> repair it through `/implement` while a spec
+  is active, or `/fix <finding id>` between work items. One that is `fixed` ->
+  `/audit` to re-review and close it. Both come before suggesting `/complete`.
+- Active spec is done but not closed -> run `/check`, then `/complete`.
+- Everything is healthy -> say so, then suggest `/status` for progress or
+  `/feature` for the next planned feature.
+
+## Rules
+
+- **Read-only, always.** This skill never writes files, never commits, never runs
+  installs, never runs builds or tests, and never switches branches.
+- **Diagnose, then order repairs.** Do not just list problems. End with the
+  smallest ordered sequence that gets the project back to a healthy state.
+- **Do not over-police adapters.** Extra adapters are optional clutter, not a
+  failure.
+- **Be conservative with stack-specific checks.** If a command or ignore pattern
+  is uncertain, mark it for review instead of inventing a hard failure.
+- **Stay concise.** A doctor pass should feel like a checklist, not an audit.
+
+## 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.