@lumenflow/cli 2.2.2 → 2.3.1

package/templates/vendors/claude/.claude/skills/initiative-management/SKILL.md.template

@@ -0,0 +1,164 @@
+---
+name: initiative-management
+description: Create, track, and coordinate multi-phase initiatives spanning multiple WUs and lanes. Use when working with INIT-NNN IDs, multi-phase projects, cross-lane coordination, or asking about initiative status.
+version: 1.1.0
+source: packages/@lumenflow/cli/src/initiative-*.ts
+last_updated: {{DATE}}
+allowed-tools: Read, Bash, Grep
+---
+
+# Initiative Management Skill
+
+Guides agents through creating, tracking, and coordinating multi-phase initiatives.
+
+## When This Skill Activates
+
+- User mentions "initiative", "INIT-", or initiative IDs
+- User asks about multi-phase projects or cross-lane coordination
+- User wants to group related WUs under a common goal
+- User asks about initiative status or progress
+
+## Available Commands
+
+### Create an Initiative
+
+```bash
+pnpm initiative:create --id INIT-001 --title "Initiative Title" --description "Description" --wus WU-001,WU-002,WU-003
+```
+
+Creates a new initiative that groups multiple WUs together.
+
+### List All Initiatives
+
+```bash
+pnpm initiative:list
+```
+
+Shows all active initiatives with their status and linked WUs.
+
+### Check Initiative Status
+
+```bash
+pnpm initiative:status --id INIT-001
+```
+
+Shows detailed status of a specific initiative including:
+
+- Linked WUs and their completion status
+- Overall progress percentage
+- Cross-lane dependencies
+- Blockers affecting the initiative
+
+### Link a WU to an Initiative
+
+```bash
+pnpm initiative:add-wu --initiative INIT-001 --wu WU-123
+```
+
+Links an existing WU to an initiative bidirectionally:
+
+- Adds `initiative: INIT-001` field to WU YAML
+- Adds WU ID to initiative `wus:` array
+- Idempotent: no error if link already exists
+- Errors if WU is already linked to a different initiative
+
+### Edit an Initiative
+
+```bash
+# Update status
+pnpm initiative:edit --id INIT-001 --status in_progress
+
+# Set blocking initiative
+pnpm initiative:edit --id INIT-001 --blocked-by INIT-002 --blocked-reason "Waiting for Phase 1"
+
+# Remove blocking
+pnpm initiative:edit --id INIT-001 --unblock
+
+# Add lane
+pnpm initiative:edit --id INIT-001 --add-lane "Operations: Tooling"
+
+# Append note
+pnpm initiative:edit --id INIT-001 --notes "Phase 2 started"
+
+# Combine multiple edits
+pnpm initiative:edit --id INIT-001 --status in_progress --add-lane "Operations: Tooling" --notes "Work started"
+```
+
+Edits initiative YAML fields atomically using micro-worktree isolation:
+
+- `--status`: Update status (draft, open, in_progress, done, archived)
+- `--blocked-by` + `--blocked-reason`: Set blocking initiative (reason required)
+- `--unblock`: Remove blocked_by and blocked_reason fields
+- `--add-lane`: Append lane (no duplicates, repeatable)
+- `--notes`: Append note to notes array
+
+## Initiative Structure
+
+Initiatives are defined in `docs/04-operations/tasks/initiatives/INIT-001.yaml`:
+
+```yaml
+id: INIT-001
+slug: initiative-slug
+title: 'Initiative Title'
+description: |
+  Multi-line description of the initiative goal
+status: draft # draft | open | in_progress | done | archived
+priority: P2 # P0 | P1 | P2 | P3
+owner: team-or-individual # optional
+created: 2025-MM-DD
+target_date: 2025-MM-DD # optional
+phases: [] # optional ordered phases
+success_metrics: [] # optional completion criteria
+labels: [] # optional cross-cutting tags
+wus: # Linked WU IDs (bidirectional with WU.initiative field)
+  - WU-001
+  - WU-002
+  - WU-003
+```
+
+## Cross-Lane Coordination
+
+Initiatives often span multiple lanes. Key coordination patterns:
+
+1. **Phase dependencies**: WU-002 in one lane depends on WU-001 in another
+2. **Parallel execution**: Multiple lanes work simultaneously on independent WUs
+3. **Integration points**: Final WU combines work from all lanes
+
+## Spawning Sub-Agents for Initiative WUs (MANDATORY)
+
+When orchestrating an initiative with multiple WUs, use `wu:spawn` to generate complete Task invocations:
+
+```bash
+# For each WU being delegated to a sub-agent:
+pnpm wu:spawn --id WU-1501   # Generates Task invocation with full context
+pnpm wu:spawn --id WU-1502
+pnpm wu:spawn --id WU-1503
+```
+
+### Orchestration Pattern
+
+1. **Generate prompts**: Run `pnpm wu:spawn --id WU-XXX` for each WU
+2. **Spawn in parallel**: Use Task tool with `run_in_background: true`
+3. **Monitor progress**: Use `pnpm mem:inbox --since 30m` (NOT TaskOutput - causes context explosion)
+4. **Synthesise**: Combine results from all sub-agents
+
+### What wu:spawn Provides
+
+- Context loading preamble (LUMENFLOW.md, README, lumenflow-complete, WU YAML)
+- Full acceptance criteria from WU spec
+- Constraints block at end (per "Lost in the Middle" research)
+
+### When NOT to Use wu:spawn
+
+- Helper agents for the orchestrator's own WU (use inline context)
+- Validation agents checking orchestrator's work
+- Explore agents for codebase research
+
+See [agent-invocation-guide.md](../../../docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-invocation-guide.md) for decision tree.
+
+## Best Practices
+
+1. **Keep initiatives focused**: 3-10 WUs per initiative
+2. **Clear dependencies**: Document which WUs block others
+3. **Regular status updates**: Update initiative notes as work progresses
+4. **Lane alignment**: Ensure each WU is in the appropriate lane

package/templates/vendors/claude/.claude/skills/library-first/SKILL.md.template

@@ -0,0 +1,98 @@
+---
+name: library-first
+description: Validate well-known libraries solve your problem before custom code. Use when implementing parsing, dates, validation, or any non-trivial logic.
+version: 1.0.0
+source: docs/04-operations/_frameworks/lumenflow/agent/onboarding/library-first-toolkit.md
+source_sections: Validation Protocol, Decision Tree, Context7 Query Templates
+last_updated: {{DATE}}
+allowed-tools: Read, mcp__context7__*
+---
+
+# Library-First Skill
+
+**Source**: `docs/04-operations/_frameworks/lumenflow/agent/onboarding/library-first-toolkit.md` (canonical)
+
+Search for libraries BEFORE writing custom code. Custom implementations create debt, violate DRY/SOLID, and introduce bugs that libraries have already solved.
+
+## Quick Reference: Validation Protocol
+
+1. **Search context7**: `"<use case> library <language>"`
+2. **Check npm trends**: >10k weekly downloads
+3. **Verify maintenance**: Last commit <12 months, issue response <7 days
+4. **Document in WU notes**: Libraries considered + justification
+
+## Context7 Query Patterns
+
+```
+# Generic
+"<functionality> library <language>"
+"<language> <functionality> npm package"
+
+# Common use cases
+"markdown parser library JavaScript"       → remark, marked
+"date manipulation library TypeScript"     → date-fns, dayjs
+"YAML validation library Node.js"          → zod, ajv, joi
+"schema validation library TypeScript"     → zod
+"git operations library Node.js"           → simple-git
+```
+
+## Decision Tree
+
+```
+Found library covering ≥70%?
+├─ YES, covers 100% → Use directly ✅
+├─ YES, covers 70-99% → Thin wrapper pattern ✅
+│   └─ Document gaps in WU notes
+└─ NO → Check requirements:
+    ├─ Searched ≥3 libraries? NO → STOP, search more ⛔
+    ├─ Complex logic (parsing, dates, crypto)? → STOP, find library ⛔
+    └─ Simple (<50 LOC, no edge cases)? → Custom OK with justification ✅
+```
+
+## Anti-Patterns (NEVER DO)
+
+| Anti-Pattern                      | Use Instead                                   |
+| --------------------------------- | --------------------------------------------- |
+| Regex for markdown/HTML/JSON/YAML | Grammar-based parsers (remark, cheerio, yaml) |
+| Custom date/time parsing          | date-fns, dayjs, luxon                        |
+| Reimplementing array/object utils | lodash or native methods                      |
+| Custom HTTP clients               | axios, fetch with thin adapter                |
+| Custom cryptography               | Node.js crypto, bcrypt                        |
+
+## Validation Criteria
+
+| Criterion        | Threshold                        |
+| ---------------- | -------------------------------- |
+| Weekly downloads | >10k (npm trends)                |
+| Last updated     | <12 months                       |
+| Issue response   | <7 days                          |
+| TypeScript types | Available (`@types/*` or native) |
+| Security         | Documented policy or audit       |
+
+## MCP Tool Reference
+
+| Tool                                | Use Case                         |
+| ----------------------------------- | -------------------------------- |
+| `mcp__context7__resolve-library-id` | Find library ID from name        |
+| `mcp__context7__query-docs`         | Get documentation for validation |
+
+**Note**: MCP tools provide connectivity; this skill provides procedural knowledge for using them correctly.
+
+## WU Notes Template
+
+```yaml
+library_decisions:
+  - use_case: 'YAML validation'
+    libraries_considered: ['ajv', 'joi', 'zod']
+    selected: 'zod'
+    reason: 'TypeScript-native, 100KB smaller, composable'
+```
+
+## Integration with Other Skills
+
+- **tdd-workflow**: Library selection happens BEFORE writing tests
+- **code-quality**: Library-first prevents DRY violations
+
+---
+
+**Red Flags**: If you're writing regex for structured formats, date parsing, or reimplementing utilities — STOP and search for a library.

package/templates/vendors/claude/.claude/skills/lumenflow-gates/SKILL.md.template

@@ -0,0 +1,87 @@
+---
+name: lumenflow-gates
+description: Quality gates troubleshooting (format, lint, typecheck, tests). Use when gates fail, debugging format/lint/typecheck errors, or determining if failure is from your changes vs pre-existing.
+version: 2.1.0
+source: docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
+source_sections: §6.4 (Validation & Gates)
+last_updated: {{DATE}}
+allowed-tools: Read, Bash, Grep
+---
+
+# LumenFlow Gates Skill
+
+**Source**: `docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md` §6.4 (canonical)
+
+## When to Use
+
+Activate this skill when:
+
+- `pnpm gates` fails with format, lint, or typecheck errors
+- Need to determine if failure is from your changes vs pre-existing
+- Debugging test failures or coverage issues
+- Deciding whether to use `--skip-gates` (emergency only)
+
+**Use skill first**: Follow the decision tree and fix patterns in this skill.
+
+**Spawn lumenflow-enforcer agent when**: Complex gate failures span multiple packages, pre-existing failures require investigation, or DoD validation needs holistic review.
+
+## Gate Sequence
+
+```
+pnpm gates = format:check → lint → typecheck → spec:linter → tests
+```
+
+## Fix Patterns
+
+| Gate      | Auto-fix        | Manual                              |
+| --------- | --------------- | ----------------------------------- |
+| Format    | `pnpm format`   | -                                   |
+| Lint      | `pnpm lint:fix` | Fix reported issues                 |
+| Typecheck | -               | Fix type errors (first error first) |
+| Tests     | -               | Debug, fix mocks, update snapshots  |
+
+## Decision Tree
+
+**Gate failed. Is it from YOUR changes?**
+
+```bash
+git checkout main && pnpm gates  # Check main
+# Pass on main → Your change caused it → Fix it
+# Fail on main → Pre-existing → Consider --skip-gates
+```
+
+**Can you fix it?**
+
+- In your `code_paths`, <=10 lines → Fix in place
+- Different paths, >10 lines → Create Bug WU
+
+## Skip Gates (Emergency)
+
+Only when pre-existing failures:
+
+```bash
+pnpm wu:done --id WU-XXX --skip-gates --reason "Pre-existing" --fix-wu WU-YYY
+```
+
+## Common Lint Fixes
+
+```
+no-explicit-any → Add proper types
+no-unused-vars → Remove or prefix with _
+no-restricted-paths → Check hex boundaries (application cannot import infrastructure)
+exhaustive-deps → Add missing dependencies
+```
+
+## Validation Commands
+
+```bash
+pnpm gates                # All gates
+pnpm gates -- --docs-only # Docs WUs
+pnpm validate:context     # Context validation
+pnpm spec:linter          # Spec validation
+pnpm tasks:validate       # WU YAML validation
+```
+
+---
+
+**Full spec**: [lumenflow-complete.md §6.4](../../../docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md)

package/templates/vendors/claude/.claude/skills/multi-agent-coordination/SKILL.md.template

@@ -0,0 +1,84 @@
+---
+name: multi-agent-coordination
+description: Coordinate multiple agents on parallel WUs using git branch locking. Use when spawning sub-agents, coordinating parallel WUs, or handling abandoned WU recovery.
+version: 2.1.0
+source: docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-invocation-guide.md
+last_updated: {{DATE}}
+allowed-tools: Read, Bash, Grep
+---
+
+# Multi-Agent Coordination Skill
+
+## When to Use
+
+Activate this skill when:
+
+- Spawning sub-agents for WU delegation
+- Coordinating parallel WUs across different lanes
+- Handling abandoned WU recovery
+- Using memory layer for inter-agent signals
+
+**Use skill first**: Follow the coordination patterns for spawning and signalling.
+
+## Git Branch Locking
+
+- Branch `lane/operations/wu-700` exists = WU claimed
+- Git prevents duplicate branches = automatic locking
+- No heartbeats, no session files
+
+## Spawning Sub-Agents
+
+**Use wu:spawn** when delegating entire WU:
+
+```bash
+pnpm wu:spawn --id WU-XXX              # Standard
+pnpm wu:spawn --id WU-XXX --thinking   # Complex WUs
+```
+
+**DON'T use wu:spawn** for helper agents (code-reviewer, test-engineer) on YOUR WU.
+
+## Parallel Spawning
+
+**Different lanes**: Safe to parallelize (`run_in_background: true`)
+**Same lane**: Sequential only (WIP=1 rule)
+
+```typescript
+// Parallel validation (single message)
+Task({ subagent_type: 'code-reviewer', run_in_background: true, prompt: '...' });
+Task({ subagent_type: 'test-engineer', run_in_background: true, prompt: '...' });
+```
+
+## Handling Abandoned WUs
+
+```bash
+# Monitor for stuck agents
+pnpm orchestrate:monitor
+
+# Review checkpoints
+pnpm mem:ready --wu WU-XXX
+
+# Take over (requires coordination)
+cd worktrees/<lane>-wu-XXX
+# Review uncommitted changes, commit, continue
+```
+
+## Memory Layer Coordination
+
+```bash
+pnpm mem:signal "WU-XXX complete" --wu WU-XXX  # Broadcast
+pnpm mem:inbox --lane Operations               # Check updates
+pnpm mem:checkpoint "Ready for handoff" --wu WU-XXX  # Handoff
+```
+
+## Common Patterns
+
+| Scenario           | Approach                                   |
+| ------------------ | ------------------------------------------ |
+| Sequential handoff | Block WU, other agent unblocks             |
+| Parallel subtasks  | Create separate WUs, work in parallel      |
+| Multi-lane feature | Create dependency WUs, complete deps first |
+| Research spike     | `type: spike`, `lane: Discovery`           |
+
+---
+
+**Full docs**: [agent-invocation-guide.md](../../../docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-invocation-guide.md) | [execution-memory skill](../execution-memory/SKILL.md)

package/templates/vendors/claude/.claude/skills/ops-maintenance/SKILL.md.template

@@ -0,0 +1,254 @@
+---
+name: ops-maintenance
+description: Run maintenance tasks, generate metrics reports, validate configurations, and manage agent sessions. Use for wu:prune, metrics reports, validation failures, agent sessions, backlog health checks, or bottleneck analysis.
+version: 1.1.0
+source: packages/@lumenflow/cli/src/
+last_updated: {{DATE}}
+allowed-tools: Read, Bash, Grep
+---
+
+# Operations & Maintenance Skill
+
+Guides agents through maintenance tasks, metrics reporting, validation, and agent session management.
+
+## When This Skill Activates
+
+- User mentions maintenance, cleanup, or pruning
+- User asks about metrics, DORA, or flow reports
+- User encounters validation errors (tasks:validate, spec:linter)
+- User asks about agent sessions
+- User wants to check backlog health
+
+## Maintenance Commands
+
+### Worktree Cleanup
+
+```bash
+# Dry-run (shows what would be pruned)
+pnpm wu:prune
+
+# Execute cleanup
+pnpm wu:prune --execute
+```
+
+Removes stale/orphaned worktrees from completed or abandoned WUs.
+
+### Backlog Cleanup
+
+```bash
+# Dry-run
+pnpm backlog:prune
+
+# Execute
+pnpm backlog:prune --execute
+```
+
+Identifies stale WUs (>60 days inactive) for review or archival.
+
+### Documentation Link Check
+
+```bash
+pnpm docs:linkcheck
+```
+
+Validates all internal links in documentation files.
+
+## Metrics & Reporting
+
+### Lane Metrics
+
+```bash
+pnpm metrics:lanes
+```
+
+Shows per-lane statistics:
+
+- WUs completed per lane
+- Average cycle time
+- Current WIP status
+
+### DORA Metrics
+
+```bash
+pnpm metrics:dora
+```
+
+Shows DevOps Research and Assessment metrics:
+
+- Deployment frequency (WUs/week)
+- Lead time (ready → done)
+- Change failure rate
+- Mean time to recovery (MTTR)
+
+### Flow Metrics
+
+```bash
+pnpm metrics:flow
+```
+
+Shows flow efficiency:
+
+- Cycle time distribution
+- Blocked time percentage
+- Throughput trends
+
+### Flow Report
+
+```bash
+pnpm flow:report
+```
+
+Generates comprehensive flow analysis report.
+
+### Flow Bottlenecks
+
+```bash
+# Show top 10 bottleneck WUs (ranked by downstream impact)
+pnpm flow:bottlenecks
+
+# Output in JSON format for scripting
+pnpm flow:bottlenecks --json
+
+# Show critical path (longest dependency chain)
+pnpm flow:bottlenecks --critical-path
+
+# Scope analysis to specific initiative
+pnpm flow:bottlenecks --initiative INIT-010
+
+# Adjust number of results (default: 10)
+pnpm flow:bottlenecks --limit 20
+```
+
+Identifies WUs that block the most downstream work:
+
+- **Impact score**: Count of WUs directly and indirectly blocked
+- **Critical path**: Longest chain of dependencies (schedule risk)
+- **Bottleneck ranking**: Prioritise completing these for maximum unblocking
+
+Use with `orchestrate:initiative` which highlights bottlenecks in execution plans, or `orchestrate:monitor` to track agent progress.
+
+## Validation Commands
+
+### Task Validation
+
+```bash
+pnpm tasks:validate
+```
+
+Validates all WU YAML files:
+
+- Required fields present
+- Status transitions valid
+- Lane assignments correct
+
+### Backlog Sync Validation
+
+```bash
+pnpm tasks:validate:backlog
+```
+
+Ensures backlog.md and status.md are synchronized with WU YAMLs.
+
+### Spec Linter
+
+```bash
+pnpm spec:linter
+```
+
+Validates specification files against schema.
+
+### Board Validation
+
+```bash
+pnpm board:validate
+```
+
+Validates kanban board state consistency.
+
+### Context Validation
+
+```bash
+pnpm validate:context
+```
+
+Checks for redundancy and reference integrity in context files.
+
+## Agent Session Management
+
+### Start Session
+
+```bash
+pnpm agent:session start --wu WU-XXX --tier 2
+```
+
+Starts telemetry session for a WU. Tier options:
+
+- `1`: Quick context (~500 tokens)
+- `2`: Standard context (~2,800 tokens)
+- `3`: Full context (~18,000 tokens)
+
+### End Session
+
+```bash
+pnpm agent:session:end
+```
+
+Ends current session and appends metadata to WU YAML.
+
+### Log Issue
+
+```bash
+pnpm agent:log-issue \
+  --category confusion \
+  --severity minor \
+  --title "Issue title" \
+  --description "Detailed description"
+```
+
+Categories: `confusion`, `tooling_error`, `doc_gap`, `workflow_violation`, `unexpected_failure`
+Severities: `minor`, `moderate`, `major`
+
+### Query Issues
+
+```bash
+# Summary of recent issues
+pnpm agent:issues summary --since 7d
+
+# List all issues
+pnpm agent:issues list
+```
+
+### Session Status
+
+```bash
+pnpm session:status
+```
+
+Shows current active sessions across agents.
+
+### Session Recommendations
+
+```bash
+pnpm session:recommend
+```
+
+Suggests optimal context tier based on task complexity.
+
+## Common Maintenance Workflows
+
+### Weekly Health Check
+
+```bash
+pnpm wu:prune              # Check for stale worktrees
+pnpm backlog:prune         # Check for stale WUs
+pnpm metrics:lanes         # Review lane performance
+pnpm docs:linkcheck        # Verify documentation links
+```
+
+### Before WU Completion
+
+```bash
+pnpm tasks:validate        # Validate WU YAML
+pnpm board:validate        # Check board state
+pnpm validate:context      # Check context integrity
+```