@jakkrichm/create-nexus-devflow 2.0.0

package/template/.agents/skills/test-driven-development/testing-patterns.md

@@ -0,0 +1,236 @@
+# Testing Patterns Reference
+
+Quick reference for common testing patterns across the stack. Use alongside the `test-driven-development` skill.
+
+## Table of Contents
+
+- [Test Structure (Arrange-Act-Assert)](#test-structure-arrange-act-assert)
+- [Test Naming Conventions](#test-naming-conventions)
+- [Common Assertions](#common-assertions)
+- [Mocking Patterns](#mocking-patterns)
+- [React/Component Testing](#reactcomponent-testing)
+- [API / Integration Testing](#api--integration-testing)
+- [E2E Testing (Playwright)](#e2e-testing-playwright)
+- [Test Anti-Patterns](#test-anti-patterns)
+
+## Test Structure (Arrange-Act-Assert)
+
+```typescript
+it('describes expected behavior', () => {
+  // Arrange: Set up test data and preconditions
+  const input = { title: 'Test Task', priority: 'high' };
+
+  // Act: Perform the action being tested
+  const result = createTask(input);
+
+  // Assert: Verify the outcome
+  expect(result.title).toBe('Test Task');
+  expect(result.priority).toBe('high');
+  expect(result.status).toBe('pending');
+});
+```
+
+## Test Naming Conventions
+
+```typescript
+// Pattern: [unit] [expected behavior] [condition]
+describe('TaskService.createTask', () => {
+  it('creates a task with default pending status', () => {});
+  it('throws ValidationError when title is empty', () => {});
+  it('trims whitespace from title', () => {});
+  it('generates a unique ID for each task', () => {});
+});
+```
+
+## Common Assertions
+
+```typescript
+// Equality
+expect(result).toBe(expected);           // Strict equality (===)
+expect(result).toEqual(expected);        // Deep equality (objects/arrays)
+expect(result).toStrictEqual(expected);  // Deep equality + type matching
+
+// Truthiness
+expect(result).toBeTruthy();
+expect(result).toBeFalsy();
+expect(result).toBeNull();
+expect(result).toBeDefined();
+expect(result).toBeUndefined();
+
+// Numbers
+expect(result).toBeGreaterThan(5);
+expect(result).toBeLessThanOrEqual(10);
+expect(result).toBeCloseTo(0.3, 5);      // Floating point
+
+// Strings
+expect(result).toMatch(/pattern/);
+expect(result).toContain('substring');
+
+// Arrays / Objects
+expect(array).toContain(item);
+expect(array).toHaveLength(3);
+expect(object).toHaveProperty('key', 'value');
+
+// Errors
+expect(() => fn()).toThrow();
+expect(() => fn()).toThrow(ValidationError);
+expect(() => fn()).toThrow('specific message');
+
+// Async
+await expect(asyncFn()).resolves.toBe(value);
+await expect(asyncFn()).rejects.toThrow(Error);
+```
+
+## Mocking Patterns
+
+### Mock Functions
+
+```typescript
+const mockFn = jest.fn();
+mockFn.mockReturnValue(42);
+mockFn.mockResolvedValue({ data: 'test' });
+mockFn.mockImplementation((x) => x * 2);
+
+expect(mockFn).toHaveBeenCalled();
+expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2');
+expect(mockFn).toHaveBeenCalledTimes(3);
+```
+
+### Mock Modules
+
+```typescript
+// Mock an entire module
+jest.mock('./database', () => ({
+  query: jest.fn().mockResolvedValue([{ id: 1, title: 'Test' }]),
+}));
+
+// Mock specific exports
+jest.mock('./utils', () => ({
+  ...jest.requireActual('./utils'),
+  generateId: jest.fn().mockReturnValue('test-id'),
+}));
+```
+
+### Mock at Boundaries Only
+
+```
+Mock these:                    Don't mock these:
+├── Database calls             ├── Internal utility functions
+├── HTTP requests              ├── Business logic
+├── File system operations     ├── Data transformations
+├── External API calls         ├── Validation functions
+└── Time/Date (when needed)    └── Pure functions
+```
+
+## React/Component Testing
+
+```tsx
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+
+describe('TaskForm', () => {
+  it('submits the form with entered data', async () => {
+    const onSubmit = jest.fn();
+    render(<TaskForm onSubmit={onSubmit} />);
+
+    // Find elements by accessible role/label (not test IDs)
+    await screen.findByRole('textbox', { name: /title/i });
+    fireEvent.change(screen.getByRole('textbox', { name: /title/i }), {
+      target: { value: 'New Task' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: /create/i }));
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledWith({ title: 'New Task' });
+    });
+  });
+
+  it('shows validation error for empty title', async () => {
+    render(<TaskForm onSubmit={jest.fn()} />);
+
+    fireEvent.click(screen.getByRole('button', { name: /create/i }));
+
+    expect(await screen.findByText(/title is required/i)).toBeInTheDocument();
+  });
+});
+```
+
+## API / Integration Testing
+
+```typescript
+import request from 'supertest';
+import { app } from '../src/app';
+
+describe('POST /api/tasks', () => {
+  it('creates a task and returns 201', async () => {
+    const response = await request(app)
+      .post('/api/tasks')
+      .send({ title: 'Test Task' })
+      .set('Authorization', `Bearer ${testToken}`)
+      .expect(201);
+
+    expect(response.body).toMatchObject({
+      id: expect.any(String),
+      title: 'Test Task',
+      status: 'pending',
+    });
+  });
+
+  it('returns 422 for invalid input', async () => {
+    const response = await request(app)
+      .post('/api/tasks')
+      .send({ title: '' })
+      .set('Authorization', `Bearer ${testToken}`)
+      .expect(422);
+
+    expect(response.body.error.code).toBe('VALIDATION_ERROR');
+  });
+
+  it('returns 401 without authentication', async () => {
+    await request(app)
+      .post('/api/tasks')
+      .send({ title: 'Test' })
+      .expect(401);
+  });
+});
+```
+
+## E2E Testing (Playwright)
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('user can create and complete a task', async ({ page }) => {
+  // Navigate and authenticate
+  await page.goto('/');
+  await page.fill('[name="email"]', 'test@example.com');
+  await page.fill('[name="password"]', 'testpass123');
+  await page.click('button:has-text("Log in")');
+
+  // Create a task
+  await page.click('button:has-text("New Task")');
+  await page.fill('[name="title"]', 'Buy groceries');
+  await page.click('button:has-text("Create")');
+
+  // Verify task appears
+  await expect(page.locator('text=Buy groceries')).toBeVisible();
+
+  // Complete the task
+  await page.click('[aria-label="Complete Buy groceries"]');
+  await expect(page.locator('text=Buy groceries')).toHaveCSS(
+    'text-decoration-line', 'line-through'
+  );
+});
+```
+
+## Test Anti-Patterns
+
+| Anti-Pattern | Problem | Better Approach |
+|---|---|---|
+| Testing implementation details | Breaks on refactor | Test inputs/outputs |
+| Snapshot everything | No one reviews snapshot diffs | Assert specific values |
+| Shared mutable state | Tests pollute each other | Setup/teardown per test |
+| Testing third-party code | Wastes time, not your bug | Mock the boundary |
+| Skipping tests to pass CI | Hides real bugs | Fix or delete the test |
+| Using `test.skip` permanently | Dead code | Remove or fix it |
+| Overly broad assertions | Doesn't catch regressions | Be specific |
+| No async error handling | Swallowed errors, false passes | Always `await` async tests |

package/template/.agents/skills/test-execution-and-coverage/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: test-execution-and-coverage
+description: Generate missing tests, run existing tests, and summarize coverage and failures. Use when implementation or verification needs explicit testing evidence beyond a general TDD reminder.
+---
+
+# Test Execution And Coverage
+
+## Overview
+
+This skill complements TDD by handling test generation, execution, and persistent reporting.
+
+## When to Use
+
+- During `/40-Implement` when tests need to be added
+- During `/50-Verify` when the test suite must be run and summarized
+- During `Debug` when a bug needs a reproduction test
+
+## Process
+
+### 1. Decide Test Mode
+
+- generate tests for a target
+- run the existing test suite
+- inspect coverage when the project supports it
+
+### 2. Use Project-Native Test Commands
+
+- prefer the project's real framework and real commands
+- highlight failed assertions clearly
+- distinguish test generation from test execution
+
+### 3. Save Reusable Report
+
+Write reusable output under:
+
+```text
+devflow/reports/{date}-test-report-{slug}.md
+```
+
+Use `.agent/resources/schemas/test_report.template.md` when saving a reusable report.
+
+### 4. Route Back
+
+- `/50-Verify` when tests support formal verification
+- `/40-Implement` when missing or failing tests require code changes
+- `Debug` when failures need RCA
+
+## Output
+
+Return:
+
+- what tests were generated or run
+- command output summary
+- pass/fail state
+- gaps and risks
+- recommended return stage

package/template/.agents/skills/type-design/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: type-design
+description: Analyzes type and interface design for encapsulation, invariant expression, usefulness, and enforcement. Use when introducing new types, reviewing PRs with type changes, or refactoring domain models.
+---
+
+# Type Design
+
+Use this skill to evaluate whether types make invalid states hard or impossible to represent without over-engineering the codebase.
+
+## Core Rule
+
+Make illegal states unrepresentable when it prevents real bugs, but do not make simple things complex.
+
+## When To Use
+
+- New type, interface, schema, model, DTO, or value object is introduced.
+- A PR changes type relationships, constructors, factories, or public API contracts.
+- A refactor moves validation, mutation, or domain rules across module boundaries.
+- A reviewer needs a pragmatic quality rating for type design.
+
+## Analysis Scope
+
+Review:
+
+- Type/interface definitions.
+- Constructors, factories, parsers, and validators.
+- Setter methods and mutation points.
+- Public API surface and exported types.
+- Relationships between fields that must remain consistent.
+
+## Evaluation Dimensions
+
+| Dimension | Ask |
+|---|---|
+| Encapsulation | Can callers violate invariants from outside the type boundary? |
+| Invariant Expression | Are the important constraints obvious from the type shape? |
+| Invariant Usefulness | Do the constraints prevent real bugs or only add ceremony? |
+| Invariant Enforcement | Are invalid instances impossible or at least rejected at boundaries? |
+
+Rate each dimension from 1 to 10. Scores below 5 require concrete findings.
+
+## Anti-Patterns
+
+| Anti-pattern | Risk |
+|---|---|
+| Exposed mutable internals | Callers can break invariants after construction. |
+| Doc-only invariants | The rule exists only in comments and is easy to bypass. |
+| No constructor or parser validation | Invalid instances can enter the system. |
+| Anemic domain model | Rules are scattered across callers. |
+| God type | Too many responsibilities make the type hard to use correctly. |
+| Over-modeled simple data | Complexity exceeds the bug-prevention value. |
+
+## Output Format
+
+```markdown
+## Type Design Review: [Scope]
+
+### Types Reviewed
+| Type | File | Purpose |
+|---|---|---|
+| `TypeName` | `path/file.ts:10` | Represents ... |
+
+### Ratings
+| Type | Encapsulation | Expression | Usefulness | Enforcement | Overall |
+|---|---:|---:|---:|---:|---:|
+| `TypeName` | 8 | 7 | 8 | 6 | 7.25 |
+
+### Findings
+#### [Severity] [Title]
+**Location**: `path/file.ts:23`
+**Problem**: [What invariant can fail]
+**Impact**: [Concrete bug or maintenance risk]
+**Recommendation**: [Smallest useful improvement]
+
+### Verdict
+[Well-designed / Adequate / Needs improvement / Significant issues]
+```
+
+## Verification
+
+- Findings cite concrete files and lines.
+- Recommendations fit the project's existing type style.
+- Suggestions include trade-offs when they add ceremony.
+- No recommendation depends on speculative future requirements.

package/template/.agents/skills/ui-ux-pro-max/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: ui-ux-pro-max
+description: AI-powered design intelligence with 50+ styles, 95+ color palettes, and automated design system generation. Use when designing, building, or reviewing UI/UX.
+---
+
+# UI/UX Pro Max (Design Intelligence)
+
+Comprehensive design guide for web and mobile applications. Contains 50+ styles, 97 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 9 technology stacks. Searchable database with priority-based recommendations.
+
+## Prerequisites
+
+Python is required for the design system search tool.
+
+## How to Use This Skill
+
+When you need to perform UI/UX work (design, build, create, implement, review, fix, improve), follow this process:
+
+### 1. Analyze User Requirements
+Extract key information:
+- **Product type**: SaaS, e-commerce, dashboard, etc.
+- **Style keywords**: minimal, playful, professional, dark mode, etc.
+- **Industry**: healthcare, fintech, gaming, etc.
+- **Stack**: React, Vue, Next.js, or default to `html-tailwind`.
+
+### 2. Generate Design System (REQUIRED)
+**Always start by generating a design system** to get comprehensive recommendations:
+
+```bash
+python3 .claude/.shared/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+```
+
+### 3. Persist Design System
+To save the design system for hierarchical retrieval:
+
+```bash
+python3 .claude/.shared/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" [--page "name"]
+```
+
+### 4. Detailed Domain Searches
+Supplement with specific details as needed:
+- `style`: `--domain style "keywords"`
+- `chart`: `--domain chart "keywords"`
+- `ux`: `--domain ux "keywords"`
+- `typography`: `--domain typography "keywords"`
+
+---
+
+## Design Guidelines & Standards
+
+### Professional UI Rules
+- **No emoji icons**: Use SVG icons (Heroicons, Lucide).
+- **Stable hover states**: Use color/opacity transitions, avoid layout shifts.
+- **Consistent icon sizing**: Use fixed viewBox (24x24) with w-6 h-6.
+- **Cursor pointer**: Add `cursor-pointer` to all interactive elements.
+
+### Contrast & Visibility
+- **Light Mode Glass**: Use `bg-white/80` or higher.
+- **Text Contrast**: Use high-contrast slates (e.g., slate-900 for body).
+- **Border visibility**: Ensure borders are visible in both light/dark modes.
+
+### Layout
+- **Floating navbar**: Add `top-4 left-4 right-4` spacing.
+- **Responsive**: Test at 375px, 768px, 1024px, 1440px.
+
+## Pre-Delivery Checklist
+
+- [ ] No emojis used as icons (use SVG instead).
+- [ ] Hover states don't cause layout shift.
+- [ ] All clickable elements have `cursor-pointer`.
+- [ ] Transitions are smooth (150-300ms).
+- [ ] Responsive at all major breakpoints.
+- [ ] No horizontal scroll on mobile.
+
+---
+*Powered by UI-UX Pro Max Engine*

package/template/.agents/skills/using-agent-skills/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: using-agent-skills
+description: Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.
+---
+
+# Using Agent Skills
+
+## Overview
+
+Agent Skills is a collection of engineering workflow skills organized by development phase. Each skill encodes a specific process that senior engineers follow. This meta-skill helps you discover and apply the right skill for your current task.
+
+## Skill Discovery
+
+When a task arrives, identify the development phase and apply the corresponding skill:
+
+```
+Task arrives
+    │
+    ├── Vague idea/need refinement? ──→ idea-refine
+    ├── New project/feature/change? ──→ spec-driven-development
+    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
+    ├── Implementing code? ────────────→ incremental-implementation
+    │   ├── UI work? ─────────────────→ frontend-ui-engineering
+    │   ├── API work? ────────────────→ api-and-interface-design
+    │   └── Need better context? ─────→ context-engineering
+    ├── Writing/running tests? ────────→ test-driven-development
+    │   └── Browser-based? ───────────→ browser-testing-with-devtools
+    ├── Something broke? ──────────────→ debugging-and-error-recovery
+    ├── Reviewing code? ───────────────→ code-review-and-quality
+    │   ├── Security concerns? ───────→ security-and-hardening
+    │   └── Performance concerns? ────→ performance-optimization
+    ├── Committing/branching? ─────────→ git-workflow-and-versioning
+    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
+    ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
+    └── Deploying/launching? ─────────→ shipping-and-launch
+```
+
+## Core Operating Behaviors
+
+These behaviors apply at all times, across all skills. They are non-negotiable.
+
+### 1. Surface Assumptions
+
+Before implementing anything non-trivial, explicitly state your assumptions:
+
+```
+ASSUMPTIONS I'M MAKING:
+1. [assumption about requirements]
+2. [assumption about architecture]
+3. [assumption about scope]
+→ Correct me now or I'll proceed with these.
+```
+
+Don't silently fill in ambiguous requirements. The most common failure mode is making wrong assumptions and running with them unchecked. Surface uncertainty early — it's cheaper than rework.
+
+### 2. Manage Confusion Actively
+
+When you encounter inconsistencies, conflicting requirements, or unclear specifications:
+
+1. **STOP.** Do not proceed with a guess.
+2. Name the specific confusion.
+3. Present the tradeoff or ask the clarifying question.
+4. Wait for resolution before continuing.
+
+**Bad:** Silently picking one interpretation and hoping it's right.
+**Good:** "I see X in the spec but Y in the existing code. Which takes precedence?"
+
+### 3. Push Back When Warranted
+
+You are not a yes-machine. When an approach has clear problems:
+
+- Point out the issue directly
+- Explain the concrete downside (quantify when possible — "this adds ~200ms latency" not "this might be slower")
+- Propose an alternative
+- Accept the human's decision if they override with full information
+
+Sycophancy is a failure mode. "Of course!" followed by implementing a bad idea helps no one. Honest technical disagreement is more valuable than false agreement.
+
+### 4. Enforce Simplicity
+
+Your natural tendency is to overcomplicate. Actively resist it.
+
+Before finishing any implementation, ask:
+- Can this be done in fewer lines?
+- Are these abstractions earning their complexity?
+- Would a staff engineer look at this and say "why didn't you just..."?
+
+If you build 1000 lines and 100 would suffice, you have failed. Prefer the boring, obvious solution. Cleverness is expensive.
+
+### 5. Maintain Scope Discipline
+
+Touch only what you're asked to touch.
+
+Do NOT:
+- Remove comments you don't understand
+- "Clean up" code orthogonal to the task
+- Refactor adjacent systems as a side effect
+- Delete code that seems unused without explicit approval
+- Add features not in the spec because they "seem useful"
+
+Your job is surgical precision, not unsolicited renovation.
+
+### 6. Verify, Don't Assume
+
+Every skill includes a verification step. A task is not complete until verification passes. "Seems right" is never sufficient — there must be evidence (passing tests, build output, runtime data).
+
+## Failure Modes to Avoid
+
+These are the subtle errors that look like productivity but create problems:
+
+1. Making wrong assumptions without checking
+2. Not managing your own confusion — plowing ahead when lost
+3. Not surfacing inconsistencies you notice
+4. Not presenting tradeoffs on non-obvious decisions
+5. Being sycophantic ("Of course!") to approaches with clear problems
+6. Overcomplicating code and APIs
+7. Modifying code or comments orthogonal to the task
+8. Removing things you don't fully understand
+9. Building without a spec because "it's obvious"
+10. Skipping verification because "it looks right"
+
+## Skill Rules
+
+1. **Check for an applicable skill before starting work.** Skills encode processes that prevent common mistakes.
+
+2. **Skills are workflows, not suggestions.** Follow the steps in order. Don't skip verification steps.
+
+3. **Multiple skills can apply.** A feature implementation might involve `idea-refine` → `spec-driven-development` → `planning-and-task-breakdown` → `incremental-implementation` → `test-driven-development` → `code-review-and-quality` → `shipping-and-launch` in sequence.
+
+4. **When in doubt, start with a spec.** If the task is non-trivial and there's no spec, begin with `spec-driven-development`.
+
+## Lifecycle Sequence
+
+For a complete feature, the typical skill sequence is:
+
+```
+1. idea-refine                 → Refine vague ideas
+2. spec-driven-development     → Define what we're building
+3. planning-and-task-breakdown → Break into verifiable chunks
+4. context-engineering         → Load the right context
+5. incremental-implementation  → Build slice by slice
+6. test-driven-development     → Prove each slice works
+7. code-review-and-quality     → Review before merge
+8. git-workflow-and-versioning → Clean commit history
+9. documentation-and-adrs      → Document decisions
+10. shipping-and-launch        → Deploy safely
+```
+
+Not every task needs every skill. A bug fix might only need: `debugging-and-error-recovery` → `test-driven-development` → `code-review-and-quality`.
+
+## Quick Reference
+
+| Phase | Skill | One-Line Summary |
+|-------|-------|-----------------|
+| Define | idea-refine | Refine ideas through structured divergent and convergent thinking |
+| Define | spec-driven-development | Requirements and acceptance criteria before code |
+| Plan | planning-and-task-breakdown | Decompose into small, verifiable tasks |
+| Build | incremental-implementation | Thin vertical slices, test each before expanding |
+| Build | context-engineering | Right context at the right time |
+| Build | frontend-ui-engineering | Production-quality UI with accessibility |
+| Build | api-and-interface-design | Stable interfaces with clear contracts |
+| Verify | test-driven-development | Failing test first, then make it pass |
+| Verify | browser-testing-with-devtools | Chrome DevTools MCP for runtime verification |
+| Verify | debugging-and-error-recovery | Reproduce → localize → fix → guard |
+| Review | code-review-and-quality | Five-axis review with quality gates |
+| Review | security-and-hardening | OWASP prevention, input validation, least privilege |
+| Review | performance-optimization | Measure first, optimize only what matters |
+| Ship | git-workflow-and-versioning | Atomic commits, clean history |
+| Ship | ci-cd-and-automation | Automated quality gates on every change |
+| Ship | documentation-and-adrs | Document the why, not just the what |
+| Ship | shipping-and-launch | Pre-launch checklist, monitoring, rollback plan |

package/template/.agents/skills/verification-orchestration/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: verification-orchestration
+description: Coordinate multi-lane QA, specialist review, test planning, and verification follow-up. Use when /50-Verify needs more structure than a single pass and the team needs a QA matrix or specialist routing.
+---
+
+# Verification Orchestration
+
+## Overview
+
+This skill structures complex verification work across multiple QA lanes without replacing the main verification stage.
+
+## When to Use
+
+- `/50-Verify` is too broad for a single simple pass
+- the change needs correctness, regression, security, performance, and UX checks together
+- the team needs specialist routing for QA
+
+## Process
+
+### 1. Validate The Verification Context
+
+- inspect the owning stage artifacts first
+- confirm what implementation scope is actually under review
+- keep markdown stage artifacts as the source of truth
+
+### 2. Choose QA Lanes
+
+Typical lanes:
+
+- correctness and acceptance criteria
+- tests and regressions
+- security and data safety
+- performance and scalability
+- UX or manual verification
+- codebase fit and maintainability
+
+### 3. Route Specialist Help
+
+Use specialist agents only when needed, such as:
+
+- `code-reviewer`
+- `test-engineer`
+- `security-auditor`
+
+### 4. Save Reusable Report
+
+Write reusable output under:
+
+```text
+devflow/reports/{date}-qa-orchestrate-{id}.md
+```
+
+Use `.agent/resources/schemas/qa_orchestration.template.md` when saving a reusable report.
+
+### 5. Route Back
+
+- `/50-Verify` when the QA matrix strengthens verification evidence
+- `/40-Implement` when actionable fixes are required
+- `Followup` when findings become new scope
+
+## Output
+
+Return:
+
+- QA lanes used
+- specialist recommendations
+- findings and blockers
+- recommended return stage