@lumenflow/cli 2.2.1 → 2.3.1

package/templates/core/ai/onboarding/wu-create-checklist.md.template

@@ -0,0 +1,117 @@
+# WU Creation Checklist
+
+**Last updated:** {{DATE}}
+
+Before running `pnpm wu:create`, verify these items.
+
+---
+
+## Step 1: Check Valid Lanes
+
+```bash
+grep -A 30 "lanes:" .lumenflow.config.yaml
+```
+
+**Format:** `"Parent: Sublane"` (colon + single space)
+
+Examples:
+
+- `"Framework: CLI"`
+- `"Framework: Core"`
+- `"Operations: CI/CD"`
+- `"Content: Documentation"`
+
+---
+
+## Step 2: Required Fields
+
+| Field              | Required For | Example                                          |
+| ------------------ | ------------ | ------------------------------------------------ |
+| `--id`             | All          | `WU-1234`                                        |
+| `--lane`           | All          | `"Experience: Chat"`                             |
+| `--title`          | All          | `"Add feature"`                                  |
+| `--description`    | All          | `"Context: ... Problem: ... Solution: ..."`      |
+| `--acceptance`     | All          | `--acceptance "Works"` (repeatable)              |
+| `--exposure`       | All          | `ui`, `api`, `backend-only`, `documentation`     |
+| `--code-paths`     | Code WUs     | `"src/a.ts,src/b.ts"`                            |
+| `--test-paths-unit`| Code WUs     | `"src/__tests__/a.test.ts"`                      |
+| `--spec-refs`      | Feature WUs  | `"lumenflow://plans/WU-XXX-plan.md"`             |
+
+---
+
+## Step 3: Plan Storage
+
+Plans go in `$LUMENFLOW_HOME/plans/` (NOT in project):
+
+```bash
+mkdir -p $LUMENFLOW_HOME/plans
+# or if LUMENFLOW_HOME is not set:
+mkdir -p ~/.lumenflow/plans
+
+# Create your plan
+vim ~/.lumenflow/plans/WU-XXX-plan.md
+```
+
+Reference in wu:create:
+
+```bash
+--spec-refs "lumenflow://plans/WU-XXX-plan.md"
+```
+
+---
+
+## Step 4: Validate First
+
+```bash
+pnpm wu:create --id WU-XXX ... --validate
+```
+
+Fix errors, then remove `--validate` to create.
+
+---
+
+## Complete Example
+
+```bash
+pnpm wu:create \
+  --id WU-1234 \
+  --lane "Framework: CLI" \
+  --title "Add feature X" \
+  --description "Context: Users need X. Problem: X doesn't exist. Solution: Add X." \
+  --acceptance "Feature X works as specified" \
+  --acceptance "Unit tests pass with >90% coverage" \
+  --code-paths "packages/@lumenflow/cli/src/x.ts" \
+  --test-paths-unit "packages/@lumenflow/cli/__tests__/x.test.ts" \
+  --exposure backend-only \
+  --spec-refs "lumenflow://plans/WU-1234-plan.md"
+```
+
+---
+
+## Common Errors
+
+### "Lane format invalid"
+
+**Cause:** Missing colon or space in lane format.
+
+**Fix:** Use `"Parent: Sublane"` format (colon + space).
+
+### "Missing required field"
+
+**Cause:** Required field not provided.
+
+**Fix:** Add the missing `--field` argument.
+
+### "WU already exists"
+
+**Cause:** WU with this ID already exists.
+
+**Fix:** Use a different ID or check existing WUs.
+
+---
+
+## After Creation
+
+1. Review the created YAML: `cat docs/04-operations/tasks/wu/WU-XXX.yaml`
+2. Claim the WU: `pnpm wu:claim --id WU-XXX --lane "Lane"`
+3. cd to worktree: `cd worktrees/<lane>-wu-xxx`

package/templates/vendors/aider/.aider.conf.yml.template

@@ -0,0 +1,27 @@
+# Aider Configuration for LumenFlow Projects
+# See LUMENFLOW.md for workflow documentation
+
+# Model settings
+model: gpt-4-turbo
+
+# Git settings
+auto-commits: false
+dirty-commits: false
+
+# Read these files for context
+read:
+  - LUMENFLOW.md
+  - .lumenflow/constraints.md
+  - ai/onboarding/troubleshooting-wu-done.md
+  - ai/onboarding/quick-ref-commands.md
+
+# Message to remind about workflow
+message: |
+  This project uses LumenFlow workflow.
+
+  Critical Rules:
+  1. Work only in worktrees after wu:claim
+  2. Run pnpm gates before completing
+  3. ALWAYS run pnpm wu:done --id WU-XXX to complete
+
+  See LUMENFLOW.md for full documentation.

package/templates/vendors/claude/.claude/CLAUDE.md.template

@@ -0,0 +1,52 @@
+# Claude Code Configuration
+
+**Last updated:** {{DATE}}
+
+This project uses LumenFlow workflow. For workflow documentation, see [LUMENFLOW.md](../LUMENFLOW.md).
+
+---
+
+## Quick Start
+
+```bash
+# 1. Read workflow documentation
+# See LUMENFLOW.md for complete workflow
+
+# 2. Claim a WU
+pnpm wu:claim --id WU-XXXX --lane <Lane>
+cd worktrees/<lane>-wu-xxxx
+
+# 3. Work in worktree, run gates
+pnpm gates
+
+# 4. Complete (ALWAYS run this!)
+cd {{PROJECT_ROOT}}
+pnpm wu:done --id WU-XXXX
+```
+
+> **Complete CLI reference:** See [quick-ref-commands.md](../ai/onboarding/quick-ref-commands.md)
+
+---
+
+## Critical: Always wu:done
+
+After completing work, ALWAYS run `pnpm wu:done --id WU-XXXX`.
+
+See [LUMENFLOW.md](../LUMENFLOW.md) and [ai/onboarding/troubleshooting-wu-done.md](../ai/onboarding/troubleshooting-wu-done.md).
+
+---
+
+## Claude-Specific Settings
+
+This directory contains Claude Code-specific configuration:
+
+- `settings.json` - Permissions and hooks
+- `hooks/` - Pre-tool validation hooks
+
+---
+
+## References
+
+- [LUMENFLOW.md](../LUMENFLOW.md) - Main workflow documentation
+- [.lumenflow/constraints.md](../.lumenflow/constraints.md) - Non-negotiable rules
+- [ai/onboarding/](../ai/onboarding/) - Agent onboarding docs

package/templates/vendors/claude/.claude/settings.json.template

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash",
+      "Read",
+      "Write",
+      "Edit",
+      "WebFetch",
+      "WebSearch",
+      "Skill",
+      "mcp__context7__*",
+      "mcp__github__*"
+    ],
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Write(./.env*)",
+      "Bash(git reset --hard *)",
+      "Bash(git stash *)",
+      "Bash(git clean -fd *)",
+      "Bash(git push --force *)",
+      "Bash(git push -f *)",
+      "Bash(git checkout -f *)",
+      "Bash(git commit --no-verify *)",
+      "Bash(/usr/bin/git reset --hard *)",
+      "Bash(/usr/bin/git stash *)",
+      "Bash(/usr/bin/git clean -fd *)",
+      "Bash(/usr/bin/git push --force *)",
+      "Bash(/usr/bin/git push -f *)",
+      "Bash(/usr/bin/git commit --no-verify *)",
+      "Bash(HUSKY=0 *)",
+      "Bash(rm -rf /*)",
+      "Bash(rm -rf /home/*)",
+      "Bash(rm -rf ~/*)",
+      "Read(~/.aws/**)",
+      "Read(~/.ssh/**)",
+      "Write(~/.aws/**)",
+      "Write(~/.ssh/**)",
+      "Bash(sudo *)",
+      "Bash(su *)",
+      "Bash(git worktree remove *)",
+      "Bash(/usr/bin/git worktree remove *)",
+      "Bash(git worktree prune *)",
+      "Bash(/usr/bin/git worktree prune *)"
+    ],
+    "disableBypassPermissionsMode": "disable"
+  }
+}

package/templates/vendors/claude/.claude/skills/bug-classification/SKILL.md.template

@@ -0,0 +1,192 @@
+---
+name: bug-classification
+description: Classify bugs (P0-P3) and determine fix-in-place vs separate Bug WU. Use when bug discovered mid-WU, deciding bug priority, or handling production issues.
+version: 1.0.0
+source: docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
+source_sections: §8 (Bug Handling Mid-WU)
+last_updated: {{DATE}}
+allowed-tools: Read, Grep
+---
+
+# Bug Classification Skill
+
+## Purpose
+
+Classify bugs (P0/P1/P2/P3) and determine whether to fix-in-place or create separate Bug WU.
+
+## When to Use
+
+- Bug discovered while working on a WU
+- Need to determine bug priority
+- Deciding fix-in-place vs separate WU
+- Production issues requiring immediate attention
+
+## Bug Classification (Priority Levels)
+
+### P0 (CRITICAL - Emergency Response)
+
+**Criteria:**
+
+- Production outage (service unavailable)
+- Data loss or corruption
+- Auth/security breakage (users can't login, data exposed)
+- Payment processing failure
+- Critical safety issue
+
+**Response:**
+
+1. Classify as P0 per this guide
+2. Create Bug WU with failing test
+3. May preempt ANY lane: `pnpm wu:block --id WU-<current> --reason "Preempted by P0 WU-###"`
+4. Immediately claim P0 WU: `pnpm wu:claim --id WU-### --lane <lane>`
+5. Fix via TDD → gates → `pnpm wu:done`
+6. Commit with `fix(EMERGENCY): <description>` convention
+7. Restore preempted WU: `pnpm wu:unblock --id WU-<previous>`
+
+**SLA**: Fix within 1-4 hours
+
+### P1 (HIGH - Fix This Sprint)
+
+**Criteria:**
+
+- Major feature broken (but service still available)
+- Significant user impact (affects >50% of workflows)
+- Performance degradation (2x+ slower than baseline)
+- Security vulnerability (non-critical)
+- Data integrity issue (recoverable)
+
+**Response:**
+
+- Create Bug WU if not fixable in current WU
+- Schedule for current sprint
+- May preempt P2/P3 work
+
+**SLA**: Fix within 1-3 days
+
+### P2 (MEDIUM - Fix Next Sprint)
+
+**Criteria:**
+
+- Minor feature broken (workarounds exist)
+- Moderate user impact (affects <50% of workflows)
+- UI/UX issues (confusing but functional)
+- Performance issue (noticeable but not blocking)
+
+**Response:**
+
+- Create Bug WU
+- Schedule for next sprint
+- Does not preempt P0/P1 work
+
+**SLA**: Fix within 1-2 weeks
+
+### P3 (LOW - Backlog)
+
+**Criteria:**
+
+- Cosmetic issues (typos, minor visual bugs)
+- Edge case failures (rare scenarios)
+- Nice-to-have improvements
+- Tech debt
+
+**Response:**
+
+- Add to backlog
+- Fix when capacity allows
+- Does not preempt P0/P1/P2 work
+
+**SLA**: No specific timeline
+
+## Fix-in-Place vs Bug WU Decision Tree
+
+### Fix-in-Place (Expand Current WU Scope)
+
+Use when ALL of the following are true:
+
+- Bug is in code touched by current WU
+- Fix is small (< 50 lines of code)
+- Fix doesn't require new tests beyond current WU acceptance
+- Bug is related to current WU's feature/refactor
+- Fix won't delay current WU by >1 hour
+
+**Process:**
+
+1. Update current WU acceptance criteria (add fix to checklist)
+2. Update `code_paths` to include bug fix
+3. Update `notes` to document bug discovery and fix
+4. Implement fix + tests
+5. Commit with WU convention: `wu(wu-xxx): fix <description> + original work`
+6. Complete via `pnpm wu:done` (includes both original work and bug fix)
+
+### Create Bug WU
+
+Use when ANY of the following are true:
+
+- Bug is in unrelated code (different feature/module)
+- Fix is large (> 50 lines of code)
+- Fix requires significant new tests
+- Bug is unrelated to current WU's feature
+- Fix will delay current WU by >1 hour
+- Bug is P0/P1 and current WU is P2/P3
+
+**Process:**
+
+1. Create Bug WU with:
+   - Type: `bug`
+   - Priority: P0/P1/P2/P3 (use classification above)
+   - Context: Bug description, steps to reproduce
+   - Acceptance: Failing test + fix + regression prevention
+2. If P0/P1: Block current WU and claim Bug WU immediately
+3. If P2/P3: Add to backlog, finish current WU first
+4. Implement fix via TDD (failing test first)
+5. Complete via `pnpm wu:done`
+
+## Bug WU Template
+
+```yaml
+id: WU-XXX
+title: 'BUG: <concise description>'
+type: bug
+lane: <affected-lane>
+status: ready
+priority: <P0|P1|P2|P3>
+created: YYYY-MM-DD
+
+context: |
+  Bug discovered: <when and where>
+
+  Symptoms:
+  - <what's broken>
+  - <user impact>
+
+  Root cause: <why it's broken>
+
+  Reproduction:
+  1. <step 1>
+  2. <step 2>
+  3. <observe failure>
+
+acceptance:
+  - '[ ] Failing test demonstrates bug'
+  - '[ ] Fix implements correct behavior'
+  - '[ ] Regression test prevents recurrence'
+  - '[ ] Related edge cases tested'
+
+code_paths:
+  - <file with bug>
+  - <test file>
+
+tests:
+  - <test file path>
+
+notes: |
+  Discovered during: WU-YYY
+  Affects: <list of affected features/workflows>
+
+blocked_by: []
+blocking: []
+```
+
+## Reference
+
+See [lumenflow-complete.md §8](../../../docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md) for complete bug handling guide.

package/templates/vendors/claude/.claude/skills/code-quality/SKILL.md.template

@@ -0,0 +1,152 @@
+---
+name: code-quality
+description: Shared patterns for SOLID/DRY code review, hexagonal architecture compliance, TypeScript best practices, and performance anti-patterns. Use when reviewing code quality, checking architecture boundaries, or validating TypeScript patterns.
+version: 1.1.0
+source: docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
+source_sections: §2 (Core Principles), §4 (Hexagonal Architecture)
+last_updated: {{DATE}}
+allowed-tools: Read, Grep, Glob
+---
+
+# Code Quality Skill
+
+**Source**: `docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md` §2, §4 (canonical)
+
+## When to Use
+
+Activate this skill when:
+
+- Reviewing code for SOLID/DRY compliance
+- Checking hexagonal architecture boundaries
+- Validating TypeScript best practices
+- Identifying performance anti-patterns
+- Preparing for code review
+
+**Use skill first**: Validate code against quality patterns.
+
+**Spawn code-reviewer agent when**: Multi-package changes need holistic review, architecture boundary violations require refactoring guidance, or pre-wu:done final review is needed.
+
+## Quick Reference: SOLID Principles
+
+| Principle                 | Check                  | Violation                           |
+| ------------------------- | ---------------------- | ----------------------------------- |
+| **S**ingle Responsibility | One reason to change   | Class handles UI + DB + validation  |
+| **O**pen/Closed           | Extend, don't modify   | Adding `if` branches for new types  |
+| **L**iskov Substitution   | Subtypes replaceable   | Override throws unexpected errors   |
+| **I**nterface Segregation | Small interfaces       | Fat interfaces force unused methods |
+| **D**ependency Inversion  | Depend on abstractions | Direct `new ConcreteService()`      |
+
+## Hexagonal Architecture Boundaries
+
+```
+┌─────────────────────────────────────────────────┐
+│                    apps/                         │
+│  (API routes, UI components, entry points)      │
+├─────────────────────────────────────────────────┤
+│                   application                    │
+│  (Use cases, business logic, orchestration)     │
+│              DEPENDS ON ↓                        │
+├─────────────────────────────────────────────────┤
+│                     ports                        │
+│  (Interfaces ONLY - no implementations)         │
+├─────────────────────────────────────────────────┤
+│                 infrastructure                   │
+│  (Adapters: DB, APIs, external services)        │
+│              IMPLEMENTS ↑                        │
+└─────────────────────────────────────────────────┘
+```
+
+**Forbidden imports**:
+
+```typescript
+// ❌ FORBIDDEN: application importing infrastructure
+import { DatabaseClient } from './infrastructure';
+
+// ✅ CORRECT: application imports port interface only
+import type { DatabasePort } from './ports';
+```
+
+## TypeScript Standards
+
+### Required Patterns
+
+```typescript
+// ✅ Explicit return types on exported functions
+export function calculate(input: Input): Result { ... }
+
+// ✅ Strict null checks - handle undefined
+const value = data?.field ?? defaultValue;
+
+// ✅ Discriminated unions over type assertions
+type Result = { success: true; data: T } | { success: false; error: string };
+
+// ✅ Const assertions for literals
+const MODES = ['default', 'strict', 'loose'] as const;
+type Mode = typeof MODES[number];
+```
+
+### Anti-Patterns to Reject
+
+```typescript
+// ❌ Using `any` - loses type safety
+function process(data: any) { ... }
+
+// ❌ Type assertions without validation
+const user = response as User;
+
+// ❌ Non-null assertions without guards
+const name = user!.name;
+
+// ❌ Implicit any in callbacks
+items.map(item => item.value);  // Missing type annotation
+```
+
+## DRY Validation
+
+**Duplication threshold**: 3+ repetitions → extract
+
+```typescript
+// ❌ Duplicated validation logic
+if (!data.title || data.title.length < 3) { ... }
+// ... repeated in 4 places
+
+// ✅ Extracted to reusable validator
+import { validateTitle } from '@/lib/validators';
+```
+
+## Performance Anti-Patterns
+
+| Pattern              | Problem           | Fix                          |
+| -------------------- | ----------------- | ---------------------------- |
+| N+1 queries          | Loop with DB call | Batch fetch, use `IN` clause |
+| Unbounded lists      | Memory exhaustion | Add pagination, limits       |
+| Missing memoization  | Expensive recalc  | `useMemo`, `React.memo`      |
+| Sync in async path   | Blocks event loop | Use async/await              |
+| Large bundle imports | Slow page load    | Tree-shake, lazy load        |
+
+## Common Violations Checklist
+
+Before approving code, verify:
+
+- [ ] No application → infrastructure imports
+- [ ] No `any` types (use `unknown` + type guards if needed)
+- [ ] No magic numbers (extract to named constants)
+- [ ] No hardcoded strings (use constants or config)
+- [ ] No regex for structured data (use libraries: date-fns, yaml, etc.)
+- [ ] Error handling present (try/catch or Result type)
+- [ ] Tests exist for new/changed code
+- [ ] No console.log (use logger)
+
+## When to Escalate
+
+Flag for human review if:
+
+- Architecture boundary violation requires refactor
+- Performance issue needs profiling
+- Security pattern unclear
+- Business logic ambiguous
+
+## Integration with Other Skills
+
+- **tdd-workflow**: Use together when implementing new features
+- **lumenflow-gates**: Quality checks overlap with gate requirements