npm - @jakkrichm/create-nexus-devflow - Versions diffs - 2.0.0 - Mend

@jakkrichm/create-nexus-devflow 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (431) hide show

package/template/.claude/skills/frontend-ui-engineering/accessibility-checklist.md ADDED Viewed

@@ -0,0 +1,159 @@
+# Accessibility Checklist
+Quick reference for WCAG 2.1 AA compliance. Use alongside the `frontend-ui-engineering` skill.
+## Table of Contents
+- [Essential Checks](#essential-checks)
+- [Common HTML Patterns](#common-html-patterns)
+- [Testing Tools](#testing-tools)
+- [Quick Reference: ARIA Live Regions](#quick-reference-aria-live-regions)
+- [Common Anti-Patterns](#common-anti-patterns)
+## Essential Checks
+### Keyboard Navigation
+- [ ] All interactive elements focusable via Tab key
+- [ ] Focus order follows visual/logical order
+- [ ] Focus is visible (outline/ring on focused elements)
+- [ ] Custom widgets have keyboard support (Enter to activate, Escape to close)
+- [ ] No keyboard traps (user can always Tab away from a component)
+- [ ] Skip-to-content link at top of page
+- [ ] Modals trap focus while open, return focus on close
+### Screen Readers
+- [ ] All images have `alt` text (or `alt=""` for decorative images)
+- [ ] All form inputs have associated labels (`<label>` or `aria-label`)
+- [ ] Buttons and links have descriptive text (not "Click here")
+- [ ] Icon-only buttons have `aria-label`
+- [ ] Page has one `<h1>` and headings don't skip levels
+- [ ] Dynamic content changes announced (`aria-live` regions)
+- [ ] Tables have `<th>` headers with scope
+### Visual
+- [ ] Text contrast ≥ 4.5:1 (normal text) or ≥ 3:1 (large text, 18px+)
+- [ ] UI components contrast ≥ 3:1 against background
+- [ ] Color is not the only way to convey information
+- [ ] Text resizable to 200% without breaking layout
+- [ ] No content that flashes more than 3 times per second
+### Forms
+- [ ] Every input has a visible label
+- [ ] Required fields indicated (not by color alone)
+- [ ] Error messages specific and associated with the field
+- [ ] Error state visible by more than color (icon, text, border)
+- [ ] Form submission errors summarized and focusable
+### Content
+- [ ] Language declared (`<html lang="en">`)
+- [ ] Page has a descriptive `<title>`
+- [ ] Links distinguish from surrounding text (not by color alone)
+- [ ] Touch targets ≥ 44x44px on mobile
+- [ ] Meaningful empty states (not blank screens)
+## Common HTML Patterns
+### Buttons vs. Links
+```html
+<!-- Use <button> for actions -->
+<button onClick={handleDelete}>Delete Task</button>
+<!-- Use <a> for navigation -->
+<a href="/tasks/123">View Task</a>
+<!-- NEVER use div/span as buttons -->
+<div onClick={handleDelete}>Delete</div>  <!-- BAD -->
+```
+### Form Labels
+```html
+<!-- Explicit label association -->
+<label htmlFor="email">Email address</label>
+<input id="email" type="email" required />
+<!-- Implicit wrapping -->
+<label>
+  Email address
+  <input type="email" required />
+</label>
+<!-- Hidden label (visible label preferred) -->
+<input type="search" aria-label="Search tasks" />
+```
+### ARIA Roles
+```html
+<!-- Navigation -->
+<nav aria-label="Main navigation">...</nav>
+<nav aria-label="Footer links">...</nav>
+<!-- Status messages -->
+<div role="status" aria-live="polite">Task saved</div>
+<!-- Alert messages -->
+<div role="alert">Error: Title is required</div>
+<!-- Modal dialogs -->
+<dialog aria-modal="true" aria-labelledby="dialog-title">
+  <h2 id="dialog-title">Confirm Delete</h2>
+  ...
+</dialog>
+<!-- Loading states -->
+<div aria-busy="true" aria-label="Loading tasks">
+  <Spinner />
+</div>
+```
+### Accessible Lists
+```html
+<ul role="list" aria-label="Tasks">
+  <li>
+    <input type="checkbox" id="task-1" aria-label="Complete: Buy groceries" />
+    <label htmlFor="task-1">Buy groceries</label>
+  </li>
+</ul>
+```
+## Testing Tools
+```bash
+# Automated audit
+npx axe-core          # Programmatic accessibility testing
+npx pa11y             # CLI accessibility checker
+# In browser
+# Chrome DevTools → Lighthouse → Accessibility
+# Chrome DevTools → Elements → Accessibility tree
+# Screen reader testing
+# macOS: VoiceOver (Cmd + F5)
+# Windows: NVDA (free) or JAWS
+# Linux: Orca
+```
+## Quick Reference: ARIA Live Regions
+| Value | Behavior | Use For |
+|-------|----------|---------|
+| `aria-live="polite"` | Announced at next pause | Status updates, saved confirmations |
+| `aria-live="assertive"` | Announced immediately | Errors, time-sensitive alerts |
+| `role="status"` | Same as `polite` | Status messages |
+| `role="alert"` | Same as `assertive` | Error messages |
+## Common Anti-Patterns
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| `div` as button | Not focusable, no keyboard support | Use `<button>` |
+| Missing `alt` text | Images invisible to screen readers | Add descriptive `alt` |
+| Color-only states | Invisible to color-blind users | Add icons, text, or patterns |
+| Autoplaying media | Disorienting, can't be stopped | Add controls, don't autoplay |
+| Custom dropdown with no ARIA | Unusable by keyboard/screen reader | Use native `<select>` or proper ARIA listbox |
+| Removing focus outlines | Users can't see where they are | Style outlines, don't remove them |
+| Empty links/buttons | "Link" announced with no description | Add text or `aria-label` |
+| `tabindex > 0` | Breaks natural tab order | Use `tabindex="0"` or `-1` only |

package/template/.claude/skills/git-workflow-and-versioning/SKILL.md ADDED Viewed

@@ -0,0 +1,300 @@
+---
+name: git-workflow-and-versioning
+description: Structures git workflow practices. Use when making any code change. Use when committing, branching, resolving conflicts, or when you need to organize work across multiple parallel streams.
+---
+# Git Workflow and Versioning
+## Overview
+Git is your safety net. Treat commits as save points, branches as sandboxes, and history as documentation. With AI agents generating code at high speed, disciplined version control is the mechanism that keeps changes manageable, reviewable, and reversible.
+## When to Use
+Always. Every code change flows through git.
+## Core Principles
+### Trunk-Based Development (Recommended)
+Keep `main` always deployable. Work in short-lived feature branches that merge back within 1-3 days. Long-lived development branches are hidden costs — they diverge, create merge conflicts, and delay integration. DORA research consistently shows trunk-based development correlates with high-performing engineering teams.
+```
+main ──●──●──●──●──●──●──●──●──●──  (always deployable)
+        ╲      ╱  ╲    ╱
+         ●──●─╱    ●──╱    ← short-lived feature branches (1-3 days)
+```
+This is the recommended default. Teams using gitflow or long-lived branches can adapt the principles (atomic commits, small changes, descriptive messages) to their branching model — the commit discipline matters more than the specific branching strategy.
+- **Dev branches are costs.** Every day a branch lives, it accumulates merge risk.
+- **Release branches are acceptable.** When you need to stabilize a release while main moves forward.
+- **Feature flags > long branches.** Prefer deploying incomplete work behind flags rather than keeping it on a branch for weeks.
+### 1. Commit Early, Commit Often
+Each successful increment gets its own commit. Don't accumulate large uncommitted changes.
+```
+Work pattern:
+  Implement slice → Test → Verify → Commit → Next slice
+Not this:
+  Implement everything → Hope it works → Giant commit
+```
+Commits are save points. If the next change breaks something, you can revert to the last known-good state instantly.
+### 2. Atomic Commits
+Each commit does one logical thing:
+```
+# Good: Each commit is self-contained
+git log --oneline
+a1b2c3d Add task creation endpoint with validation
+d4e5f6g Add task creation form component
+h7i8j9k Connect form to API and add loading state
+m1n2o3p Add task creation tests (unit + integration)
+# Bad: Everything mixed together
+git log --oneline
+x1y2z3a Add task feature, fix sidebar, update deps, refactor utils
+```
+### 3. Descriptive Messages
+Commit messages explain the *why*, not just the *what*:
+```
+# Good: Explains intent
+feat: add email validation to registration endpoint
+Prevents invalid email formats from reaching the database.
+Uses Zod schema validation at the route handler level,
+consistent with existing validation patterns in auth.ts.
+# Bad: Describes what's obvious from the diff
+update auth.ts
+```
+**Format:**
+```
+<type>: <short description>
+<optional body explaining why, not what>
+```
+**Types:**
+- `feat` — New feature
+- `fix` — Bug fix
+- `refactor` — Code change that neither fixes a bug nor adds a feature
+- `test` — Adding or updating tests
+- `docs` — Documentation only
+- `chore` — Tooling, dependencies, config
+### 4. Keep Concerns Separate
+Don't combine formatting changes with behavior changes. Don't combine refactors with features. Each type of change should be a separate commit — and ideally a separate PR:
+```
+# Good: Separate concerns
+git commit -m "refactor: extract validation logic to shared utility"
+git commit -m "feat: add phone number validation to registration"
+# Bad: Mixed concerns
+git commit -m "refactor validation and add phone number field"
+```
+**Separate refactoring from feature work.** A refactoring change and a feature change are two different changes — submit them separately. This makes each change easier to review, revert, and understand in history. Small cleanups (renaming a variable) can be included in a feature commit at reviewer discretion.
+### 5. Size Your Changes
+Target ~100 lines per commit/PR. Changes over ~1000 lines should be split. See the splitting strategies in `code-review-and-quality` for how to break down large changes.
+```
+~100 lines  → Easy to review, easy to revert
+~300 lines  → Acceptable for a single logical change
+~1000 lines → Split into smaller changes
+```
+## Branching Strategy
+### Feature Branches
+```
+main (always deployable)
+  │
+  ├── feature/task-creation    ← One feature per branch
+  ├── feature/user-settings    ← Parallel work
+  └── fix/duplicate-tasks      ← Bug fixes
+```
+- Branch from `main` (or the team's default branch)
+- Keep branches short-lived (merge within 1-3 days) — long-lived branches are hidden costs
+- Delete branches after merge
+- Prefer feature flags over long-lived branches for incomplete features
+### Branch Naming
+```
+feature/<short-description>   → feature/task-creation
+fix/<short-description>       → fix/duplicate-tasks
+chore/<short-description>     → chore/update-deps
+refactor/<short-description>  → refactor/auth-module
+```
+## Working with Worktrees
+For parallel AI agent work, use git worktrees to run multiple branches simultaneously:
+```bash
+# Create a worktree for a feature branch
+git worktree add ../project-feature-a feature/task-creation
+git worktree add ../project-feature-b feature/user-settings
+# Each worktree is a separate directory with its own branch
+# Agents can work in parallel without interfering
+ls ../
+  project/              ← main branch
+  project-feature-a/    ← task-creation branch
+  project-feature-b/    ← user-settings branch
+# When done, merge and clean up
+git worktree remove ../project-feature-a
+```
+Benefits:
+- Multiple agents can work on different features simultaneously
+- No branch switching needed (each directory has its own branch)
+- If one experiment fails, delete the worktree — nothing is lost
+- Changes are isolated until explicitly merged
+## The Save Point Pattern
+```
+Agent starts work
+    │
+    ├── Makes a change
+    │   ├── Test passes? → Commit → Continue
+    │   └── Test fails? → Revert to last commit → Investigate
+    │
+    ├── Makes another change
+    │   ├── Test passes? → Commit → Continue
+    │   └── Test fails? → Revert to last commit → Investigate
+    │
+    └── Feature complete → All commits form a clean history
+```
+This pattern means you never lose more than one increment of work. If an agent goes off the rails, stop, inspect `git status`, and ask for explicit approval before any destructive reset back to the last successful state.
+## Change Summaries
+After any modification, provide a structured summary. This makes review easier, documents scope discipline, and surfaces unintended changes:
+```
+CHANGES MADE:
+- src/routes/tasks.ts: Added validation middleware to POST endpoint
+- src/lib/validation.ts: Added TaskCreateSchema using Zod
+THINGS I DIDN'T TOUCH (intentionally):
+- src/routes/auth.ts: Has similar validation gap but out of scope
+- src/middleware/error.ts: Error format could be improved (separate task)
+POTENTIAL CONCERNS:
+- The Zod schema is strict — rejects extra fields. Confirm this is desired.
+- Added zod as a dependency (72KB gzipped) — already in package.json
+```
+This pattern catches wrong assumptions early and gives reviewers a clear map of the change. The "DIDN'T TOUCH" section is especially important — it shows you exercised scope discipline and didn't go on an unsolicited renovation.
+## Pre-Commit Hygiene
+Before every commit:
+```bash
+# 1. Check what you're about to commit
+git diff --staged
+# 2. Ensure no secrets
+git diff --staged | grep -i "password\|secret\|api_key\|token"
+# 3. Run tests
+npm test
+# 4. Run linting
+npm run lint
+# 5. Run type checking
+npx tsc --noEmit
+```
+Automate this with git hooks:
+```json
+// package.json (using lint-staged + husky)
+{
+  "lint-staged": {
+    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+    "*.{json,md}": ["prettier --write"]
+  }
+}
+```
+## Handling Generated Files
+- **Commit generated files** only if the project expects them (e.g., `package-lock.json`, Prisma migrations)
+- **Don't commit** build output (`dist/`, `.next/`), environment files (`.env`), or IDE config (`.vscode/settings.json` unless shared)
+- **Have a `.gitignore`** that covers: `node_modules/`, `dist/`, `.env`, `.env.local`, `*.pem`
+## Using Git for Debugging
+```bash
+# Find which commit introduced a bug
+git bisect start
+git bisect bad HEAD
+git bisect good <known-good-commit>
+# Git checkouts midpoints; run your test at each to narrow down
+# View what changed recently
+git log --oneline -20
+git diff HEAD~5..HEAD -- src/
+# Find who last changed a specific line
+git blame src/services/task.ts
+# Search commit messages for a keyword
+git log --grep="validation" --oneline
+```
+## Common Rationalizations
+| Rationalization | Reality |
+|---|---|
+| "I'll commit when the feature is done" | One giant commit is impossible to review, debug, or revert. Commit each slice. |
+| "The message doesn't matter" | Messages are documentation. Future you (and future agents) will need to understand what changed and why. |
+| "I'll squash it all later" | Squashing destroys the development narrative. Prefer clean incremental commits from the start. |
+| "Branches add overhead" | Short-lived branches are free and prevent conflicting work from colliding. Long-lived branches are the problem — merge within 1-3 days. |
+| "I'll split this change later" | Large changes are harder to review, riskier to deploy, and harder to revert. Split before submitting, not after. |
+| "I don't need a .gitignore" | Until `.env` with production secrets gets committed. Set it up immediately. |
+## Red Flags
+- Large uncommitted changes accumulating
+- Commit messages like "fix", "update", "misc"
+- Formatting changes mixed with behavior changes
+- No `.gitignore` in the project
+- Committing `node_modules/`, `.env`, or build artifacts
+- Long-lived branches that diverge significantly from main
+- Force-pushing to shared branches
+## Verification
+For every commit:
+- [ ] Commit does one logical thing
+- [ ] Message explains the why, follows type conventions
+- [ ] Tests pass before committing
+- [ ] No secrets in the diff
+- [ ] No formatting-only changes mixed with behavior changes
+- [ ] `.gitignore` covers standard exclusions

package/template/.claude/skills/goal/SKILL.md ADDED Viewed

@@ -0,0 +1,148 @@
+---
+name: goal
+description: Goal workflow
+---
+---
+description: Goal Router - Route a high-level goal into the correct DevFlow 2.0 path and record recommendation metrics.
+---
+# Phase 05: Goal Router
+Route a high-level `/goal` request into the most appropriate DevFlow path.
+## Usage
+```text
+/goal {GOAL_DESCRIPTION}
+```
+Local CLI equivalent:
+```powershell
+npm run goal -- --goal "Implement goal command" --max-turns 30 --parallel
+npm run goal -- goal "Implement goal command" max-turns 30 parallel
+```
+## Purpose
+The goal router turns an open-ended request into a routed DevFlow recommendation plan.
+It should:
+- classify the goal into the right path
+- decompose large goals into worker-sized chunks
+- recommend the exact next command
+- record routing decisions, turn budget, and context notes in a session log
+The current goal runner is a routing and recommendation surface. It does not replace the mainline workflow or silently execute the full delivery lifecycle.
+## Boss-Worker Roles
+- `prp-core-boss` owns routing, decomposition, turn budgets, validation gates, and final synthesis.
+- `prp-core-worker` owns focused implementation or analysis subtasks assigned by the Boss.
+- Specialist agents may still be invoked with `Agent` when a task needs deeper domain expertise.
+## Flow Routing
+The Boss first classifies the request into one of these paths:
+| Flow | Use When | Typical Next Step |
+| :--- | :--- | :--- |
+| DevFlow Mainline | New feature, bug, test, docs, migration, or refactor requests. | `/00-Discover`, which owns the delivery decision |
+| PRD / Spec Orchestration | Product ideas or requirement-heavy planning before a Discovery ID exists. | `/00-Discover`, likely routing to `PRD` |
+| Brainstorm Flow | Early ambiguous ideas that need options and tradeoff analysis. | `/00-Discover`, likely routing to `Brainstorm` |
+| Research Flow | External facts, docs, codebase evidence, or feasibility proof are needed. | `/00-Discover`, likely routing to `Research` |
+| RCA / Debug Flow | Failures, errors, regressions, or investigation-heavy bug reports. | `/00-Discover`, likely routing to `Debug` |
+## Process
+1. Parse the goal text and runtime config.
+2. Select a flow path and record the reasoning.
+3. Estimate complexity and split large goals into worker-sized tasks.
+4. Recommend the relevant DevFlow commands in the correct order.
+5. Track turns by phase and stop when the configured `max-turns` budget is reached.
+6. Run validation gates appropriate to the selected flow.
+7. Add lightweight context usage notes when the runtime or operator can provide them.
+8. Save a structured session report.
+## Log Contract
+Session logs are written to:
+```text
+devflow/runs/goal-sessions/session-{goal_id}.json
+devflow/runs/goal_latest_session.json
+devflow/runs/goal_execution_log.json
+```
+Each log includes:
+- `goal_id`
+- `goal_description`
+- `status`
+- `execution_mode`
+- `config`
+- `metrics`
+- `context_usage`
+- `flow_selected`
+- `tasks_decomposed`
+- `execution_steps`
+- `recommended_commands`
+### Context Usage Notes
+`context_usage` is intentionally manual and optional until the runtime exposes exact token telemetry. Use it to capture:
+- `context_loaded`
+- `files_read`
+- `artifacts_read`
+- `token_usage`
+- `optimization_notes`
+## Validation
+After changing goal runner behavior, run:
+```powershell
+npm run validate
+node .agent/scripts/test-goal-runner.mjs
+npm run goal -- goal "Create a small test task" max-turns 15 dry-run
+```
+## Output
+Report:
+- selected flow
+- task decomposition summary
+- session log path
+- recommended next command
+- key assumptions or routing risks
+## Relationship To DevFlow 2.0
+- Classification: Companion command
+- Mainline status: Not a numbered stage
+- Typical entry points: broad goals before a Discovery ID exists
+- Typical handoff target: `/00-Discover`, with a likely companion route recorded as guidance rather than executed outside Discover
+## Sources
+- `AGENTS.md`
+- `.agent/scripts/goal-runner.mjs`
+- Related commands: `/00-Discover`, `Brainstorm`, `Research`, `PRD`, `Spec-Orchestrate`, `Debug`
+## Next Workflow Recommendation
+- **Primary**: the first command listed in `recommended_commands`
+- **Why**: `Goal` exists to route broad intent into the correct DevFlow 2.0 entry point
+- **Alternatives**:
+  - `/00-Discover "{goal}"` for all new work; Discover chooses Brainstorm, PRD, Research, Debug, or direct decision
+  - `/10-Define {discovery_id}` only after an approved Proceed decision
+  - `/20-Spec {running_id}` only for an existing approved delivery run
+## Wiki Update Recommendation
+- Update the wiki only when the goal-routing session reveals a durable pattern, intake heuristic, or onboarding note worth reusing.
+- If the output is only a one-off routing decision, do not create or update wiki pages.

package/template/.claude/skills/handoff/SKILL.md ADDED Viewed

@@ -0,0 +1,46 @@
+---
+name: handoff
+description: Compact active context into a handoff note. Use when a DevFlow run must continue in another session, agent, or report without duplicating existing artifacts.
+disable-model-invocation: true
+---
+# Handoff
+Use this support skill when work needs to move to another session or agent.
+DevFlow stage artifacts remain the source of truth. This skill should reference them instead of duplicating them.
+## Process
+1. Identify the continuation purpose.
+   - next stage
+   - specialist agent
+   - interrupted implementation
+   - verification follow-up
+   - release/report handoff
+2. Collect existing durable artifacts.
+   - stage markdown files
+   - checklists
+   - ADRs
+   - issues or PR links
+   - commits and diffs
+3. Write only the missing bridge context.
+   - current state
+   - decisions already made
+   - open blockers
+   - files or commands the next agent should inspect first
+   - suggested skills
+4. Redact secrets and sensitive data.
+## Output Location
+Prefer the active task workspace when the handoff belongs to the work item:
+```text
+devflow/runs/{ID}-{slug}/handoff-{date}.md
+```
+Use the OS temp directory only for throwaway cross-session transfer that should not become project history.