@lumenflow/cli 2.6.0 → 2.8.0

package/templates/core/ai/onboarding/rapid-prototyping.md

@@ -0,0 +1,143 @@
+# Rapid Prototyping with LumenFlow
+
+**Last updated:** {{DATE}}
+
+This guide explains how to move fast WITHIN the LumenFlow workflow, not by bypassing it.
+
+---
+
+## The Wrong Way: Skipping the Workflow
+
+When asked to "prototype quickly" or "just get something working," agents often:
+
+1. Skip WU creation ("let's just commit directly")
+2. Work on main branch ("worktrees slow us down")
+3. Skip tests ("we'll add them later")
+4. Bypass gates ("pre-commit hooks are annoying")
+
+**This creates technical debt, breaks workflow tracking, and causes merge conflicts.**
+
+---
+
+## The Right Way: Speed Through Parallelism
+
+LumenFlow enables speed through **parallel WUs across lanes**, not by skipping steps.
+
+### Speed Strategy 1: Multiple Small WUs
+
+Instead of one large WU, create multiple focused WUs:
+
+```bash
+# SLOW: One massive WU
+pnpm wu:create --lane "Framework: Core" --title "Build entire auth system"
+# Takes 4 hours, blocks the lane
+
+# FAST: Multiple parallel WUs
+pnpm wu:create --lane "Framework: Core" --title "Add user model"
+pnpm wu:create --lane "Framework: API" --title "Add auth endpoints"
+pnpm wu:create --lane "Experience: UI" --title "Add login form"
+# Each takes 1 hour, run in parallel across 3 lanes
+```
+
+### Speed Strategy 2: Spawn Sub-Agents
+
+For complex work, spawn sub-agents to work in parallel:
+
+```bash
+# Generate spawn prompt for parallel agent
+pnpm wu:spawn --id WU-123 --client claude-code
+```
+
+Sub-agents work on different aspects simultaneously:
+
+- Agent 1: Core business logic
+- Agent 2: API endpoints
+- Agent 3: UI components
+- Agent 4: Tests
+
+### Speed Strategy 3: Wave-Based Execution
+
+Orchestrate initiatives in waves:
+
+```bash
+# View what can run in parallel
+pnpm orchestrate:init-status --id INIT-001
+
+# Spawn wave of WUs
+pnpm orchestrate:initiative --id INIT-001 --wave 1
+```
+
+### Speed Strategy 4: Docs-Only Fast Path
+
+For documentation changes, use the fast path:
+
+```bash
+# Skip lint/typecheck/tests for docs
+pnpm gates --docs-only
+```
+
+---
+
+## Time Comparison
+
+| Approach        | Perceived Speed | Actual Time             | Technical Debt |
+| --------------- | --------------- | ----------------------- | -------------- |
+| Skip workflow   | "Instant"       | +2h later fixing issues | High           |
+| Single large WU | Slow            | 4h blocked              | Low            |
+| Parallel WUs    | Fast            | 1h each, parallel       | None           |
+
+---
+
+## Quick Reference: Fast But Safe
+
+```bash
+# Fast: Create focused WU
+pnpm wu:create --lane "Framework: Core" --title "Specific task"
+
+# Fast: Claim and work
+pnpm wu:claim --id WU-XXX --lane "Framework: Core"
+cd worktrees/framework-core-wu-xxx
+
+# Fast: Minimal viable implementation
+# Write ONE test, implement, pass
+
+# Fast: Complete
+pnpm wu:prep --id WU-XXX
+cd /path/to/main && pnpm wu:done --id WU-XXX
+```
+
+---
+
+## What to Say When Asked to "Skip the Workflow"
+
+When a user says "just prototype this quickly":
+
+1. **Acknowledge the urgency**: "I understand you want this fast."
+2. **Explain the approach**: "I'll create focused WUs that can run in parallel."
+3. **Deliver value quickly**: "Here's the first deliverable in 30 minutes."
+
+**Never say**: "Let me skip the workflow to save time."
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern           | Why It's Slow                 | Better Alternative      |
+| ---------------------- | ----------------------------- | ----------------------- |
+| Direct commits to main | Merge conflicts, broken gates | Use worktrees           |
+| One massive WU         | Blocks lane for hours         | Split into parallel WUs |
+| Skip tests             | Bugs found late, rework       | TDD from start          |
+| "We'll document later" | Context lost, debt            | Capture as you go       |
+
+---
+
+## Summary
+
+**Speed in LumenFlow comes from parallelism, not shortcuts.**
+
+- Multiple small WUs across lanes
+- Sub-agents for complex work
+- Wave-based orchestration
+- Docs-only fast path when applicable
+
+The workflow exists to prevent the slowdowns that come from technical debt, merge conflicts, and broken builds.

package/templates/core/ai/onboarding/starting-prompt.md.template

@@ -10,7 +10,7 @@ This is the complete onboarding document for AI agents working with LumenFlow. R
 
 ```bash
 # 1. Check your assigned WU
-cat docs/04-operations/tasks/wu/WU-XXXX.yaml
+cat {{DOCS_TASKS_PATH}}/wu/WU-XXXX.yaml
 
 # 2. Claim the WU (creates isolated worktree)
 pnpm wu:claim --id WU-XXXX --lane "Lane Name"
@@ -160,7 +160,7 @@ git add . && git commit -m "your message"
 **Fix:** Regenerate the backlog or manually add the missing WU:
 
 ```bash
-# In worktree, edit docs/04-operations/tasks/backlog.md
+# In worktree, edit {{DOCS_TASKS_PATH}}/backlog.md
 # Add the missing WU reference in the appropriate section
 ```
 
@@ -266,7 +266,7 @@ pnpm wu:spawn --id WU-XXXX --client <client-type>
 
 ```
 /path/to/repo/
-├── docs/04-operations/tasks/
+├── {{DOCS_TASKS_PATH}}/
 │   ├── backlog.md              # All WUs listed here
 │   └── wu/WU-XXXX.yaml         # Individual WU specs
 ├── worktrees/

package/templates/vendors/claude/.claude/CLAUDE.md.template

@@ -36,6 +36,31 @@ See [LUMENFLOW.md](../LUMENFLOW.md) and [ai/onboarding/troubleshooting-wu-done.m
 
 ---
 
+## Orchestration & Memory Commands
+
+Essential commands for multi-agent coordination and context management:
+
+| Command                                    | Description                       |
+| ------------------------------------------ | --------------------------------- |
+| `pnpm orchestrate:init-status -i INIT-XXX` | View initiative progress          |
+| `pnpm orchestrate:monitor`                 | Monitor spawn/agent activity      |
+| `pnpm mem:checkpoint --wu WU-XXX`          | Save progress checkpoint          |
+| `pnpm mem:inbox --since 30m`               | Check coordination signals        |
+| `pnpm mem:signal "msg" --wu WU-XXX`        | Broadcast signal to other agents  |
+| `pnpm mem:create "msg" --wu WU-XXX`        | Create memory node (bug capture)  |
+| `pnpm wu:spawn --id WU-XXX --client claude-code` | Spawn sub-agent prompt     |
+
+**When to checkpoint:**
+- After each acceptance criterion completed
+- Before running gates
+- Every 30+ tool calls
+
+**When to check inbox:**
+- Before starting complex work (parallel agents may have signals)
+- When blocked (other agents may have completed dependencies)
+
+---
+
 ## Claude-Specific Settings
 
 This directory contains Claude Code-specific configuration:

package/templates/vendors/claude/.claude/hooks/enforce-worktree.sh

@@ -0,0 +1,135 @@
+#!/bin/bash
+#
+# enforce-worktree.sh
+#
+# Claude PreToolUse hook that blocks Write/Edit operations on main branch.
+#
+# This hook enforces worktree discipline for Claude Code specifically,
+# complementing the git pre-commit hook for stronger enforcement.
+#
+# Exit codes:
+#   0 = Allow operation
+#   2 = Block operation (stderr shown to Claude as guidance)
+#
+# Security: Fail-open design for this hook (branches can't always be detected)
+#   - If branch detection fails, allow operation (git hooks will catch it)
+#   - If JSON parse fails, allow operation (defensive, log warning)
+#
+# Blocking conditions:
+#   - Current branch is main or master
+#   - Tool is Write or Edit
+#   - Target file is in the main repo (not a worktree)
+#
+
+set -euo pipefail
+
+# Derive repo paths from CLAUDE_PROJECT_DIR
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+  MAIN_REPO_PATH="$CLAUDE_PROJECT_DIR"
+else
+  MAIN_REPO_PATH=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+  if [[ -z "$MAIN_REPO_PATH" ]]; then
+    # Not in a git repo - allow operation
+    exit 0
+  fi
+fi
+
+# Check if we're on main/master branch
+CURRENT_BRANCH=$(git -C "$MAIN_REPO_PATH" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+
+# If branch detection fails, fail-open (git hooks will catch issues)
+if [[ -z "$CURRENT_BRANCH" ]]; then
+  exit 0
+fi
+
+# Allow operations on non-main branches
+case "$CURRENT_BRANCH" in
+  main|master)
+    # Continue to check tool type
+    ;;
+  *)
+    # Not on main/master - allow
+    exit 0
+    ;;
+esac
+
+# Read JSON input from stdin
+INPUT=$(cat)
+
+# If no input, fail-open (defensive)
+if [[ -z "$INPUT" ]]; then
+  exit 0
+fi
+
+# Parse JSON with Python to extract tool_name and file_path
+PARSE_RESULT=$(python3 -c "
+import json
+import sys
+try:
+    data = json.loads('''$INPUT''')
+    tool_name = data.get('tool_name', '')
+    tool_input = data.get('tool_input', {})
+    if not isinstance(tool_input, dict):
+        tool_input = {}
+    file_path = tool_input.get('file_path', '')
+    print('OK')
+    print(tool_name if tool_name else '')
+    print(file_path if file_path else '')
+except Exception as e:
+    print('ERROR')
+    print(str(e))
+    print('')
+" 2>&1)
+
+# Parse the result
+PARSE_STATUS=$(echo "$PARSE_RESULT" | head -1)
+TOOL_NAME=$(echo "$PARSE_RESULT" | sed -n '2p')
+FILE_PATH=$(echo "$PARSE_RESULT" | sed -n '3p')
+
+# If parse failed, fail-open (defensive)
+if [[ "$PARSE_STATUS" != "OK" ]]; then
+  exit 0
+fi
+
+# Only block Write and Edit tools
+if [[ "$TOOL_NAME" != "Write" && "$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+# Check if file path is in a worktree (allowed) or main repo (blocked)
+WORKTREES_DIR="${MAIN_REPO_PATH}/worktrees"
+
+if [[ -n "$FILE_PATH" ]]; then
+  RESOLVED_PATH=$(realpath -m "$FILE_PATH" 2>/dev/null || echo "$FILE_PATH")
+
+  # Allow if path is inside a worktree
+  if [[ "$RESOLVED_PATH" == "${WORKTREES_DIR}/"* ]]; then
+    exit 0
+  fi
+fi
+
+# Block: We're on main/master and trying to Write/Edit outside a worktree
+echo "" >&2
+echo "=== LumenFlow Worktree Enforcement ===" >&2
+echo "" >&2
+echo "BLOCKED: ${TOOL_NAME} operation on main branch" >&2
+echo "" >&2
+echo "You are on the '${CURRENT_BRANCH}' branch. Direct edits to main are not allowed." >&2
+echo "" >&2
+echo "WHAT TO DO:" >&2
+echo "  1. Claim a WU to create a worktree:" >&2
+echo "     pnpm wu:claim --id WU-XXXX --lane \"<Lane>\"" >&2
+echo "" >&2
+echo "  2. Move to the worktree:" >&2
+echo "     cd worktrees/<lane>-wu-xxxx" >&2
+echo "" >&2
+echo "  3. Make your edits in the worktree" >&2
+echo "" >&2
+echo "WHY THIS MATTERS:" >&2
+echo "  - Worktrees isolate your changes from other work" >&2
+echo "  - All changes are tracked through the WU workflow" >&2
+echo "  - Parallel work across lanes stays independent" >&2
+echo "" >&2
+echo "See: LUMENFLOW.md for complete workflow documentation" >&2
+echo "========================================" >&2
+exit 2