@lumenflow/cli 2.17.0 → 2.18.0

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

@@ -55,13 +55,6 @@ Claude Code is Anthropic's official CLI for Claude. It has the deepest integrati
 - `.claude/settings.json` - Permission configuration
 - `.claude/agents/` - Agent definitions
 - `.claude/skills/` - Skill definitions
-- `.mcp.json` - MCP server configuration (WU-1413)
-
-**MCP Integration:** Claude Code supports MCP (Model Context Protocol) servers. When initializing with `--client claude`, LumenFlow automatically configures the `@lumenflow/mcp` server which provides:
-
-- WU lifecycle tools (status, claim, gates)
-- Memory coordination tools (checkpoint, signal, inbox)
-- Lane management tools (health, suggest)
 
 **Auto-detection:** Environment variables `CLAUDE_PROJECT_DIR` or `CLAUDE_CODE`
 
@@ -177,93 +170,89 @@ For projects using Antigravity:
 
 ---
 
-## Using Another AI?
+## Cloud Workflow Mode (Branch-PR)
 
-If your AI coding assistant isn't listed above, LumenFlow still works:
+Cloud-hosted agents (Codex, Claude web, GitHub Actions, CI bots) cannot create local
+worktrees. LumenFlow provides a first-class **branch-pr** mode for these environments.
 
-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
+### Explicit Activation
 
-**Want enhanced integration for your AI?** See [Adding New Integrations](#adding-new-integrations) below.
+Cloud mode is always available via explicit activation:
 
----
+```bash
+# Flag-based
+pnpm wu:claim --id WU-XXX --lane "<Lane>" --cloud
 
-## All Integrations Setup
+# Environment variable
+LUMENFLOW_CLOUD=1 pnpm wu:claim --id WU-XXX --lane "<Lane>"
+```
 
-To configure all enhanced integrations at once:
+Explicit activation (`--cloud` or `LUMENFLOW_CLOUD=1`) always takes precedence over
+auto-detection.
 
-```bash
-lumenflow init --client all
+### Config-Driven Auto-Detection (Opt-In)
+
+For environments where agents should automatically enter cloud mode, enable
+auto-detection in `.lumenflow.config.yaml`:
+
+```yaml
+cloud:
+  auto_detect: true # default: false
+  env_signals:
+    - name: CI # presence check (any non-empty value)
+    - name: CODEX
+    - name: GITHUB_ACTIONS
+      equals: 'true' # exact match required
 ```
 
-This creates all vendor-specific configuration files alongside the universal entry points.
+**Key design decisions:**
 
----
+- `auto_detect` defaults to `false` (opt-in, not opt-out)
+- No vendor-specific signals are hardcoded; all signals are user-configured
+- Each signal supports either presence checks (`name` only) or exact-value
+  matches (`name` + `equals`)
+- Explicit activation always wins over auto-detection
 
-## MCP Server Integration
+### Cloud Lifecycle
 
-LumenFlow provides an MCP (Model Context Protocol) server package for deeper AI integration.
+| Step     | Command                                   | What happens                                                     |
+| -------- | ----------------------------------------- | ---------------------------------------------------------------- |
+| Claim    | `wu:claim --id WU-XXX --lane <L> --cloud` | Sets `claimed_mode: branch-pr`, creates lane branch, no worktree |
+| Work     | (agent works on lane branch)              | Push commits to `lane/<lane>/wu-xxx`                             |
+| Prep     | `wu:prep --id WU-XXX`                     | Validates branch, runs gates in-place                            |
+| Complete | `wu:done --id WU-XXX`                     | Creates PR, commits metadata on lane branch                      |
+| Cleanup  | `wu:cleanup --id WU-XXX`                  | Post-merge: creates stamp, updates state, deletes branch         |
 
-### What is MCP?
+### Vendor-Specific Notes
 
-MCP is a protocol that allows AI assistants to access tools and context from external servers. LumenFlow's MCP server (`@lumenflow/mcp`) exposes workflow tools directly to compatible AI assistants.
+- **Codex**: Set `LUMENFLOW_CLOUD=1` in the environment or configure auto-detection with `name: CODEX`
+- **Claude web**: Use `--cloud` flag explicitly or configure `name: CLAUDE_CODE` in env_signals
+- **GitHub Actions**: Configure `name: GITHUB_ACTIONS, equals: 'true'` in env_signals
+- **Antigravity**: Expected to work with explicit `--cloud` flag; auto-detection signals TBD
 
-### Supported Assistants
+---
 
-| Assistant     | MCP Support | Configuration   |
-| ------------- | ----------- | --------------- |
-| Claude Code   | Yes         | `.mcp.json`     |
-| Antigravity   | Yes         | TBD             |
-| Cursor        | No          | Uses rules file |
-| Windsurf      | No          | Uses rules file |
+## Using Another AI?
 
-### Setup (Claude Code)
+If your AI coding assistant isn't listed above, LumenFlow still works:
 
-When you run `lumenflow init --client claude`, a `.mcp.json` is automatically created:
+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
 
-```json
-{
-  "mcpServers": {
-    "lumenflow": {
-      "command": "npx",
-      "args": ["@lumenflow/mcp"]
-    }
-  }
-}
-```
+**Want enhanced integration for your AI?** See [Adding New Integrations](#adding-new-integrations) below.
 
-### Manual Setup
+---
+
+## All Integrations Setup
 
-If you already have LumenFlow but need to add MCP support:
+To configure all enhanced integrations at once:
 
 ```bash
-# Option 1: Re-run init with force to regenerate all files
-lumenflow init --client claude --force
-
-# Option 2: Manually create .mcp.json
-echo '{
-  "mcpServers": {
-    "lumenflow": {
-      "command": "npx",
-      "args": ["@lumenflow/mcp"]
-    }
-  }
-}' > .mcp.json
+lumenflow init --client all
 ```
 
-### Available MCP Tools
-
-The `@lumenflow/mcp` server provides these tools to AI assistants:
-
-| Tool           | Description                          |
-| -------------- | ------------------------------------ |
-| `wu_status`    | Get current WU status and location   |
-| `wu_claim`     | Claim a WU and create worktree       |
-| `gates`        | Run quality gates                    |
-| `mem_checkpoint` | Save progress checkpoint           |
-| `mem_inbox`    | Check coordination signals           |
-| `lane_health`  | Check lane configuration health      |
+This creates all vendor-specific configuration files alongside the universal entry points.
 
 ---
 

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

@@ -42,7 +42,7 @@ 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
+pnpm wu:brief --id WU-XXX --client claude-code
 
 # 4. EXIT current session (do NOT continue after compaction)
 
@@ -97,8 +97,8 @@ LumenFlow implements automatic recovery hooks that preserve context across compa
 # Generate recovery context manually (if hooks didn't fire)
 pnpm mem:recover --wu WU-XXX
 
-# Generate spawn prompt with full context
-pnpm wu:spawn --id WU-XXX
+# Generate prompt with full context
+pnpm wu:brief --id WU-XXX --client claude-code
 ```
 
 **Important**: The recovery hooks are a safety net. The recommended approach is still to spawn

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

@@ -0,0 +1,151 @@
+---
+name: design-first
+description: 5-step design validation before implementation. Question requirements, delete unnecessary, simplify, speed up, automate last. Use BEFORE TDD, BEFORE writing any code.
+version: 1.0.0
+source: .claude/skills/design-first/SKILL.md
+last_updated: {{DATE}}
+allowed-tools: Read, Grep, Glob
+---
+
+# Design-First Skill (5-Step Algorithm)
+
+Before writing code, follow these 5 steps IN ORDER. The order matters—don't optimize something that shouldn't exist.
+
+## When to Use
+
+Activate this skill when:
+
+- Starting work on a feature WU
+- Creating an initiative plan
+- Designing a new component or system
+- Before loading tdd-workflow skill
+
+**Critical**: This skill comes BEFORE TDD. Question whether the feature should exist before writing the first failing test.
+
+## The 5 Steps
+
+### Step 1: Question the Requirements
+
+Before accepting any requirement, ask:
+
+| Question                          | If "No" Then...                  |
+| --------------------------------- | -------------------------------- |
+| Is the requirement specific?      | Get clarity before proceeding    |
+| Is this the real problem?         | Dig deeper into root cause       |
+| Would users actually want this?   | Validate with evidence           |
+| Does this already exist?          | Use existing feature/library     |
+| Who requested this? Right person? | Verify authority to define scope |
+
+**STOP if**: You cannot articulate the specific user problem being solved in 1-2 sentences.
+
+### Step 2: Try to Delete
+
+Before building anything:
+
+| Question                             | Action             |
+| ------------------------------------ | ------------------ |
+| Can we remove this feature entirely? | Try removing it    |
+| What would break without it?         | If nothing, cut it |
+| Is this "nice to have"?              | Cut for MVP        |
+| Are there unnecessary steps?         | Eliminate them     |
+
+**The 10% Rule**: You must consider at least 3 things for deletion. If you end up keeping everything, you weren't aggressive enough. If you don't have to put back at least 10% of what you deleted, you didn't delete enough.
+
+**Document**: What you considered deleting and why it was retained.
+
+### Step 3: Simplify / Optimize
+
+Only after Steps 1-2:
+
+- Can this use fewer abstractions?
+- Can this use existing patterns? (Check codebase first)
+- Can this use a library? (Load `/skill library-first`)
+- Is this the simplest solution that works?
+
+**Warning**: The most common mistake of smart engineers is optimizing something that should not exist.
+
+### Step 4: Speed Up
+
+Only after Step 3:
+
+- Are there performance bottlenecks?
+- Can caching help?
+- Is latency acceptable?
+
+**Skip if**: Feature doesn't have explicit performance requirements. Don't prematurely optimize.
+
+### Step 5: Automate
+
+Last step, never first:
+
+- Is the manual process proven to work?
+- Is the process stable enough to automate?
+- Will automation actually help users?
+
+**Warning**: Automating a bad process makes bad things happen faster.
+
+## Required Documentation
+
+Before implementation, document in WU notes or plan:
+
+```yaml
+design_validation:
+  step1_requirements:
+    problem: 'User cannot X because Y'
+    validated_by: 'User interview / data / assumption'
+  step2_deletion:
+    considered: ['Feature A', 'Component B', 'Step C']
+    removed: ['Component B']
+    retained_reason: 'Feature A needed for acceptance criteria'
+  step3_simplification:
+    approach: 'Using existing library X instead of custom code'
+    library_refs: ['zod', 'date-fns']
+  step4_speed: 'N/A - no performance requirements'
+  step5_automation: 'Manual first, will automate in future WU'
+```
+
+## Decision Tree
+
+```
+Starting a feature?
+├─ Can you articulate the user problem in 1-2 sentences?
+│   └─ NO → STOP. Clarify requirements first.
+│
+├─ Have you considered what to delete?
+│   └─ NO → STOP. List 3+ things to potentially cut.
+│
+├─ Is there a simpler approach?
+│   └─ MAYBE → Load /skill library-first, check for existing patterns
+│
+└─ All steps complete?
+    └─ YES → Proceed to /skill tdd-workflow
+```
+
+## Integration with Other Skills
+
+| Skill           | Relationship                                               |
+| --------------- | ---------------------------------------------------------- |
+| `library-first` | Step 3 — Use during Simplify phase                         |
+| `tdd-workflow`  | Comes AFTER design-first. Don't test what shouldn't exist. |
+| `code-quality`  | Step 3 — SOLID/DRY/KISS alignment                          |
+
+## Red Flags (Stop and Reconsider)
+
+- Writing code without answering Step 1 questions
+- Keeping everything you started with (Step 2 not applied)
+- Automating before manual process proven (Step 5 violation)
+- Optimizing before simplifying (Steps 3-4 order violation)
+- Building custom code when a library exists (Step 3 violation)
+
+## Anti-Patterns
+
+| Anti-Pattern                           | What to Do Instead                      |
+| -------------------------------------- | --------------------------------------- |
+| "We might need this later"             | YAGNI — delete it, add when needed      |
+| "Let me optimize this first"           | Simplify first, optimize after it works |
+| "I'll automate this from the start"    | Prove it manually, then automate        |
+| "The requirement says X, so I'll do X" | Question X first                        |
+
+---
+
+**Core Principle**: "The best code is no code. The best feature is no feature. Question everything before building anything."

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

@@ -124,31 +124,31 @@ Initiatives often span multiple lanes. Key coordination patterns:
 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)
+## Delegating Sub-Agents for Initiative WUs (MANDATORY)
 
-When orchestrating an initiative with multiple WUs, use `wu:spawn` to generate complete Task invocations:
+When orchestrating an initiative with multiple WUs, use `wu:brief` or `wu:delegate` 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
+pnpm wu:brief --id WU-1501 --client claude-code    # Prompt generation only
+pnpm wu:delegate --id WU-1502 --parent-wu WU-1500  # Prompt + lineage recording
+pnpm wu:delegate --id WU-1503 --parent-wu WU-1500
 ```
 
 ### Orchestration Pattern
 
-1. **Generate prompts**: Run `pnpm wu:spawn --id WU-XXX` for each WU
+1. **Generate prompts**: Run `pnpm wu:brief --id WU-XXX` (or `wu:delegate` for lineage) 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
+### What wu:brief/wu:delegate 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
+### When NOT to Use wu:brief/wu:delegate
 
 - Helper agents for the orchestrator's own WU (use inline context)
 - Validation agents checking orchestrator's work

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

@@ -90,6 +90,7 @@ library_decisions:
 
 ## Integration with Other Skills
 
+- **design-first**: Library-First is Step 3 (Simplify) of the 5-step algorithm
 - **tdd-workflow**: Library selection happens BEFORE writing tests
 - **code-quality**: Library-first prevents DRY violations
 

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

@@ -26,16 +26,16 @@ Activate this skill when:
 - Git prevents duplicate branches = automatic locking
 - No heartbeats, no session files
 
-## Spawning Sub-Agents
+## Delegating to Sub-Agents
 
-**Use wu:spawn** when delegating entire WU:
+**Use wu:brief/wu:delegate** when delegating an entire WU:
 
 ```bash
-pnpm wu:spawn --id WU-XXX              # Standard
-pnpm wu:spawn --id WU-XXX --thinking   # Complex WUs
+pnpm wu:brief --id WU-XXX --client claude-code      # Generate prompt only
+pnpm wu:delegate --id WU-XXX --parent-wu WU-YYY     # Generate prompt + record lineage
 ```
 
-**DON'T use wu:spawn** for helper agents (code-reviewer, test-engineer) on YOUR WU.
+**DON'T use wu:brief/wu:delegate** for helper agents (code-reviewer, test-engineer) on YOUR WU.
 
 ## Parallel Spawning
 

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

@@ -27,20 +27,23 @@ Activate this skill when:
 # ✅ 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
+# ✅ CORRECT: Use wu:brief for prompt generation
+pnpm wu:brief --id WU-XXX --client claude-code
+
+# ✅ CORRECT: Use wu:delegate for lineage-tracked delegation
+pnpm wu:delegate --id WU-XXX --parent-wu WU-YYY
 ```
 
 **❌ NEVER do this:**
 
-- Directly invoke Task tool for WU execution without using wu:spawn output
+- Directly invoke Task tool for WU execution without using wu:brief/wu:delegate output
 - Manually craft spawn prompts (they miss context loading, TDD directives, constraints)
-- Skip wu:spawn when delegating entire WUs to sub-agents
+- Skip wu:brief/wu:delegate 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
+1. `wu:brief` generates prompts with context loading preamble, TDD directives, and constraints block
+2. Sub-agents need `wu:claim` (inside generated 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.**
@@ -49,18 +52,18 @@ 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.
+When using `wu:brief`/`wu:delegate` output to invoke Task agents, you **MUST** verify the output was not truncated.
 
 ### Truncation Detection
 
-`wu:spawn` output includes:
+`wu:brief`/`wu:delegate` 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:
+Before spawning a sub-agent with `wu:brief`/`wu:delegate` 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
@@ -68,9 +71,9 @@ Before spawning a sub-agent with `wu:spawn` output:
 
 ```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)
+pnpm wu:brief --id WU-XXX | tail -5    # Should show LUMENFLOW_SPAWN_END
+pnpm wu:brief --id WU-XXX | head -20   # Should show TRUNCATION_WARNING
+pnpm wu:brief --id WU-XXX | grep -c 'constraints'  # Should return 2 (open and close tags)
 ```
 
 ### What Truncation Causes
@@ -84,7 +87,7 @@ If spawn output is truncated, sub-agents will:
 
 ### If Truncation Is Detected
 
-1. Re-run `wu:spawn` and capture full output
+1. Re-run `wu:brief` 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
 
@@ -205,16 +208,16 @@ 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
+# After recovery, re-delegate
 pnpm wu:unblock --id WU-XXX
-pnpm wu:spawn --id WU-XXX
+pnpm wu:brief --id WU-XXX
 ```
 
 ## Decision Tree
 
 ```
 Starting WU?
-├── Run: pnpm wu:spawn --id WU-XXX
+├── Run: pnpm wu:brief --id WU-XXX --client <client>
 └── Review generated prompt with agent recommendations
 
 Initiative with multiple WUs?

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

@@ -21,6 +21,8 @@ Activate this skill when:
 - Need to understand which layer code belongs in
 - Writing use cases with dependency injection
 
+**Prerequisite**: Load `/skill design-first` FIRST to question requirements and simplify before writing tests.
+
 **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.