@lumenflow/cli 2.2.1 → 2.3.1

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

@@ -0,0 +1,155 @@
+---
+name: context-management
+description: Session checkpoint patterns, output bypass for large results, when to spawn fresh sub-agents. Use for long-running sessions, context exhaustion, or agent coordination.
+version: 1.2.0
+source: docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-invocation-guide.md
+source_sections: Context Tiers, Session Management, Wave Orchestration
+last_updated: {{DATE}}
+allowed-tools: Read, Write, Bash
+---
+
+# Context Management Skill
+
+**Source**: `docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-invocation-guide.md`
+
+Patterns for managing context in long-running AI coding sessions.
+
+## Primary Strategy: Spawn Fresh, Don't Continue
+
+**When approaching context limits, spawn a fresh agent instead of continuing after compaction.**
+
+Context compaction (summarization) causes agents to lose critical rules. The recommended approach from [Anthropic's engineering guidance](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents):
+
+> "An initializer agent that sets up the environment, and a coding agent tasked with **making incremental progress in every session**, while leaving clear artifacts for the next session."
+
+### Mandatory Triggers
+
+Spawn a fresh agent when ANY of these apply:
+
+- Context usage exceeds **80%**
+- **50+ tool calls** in current session
+- Performance degradation (redundant queries, forgotten context)
+- You're about to run `/compact` or `/clear`
+
+### Spawn Fresh Protocol
+
+```bash
+# 1. Checkpoint your progress
+pnpm mem:checkpoint "Progress: completed X, next: Y" --wu WU-XXX
+
+# 2. Commit and push work
+git add -A && git commit -m "checkpoint: progress on X"
+git push origin lane/<lane>/wu-xxx
+
+# 3. Generate fresh agent prompt
+pnpm wu:spawn --id WU-XXX
+
+# 4. EXIT current session (do NOT continue after compaction)
+
+# 5. Start fresh agent with the generated prompt
+```
+
+### Why Not Continue After Compaction?
+
+- Compaction summarizes conversation → rules get lost in summary
+- Agent forgets worktree discipline, WU context, constraints
+- Recovery mechanisms are complex and vendor-specific
+- Prevention (fresh agent) is simpler and more reliable than recovery
+
+**This is not failure—it's disciplined execution.** See [wu-sizing-guide.md](../../../docs/04-operations/_frameworks/lumenflow/wu-sizing-guide.md) for complete sizing thresholds.
+
+---
+
+## Session Checkpoints
+
+Use memory commands to preserve state across context boundaries:
+
+```bash
+# Start session tracking
+pnpm mem:start --wu WU-123
+
+# Save checkpoint before context-heavy operation
+pnpm mem:checkpoint --wu WU-123 --note "Completed step 2, starting API integration"
+
+# Resume after /clear
+pnpm mem:ready --wu WU-123  # Shows pending work
+pnpm mem:inbox --wu WU-123  # Check signals from other agents
+```
+
+## Output Bypass Pattern
+
+For large results that would exhaust context:
+
+```typescript
+// ❌ BAD: Returns 10MB of data into context
+const allLogs = await fetchAllLogs();
+return allLogs;
+
+// ✅ GOOD: Store to filesystem, return reference
+const allLogs = await fetchAllLogs();
+await writeFile('/tmp/analysis-results.json', JSON.stringify(allLogs));
+console.log('Results saved to /tmp/analysis-results.json');
+return { resultPath: '/tmp/analysis-results.json', summary: summarize(allLogs) };
+```
+
+## When to Spawn Sub-Agents
+
+Spawn fresh agent when:
+
+- Current context >80% exhausted
+- Task is independent and parallelizable
+- Need specialized agent (e.g., code-reviewer, test-engineer)
+- Switching to different WU scope
+
+Keep in current context when:
+
+- Tasks share significant state
+- Sequential dependencies exist
+- Context usage still low
+
+## Wave Orchestration Pattern
+
+When orchestrating multi-wave initiatives, use the checkpoint-per-wave pattern to prevent context exhaustion:
+
+```bash
+# Spawn next wave then exit (no polling)
+pnpm orchestrate:initiative -i INIT-009 -c
+
+# Check progress via stamps
+pnpm orchestrate:initiative -i INIT-009 -p
+
+# Repeat for next wave when complete
+pnpm orchestrate:initiative -i INIT-009 -c
+```
+
+**Key principles:**
+
+1. **Exit immediately after spawning** — No polling loops in the orchestrator
+2. **Wave manifests for idempotency** — `.beacon/artifacts/waves/INIT-XXX-wave-N.json`
+3. **Stamp-based completion** — Check `.beacon/stamps/WU-*.done` for progress
+4. **Compact output** — Keep orchestrator output under 20 lines
+
+See [orchestration skill](../orchestration/SKILL.md) for complete documentation.
+
+## Context Loading Order
+
+Always load context in this order for best comprehension:
+
+1. `LUMENFLOW.md` — Workflow fundamentals
+2. `README.md` — Project structure
+3. `lumenflow-complete.md` §§1-7 — Constraints
+4. WU YAML — Current task spec
+5. Task instructions — What to do
+6. Constraints block — Critical rules (at END per "Lost in Middle" research)
+
+## Integration with Other Skills
+
+- **multi-agent-coordination**: For parallel sub-agent work
+- **wu-lifecycle**: Session ties to WU lifecycle
+- **orchestration**: Agent selection guidance, wave orchestration pattern
+- **execution-memory**: Memory layer commands for checkpoints and signals
+
+## Version History
+
+- **v1.1.0** ({{DATE}}): Added wave orchestration pattern cross-reference
+- **v1.0.0** ({{DATE}}): Initial skill created

package/templates/vendors/claude/.claude/skills/execution-memory/SKILL.md.template

@@ -0,0 +1,304 @@
+---
+name: execution-memory
+description: Memory layer for session tracking, context recovery, and agent coordination. Use when resuming work after /clear, coordinating with parallel agents, or managing long-running sessions.
+version: 1.1.0
+source: docs/04-operations/_frameworks/lumenflow/agent/onboarding/quick-ref-commands.md
+source_sections: Memory Commands
+last_updated: {{DATE}}
+allowed-tools: Read, Bash, Grep
+---
+
+# Execution Memory Skill
+
+**Source**: Memory Layer (implemented across wu:claim, wu:done, and mem:\* commands)
+
+This skill documents the memory layer for agent session tracking, context recovery, and coordination. It provides patterns for resuming work after `/clear`, coordinating with parallel agents, and managing discoveries during execution.
+
+## When to Use This Skill
+
+Activate automatically when:
+
+- Resuming work after `/clear` or session handoff
+- Coordinating with parallel agents (signals/inbox)
+- Managing long-running sessions (>20 tool calls)
+- Capturing discoveries (bugs, ideas) mid-WU
+- Context window feels constrained
+
+## Quick Reference: Storage Location
+
+All memory data is stored in `.beacon/memory/`:
+
+```
+.beacon/memory/
+├── sessions/               # Session metadata by session ID
+│   └── <session-id>.json   # Session start time, WU link, tier
+├── checkpoints/            # Progress checkpoints
+│   └── <wu-id>/            # Checkpoints grouped by WU
+│       └── <timestamp>.md  # Individual checkpoint
+├── discoveries/            # Bugs, ideas, discoveries
+│   └── <node-id>.json      # Discovery node with type, status
+├── signals/                # Inter-agent coordination signals
+│   └── <timestamp>-<wu>.json  # Signal with lane, message
+└── summaries/              # Rollup summaries for compaction
+    └── <wu-id>-summary.md  # Summarised session history
+```
+
+## Automatic Integration
+
+The memory layer integrates automatically with WU lifecycle commands:
+
+### wu:claim (automatic)
+
+When you run `pnpm wu:claim`:
+
+1. Creates session node in `.beacon/memory/sessions/`
+2. Links session to WU ID
+3. Records baseline main SHA for recovery
+
+### wu:done (automatic)
+
+When you run `pnpm wu:done`:
+
+1. Creates pre-gates checkpoint (recovery point if gates fail)
+2. Broadcasts completion signal to parallel agents
+3. Checks `mem:inbox` for recent signals from other agents
+4. Ends session and marks as completed
+
+**No manual intervention required** for basic session tracking.
+
+## Manual Commands Reference
+
+### Session Management
+
+```bash
+# Start a new session (usually automatic via wu:claim)
+pnpm mem:start --wu WU-XXX
+
+# Create progress checkpoint
+pnpm mem:checkpoint "Completed port definitions, starting tests" --wu WU-XXX
+
+# Query ready nodes (what's pending/next?)
+pnpm mem:ready --wu WU-XXX
+pnpm mem:ready --wu WU-XXX --type discovery  # Filter by type
+pnpm mem:ready --wu WU-XXX --format json     # JSON output
+```
+
+### Discovery Capture
+
+```bash
+# Create discovery node with type aliases
+pnpm mem:create "Found race condition in auth flow" --type bug         # → type=discovery, tags=[bug]
+pnpm mem:create "Could extract common validation logic" --type idea    # → type=discovery, tags=[idea]
+
+# Canonical form (equivalent, explicit)
+pnpm mem:create "Performance issue" --type discovery --tags bug,performance
+
+# Tags are merged and deduplicated
+pnpm mem:create "Bug with extra tags" --type bug --tags scope-creep   # → tags=[bug, scope-creep]
+
+# WU is auto-inferred from current session (no --wu required if session exists)
+pnpm mem:create "Found issue" --type bug                               # auto-links to current WU
+
+# List discoveries for review
+pnpm mem:triage --list
+
+# Promote discovery to WU
+pnpm mem:triage --promote mem-xxxx --lane "Operations: Tooling"
+```
+
+### Agent Coordination
+
+```bash
+# Send signal to other agents
+pnpm mem:signal "Completed auth refactor, ready for integration" --wu WU-XXX
+
+# Read signals for your lane
+pnpm mem:inbox --lane Operations
+pnpm mem:inbox --lane "Operations: Tooling"
+
+# Watch mode for real-time coordination
+pnpm mem:inbox --since 1h --watch
+```
+
+### Maintenance
+
+```bash
+# Summarise nodes for context compaction
+pnpm mem:summarize --wu WU-XXX
+
+# Preview cleanup
+pnpm mem:cleanup --dry-run
+
+# Execute cleanup per lifecycle rules
+pnpm mem:cleanup
+
+# Initialize memory directory (first time setup)
+pnpm mem:init
+```
+
+## Context Recovery Pattern
+
+When resuming work after `/clear` or session handoff:
+
+### Step 1: Check Pending Work
+
+```bash
+# What's pending for this WU?
+pnpm mem:ready --wu WU-XXX
+```
+
+Output shows:
+
+- Checkpoints with progress notes
+- Pending discoveries to triage
+- Incomplete tasks from previous session
+
+### Step 2: Check Coordination Signals
+
+```bash
+# Any messages from parallel agents?
+pnpm mem:inbox --wu WU-XXX
+pnpm mem:inbox --lane Operations --since 2h
+```
+
+### Step 3: Resume or Start Fresh
+
+```bash
+# Option A: Resume from checkpoint (context available)
+# Read the checkpoint, continue from where you left off
+
+# Option B: Start new session (fresh context)
+pnpm mem:start --wu WU-XXX
+```
+
+### Context Compaction Workflow
+
+For long sessions (>20 tool calls):
+
+1. **Checkpoint progress**: `pnpm mem:checkpoint "status" --wu WU-XXX`
+2. **Clear context**: `/clear` in your AI coding tool
+3. **Reload minimal context**: Tier 1 docs + WU YAML
+4. **Query ready nodes**: `pnpm mem:ready --wu WU-XXX`
+5. **Continue from checkpoint**
+
+## Discovery Lifecycle
+
+Discoveries captured via `mem:create` follow this lifecycle:
+
+```
+created → triaged → promoted/dismissed
+```
+
+**States:**
+
+- `created`: Just captured, needs review
+- `triaged`: Reviewed, decision pending
+- `promoted`: Converted to WU via `mem:triage --promote`
+- `dismissed`: Not actionable, archived
+
+**Discovery Types (via `--type` argument):**
+
+| Type Alias  | Stored As   | Auto-Tag | Description                      |
+| ----------- | ----------- | -------- | -------------------------------- |
+| `bug`       | `discovery` | `bug`    | Defect found during work         |
+| `idea`      | `discovery` | `idea`   | Improvement suggestion           |
+| `discovery` | `discovery` | -        | General finding (canonical type) |
+
+## Signal Patterns
+
+### Completion Broadcast
+
+After completing significant work:
+
+```bash
+pnpm mem:signal "WU-XXX complete: auth refactor merged" --wu WU-XXX
+```
+
+### Coordination Request
+
+When needing input from parallel agent:
+
+```bash
+pnpm mem:signal "Need review of auth flow before proceeding" --wu WU-XXX
+```
+
+### Polling Pattern (Orchestrators)
+
+For orchestrators managing multiple agents:
+
+```bash
+# Check for updates from all lanes
+pnpm mem:inbox --since 30m
+pnpm mem:inbox --lane "Operations: Tooling"
+```
+
+## Integration with Other Skills
+
+### wu-lifecycle
+
+The execution-memory skill complements wu-lifecycle:
+
+- `wu:claim` automatically starts session
+- `wu:done` automatically creates checkpoint and broadcasts signal
+- `wu:block/unblock` preserves session state
+
+### multi-agent-coordination
+
+For parallel WU coordination:
+
+- Use `mem:signal` to notify completion
+- Use `mem:inbox` to receive coordination messages
+- Use `mem:ready` to check handoff status
+
+### orchestration
+
+For initiative orchestration:
+
+- `orchestrate:initiative` polls `mem:inbox` during wave execution
+- Signals inform wave coordination decisions
+- Discoveries feed into WU creation pipeline
+
+## Decision Trees
+
+### When to Create Checkpoint
+
+**Create checkpoint if:**
+
+- Completing significant milestone (port definition, test pass)
+- Context window feeling constrained (>50 tool calls)
+- About to run `/clear`
+- Switching to sub-task (will return later)
+
+**Skip checkpoint if:**
+
+- Quick edit (<5 tool calls total)
+- Already near completion
+- WU is simple single-file change
+
+### When to Capture Discovery
+
+**Capture as discovery if:**
+
+- Bug found in code outside current WU's `code_paths`
+- Idea for improvement unrelated to current work
+- Performance/security concern for later investigation
+- Question needs external input
+
+**Fix in place if:**
+
+- Bug is in current WU's `code_paths`
+- Fix is small (<=10 lines)
+- Directly blocks acceptance criteria
+
+See `bug-classification` skill for full decision tree.
+
+## Related Skills
+
+- [wu-lifecycle](../wu-lifecycle/SKILL.md) - WU claim/block/done (auto-integrated)
+- [multi-agent-coordination](../multi-agent-coordination/SKILL.md) - Parallel agent patterns
+- [orchestration](../orchestration/SKILL.md) - Initiative wave coordination
+
+## Version History
+
+- **v1.1.0** ({{DATE}}): Added type aliases (`--type bug/idea`) and worktree-aware WU auto-inference
+- **v1.0.0** ({{DATE}}): Initial skill for memory layer

package/templates/vendors/claude/.claude/skills/frontend-design/SKILL.md.template

@@ -0,0 +1,131 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces. Use when building React components, pages, UI features, or when user requests visual/design work.
+version: 1.0.0
+source: docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
+last_updated: {{DATE}}
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# Frontend Design Skill
+
+## Purpose
+
+Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics.
+
+## When to Use
+
+- Building new React components or pages
+- Creating UI features or visual elements
+- User requests "make it look good" or design-focused work
+- Implementing dashboards, forms, or interactive features
+- Working on Experience/UI lane WUs with components
+
+## Capabilities
+
+This skill provides patterns for:
+
+- **Creative UI generation** - Distinctive designs, not generic templates
+- **Production-ready code** - Clean, maintainable React/TypeScript
+- **Design system awareness** - Respects existing component libraries
+- **Accessibility built-in** - WCAG compliance by default
+- **Responsive design** - Mobile-first approach
+
+## Common Tech Stack Patterns
+
+Projects commonly use:
+
+- **Tailwind CSS** for styling
+- **shadcn/ui** or similar component libraries
+- **React 18+** with TypeScript
+- **Next.js** App Router (for Next.js projects)
+
+Adapt to your project's specific stack.
+
+## Accessibility Requirements
+
+All UI must meet:
+
+- WCAG 2.1 AA compliance
+- Screen reader compatibility
+- Keyboard navigation support
+- Sufficient colour contrast
+
+## Component Patterns
+
+### File Organization
+
+```
+components/
+├── ui/           # Primitive UI components
+├── features/     # Feature-specific components
+├── layouts/      # Layout components
+└── forms/        # Form components
+```
+
+### Component Structure
+
+```typescript
+// components/features/user-card.tsx
+import { Card, CardContent, CardHeader } from '@/components/ui/card';
+
+interface UserCardProps {
+  name: string;
+  email: string;
+  avatar?: string;
+}
+
+export function UserCard({ name, email, avatar }: UserCardProps) {
+  return (
+    <Card>
+      <CardHeader>
+        {avatar && <img src={avatar} alt="" className="h-10 w-10 rounded-full" />}
+        <h3 className="font-semibold">{name}</h3>
+      </CardHeader>
+      <CardContent>
+        <p className="text-muted-foreground">{email}</p>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+## Usage Pattern
+
+```markdown
+1. Activate this skill when UI work is needed
+2. Describe the component/page requirements
+3. Specify any design constraints or existing patterns to follow
+4. Review generated code for project conventions
+5. Test accessibility with screen reader and keyboard
+```
+
+## Example Prompts
+
+**Component creation**:
+
+> "Create a user profile card component that displays avatar, name, email, and status. Should match our existing card style."
+
+**Page layout**:
+
+> "Build a dashboard page showing metrics with charts and a recent activity feed."
+
+**Form design**:
+
+> "Design an accessible multi-step form for user registration."
+
+## Quality Checklist
+
+Before completing UI work:
+
+- [ ] Responsive across breakpoints (mobile, tablet, desktop)
+- [ ] Keyboard navigable (Tab, Enter, Escape)
+- [ ] Screen reader friendly (proper ARIA labels)
+- [ ] Colour contrast meets WCAG AA
+- [ ] Loading and error states handled
+- [ ] Animations respect `prefers-reduced-motion`
+
+## Related Skills
+
+- **tdd-workflow** - For component testing approach
+- **code-quality** - For TypeScript patterns