@jakkrichm/create-nexus-devflow 2.1.0 → 2.2.0

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

@@ -1,6 +1,6 @@
 ---
 name: overview
-description: "[Devflow] Distill user-owned planning docs into `devflow/context/project-overview.md` using a deterministic compiler so the workspace context stays live and generated, not hand-authored."
+description: "[devflow][B] Distill user-owned planning docs into `devflow/context/project-overview.md` using a deterministic compiler. The overview is the living source of truth that agents read every session."
 ---
 
 # overview - dynamic project overview compiler
@@ -14,31 +14,34 @@ project-plan.md + build-plan.md + history + codebase signals
             -> /feature / fix / check / complete
 ```
 
-`/overview` turns planning and delivery context into one generated
-`devflow/context/project-overview.md` artifact.
+`/overview` updates the living context from planning documents and runtime signals.
 
 ## Input
 
-- `devflow/project-plan.md` - product vision, users, stack, constraints
-- `devflow/build-plan.md` - ordered checkbox feature queue
-- `devflow/history/HISTORY.md` - shipped capability context
-- `devflow/ideas.md` - backlog pulse
-- `package.json` (if available) - command/tooling signal
+- `devflow/project-plan.md` - Product vision, users, stack, constraints, roadmap
+- `devflow/build-plan.md` - Ordered checkbox feature queue
+- `devflow/history/HISTORY.md` - Shipped capability context
+- `devflow/ideas.md` - Current idea pressure and backlog pulse
+- `package.json` (if present) - Verified commands and language/tooling signals
 
-## Process
+If either primary plan file is missing or still placeholder-only, stop and ask for
+actual planning content first.
 
-### Step 1: Read and validate plans
+## Step 1 - read and validate planning docs
 
-1. Read `project-plan.md` and `build-plan.md`.
-2. Validate plan shape:
-   - checkbox list in `build-plan.md`
-   - feature-sized items
-   - no pre-build setup or unclear one-liners
+1. Read `devflow/project-plan.md` and `devflow/build-plan.md`.
+2. Validate shape:
+   - `build-plan.md` must be a checkbox list in tracked order (`- [ ]`, `- [x]`).
+   - plan items must be feature-sized and executable by `/feature`.
+   - unresolved feature mismatch between plan and overview is reported in the final note.
 
-If `build-plan.md` is still placeholder-only while planning is real in `project-plan.md`,
-pause for user approval before normalizing and writing.
+### Stub plan hard-stop (existing contract)
 
-### Step 2: Compile overview
+- If `build-plan.md` is still a template stub but `project-plan.md` contains real features,
+  **do not** generate a fake overview from `project-plan.md` alone.
+- Offer normalization first, then ask for approval before writing.
+
+## Step 2 - compile overview payload
 
 Run:
 
@@ -46,20 +49,32 @@ Run:
 npm run overview
 ```
 
-The script uses `devflow/reference/project-overview-template.md` and writes the output
-to `devflow/context/project-overview.md`.
+The compiler writes:
+
+- purpose + architecture summary (from `project-plan.md`)
+- ordered queue (from `build-plan.md`)
+- shipped features snapshot (from `devflow/history/HISTORY.md`)
+- idea status and backlog pulse (from `devflow/ideas.md`)
+- stack/tooling context (from project root signals)
+
+The generated output follows `devflow/reference/project-overview-template.md`.
 
-### Step 3: Report
+## Step 3 - output and report
 
-Summarize what changed and list:
+After compilation:
 
-- sections marked `TODO`
-- any plan conflicts / unresolved scope gaps
-- next recommended action (`/feature` when queue is clean)
+- report what changed in structure and which sections are now `TODO`
+- list conflicts or unresolved questions between the two plans
+- suggest `/feature` as the next action when the queue is ready
 
 ## Rules
 
-- Keep overview generation deterministic and input-sourced.
-- Do not invent scope.
-- Never rewrite user-owned plan files unless explicitly requested.
-- Re-run whenever plans or history materially change.
+- `project-overview.md` is generated, not authored manually.
+- Do not invent features, data models, or stack claims not sourced from inputs.
+- Keep user-owned plans intact unless the user explicitly approved normalization.
+- Re-run `/overview` whenever plan docs or shipped-history change materially.
+
+## Formatting
+
+- Use concise lists and tables for matrices.
+- Follow `devflow/context/ai-interaction.md` language and tone conventions.

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

@@ -1,44 +1,99 @@
 ---
 name: prototype
-description: "[Devflow] Build a throwaway prototype to answer a design question during Discover, Define, Spec, Research, or Plan."
-disable-model-invocation: true
+description: "[devflow][B] Interactively prototype the look of a project. Asks about the desired look and feel and which pages to draft, proposes a plan, and only then writes throwaway static HTML/CSS mockups to prototypes/ that share one theme (a set of CSS theme variables). A plan-first, pre-build helper that sits outside the spec-driven feature loop, like scaffolding. Use when the user runs /prototype, names screens to mock up, or asks to prototype the layout, theme, or look and feel."
 ---
 
-# Prototype
+# prototype - lock the look before you build
 
-A prototype is throwaway code that answers one question.
+Where this sits in the workflow:
 
-Use this support skill behind `Research`, `Brainstorm`, `00-explore`, `10-define`, `20-spec`, or `30-plan` when conversation alone cannot settle the uncertainty.
+    plan  ->  /overview  ->  [prototype]  ->  /feature  ->  build
+    (you      (project-      (lock the       (one spec    (real
+     write)    overview.md)   look)           at a time)   code)
 
-## Branches
+Prototyping is a pre-build step, not a feature. It's fast, visual, and throwaway.
+Its one durable output is the theme: a set of CSS theme variables that port into
+the real app's `globals.css` `@theme` when you build the first UI feature.
+Everything else here gets discarded.
 
-Choose one:
+**This skill is plan-first.** Gather the look and the page list, agree on a plan,
+and only then write any files. Never generate mockups before the user approves.
 
-- **Logic prototype**: use when the question is about state, business rules, parsing, scheduling, or algorithm behavior.
-- **UI prototype**: use when the question is about interaction, visual hierarchy, layout, or user flow.
+## Step 1 - read what the plan already says
 
-If the branch is ambiguous, state the assumption and choose the one closest to the surrounding code.
+Pull the stated look and feel and the screen/route list from
+`devflow/context/project-overview.md` (its UI/UX section); fall back to the UI/UX section
+of `devflow/project-plan.md` if the overview isn't generated yet. Use this
+as the starting point, so you're refining the user's intent, not asking from
+scratch.
 
-## Rules
+## Step 2 - ask about the look and the pages
 
-- Mark it as throwaway.
-- Keep it close to the relevant module or task workspace.
-- Provide one command to run it.
-- Avoid persistence unless the question is specifically about persistence.
-- Skip polish, broad error handling, and abstractions.
-- Show state clearly after each action or variant switch.
-- Delete, absorb, or explicitly mark the prototype after it answers the question.
+Work in plan mode. Ask the user a short set of questions (use the current tool's
+short user-input prompt for discrete choices when available), seeded with what
+the plan already says:
 
-## Durable Capture
+- **Look and feel** - confirm or adjust the vibe (light/dark, minimal/rich,
+  density, editor-like, and so on), and ask for any reference apps or sites they
+  want it to feel like.
+- **Color and type** - any accent color or font direction (for example,
+  mono-forward for code).
+- **Which pages** - which screens to draft now. Default to the key routes from the
+  plan; let the user add, drop, or reorder. Lean to a few, not every screen.
 
-The answer is the artifact worth keeping.
+Keep it short. The user's answers, plus the plan, are the brief for the mockups.
 
-Capture:
+## Step 3 - propose the plan, then wait
 
-- the question
-- prototype path and command
-- what was learned
-- decision or remaining uncertainty
-- next DevFlow route
+Present a short plan and stop for approval:
 
-Use an ADR only if the prototype resolves a hard-to-reverse, surprising trade-off.
+- the theme direction in a sentence or two (the vibe, accent, fonts), and
+- the list of screens you'll mock, one line each on what each will show (the real
+  states that exercise the theme, not empty shells).
+
+Write nothing until the user approves. Adjust the plan if they push back.
+
+## Step 4 - lock one theme
+
+Once approved, write a single shared `prototypes/theme.css` that defines the theme
+as CSS variables, following `reference/theme-variables.css`: surfaces, text,
+accent, any component-specific states, font stacks, and a small scale. Derive the
+values from the agreed brief.
+
+This file is the deliverable. Keep it the single source of the theme, so tweaking
+it restyles every mockup at once.
+
+## Step 5 - mock each screen
+
+For each approved screen, write a self-contained `prototypes/<screen>.html` that
+links `theme.css` and lays out that screen with realistic dummy content and the
+states that matter (a typing page mid-type with correct/wrong/pending chars and a
+caret; a dashboard with believable stats and history rows; and so on).
+
+- Plain HTML + CSS only. No framework, no build step. A few lines of inline JS for
+  a view toggle is fine; nothing more.
+- Pull every color, font, and spacing value from the `theme.css` variables, never
+  hard-coded. That's what keeps the look consistent and portable.
+- Realistic placeholder content over lorem ipsum. Desktop-first is enough.
+
+## Then stop
+
+Tell the user to open the files in a browser and iterate on the look. Point them
+at the concrete next step: run `/feature` on the first UI feature - it detects
+`prototypes/`, links these mockups as the spec's Design reference, and makes
+porting `theme.css` into the app's `@theme` its first build step. When the theme
+feels right the tokens carry into the real stylesheet; the HTML mockups are
+reference and get discarded at that feature's `/complete`.
+
+**Commit `prototypes/`, do not ignore it.** `theme.css` is the durable output and
+until it is ported it lives nowhere else, and the mockups are the build reference
+the next feature needs - both must survive a context clear or a switch between
+machines. So do not add `prototypes/` to `.gitignore`; it is short-lived in git
+(born here, discarded at the first UI feature's `/complete`), not throwaway that
+never lands. This skill locks the look, it does not build the app.
+
+## 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/release/SKILL.md

@@ -1,171 +1,160 @@
 ---
 name: release
-description: "Prepare a DevFlow project for deployment to Render or Vercel. Inspects project stack, package manager, commands, and environment variables; verifies local build, start, output, and health endpoints; creates or updates render.yaml or vercel.json; and enforces strict safety gates before any remote action. Use when the user runs /release, invokes $release, asks for Render setup, Vercel setup, deploy readiness, deployment config, render.yaml, or vercel.json."
-argument-hint: "[render | vercel | check | config]"
+description: "[devflow][B] Prepare a Blueprint project for deployment to Render or Vercel. Reads the plans, project commands, app config, and current repo state; verifies build, start, output, env, health checks, and provider config; can create or update render.yaml or vercel.json when requested; and stops before any external deploy, service creation, remote env change, push, publish, or destructive action unless the user explicitly approves. Use when the user runs /release, invokes $release, asks for Render setup, Vercel setup, deploy readiness, deployment config, render.yaml, or vercel.json."
 ---
 
 # release - deployment readiness for Render and Vercel
 
 Where this sits in the workflow:
 
-```text
-/complete (or 70-deliver)  ->  [release]  ->  deploy with explicit approval
-(feature / run finished)        (config,       (human confirms external action)
-                                 readiness)
-```
+    /complete  ->  [release]  ->  deploy with explicit approval
+    (feature       (config,       (human confirms
+     finished)      checks)        external action)
 
-`/release` is an optional deployment preparation step. It gets the application ready to ship, but it is **not** an auto-deploy button. It can inspect, recommend, create local config files (`render.yaml`, `vercel.json`), and run local readiness checks. It **must stop** before any external provider action unless the user gives an explicit confirmation in the current chat.
+`/release` is an optional deployment prep step. It gets the app ready to ship,
+but it is not a deploy button. It can inspect, recommend, create local config
+files, and run local checks. It must stop before any external provider action
+unless the user gives an explicit yes in the current chat.
 
-Supported initial targets:
+Initial targets:
 
-- **Render** - static sites, web services, background workers, cron jobs, databases, and `render.yaml`.
-- **Vercel** - frontend apps, full-stack framework apps, serverless functions, and `vercel.json`.
+- **Render** - static sites, web services, background workers, cron jobs, and
+  `render.yaml` when useful.
+- **Vercel** - frontend apps, full-stack framework apps, serverless functions,
+  and `vercel.json` when useful.
 
----
+## Input
 
-## Usage
+Optional scope:
 
-```text
-release
-release render
-release vercel
-release check
-release config
-```
+- no argument: inspect the project and recommend Render or Vercel if the target
+  is obvious; otherwise ask which target to prepare
+- `render`: prepare Render readiness and config
+- `vercel`: prepare Vercel readiness and config
+- `check`: read-only deployment readiness report
+- `config`: focus on creating or updating local provider config files
 
-### Scopes & Arguments
+If the user asks to deploy, connect a provider, create a remote service, set
+remote env vars, push, publish, or run provider commands that affect a remote,
+pause and ask for explicit confirmation before doing it.
 
-- **no argument**: inspect the project and recommend Render or Vercel if the target is obvious; otherwise ask which target to prepare.
-- `render`: prepare Render readiness and local configuration (`render.yaml`).
-- `vercel`: prepare Vercel readiness and local configuration (`vercel.json`).
-- `check`: read-only deployment readiness report (runs local checks without changing files).
-- `config`: focus on creating or updating local provider configuration files.
+## Step 1 - read the project
 
-> [!CAUTION]
-> **Strict Safety Gate**: If the user asks to deploy, connect a cloud provider, create a remote service, set remote env vars, push, publish, or run CLI commands that affect a remote infrastructure, pause and request explicit user confirmation before executing.
+Read:
 
----
+- `AGENTS.md`
+- `devflow/project-plan.md`
+- `devflow/build-plan.md`
+- `devflow/context/project-overview.md`
+- `devflow/context/current-feature.md`
+- package or build files such as `package.json`, lockfiles, framework config,
+  Dockerfile, `render.yaml`, `vercel.json`, `.env.example`, and README files
+- git branch and working tree status
 
-## 5-Step Deployment Readiness Protocol
+Identify:
 
-### Step 1 - Read & Inspect the Project
+- app type: static frontend, SSR app, API service, worker, CLI, monorepo, or
+  hybrid
+- build command, start command, dev command, test command, output directory, and
+  package manager
+- runtime needs: Node version, Python version, Docker, database, cache, object
+  storage, queues, background jobs, cron, migrations, or file uploads
+- env vars by name only; never print or write secret values
+- health path or smoke test path
 
-Read:
-- `AGENTS.md` and `devflow/context/project-overview.md`
-- `devflow/project-plan.md` and `devflow/build-plan.md` (if present)
-- `devflow/context/current-feature.md` or recent history
-- Package and build manifests: `package.json`, lockfiles, framework configs, Dockerfile, `render.yaml`, `vercel.json`, `.env.example`, README
-- Git working tree status
+## Step 2 - choose the provider shape
 
-Identify:
-- **App Type**: static frontend, SSR/hybrid app, API service, background worker, CLI, monorepo
-- **Commands & Output**: build command, start command, dev command, test command, output directory (`dist/`, `build/`, `.next/`, `out/`), package manager
-- **Runtime Needs**: Node version, Python version, Docker, database, cache, object storage, background jobs, cron, migrations
-- **Environment Variables**: identify required variables **by name only**; never print, request, or record secret values
-- **Health / Smoke Path**: health endpoint (e.g. `/api/health`, `/healthz`, `/`) or smoke test command
+For **Render**, decide whether the app should be:
 
----
+- static site
+- web service
+- background worker
+- cron job
+- database paired with a service
 
-### Step 2 - Choose Provider Shape
+For **Vercel**, decide whether the app should be:
 
-For **Render**, decide whether the service should be configured as:
-- **Static Site**: client-side SPAs (Vite, React, Vue) with static publish path
-- **Web Service**: Node.js/Python/Go API or SSR server running on a specified port
-- **Background Worker**: queue consumers or long-running worker processes
-- **Cron Job**: periodic scheduled jobs
-- **Database**: PostgreSQL or Redis paired with a service
+- framework deployment with auto-detected settings
+- static output deployment
+- serverless or edge function app
+- monorepo project with a root directory
 
-For **Vercel**, decide whether the app should be:
-- **Framework Deployment**: Next.js, Nuxt, SvelteKit, Astro with zero-config auto-detection
-- **Static Output**: static site export
-- **Serverless / Edge Functions**: API routes or standalone serverless functions
-- **Monorepo Project**: root directory specification
+If the provider is a poor fit, say that plainly and recommend the better target.
+Examples: long-running workers usually fit Render better; a mostly frontend
+Next.js or Astro site usually fits Vercel well.
 
-*Note*: If a provider is a poor fit for the stack, state it plainly and recommend the better target (e.g. long-running background workers fit Render better than Vercel serverless).
+## Step 3 - verify local readiness
 
----
+Run only local, non-destructive checks that match `AGENTS.md`:
 
-### Step 3 - Verify Local Readiness
+- install check only if dependencies are already present or the user approves an
+  install
+- build command
+- test command when declared
+- preview or start command if safe, then smoke test the health path
+- lint or typecheck only when listed in project commands or package scripts
 
-Run only local, non-destructive checks:
-1. **Dependency check**: verify required dependencies are installed.
-2. **Build check**: run the project build command (e.g. `npm run build`).
-3. **Test check**: run unit/integration tests when declared (e.g. `npm test`).
-4. **Smoke test**: start local server in test mode or verify health endpoints if safe.
-5. **Lint / Typecheck**: run typecheck/lint when listed in project scripts.
+If a command is missing, report the gap instead of inventing certainty. If a
+command needs secrets, list the env var names needed and skip that check.
 
-If a command fails or is missing, report the exact gap. If a check requires remote credentials, list the required environment variable names and skip that check.
+## Step 4 - prepare local config
 
----
+Only create or update local config files when the target is clear or the user
+asked for config.
 
-### Step 4 - Prepare Local Config Files
-
-Only create or update local configuration files when the target is clear or requested.
-
-#### For Render (`render.yaml`)
-Create or update `render.yaml` for repeatable infrastructure:
-```yaml
-services:
-  - type: web # or static, worker, cron
-    name: my-app
-    runtime: node # or python, docker, etc.
-    buildCommand: npm run build
-    startCommand: npm run start
-    staticPublishPath: dist # for static sites
-    healthCheckPath: /api/health
-    envVars:
-      - key: NODE_ENV
-        value: production
-      - key: DATABASE_URL
-        sync: false # prompt in Render dashboard, no secret in code
-```
-
-#### For Vercel (`vercel.json`)
-Create `vercel.json` only when default framework auto-detection is insufficient:
-```json
-{
-  "buildCommand": "npm run build",
-  "outputDirectory": "dist",
-  "framework": "vite",
-  "rewrites": [
-    { "source": "/(.*)", "destination": "/" }
-  ]
-}
-```
-
-#### For Both Providers
-- Sync `.env.example` with newly required environment variable names (with empty or dummy placeholder values).
-- Add deployment instructions to `README.md` if requested.
-- **Never write secret values into config files or git commits.**
+For **Render**, prefer `render.yaml` when the app needs repeatable setup or has
+more than one service. Include:
 
----
+- service type
+- build command
+- start command for web services
+- static publish path for static sites
+- health check path when known
+- env var names without values
+- region or plan only if the user specified it
 
-### Step 5 - Report Deployment Readiness Packet
+For **Vercel**, create `vercel.json` only when the defaults are not enough.
+Many Vercel projects need no config file. Include:
 
-Produce a clean, scannable summary:
+- build command only when it differs from defaults
+- output directory only when needed
+- rewrites or headers only when the app requires them
+- install command only when the package manager cannot be inferred
 
-```markdown
-## 🚀 Deployment Readiness Packet
+For both providers:
 
-- **Target Provider**: Render / Vercel (Rationale: ...)
-- **Service Shape**: Web Service / Static Site / Framework App / Worker
-- **Config Files Changed**: `render.yaml` / `vercel.json` / `.env.example` (or None)
-- **Local Checks Run**:
-  - Build: ✅ PASS
-  - Tests: ✅ PASS (X/X tests)
-  - Typecheck: ✅ PASS
-- **Required Env Variables**: `DATABASE_URL`, `API_KEY` (names only)
-- **Smoke Test Command / Path**: `/api/health`
-- **Blockers / Warnings**: None (or list any gaps)
-- **Next Action**: Review generated config files. When ready, deploy via Provider Dashboard or CLI.
-```
+- update `.env.example` with required names when useful
+- add a short deployment note to README only if the project already has a
+  deployment section or the user asks
+- never write secret values
 
----
+## Step 5 - report the release packet
+
+Finish with a concise packet:
+
+- **Target** - Render or Vercel, and why
+- **Shape** - static site, web service, framework app, worker, or hybrid
+- **Config changed** - files created or edited, or "none"
+- **Checks run** - commands and result
+- **Env needed** - names only
+- **Smoke test** - exact path or command to verify after deploy
+- **Blockers** - anything that must be fixed before shipping
+- **Next action** - exact command or provider step, stopping before external
+  action unless approved
+
+## Rules
+
+- Optional only. Do not add `/release` to the mandatory build loop.
+- Do not deploy, create remote services, set remote env vars, push, publish, or
+  transmit externally without explicit approval in the current chat.
+- Do not write secret values to files or chat.
+- Do not hide failing builds, missing env vars, or unknown output paths.
+- Do not add provider config if the platform defaults are better.
+- Keep the change small. Deployment setup should not become a full DevOps
+  framework.
 
-## Strict Rules & Guardrails
+## Formatting
 
-1. **Optional Step**: `/release` is an optional helper sitting outside the core development loop.
-2. **No Unprompted Remote Actions**: Never deploy, create remote cloud services, modify remote environment variables, push, or publish without explicit confirmation in the current chat.
-3. **Zero Secret Leaks**: Never print, log, or commit passwords, tokens, API keys, or private certificates.
-4. **Lean Configurations**: Do not add unnecessary configuration files if platform zero-config defaults suffice.
-5. **No Hallucinations**: Do not mask failing local builds or unknown output directories; report failures accurately.
+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/report-html/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: report-html
-description: "[Devflow] Standalone HTML Report Generator - render an interactive standalone HTML dashboard from current-feature.md or 60-report.md on demand."
+description: "[devflow][B] Standalone HTML Report Generator - render an interactive standalone HTML dashboard from current-feature.md or 60-report.md on demand."
 argument-hint: "{running-id or workspace path}"
 ---
 
@@ -42,4 +42,4 @@ Or execute the renderer to transform Markdown into a styled, standalone HTML doc
 Provide:
 - Generated HTML file path: `file:///devflow/runs/{RUNNING_ID}/report.html`
 - Summary of sections rendered (Spec, Plan, Progress, QA Evidence, Release Notes)
-- Instructions to open the file in any browser
+- Instructions to open the file in any browser