@lumenflow/cli 2.2.1 → 2.3.1

package/templates/vendors/claude/.claude/skills/orchestration/SKILL.md.template

@@ -0,0 +1,189 @@
+---
+name: orchestration
+description: Agent orchestration dashboard and initiative execution. Use when running initiatives, monitoring spawned agents, or debugging stuck spawns.
+version: 2.4.0
+source: packages/@lumenflow/cli/src/orchestrate.ts
+last_updated: {{DATE}}
+allowed-tools: Read, Bash, Grep
+---
+
+# Agent Orchestration Skill
+
+## When to Use
+
+Activate this skill when:
+
+- Running multi-WU initiatives (`pnpm orchestrate:initiative`)
+- Monitoring spawned agents for stuck/crashed states
+- Debugging spawn failures or zombie lane locks
+
+**Use skill first**: Run `pnpm orchestrate:monitor` and `pnpm orchestrate:init-status -i <initiative-id>`.
+
+## ⛔ MANDATORY: Never Spawn Task Agents Directly
+
+**CRITICAL PROHIBITION:** When delegating WUs to sub-agents, you MUST use the proper tooling:
+
+```bash
+# ✅ CORRECT: Use orchestrate:initiative for initiatives
+pnpm orchestrate:initiative --initiative INIT-XXX
+
+# ✅ CORRECT: Use wu:spawn for individual WUs
+pnpm wu:spawn --id WU-XXX
+```
+
+**❌ NEVER do this:**
+
+- Directly invoke Task tool for WU execution without using wu:spawn output
+- Manually craft spawn prompts (they miss context loading, TDD directives, constraints)
+- Skip wu:spawn when delegating entire WUs to sub-agents
+
+**Why this matters:**
+
+1. `wu:spawn` generates prompts with context loading preamble, TDD directives, and constraints block
+2. Sub-agents need `wu:claim` (inside spawn prompts) to create proper lane locks and event tracking
+3. Direct Task spawns bypass all safety mechanisms, coordination signals, and spawn registry tracking
+
+**If you see agents running without proper worktree claims, STOP and investigate.**
+
+---
+
+## Commands
+
+```bash
+# Initiative status (compact progress view)
+pnpm orchestrate:init-status -i INIT-001
+
+# Initiative execution
+pnpm orchestrate:initiative --initiative INIT-001 --dry-run   # Show plan
+pnpm orchestrate:initiative --initiative INIT-001             # Execute
+pnpm orchestrate:initiative --initiative INIT-001 --progress  # Progress only
+```
+
+## Monitoring Commands
+
+```bash
+# Monitor spawn registry for stuck agents (default: 30 min threshold)
+pnpm orchestrate:monitor
+
+# Custom threshold
+pnpm orchestrate:monitor --threshold 60
+
+# Filter to initiative
+pnpm orchestrate:monitor --initiative INIT-001
+
+# JSON output for scripting
+pnpm orchestrate:monitor --json
+```
+
+## Spawn Tree Visualisation
+
+```bash
+# View spawn tree for a WU
+pnpm spawn:list --wu WU-XXX
+
+# View all spawns for an initiative
+pnpm spawn:list --initiative INIT-001
+
+# JSON output
+pnpm spawn:list --wu WU-XXX --json
+```
+
+**Spawn states:** `pending`, `completed`, `timeout`, `crashed`, `escalated`
+
+## Self-Healing Signal Flow
+
+When spawns fail, the system uses agent-in-loop recovery:
+
+```
+orchestrate:monitor
+      │
+      ▼
+detectStuckSpawns() ──► recoverStuckSpawn()
+                              │
+                              ▼
+                  [auto-recovery failed?]
+                              │
+                              ▼
+                  signalOrchestratorFailure()
+                              │
+              ┌───────────────┴───────────────┐
+              ▼                               ▼
+     mem:signal broadcast           spawn status = ESCALATED
+              │
+              ▼
+     ORCHESTRATOR INBOX
+     (agent-in-loop)
+              │
+              ▼
+     [orchestrator decides]
+```
+
+**Escalation Levels:**
+
+| Attempt | Severity | Action         | Outcome                                 |
+| ------- | -------- | -------------- | --------------------------------------- |
+| 1st     | warning  | retry          | Re-spawn with same params               |
+| 2nd     | error    | block          | Mark WU blocked, notify parallel agents |
+| 3rd+    | critical | human_escalate | Create Bug WU, alert human              |
+
+**Check orchestrator inbox:**
+
+```bash
+pnpm mem:inbox --wu WU-XXX --type spawn_failure
+```
+
+## Initiative Orchestration
+
+**Wave-based execution**:
+
+- Groups WUs by dependency depth (Kahn's algorithm)
+- Parallel spawning within waves
+- Checkpoint mode auto-enabled for >3 WUs or >2 waves
+
+```bash
+pnpm orchestrate:initiative -i INIT-009 -c     # Explicit checkpoint
+pnpm orchestrate:initiative -i INIT-009        # Auto-detects
+```
+
+**Checkpoint mode**:
+
+- Spawns one wave then exits (no polling)
+- Writes manifest to `.beacon/artifacts/waves/`
+- Idempotent re-runs advance to next wave
+
+## Recovery Suggestions
+
+When issues are detected, `orchestrate:monitor` outputs copy-pasteable commands:
+
+```bash
+# For stuck spawns
+pnpm wu:block --id WU-XXX --reason "Spawn stuck for 45 minutes"
+
+# For zombie lane locks
+pnpm lane:unlock "Operations: Tooling" --reason "Zombie lock (PID 12345 not running)"
+
+# After recovery, re-spawn
+pnpm wu:unblock --id WU-XXX
+pnpm wu:spawn --id WU-XXX
+```
+
+## Decision Tree
+
+```
+Starting WU?
+├── Run: pnpm orchestrate:monitor
+└── Review agent status and recommendations
+
+Initiative with multiple WUs?
+├── Run: pnpm orchestrate:initiative -i INIT-XXX --dry-run
+└── Review wave plan, then execute
+
+Agent appears stuck or crashed?
+├── Run: pnpm orchestrate:monitor
+├── Check spawn tree: pnpm spawn:list --wu WU-XXX
+└── Follow recovery suggestions in output
+```
+
+---
+
+**Full docs**: [execution-memory skill](../execution-memory/SKILL.md)

package/templates/vendors/claude/.claude/skills/tdd-workflow/SKILL.md.template

@@ -0,0 +1,139 @@
+---
+name: tdd-workflow
+description: Test-driven development workflow. RED-GREEN-REFACTOR applies to all code; 5-step ports-first for hex architecture. Use when implementing new features, writing tests, or working with hexagonal architecture.
+version: 2.1.0
+source: docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
+source_sections: §5 (AI-TDD 5-Step Workflow), §4 (Hexagonal Architecture)
+last_updated: {{DATE}}
+allowed-tools: Read, Write, Edit, Bash, Grep
+---
+
+# TDD Workflow Skill
+
+**Source**: `docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md` §5 (canonical)
+
+## When to Use
+
+Activate this skill when:
+
+- Implementing new features (write tests first)
+- Working with hexagonal architecture (ports-first pattern)
+- Need to understand which layer code belongs in
+- Writing use cases with dependency injection
+
+**Use skill first**: Follow RED-GREEN-REFACTOR cycle and 5-step AI-TDD pattern.
+
+**Spawn test-engineer agent when**: Complex test scenarios require golden dataset creation, VCR cassette setup needed, or coverage gaps require investigation.
+
+## Universal TDD: RED-GREEN-REFACTOR
+
+All code follows this cycle:
+
+1. **RED**: Write failing test defining expected behaviour
+2. **GREEN**: Write minimal code to pass
+3. **REFACTOR**: Improve quality, keep tests green
+
+**Coverage**: >= 90% for application code.
+
+## 5-Step AI-TDD (Hex Architecture)
+
+```
+Step 1: Define Ports     → @lumenflow/ports (interfaces only)
+Step 2: Write Tests      → @lumenflow/application/__tests__ (mocks)
+Step 3: Implement        → @lumenflow/application/usecases
+Step 4: Run Tests        → RED → GREEN
+Step 5: Create Adapter   → @lumenflow/infrastructure
+```
+
+## Architecture Boundaries
+
+**Allowed**:
+
+- Application → Ports (use interfaces)
+- Infrastructure → Ports (implement interfaces)
+- Apps → Application + Infrastructure (wiring)
+
+**Forbidden**:
+
+- Application → Infrastructure (blocked by ESLint)
+
+## Dependency Injection Pattern
+
+```typescript
+// Use case accepts deps first, input second
+export async function exampleUseCase(
+  deps: { service: ExampleService; observability: ObservabilityService },
+  input: { id: string },
+): Promise<ServiceResponse<Result>> {
+  const span = deps.observability.startSpan('usecase.example');
+  try {
+    const result = await deps.service.doSomething(input);
+    span.end();
+    return result;
+  } catch (error) {
+    deps.observability.recordError(error as Error);
+    span.end();
+    return { success: false, error: 'Operation failed', code: 'OPERATION_ERROR' };
+  }
+}
+```
+
+## Test Pattern
+
+```typescript
+describe('exampleUseCase', () => {
+  let mockService: ExampleService;
+
+  beforeEach(() => {
+    mockService = { doSomething: vi.fn() };
+  });
+
+  it('should handle happy path', async () => {
+    vi.mocked(mockService.doSomething).mockResolvedValue({ success: true, data: {} });
+    const result = await exampleUseCase({ service: mockService }, { id: '1' });
+    expect(result.success).toBe(true);
+  });
+
+  it('should handle errors', async () => {
+    vi.mocked(mockService.doSomething).mockRejectedValue(new Error('fail'));
+    const result = await exampleUseCase({ service: mockService }, { id: '1' });
+    expect(result.success).toBe(false);
+  });
+});
+```
+
+## Decision Trees
+
+**Which Layer?**
+
+- Interface definition → ports
+- Business logic → application
+- External services → infrastructure
+- UI → apps
+
+**Need a Port?**
+
+- Testable with mocks? → YES
+- Swappable implementation? → YES
+- Pure utility? → NO
+
+## Commands
+
+```bash
+pnpm test                    # Run all tests
+pnpm test --filter <pkg>     # Run tests for specific package
+pnpm test -- --watch         # Watch mode
+pnpm test:coverage           # Check coverage
+```
+
+## Definition of Done
+
+- [ ] Ports defined
+- [ ] Tests written BEFORE implementation
+- [ ] Coverage >= 90%
+- [ ] No application → infrastructure imports
+- [ ] Gates pass
+
+---
+
+**Full spec**: [lumenflow-complete.md §5](../../../docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md)

package/templates/vendors/claude/.claude/skills/worktree-discipline/SKILL.md.template

@@ -0,0 +1,138 @@
+---
+name: worktree-discipline
+description: Prevents the "absolute path trap" in Write/Edit/Read tools. Use when working in worktrees, before file operations, or when changes don't appear in git status.
+version: 2.0.0
+source: docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
+source_sections: §2.4 (Worktree Discipline), §4.1 (Tool Usage)
+last_updated: {{DATE}}
+allowed-tools: Read, Bash, Grep
+---
+
+# Worktree Discipline: Absolute Path Trap Prevention
+
+**Purpose**: Prevent AI agents from bypassing worktree isolation via absolute file paths.
+
+**For full worktree workflow**: See `wu-lifecycle` skill or `lumenflow-complete.md` §2.4.
+
+## The Absolute Path Trap
+
+**Problem**: AI agents using Write/Edit/Read tools can bypass worktree isolation by passing absolute paths. Even when your shell is in the worktree, absolute paths target the main checkout.
+
+### Example
+
+```typescript
+// Shell: cd worktrees/operations-wu-427
+
+// WRONG - Absolute path bypasses worktree
+Write({
+  file_path: '/home/user/source/project/apps/web/src/validator.ts',
+  content: '...',
+});
+// Result: Written to MAIN checkout, not worktree!
+
+// RIGHT - Relative path respects worktree
+Write({
+  file_path: 'apps/web/src/validator.ts',
+  content: '...',
+});
+// Result: Written to worktree correctly
+```
+
+## Pre-Operation Checklist
+
+**Before ANY Write/Edit/Read operation:**
+
+1. **Verify working directory**:
+
+   ```bash
+   pwd
+   # Must show: .../worktrees/<lane>-wu-xxx
+   ```
+
+2. **Check file path format**:
+
+   | Pattern                           | Safe? | Example                  |
+   | --------------------------------- | ----- | ------------------------ |
+   | Starts with `/home/` or `/Users/` | NO    | `/home/user/.../file.ts` |
+   | Contains full repo path           | NO    | `/source/project/...`    |
+   | Starts with package name          | YES   | `apps/web/src/...`       |
+   | Starts with `./` or `../`         | YES   | `./src/lib/...`          |
+   | Just filename                     | YES   | `README.md`              |
+
+3. **Use relative paths for ALL file operations**
+
+## Quick Detection
+
+**Red flags** (you're about to fall into the trap):
+
+- Path starts with `/home/` or `/Users/`
+- Path contains organisation/project name
+- Path length > 50 characters (suspiciously long)
+
+**Safe patterns**:
+
+- `apps/web/src/...`
+- `packages/@lumenflow/...`
+- `tools/...`
+- `docs/...`
+
+## Troubleshooting
+
+### "Changes not showing in git status"
+
+**Cause**: Absolute paths wrote to main instead of worktree.
+
+**Fix**:
+
+```bash
+# Check where changes landed
+cd /path/to/main && git status
+
+# If changes are in main, move them
+git stash
+cd worktrees/<lane>-wu-xxx
+git stash pop
+
+# Re-apply with relative paths
+```
+
+### "Pre-commit hook blocked my commit"
+
+**Cause**: Attempted WU commit from main checkout.
+
+**Fix**: Move to worktree, commit there:
+
+```bash
+cd worktrees/<lane>-wu-xxx
+git add . && git commit -m "..."
+```
+
+## Decision Tree
+
+```
+About to use Write/Edit/Read?
+├─ Check: Am I in a worktree?
+│   ├─ YES → Use RELATIVE paths only
+│   └─ NO → Did I claim a WU?
+│       ├─ YES → cd worktrees/<lane>-wu-xxx first
+│       └─ NO → Claim WU or use docs-only paths
+└─ Path starts with "/" ?
+    ├─ YES → STOP! Convert to relative path
+    └─ NO → Safe to proceed
+```
+
+## Golden Rules
+
+1. **Always verify pwd** before file operations
+2. **Never use absolute paths** in Write/Edit/Read tools
+3. **When in doubt, use relative paths**
+
+## Cross-References
+
+- **Full worktree workflow**: `wu-lifecycle` skill
+- **Git command restrictions**: `lumenflow-complete.md` §2.4
+
+## Version History
+
+- **v2.0.0** ({{DATE}}): Refactored to focus on absolute path trap (per Anthropic one-capability-per-skill guideline)
+- **v1.0.0** ({{DATE}}): Initial skill from lumenflow-complete.md

package/templates/vendors/claude/.claude/skills/wu-lifecycle/SKILL.md.template

@@ -0,0 +1,106 @@
+---
+name: wu-lifecycle
+description: Work Unit claim/block/done workflow automation. Use when claiming WUs, blocking/unblocking, running wu:done, or understanding WU state transitions.
+version: 2.1.0
+source: docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
+source_sections: §2.4, §6 (WU Lifecycle)
+last_updated: {{DATE}}
+allowed-tools: Read, Bash, Grep
+---
+
+# WU Lifecycle Skill
+
+**Source**: `docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md` §2.4, §6 (canonical)
+
+## When to Use
+
+Activate this skill when:
+
+- Claiming a WU (`pnpm wu:claim`)
+- Blocking/unblocking WUs due to dependencies
+- Running `wu:done` completion workflow
+- Understanding WU state machine transitions
+
+**Use skill first**: Follow the core commands and worktree discipline patterns.
+
+**Spawn lumenflow-pm agent when**: WU lifecycle issues require investigation, coordination across multiple blocked WUs needed, or worktree state requires recovery.
+
+## State Machine
+
+```
+ready → in_progress → waiting/blocked → done
+```
+
+## Core Commands
+
+```bash
+# Claim WU
+pnpm wu:claim --id WU-XXX --lane <lane>
+cd worktrees/<lane>-wu-xxx   # IMMEDIATELY
+
+# Complete WU (from main)
+cd ../..
+pnpm wu:done --id WU-XXX
+
+# Block/Unblock
+pnpm wu:block --id WU-XXX --reason "..."
+pnpm wu:unblock --id WU-XXX
+
+# Create (full spec)
+pnpm wu:create --id WU-999 --lane "Operations" --title "Add feature" \
+  --description "Context: ... Problem: ... Solution: ..." \
+  --acceptance "Feature works" --code-paths "src/a.ts" --validate
+
+# Edit spec
+pnpm wu:edit --id WU-XXX --description "..." --acceptance "..."
+
+# Maintenance
+pnpm wu:prune --execute     # Clean stale worktrees
+pnpm wu:cleanup --id WU-XXX # After PR merge
+```
+
+## wu:done Workflow
+
+1. Runs gates in worktree
+2. Fast-forward merge to main
+3. Creates `.beacon/stamps/WU-XXX.done`
+4. Updates backlog.md + status.md
+5. Removes worktree
+
+**GitHub rules REJECT merge commits**. Never `git merge` on main.
+
+## Worktree Discipline
+
+After `wu:claim`:
+
+- `cd worktrees/<lane>-wu-xxx` immediately
+- Use relative paths (never absolute)
+- Main is read-only
+
+**Blocked on main**: `reset --hard`, `stash`, `clean -fd`, manual merge
+
+## Skip Gates (Emergency)
+
+Only when pre-existing failures:
+
+```bash
+pnpm wu:done --id WU-XXX --skip-gates --reason "Pre-existing" --fix-wu WU-YYY
+```
+
+## Fix-in-Place vs Bug WU
+
+**Create Bug WU if ANY true**:
+
+- Bug in different `code_paths`
+- Fix >10 lines
+- Bug doesn't block acceptance criteria
+
+**Fix in place if ALL true**:
+
+- Bug blocks your acceptance criteria
+- Bug in your `code_paths`
+- Fix <=10 lines
+
+---
+
+**Full spec**: [lumenflow-complete.md](../../../docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md)

package/templates/vendors/cline/.clinerules.template

@@ -0,0 +1,53 @@
+# Cline LumenFlow Rules
+
+This project uses LumenFlow workflow. See [LUMENFLOW.md](LUMENFLOW.md) for complete documentation.
+
+## Critical Rules
+
+1. **Always run wu:done** - After gates pass, run `pnpm wu:done --id WU-XXX`
+2. **Work in worktrees** - After `wu:claim`, work only in the worktree
+3. **Never bypass hooks** - No `--no-verify`
+4. **TDD** - Write tests first
+
+## Forbidden Commands
+
+- `git reset --hard`
+- `git push --force`
+- `git stash` (on main)
+- `--no-verify`
+
+## Quick Reference
+
+```bash
+# Claim WU
+pnpm wu:claim --id WU-XXX --lane <Lane>
+cd worktrees/<lane>-wu-xxx
+
+# Run gates
+pnpm gates
+
+# Complete (from main)
+cd {{PROJECT_ROOT}}
+pnpm wu:done --id WU-XXX
+```
+
+> **Complete CLI reference (60+ commands):** See [quick-ref-commands.md](ai/onboarding/quick-ref-commands.md)
+
+---
+
+## Workflow Summary
+
+| Step | Command |
+|------|---------|
+| 1. Create WU | `pnpm wu:create --id WU-XXX ...` |
+| 2. Claim | `pnpm wu:claim --id WU-XXX --lane <Lane>` |
+| 3. Work | `cd worktrees/<lane>-wu-xxx` |
+| 4. Gates | `pnpm gates` |
+| 5. Complete | `pnpm wu:done --id WU-XXX` |
+
+## Safety Reminders
+
+- **Worktree Discipline**: After claiming a WU, immediately `cd` to the worktree
+- **Main is read-only**: Do not edit files in the main checkout after claiming
+- **Gates before done**: Always run `pnpm gates` before `wu:done`
+- **Never skip hooks**: The `--no-verify` flag is forbidden

package/templates/vendors/cursor/.cursor/rules/lumenflow.md.template

@@ -0,0 +1,34 @@
+# Cursor LumenFlow Rules
+
+This project uses LumenFlow workflow. See [LUMENFLOW.md](../../LUMENFLOW.md) for complete documentation.
+
+## Critical Rules
+
+1. **Always run wu:done** - After gates pass, run `pnpm wu:done --id WU-XXX`
+2. **Work in worktrees** - After `wu:claim`, work only in the worktree
+3. **Never bypass hooks** - No `--no-verify`
+4. **TDD** - Write tests first
+
+## Forbidden Commands
+
+- `git reset --hard`
+- `git push --force`
+- `git stash` (on main)
+- `--no-verify`
+
+## Quick Reference
+
+```bash
+# Claim WU
+pnpm wu:claim --id WU-XXX --lane <Lane>
+cd worktrees/<lane>-wu-xxx
+
+# Run gates
+pnpm gates
+
+# Complete (from main)
+cd {{PROJECT_ROOT}}
+pnpm wu:done --id WU-XXX
+```
+
+> **Complete CLI reference (60+ commands):** See [quick-ref-commands.md](../../ai/onboarding/quick-ref-commands.md)

package/templates/vendors/cursor/.cursor/rules.md.template

@@ -0,0 +1,28 @@
+# Cursor Rules
+
+This project uses LumenFlow workflow. See [LUMENFLOW.md](../LUMENFLOW.md).
+
+## Critical Rules
+
+1. **Always run wu:done** - After gates pass, run `pnpm wu:done --id WU-XXX`
+2. **Work in worktrees** - After `wu:claim`, work only in the worktree
+3. **Never bypass hooks** - No `--no-verify`
+4. **TDD** - Write tests first
+
+## Forbidden Commands
+
+- `git reset --hard`
+- `git push --force`
+- `git stash` (on main)
+- `--no-verify`
+
+## Quick Start
+
+```bash
+pnpm wu:claim --id WU-XXX --lane <Lane>
+cd worktrees/<lane>-wu-xxx
+# ... work ...
+pnpm gates
+cd {{PROJECT_ROOT}}
+pnpm wu:done --id WU-XXX
+```