@lumenflow/cli 2.4.0 → 2.5.1

package/templates/core/ai/onboarding/troubleshooting-wu-done.md.template

@@ -1,8 +1,17 @@
-# Troubleshooting: wu:done Not Run
+# Troubleshooting: wu:prep and wu:done Workflow
 
 **Last updated:** {{DATE}}
 
-This is the most common mistake agents make. This document explains why it happens and how to fix it.
+This is the most common mistake agents make. This document explains the two-step completion workflow introduced in WU-1223.
+
+---
+
+## The New Workflow (WU-1223)
+
+As of WU-1223, completion is a **two-step process**:
+
+1. **From worktree**: Run `pnpm wu:prep --id WU-XXX` (runs gates, prints copy-paste instruction)
+2. **From main**: Run `pnpm wu:done --id WU-XXX` (merge + cleanup only)
 
 ---
 
@@ -21,54 +30,87 @@ Agents complete their work, write "To Complete: pnpm wu:done --id WU-XXX" in the
 
 ## The Fix
 
-### Rule: ALWAYS Run wu:done
+### Rule: Use wu:prep Then wu:done
 
-After gates pass, you MUST run:
+After implementation is complete:
 
 ```bash
-cd /path/to/main
-pnpm wu:done --id WU-XXX
+# Step 1: From worktree, run wu:prep
+pnpm wu:prep --id WU-XXX
+# This runs gates and prints a copy-paste instruction
+
+# Step 2: Copy-paste the instruction from wu:prep output
+cd /path/to/main && pnpm wu:done --id WU-XXX
 ```
 
 Do NOT:
 
 - Ask "Should I run wu:done?"
 - Write "To Complete: pnpm wu:done"
-- Wait for permission
-- Treat it as a "future step"
+- Run wu:done directly from a worktree (it will error)
+- Skip wu:prep and go directly to wu:done from main (gates won't run in worktree)
 
 ---
 
 ## Correct Completion Flow
 
 ```bash
-# 1. In worktree, run gates
-pnpm gates
+# 1. In worktree, run wu:prep
+pnpm wu:prep --id WU-XXX
+# Output includes: cd /path/to/main && pnpm wu:done --id WU-XXX
 
-# 2. If gates pass, return to main
-cd /path/to/main
+# 2. Copy-paste the wu:done command from the output
+cd /path/to/main && pnpm wu:done --id WU-XXX
 
-# 3. IMMEDIATELY run wu:done
-pnpm wu:done --id WU-XXX
-
-# 4. Report success with the wu:done output
+# 3. Report success with the wu:done output
 ```
 
 ---
 
-## What wu:done Does
+## What wu:prep Does (WU-1223)
+
+When you run `pnpm wu:prep --id WU-XXX` from a worktree:
+
+1. Validates you're in a worktree (errors if in main)
+2. Runs gates in the worktree
+3. Prints copy-paste instruction for wu:done
+
+## What wu:done Does (WU-1223)
+
+When you run `pnpm wu:done --id WU-XXX` from main:
+
+1. Validates you're in main checkout (errors if in worktree)
+2. Fast-forward merges the lane branch to main
+3. Creates the done stamp
+4. Updates status and backlog docs
+5. Removes the worktree
+6. Pushes to origin
+
+**This two-step process is the ONLY way to complete a WU.** Manual steps will leave things in an inconsistent state.
+
+---
+
+## Error Messages
+
+### "wu:done must be run from main checkout"
+
+If you see this error, you ran wu:done from a worktree. Use wu:prep instead:
+
+```bash
+# You're in the worktree - use wu:prep
+pnpm wu:prep --id WU-XXX
+# Then follow the copy-paste instruction it prints
+```
 
-When you run `pnpm wu:done --id WU-XXX`:
+### "wu:prep must be run from a worktree"
 
-1. Validates the worktree exists and has commits
-2. Runs gates in the worktree (not main)
-3. Fast-forward merges to main
-4. Creates the done stamp
-5. Updates status and backlog docs
-6. Removes the worktree
-7. Pushes to origin
+If you see this error, you ran wu:prep from main. Navigate to the worktree:
 
-**This is the ONLY way to complete a WU.** Manual steps will leave things in an inconsistent state.
+```bash
+# Navigate to worktree first
+cd worktrees/<lane>-wu-xxx
+pnpm wu:prep --id WU-XXX
+```
 
 ---
 
@@ -76,8 +118,8 @@ When you run `pnpm wu:done --id WU-XXX`:
 
 If a WU is missing `exposure`, `wu:done` auto-sets a safe default:
 
-- **Content lanes** → `documentation`
-- **Framework/Operations lanes** → `backend-only`
+- **Content lanes** -> `documentation`
+- **Framework/Operations lanes** -> `backend-only`
 
 Existing exposure values are preserved.
 
@@ -102,11 +144,12 @@ If a previous agent forgot to run wu:done:
 # 1. Check worktree exists
 ls worktrees/
 
-# 2. If it does, run wu:done
-pnpm wu:done --id WU-XXX
+# 2. If it does, navigate there and run wu:prep
+cd worktrees/<lane>-wu-xxx
+pnpm wu:prep --id WU-XXX
 
-# 3. If worktree was deleted but branch exists
-# This is a bad state - may need manual recovery
+# 3. Follow the copy-paste instruction
+cd /path/to/main && pnpm wu:done --id WU-XXX
 ```
 
 ---
@@ -124,9 +167,9 @@ An incomplete WU causes problems:
 
 ## Checklist Before Ending Session
 
-- [ ] Did I run `pnpm gates` in the worktree?
-- [ ] Did gates pass?
-- [ ] Did I `cd` back to main?
+- [ ] Did I run `pnpm wu:prep --id WU-XXX` in the worktree?
+- [ ] Did wu:prep (gates) pass?
+- [ ] Did I `cd` back to main using the copy-paste instruction?
 - [ ] Did I run `pnpm wu:done --id WU-XXX`?
 - [ ] Did wu:done complete successfully?
 
@@ -143,12 +186,22 @@ I've completed all the work. To finish:
 1. Run `pnpm wu:done --id WU-123`
 ```
 
-### RIGHT:
+### ALSO WRONG:
 
 ```bash
-# Actually run it
-cd /home/project/main
+# Running wu:done from worktree (will error)
 pnpm wu:done --id WU-123
+```
+
+### RIGHT:
+
+```bash
+# Step 1: From worktree, run wu:prep
+pnpm wu:prep --id WU-123
+# Output: cd /path/to/main && pnpm wu:done --id WU-123
+
+# Step 2: Copy-paste the instruction
+cd /path/to/main && pnpm wu:done --id WU-123
 # Output: WU-123 completed successfully
 ```
 

package/templates/core/ai/onboarding/vendor-support.md.template

@@ -0,0 +1,219 @@
+# AI Coding Assistant Integrations
+
+**Last updated:** {{DATE}}
+
+---
+
+## Works with Any AI
+
+**LumenFlow is friction-free for any AI coding assistant.** If your AI can read project files, it can use LumenFlow.
+
+### Universal Entry Points
+
+Every LumenFlow project includes these plain markdown files that work with ANY AI:
+
+| File                        | Purpose                                  |
+| --------------------------- | ---------------------------------------- |
+| `AGENTS.md`                 | Universal agent instructions             |
+| `LUMENFLOW.md`              | Workflow fundamentals and critical rules |
+| `.lumenflow/constraints.md` | Non-negotiable constraints               |
+
+**No vendor lock-in.** Point any AI at these files and it understands the workflow.
+
+```bash
+# Initialize with universal files only (works with any AI)
+lumenflow init
+```
+
+---
+
+## Enhanced Integrations
+
+For popular AI coding assistants, LumenFlow provides **optional enhanced integrations** with deeper features like auto-detection, skills, and vendor-specific configurations.
+
+| Assistant   | Config File                    | Auto-detected | Enhanced Features               |
+| ----------- | ------------------------------ | ------------- | ------------------------------- |
+| Claude Code | `CLAUDE.md`, `.claude/`        | Yes           | Skills, agents, hooks, settings |
+| Cursor      | `.cursor/rules/lumenflow.md`   | Yes           | Rules integration               |
+| Windsurf    | `.windsurf/rules/lumenflow.md` | Yes           | Rules integration               |
+| Cline       | `.clinerules`                  | No            | Rules file                      |
+| Codex       | `AGENTS.md` (native)           | No            | Uses universal files directly   |
+| Aider       | `.aider.conf.yml`              | No            | Config file                     |
+| Antigravity | `AGENTS.md` (native)           | Unknown       | Research phase                  |
+
+---
+
+## Integration Details
+
+### Claude Code (Anthropic)
+
+Claude Code is Anthropic's official CLI for Claude. It has the deepest integration with LumenFlow.
+
+**Config Files:**
+
+- `CLAUDE.md` - Root-level instructions
+- `.claude/settings.json` - Permission configuration
+- `.claude/agents/` - Agent definitions
+- `.claude/skills/` - Skill definitions
+
+**Auto-detection:** Environment variables `CLAUDE_PROJECT_DIR` or `CLAUDE_CODE`
+
+**Initialize:**
+
+```bash
+lumenflow init --client claude
+```
+
+### Cursor
+
+Cursor is an AI-first code editor built on VS Code.
+
+**Config Files:**
+
+- `.cursor/rules/lumenflow.md` - LumenFlow rules
+
+**Auto-detection:** Environment variables starting with `CURSOR_`
+
+**Initialize:**
+
+```bash
+lumenflow init --client cursor
+```
+
+### Windsurf
+
+Windsurf (Codeium) is an AI IDE with agentic capabilities.
+
+**Config Files:**
+
+- `.windsurf/rules/lumenflow.md` - LumenFlow rules
+
+**Auto-detection:** Environment variables starting with `WINDSURF_`
+
+**Initialize:**
+
+```bash
+lumenflow init --client windsurf
+```
+
+### Cline
+
+Cline is an autonomous coding agent that works in VS Code.
+
+**Config Files:**
+
+- `.clinerules` - LumenFlow rules (root-level)
+
+**Auto-detection:** Not supported
+
+**Initialize:**
+
+```bash
+lumenflow init --client cline
+```
+
+### OpenAI Codex
+
+Codex reads the AGENTS.md file directly for universal instructions.
+
+**Config Files:**
+
+- `AGENTS.md` - Universal agent instructions (always created)
+
+**Initialize:**
+
+```bash
+lumenflow init  # AGENTS.md is created by default
+```
+
+### Aider
+
+Aider is a terminal-based pair programming tool.
+
+**Config Files:**
+
+- `.aider.conf.yml` - Aider configuration
+
+**Initialize:**
+
+```bash
+lumenflow init --client aider
+```
+
+---
+
+## Antigravity (Research Phase)
+
+**Status:** Research Phase
+
+Antigravity is Google's AI IDE, announced in November 2025. It is MCP-based and appears to read `AGENTS.md` natively.
+
+### What We Know
+
+- **Announced:** November 2025
+- **Platform:** Google's AI IDE
+- **Protocol:** MCP (Model Context Protocol)
+- **Agent Config:** Appears to read `AGENTS.md` natively (similar to Codex)
+
+### Research Links
+
+- [Google Codelabs - Getting Started with Antigravity](https://codelabs.developers.google.com/getting-started-google-antigravity)
+- Google AI documentation (when available)
+
+### Current Recommendation
+
+For projects using Antigravity:
+
+1. Ensure `AGENTS.md` is present (created by default with `lumenflow init`)
+2. The universal instructions in AGENTS.md should work out of the box
+3. Report any issues for future vendor-specific support
+
+---
+
+## Using Another AI?
+
+If your AI coding assistant isn't listed above, LumenFlow still works:
+
+1. Run `lumenflow init` to create universal entry points
+2. Tell your AI to read `AGENTS.md` and `LUMENFLOW.md`
+3. The workflow commands (`wu:claim`, `wu:done`, `gates`) work the same
+
+**Want enhanced integration for your AI?** See [Adding New Integrations](#adding-new-integrations) below.
+
+---
+
+## All Integrations Setup
+
+To configure all enhanced integrations at once:
+
+```bash
+lumenflow init --client all
+```
+
+This creates all vendor-specific configuration files alongside the universal entry points.
+
+---
+
+## Sync Vendor Configs
+
+To ensure all vendor configs are in sync with the template:
+
+```bash
+# Check if configs are in sync
+./scripts/sync-vendor-configs.sh --check
+
+# Regenerate all configs from template
+./scripts/sync-vendor-configs.sh
+```
+
+---
+
+## Adding New Integrations
+
+To add enhanced integration for a new AI coding assistant:
+
+1. Update `templates/vendor-rules.template.md` (single source of truth)
+2. Add vendor config path to `scripts/sync-vendor-configs.sh`
+3. Add scaffolding in `packages/@lumenflow/cli/src/init.ts`
+4. Update this integrations document
+5. Test with `lumenflow init --client <vendor>`

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

@@ -1,7 +1,7 @@
 ---
 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
+version: 1.3.0
 source: docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-invocation-guide.md
 source_sections: Context Tiers, Session Management, Wave Orchestration
 last_updated: {{DATE}}
@@ -76,6 +76,17 @@ pnpm mem:ready --wu WU-123  # Shows pending work
 pnpm mem:inbox --wu WU-123  # Check signals from other agents
 ```
 
+### Optional: Pre-Clear Checkpoint Hook
+
+If your client supports hooks, add a pre-clear/pre-compaction hook that runs:
+
+```bash
+pnpm mem:checkpoint "Pre-clear: <summary>" --wu WU-XXX --trigger pre-clear
+```
+
+This is a safety net for when humans forget to checkpoint. It does **not** replace the
+spawn-fresh protocol; still exit and spawn a new agent after `/clear`.
+
 ## Output Bypass Pattern
 
 For large results that would exhaust context:
@@ -151,5 +162,6 @@ Always load context in this order for best comprehension:
 
 ## Version History
 
+- **v1.3.0** ({{DATE}}): Added pre-clear checkpoint hook guidance
 - **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

@@ -1,7 +1,7 @@
 ---
 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
+version: 1.2.0
 source: docs/04-operations/_frameworks/lumenflow/agent/onboarding/quick-ref-commands.md
 source_sections: Memory Commands
 last_updated: {{DATE}}
@@ -26,23 +26,18 @@ Activate automatically when:
 
 ## Quick Reference: Storage Location
 
-All memory data is stored in `.beacon/memory/`:
+All memory data is stored in `.lumenflow/memory/` as append-only JSONL:
 
 ```
-.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
+.lumenflow/memory/
+├── memory.jsonl        # Session/checkpoint/discovery/summary nodes
+├── relationships.jsonl # Optional node relationships (blocks, related)
+├── signals.jsonl       # Inter-agent coordination signals
+└── config.yaml         # Retention policy defaults
 ```
 
+Legacy docs may mention `.beacon/memory/`; the current source of truth is `.lumenflow/memory/`.
+
 ## Automatic Integration
 
 The memory layer integrates automatically with WU lifecycle commands:
@@ -51,7 +46,7 @@ The memory layer integrates automatically with WU lifecycle commands:
 
 When you run `pnpm wu:claim`:
 
-1. Creates session node in `.beacon/memory/sessions/`
+1. Creates session node in `.lumenflow/memory/memory.jsonl`
 2. Links session to WU ID
 3. Records baseline main SHA for recovery
 
@@ -60,7 +55,7 @@ When you run `pnpm wu:claim`:
 When you run `pnpm wu:done`:
 
 1. Creates pre-gates checkpoint (recovery point if gates fail)
-2. Broadcasts completion signal to parallel agents
+2. Broadcasts completion signal to parallel agents (`signals.jsonl`)
 3. Checks `mem:inbox` for recent signals from other agents
 4. Ends session and marks as completed
 
@@ -181,6 +176,9 @@ For long sessions (>20 tool calls):
 4. **Query ready nodes**: `pnpm mem:ready --wu WU-XXX`
 5. **Continue from checkpoint**
 
+If your client supports hooks, add a pre-clear hook that runs `pnpm mem:checkpoint` automatically
+before `/clear` or `/compact` to avoid losing context.
+
 ## Discovery Lifecycle
 
 Discoveries captured via `mem:create` follow this lifecycle:

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

@@ -1,7 +1,7 @@
 ---
 name: orchestration
 description: Agent orchestration dashboard and initiative execution. Use when running initiatives, monitoring spawned agents, or debugging stuck spawns.
-version: 2.4.0
+version: 2.5.0
 source: packages/@lumenflow/cli/src/orchestrate.ts
 last_updated: {{DATE}}
 allowed-tools: Read, Bash, Grep
@@ -47,6 +47,49 @@ pnpm wu:spawn --id WU-XXX
 
 ---
 
+## Verbatim Output Verification (WU-1131)
+
+When using `wu:spawn` output to invoke Task agents, you **MUST** verify the output was not truncated.
+
+### Truncation Detection
+
+`wu:spawn` output includes:
+
+- **Warning banner** at the start with truncation instructions
+- **End sentinel** `<!-- LUMENFLOW_SPAWN_END -->` after the constraints block
+
+### Verification Checklist
+
+Before spawning a sub-agent with `wu:spawn` output:
+
+1. **Check for end sentinel**: The output MUST end with `<!-- LUMENFLOW_SPAWN_END -->`
+2. **Verify constraints block**: Look for `</constraints>` before the end sentinel
+3. **Check warning banner**: The start should contain `LUMENFLOW_TRUNCATION_WARNING`
+
+```bash
+# Quick verification commands
+pnpm wu:spawn --id WU-XXX | tail -5    # Should show LUMENFLOW_SPAWN_END
+pnpm wu:spawn --id WU-XXX | head -20   # Should show TRUNCATION_WARNING
+pnpm wu:spawn --id WU-XXX | grep -c 'constraints'  # Should return 2 (open and close tags)
+```
+
+### What Truncation Causes
+
+If spawn output is truncated, sub-agents will:
+
+- Miss TDD directives (skip writing tests first)
+- Miss constraints block (ignore safety rules)
+- Miss worktree discipline (edit main instead of worktree)
+- Miss wu:done instructions (ask for permission instead of completing)
+
+### If Truncation Is Detected
+
+1. Re-run `wu:spawn` and capture full output
+2. If context window is too small, use `--codex` for shorter Markdown format
+3. Consider breaking WU into smaller sub-WUs if prompt is too large
+
+---
+
 ## Commands
 
 ```bash
@@ -171,12 +214,13 @@ pnpm wu:spawn --id WU-XXX
 
 ```
 Starting WU?
-├── Run: pnpm orchestrate:monitor
-└── Review agent status and recommendations
+├── Run: pnpm wu:spawn --id WU-XXX
+└── Review generated prompt with agent recommendations
 
 Initiative with multiple WUs?
 ├── Run: pnpm orchestrate:initiative -i INIT-XXX --dry-run
-└── Review wave plan, then execute
+├── Review wave plan
+└── Run: pnpm orchestrate:init-status -i INIT-XXX for progress
 
 Agent appears stuck or crashed?
 ├── Run: pnpm orchestrate:monitor

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

@@ -61,6 +61,10 @@ Write({
 
 3. **Use relative paths for ALL file operations**
 
+4. **Docs-only exception (documentation WUs)**:
+   - Read-only commands may run from main.
+   - **All file writes still require a worktree** (claim first if needed).
+
 ## Quick Detection
 
 **Red flags** (you're about to fall into the trap):
@@ -115,7 +119,7 @@ About to use Write/Edit/Read?
 │   ├─ 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
+│       └─ NO → Claim WU or use docs-only paths (read-only only)
 └─ Path starts with "/" ?
     ├─ YES → STOP! Convert to relative path
     └─ NO → Safe to proceed

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

@@ -1,7 +1,7 @@
 ---
 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
+description: Work Unit claim/block/done workflow automation. Use when claiming WUs, blocking/unblocking, running wu:prep + wu:done, or understanding WU state transitions.
+version: 2.2.0
 source: docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
 source_sections: §2.4, §6 (WU Lifecycle)
 last_updated: {{DATE}}
@@ -38,9 +38,13 @@ ready → in_progress → waiting/blocked → done
 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
+# Complete WU - TWO STEPS (WU-1223)
+# Step 1: From worktree, run wu:prep
+pnpm wu:prep --id WU-XXX
+# This prints: cd /path/to/main && pnpm wu:done --id WU-XXX
+
+# Step 2: From main, run wu:done (copy-paste from wu:prep output)
+cd /path/to/main && pnpm wu:done --id WU-XXX
 
 # Block/Unblock
 pnpm wu:block --id WU-XXX --reason "..."
@@ -59,11 +63,18 @@ pnpm wu:prune --execute     # Clean stale worktrees
 pnpm wu:cleanup --id WU-XXX # After PR merge
 ```
 
-## wu:done Workflow
+## wu:prep + wu:done Workflow (WU-1223)
+
+**Two-step completion:**
+
+1. `wu:prep` (from worktree): Runs gates, prints copy-paste instruction
+2. `wu:done` (from main): Fast-forward merge, stamp, cleanup
+
+**wu:done workflow (from main):**
 
-1. Runs gates in worktree
+1. Validates running from main (errors if in worktree)
 2. Fast-forward merge to main
-3. Creates `.beacon/stamps/WU-XXX.done`
+3. Creates `.lumenflow/stamps/WU-XXX.done`
 4. Updates backlog.md + status.md
 5. Removes worktree