@jakkrichm/create-nexus-devflow 2.0.25 → 2.1.0

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

@@ -1,114 +1,80 @@
 ---
 name: overview
-description: "[Devflow] Scan codebase architecture, data models, and shipped history to synthesize or refresh devflow/context/project-overview.md as the living source of truth."
+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 - Living Context Synthesis & Sync
+# overview - dynamic project overview compiler
 
-Where this sits in the workflow:
+## Position in workflow
 
 ```text
-codebase + devflow/history/HISTORY.md  ->  [overview]  ->  devflow/context/project-overview.md  ->  00-discover / 10-define / 20-spec
-(reality & shipped runs)                    (sync &         (living source of truth)             (informed planning)
-                                             synthesize)
+project-plan.md + build-plan.md + history + codebase signals
+            -> scripts/overview.ts
+            -> devflow/context/project-overview.md
+            -> /feature / fix / check / complete
 ```
 
-`overview` is the context synchronization and synthesis engine for Nexus-DevFlow. It inspects the actual codebase (manifest, dependencies, directory layout, models/schemas, entry points) along with the completed delivery history (`devflow/history/HISTORY.md` and `devflow/history/`) to build or refresh `devflow/context/project-overview.md`.
+`/overview` updates the living context from planning documents and runtime signals.
 
-It ensures that `project-overview.md` remains a **Living Source of Truth** that evolves alongside your software, rather than a stale artifact left behind after onboarding.
+## Input
 
-## Usage
+- `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
 
-```text
-/overview
-$overview
-overview
-```
-
-Use this when:
-- Multiple delivery runs (`xxx-slug`) have shipped and `project-overview.md` needs to reflect newly added capabilities.
-- New database schemas, ORM models, or API boundaries were introduced.
-- Major dependencies or architectural patterns were added or modified.
-- After completing `70-release` to keep project context perfectly aligned.
-- Preparing for a new initiative or discovery pass.
-
----
-
-## Process
-
-### Step 1 - Scan Reality (Codebase Survey)
-
-Inspect the actual codebase to establish hard facts:
-
-1. **Manifest & Tooling**:
-   - Read `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, or `Gemfile`.
-   - Identify language versions, primary framework, state management, and build tools.
-2. **Directory Architecture**:
-   - Map high-level directory layout (`src/`, `app/`, `api/`, `lib/`, `components/`, etc.).
-   - Identify major modules, entry points, and routing conventions.
-3. **Concrete Data Models & Schemas**:
-   - Search for ORM schemas (`schema.prisma`, Drizzle schemas, TypeORM entities, SQLAlchemy models, Zod schemas, or core TypeScript types).
-   - Extract entity names, core fields, relationships, and invariants.
-4. **Verified Commands**:
-   - Inspect package scripts (`dev`, `build`, `test`, `lint`, `check`, `verify`).
-
----
-
-### Step 2 - Scan History (Delivered Capabilities)
-
-Inspect DevFlow history records:
-
-1. Read `devflow/history/HISTORY.md` for completed and released milestones.
-2. Scan completed delivery runs in `devflow/history/features/`, `devflow/history/fixes/`, and `devflow/history/rollbacks/` to extract shipped user-visible capabilities and core system features.
-
----
+If either primary plan file is missing or still placeholder-only, stop and ask for
+actual planning content first.
 
-### Step 3 - Synthesize `project-overview.md`
+## Step 1 - read and validate planning docs
 
-Write or update `devflow/context/project-overview.md` following standard structure:
+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.
 
-```markdown
-# Project Overview & Source of Truth
+### Stub plan hard-stop (existing contract)
 
-> Living context artifact automatically synchronized with codebase reality and DevFlow delivery history.
+- 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.
 
-## 1. Project Purpose & Target Users
-- High-level summary of what the system does, who it serves, and the core problem it solves.
+## Step 2 - compile overview payload
 
-## 2. Architecture & Directory Layout
-- Visual directory layout tree with short descriptions for major modules and boundaries.
+Run:
 
-## 3. Technology Stack & Key Tooling
-- Frontend, Backend, Database, ORM, Testing frameworks, CI/CD, and Package Manager.
+```bash
+npm run overview
+```
 
-## 4. Concrete Data Models & Entities
-- Field-level definitions of major entities, types, and relationships.
+The compiler writes:
 
-## 5. Shipped Capabilities & Key Modules
-- Consolidated list of active features and subsystems verified in the codebase.
+- 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)
 
-## 6. Verified Commands & Developer Workflow
-- Exact commands for Dev, Build, Test, Lint, and Verify.
+The generated output follows `devflow/reference/project-overview-template.md`.
 
-## 7. Known Architectural Focus Areas
-- Known technical debt, active migrations, or upcoming architectural focus points.
-```
+## Step 3 - output and report
 
----
+After compilation:
 
-### Step 4 - Review & Report
+- 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
 
-Present a concise summary of the sync:
-- Models or entities detected and added
-- Shipped capabilities refreshed from history
-- Stack and tooling updates
-- Any inconsistencies or gaps found between code and documentation
+## Rules
 
----
+- `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.
 
-## Rules & Guardrails
+## Formatting
 
-1. **Grounded in Reality**: Never invent non-existent packages, fictional data models, or unverified endpoints. Everything in `project-overview.md` must be traceable to real code or recorded history.
-2. **Preserve User Intent**: Do not erase custom business rules or user-written notes. Integrate new facts smoothly around existing intent.
-3. **Concrete Over Vague**: Provide actual model names, field types, and route paths rather than vague one-line summaries.
-4. **Non-Destructive**: `overview` only writes to `devflow/context/project-overview.md`. It never modifies source code, runs migrations, or touches git history.
+- Use concise lists and tables for matrices.
+- Follow `devflow/context/ai-interaction.md` language and tone conventions.

package/template/.agents/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-discover`, `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/.agents/skills/release/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: release
+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:
+
+    /complete  ->  [release]  ->  deploy with explicit approval
+    (feature       (config,       (human confirms
+     finished)      checks)        external action)
+
+`/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.
+
+Initial targets:
+
+- **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
+
+Optional scope:
+
+- 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
+
+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.
+
+## Step 1 - read the project
+
+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
+
+Identify:
+
+- 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
+
+## Step 2 - choose the provider shape
+
+For **Render**, decide whether the app should be:
+
+- static site
+- web service
+- background worker
+- cron job
+- database paired with a service
+
+For **Vercel**, decide whether the app should be:
+
+- framework deployment with auto-detected settings
+- static output deployment
+- serverless or edge function app
+- monorepo project with a root directory
+
+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.
+
+## Step 3 - verify local readiness
+
+Run only local, non-destructive checks that match `AGENTS.md`:
+
+- 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
+
+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.
+
+## Step 4 - prepare local config
+
+Only create or update local config files when the target is clear or the user
+asked for config.
+
+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
+
+For **Vercel**, create `vercel.json` only when the defaults are not enough.
+Many Vercel projects need no config file. Include:
+
+- 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
+
+For both providers:
+
+- 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.
+
+## 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/.agents/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