@lumenflow/cli 1.3.6 → 1.4.0

package/README.md

@@ -63,6 +63,13 @@ This package provides CLI commands for the LumenFlow workflow framework, includi
 | `initiative-status` | Show initiative status and progress |
 | `initiative-add-wu` | Link a WU to an initiative          |
 
+### Setup Commands
+
+| Command     | Description                                         |
+| ----------- | --------------------------------------------------- |
+| `init`      | Scaffold LumenFlow into a project                   |
+| `docs-sync` | Sync agent onboarding docs (for upgrading projects) |
+
 ### Other Commands
 
 | Command      | Description                                        |

package/dist/docs-sync.js

@@ -0,0 +1,452 @@
+/**
+ * @file docs-sync.ts
+ * LumenFlow docs:sync command for syncing agent docs to existing projects (WU-1083)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Get current date in YYYY-MM-DD format
+ */
+function getCurrentDate() {
+    return new Date().toISOString().split('T')[0];
+}
+/**
+ * Process template content by replacing placeholders
+ */
+function processTemplate(content, tokens) {
+    let output = content;
+    for (const [key, value] of Object.entries(tokens)) {
+        output = output.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value);
+    }
+    return output;
+}
+function getRelativePath(targetDir, filePath) {
+    return path.relative(targetDir, filePath).split(path.sep).join('/');
+}
+/**
+ * Create a directory if missing
+ */
+async function createDirectory(dirPath, result, targetDir) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+        result.created.push(getRelativePath(targetDir, dirPath));
+    }
+}
+/**
+ * Create a file, respecting force option
+ */
+async function createFile(filePath, content, force, result, targetDir) {
+    const relativePath = getRelativePath(targetDir, filePath);
+    if (fs.existsSync(filePath) && !force) {
+        result.skipped.push(relativePath);
+        return;
+    }
+    const parentDir = path.dirname(filePath);
+    if (!fs.existsSync(parentDir)) {
+        fs.mkdirSync(parentDir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, content);
+    result.created.push(relativePath);
+}
+// Agent onboarding docs templates (duplicated from init.ts for modularity)
+const QUICK_REF_COMMANDS_TEMPLATE = `# Quick Reference: LumenFlow Commands
+
+**Last updated:** {{DATE}}
+
+---
+
+## Project Setup
+
+| Command                                       | Description                             |
+| --------------------------------------------- | --------------------------------------- |
+| \`pnpm exec lumenflow init\`                    | Scaffold minimal LumenFlow core         |
+| \`pnpm exec lumenflow init --full\`             | Add docs/04-operations task scaffolding |
+| \`pnpm exec lumenflow init --framework <name>\` | Add framework hint + overlay docs       |
+| \`pnpm exec lumenflow init --force\`            | Overwrite existing files                |
+
+---
+
+## WU Management
+
+| Command                                                                                                                                                                                                               | Description                                   |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| \`pnpm wu:create --id WU-XXX --lane <Lane> --title "Title" --description "..." --acceptance "..." --code-paths "path" --test-paths-unit "path" --exposure backend-only --spec-refs "~/.lumenflow/plans/WU-XXX.md"\` | Create new WU                                 |
+| \`pnpm wu:claim --id WU-XXX --lane <Lane>\`                                                                                                                                                                             | Claim WU (creates worktree)                   |
+| \`pnpm wu:done --id WU-XXX\`                                                                                                                                                                                            | Complete WU (merge, stamp, cleanup)           |
+| \`pnpm wu:block --id WU-XXX --reason "Reason"\`                                                                                                                                                                         | Block a WU                                    |
+| \`pnpm wu:unblock --id WU-XXX\`                                                                                                                                                                                         | Unblock a WU                                  |
+
+---
+
+## Gates
+
+| Command                  | Description                |
+| ------------------------ | -------------------------- |
+| \`pnpm gates\`             | Run all quality gates      |
+| \`pnpm gates --docs-only\` | Run gates for docs changes |
+| \`pnpm format\`            | Format all files           |
+| \`pnpm lint\`              | Run linter                 |
+| \`pnpm typecheck\`         | Run TypeScript check       |
+
+---
+
+## File Paths
+
+| Path                                      | Description          |
+| ----------------------------------------- | -------------------- |
+| \`docs/04-operations/tasks/wu/WU-XXX.yaml\` | WU specification     |
+| \`docs/04-operations/tasks/status.md\`      | Current status board |
+| \`.lumenflow/stamps/WU-XXX.done\`           | Completion stamp     |
+| \`worktrees/<lane>-wu-xxx/\`                | Worktree directory   |
+`;
+const FIRST_WU_MISTAKES_TEMPLATE = `# First WU Mistakes
+
+**Last updated:** {{DATE}}
+
+Common mistakes agents make on their first WU, and how to avoid them.
+
+---
+
+## Mistake 1: Not Using Worktrees
+
+### Wrong
+
+\`\`\`bash
+# Working directly in main
+vim src/feature.ts
+git commit -m "feat: add feature"
+git push origin main
+\`\`\`
+
+### Right
+
+\`\`\`bash
+# Claim first, then work in worktree
+pnpm wu:claim --id WU-123 --lane Core
+cd worktrees/core-wu-123
+vim src/feature.ts
+git commit -m "feat: add feature"
+git push origin lane/core/wu-123
+cd /path/to/main
+pnpm wu:done --id WU-123
+\`\`\`
+
+---
+
+## Mistake 2: Forgetting to Run wu:done
+
+**TL;DR:** After gates pass, ALWAYS run \`pnpm wu:done --id WU-XXX\`.
+
+---
+
+## Mistake 3: Working Outside code_paths
+
+Only edit files within the specified \`code_paths\`.
+
+---
+
+## Quick Checklist
+
+- [ ] Claim the WU with \`pnpm wu:claim\`
+- [ ] cd to the worktree IMMEDIATELY
+- [ ] Work only in the worktree
+- [ ] Run gates before wu:done
+- [ ] ALWAYS run wu:done
+`;
+const TROUBLESHOOTING_WU_DONE_TEMPLATE = `# Troubleshooting: wu:done Not Run
+
+**Last updated:** {{DATE}}
+
+This is the most common mistake agents make.
+
+---
+
+## The Fix
+
+### Rule: ALWAYS Run wu:done
+
+After gates pass, you MUST run:
+
+\`\`\`bash
+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
+
+---
+
+## What wu:done Does
+
+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
+`;
+const AGENT_SAFETY_CARD_TEMPLATE = `# Agent Safety Card
+
+**Last updated:** {{DATE}}
+
+Quick reference for AI agents working in LumenFlow projects.
+
+---
+
+## Stop and Ask When
+
+- Same error repeats 3 times
+- Auth or permissions changes needed
+- PII/PHI/secrets involved
+- Cloud spend decisions
+
+---
+
+## Never Do
+
+| Action                   | Why              |
+| ------------------------ | ---------------- |
+| \`git reset --hard\`       | Data loss        |
+| \`git push --force\`       | History rewrite  |
+| \`--no-verify\`            | Bypasses safety  |
+| Work in main after claim | Breaks isolation |
+| Skip wu:done             | Incomplete WU    |
+
+---
+
+## Always Do
+
+| Action                     | Why              |
+| -------------------------- | ---------------- |
+| Read WU spec first         | Understand scope |
+| cd to worktree after claim | Isolation        |
+| Write tests before code    | TDD              |
+| Run gates before wu:done   | Quality          |
+| Run wu:done                | Complete WU      |
+`;
+const WU_CREATE_CHECKLIST_TEMPLATE = `# WU Creation Checklist
+
+**Last updated:** {{DATE}}
+
+Before running \`pnpm wu:create\`, verify these items.
+
+---
+
+## Step 1: Check Valid Lanes
+
+\`\`\`bash
+grep -A 30 "lanes:" .lumenflow.config.yaml
+\`\`\`
+
+**Format:** \`"Parent: Sublane"\` (colon + single space)
+
+---
+
+## Step 2: Required Fields
+
+| Field | Required For | Example |
+|-------|--------------|---------|
+| \`--id\` | All | \`WU-1234\` |
+| \`--lane\` | All | \`"Experience: Chat"\` |
+| \`--title\` | All | \`"Add feature"\` |
+| \`--description\` | All | \`"Context: ... Problem: ... Solution: ..."\` |
+| \`--acceptance\` | All | \`--acceptance "Works"\` (repeatable) |
+| \`--exposure\` | All | \`ui\`, \`api\`, \`backend-only\`, \`documentation\` |
+| \`--code-paths\` | Code WUs | \`"src/a.ts,src/b.ts"\` |
+| \`--test-paths-unit\` | Code WUs | \`"src/__tests__/a.test.ts"\` |
+| \`--spec-refs\` | Feature WUs | \`"~/.lumenflow/plans/WU-XXX.md"\` |
+
+---
+
+## Step 3: Plan Storage
+
+Plans go in \`~/.lumenflow/plans/\` (NOT in project):
+
+\`\`\`bash
+mkdir -p ~/.lumenflow/plans
+vim ~/.lumenflow/plans/WU-XXX-plan.md
+\`\`\`
+
+Reference in wu:create:
+\`\`\`bash
+--spec-refs "~/.lumenflow/plans/WU-XXX-plan.md"
+\`\`\`
+
+---
+
+## Step 4: Validate First
+
+\`\`\`bash
+pnpm wu:create --id WU-XXX ... --validate
+\`\`\`
+
+Fix errors, then remove \`--validate\` to create.
+`;
+// Claude skills templates
+const WU_LIFECYCLE_SKILL_TEMPLATE = `---
+name: wu-lifecycle
+description: Work Unit claim/block/done workflow automation.
+version: 1.0.0
+---
+
+# WU Lifecycle Skill
+
+## State Machine
+
+\`\`\`
+ready -> in_progress -> waiting/blocked -> done
+\`\`\`
+
+## Core Commands
+
+\`\`\`bash
+# Claim WU
+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
+\`\`\`
+`;
+const WORKTREE_DISCIPLINE_SKILL_TEMPLATE = `---
+name: worktree-discipline
+description: Prevents the "absolute path trap" in Write/Edit/Read tools.
+version: 1.0.0
+---
+
+# Worktree Discipline: Absolute Path Trap Prevention
+
+**Purpose**: Prevent AI agents from bypassing worktree isolation via absolute file paths.
+
+## The Absolute Path Trap
+
+**Problem**: AI agents using Write/Edit/Read tools can bypass worktree isolation by passing absolute paths.
+
+## Golden Rules
+
+1. **Always verify pwd** before file operations
+2. **Never use absolute paths** in Write/Edit/Read tools
+3. **When in doubt, use relative paths**
+`;
+const LUMENFLOW_GATES_SKILL_TEMPLATE = `---
+name: lumenflow-gates
+description: Quality gates troubleshooting (format, lint, typecheck, tests).
+version: 1.0.0
+---
+
+# LumenFlow Gates Skill
+
+## 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  |
+`;
+/**
+ * Sync agent onboarding docs to an existing project
+ */
+export async function syncAgentDocs(targetDir, options) {
+    const result = {
+        created: [],
+        skipped: [],
+    };
+    const tokens = {
+        DATE: getCurrentDate(),
+    };
+    const onboardingDir = path.join(targetDir, 'docs', '04-operations', '_frameworks', 'lumenflow', 'agent', 'onboarding');
+    await createDirectory(onboardingDir, result, targetDir);
+    await createFile(path.join(onboardingDir, 'quick-ref-commands.md'), processTemplate(QUICK_REF_COMMANDS_TEMPLATE, tokens), options.force, result, targetDir);
+    await createFile(path.join(onboardingDir, 'first-wu-mistakes.md'), processTemplate(FIRST_WU_MISTAKES_TEMPLATE, tokens), options.force, result, targetDir);
+    await createFile(path.join(onboardingDir, 'troubleshooting-wu-done.md'), processTemplate(TROUBLESHOOTING_WU_DONE_TEMPLATE, tokens), options.force, result, targetDir);
+    await createFile(path.join(onboardingDir, 'agent-safety-card.md'), processTemplate(AGENT_SAFETY_CARD_TEMPLATE, tokens), options.force, result, targetDir);
+    await createFile(path.join(onboardingDir, 'wu-create-checklist.md'), processTemplate(WU_CREATE_CHECKLIST_TEMPLATE, tokens), options.force, result, targetDir);
+    return result;
+}
+/**
+ * Sync Claude skills to an existing project
+ */
+export async function syncSkills(targetDir, options) {
+    const result = {
+        created: [],
+        skipped: [],
+    };
+    const vendor = options.vendor ?? 'none';
+    if (vendor !== 'claude' && vendor !== 'all') {
+        return result;
+    }
+    const tokens = {
+        DATE: getCurrentDate(),
+    };
+    const skillsDir = path.join(targetDir, '.claude', 'skills');
+    // wu-lifecycle skill
+    const wuLifecycleDir = path.join(skillsDir, 'wu-lifecycle');
+    await createDirectory(wuLifecycleDir, result, targetDir);
+    await createFile(path.join(wuLifecycleDir, 'SKILL.md'), processTemplate(WU_LIFECYCLE_SKILL_TEMPLATE, tokens), options.force, result, targetDir);
+    // worktree-discipline skill
+    const worktreeDir = path.join(skillsDir, 'worktree-discipline');
+    await createDirectory(worktreeDir, result, targetDir);
+    await createFile(path.join(worktreeDir, 'SKILL.md'), processTemplate(WORKTREE_DISCIPLINE_SKILL_TEMPLATE, tokens), options.force, result, targetDir);
+    // lumenflow-gates skill
+    const gatesDir = path.join(skillsDir, 'lumenflow-gates');
+    await createDirectory(gatesDir, result, targetDir);
+    await createFile(path.join(gatesDir, 'SKILL.md'), processTemplate(LUMENFLOW_GATES_SKILL_TEMPLATE, tokens), options.force, result, targetDir);
+    return result;
+}
+/**
+ * Parse vendor flag from arguments
+ */
+function parseVendorArg(args) {
+    const vendorIndex = args.findIndex((arg) => arg === '--vendor');
+    if (vendorIndex !== -1 && args[vendorIndex + 1]) {
+        const vendor = args[vendorIndex + 1].toLowerCase();
+        if (['claude', 'cursor', 'aider', 'all', 'none'].includes(vendor)) {
+            return vendor;
+        }
+    }
+    return undefined;
+}
+/**
+ * CLI entry point for docs:sync command
+ */
+export async function main() {
+    const args = process.argv.slice(2);
+    const force = args.includes('--force') || args.includes('-f');
+    const vendor = parseVendorArg(args) ?? 'claude'; // Default to claude
+    const targetDir = process.cwd();
+    console.log('[lumenflow docs:sync] Syncing agent documentation...');
+    console.log(`  Vendor: ${vendor}`);
+    console.log(`  Force: ${force}`);
+    const docsResult = await syncAgentDocs(targetDir, { force });
+    const skillsResult = await syncSkills(targetDir, { force, vendor });
+    const created = [...docsResult.created, ...skillsResult.created];
+    const skipped = [...docsResult.skipped, ...skillsResult.skipped];
+    if (created.length > 0) {
+        console.log('\nCreated:');
+        created.forEach((f) => console.log(`  + ${f}`));
+    }
+    if (skipped.length > 0) {
+        console.log('\nSkipped (already exists, use --force to overwrite):');
+        skipped.forEach((f) => console.log(`  - ${f}`));
+    }
+    console.log('\n[lumenflow docs:sync] Done!');
+}
+// CLI entry point (WU-1071 pattern: import.meta.main)
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    runCLI(main);
+}

package/dist/init.js

@@ -118,6 +118,773 @@ const WU_TEMPLATE_YAML = `# Work Unit Template (LumenFlow WU Schema)\n#\n# Copy
 const FRAMEWORK_HINT_TEMPLATE = `# LumenFlow Framework Hint\n# Generated by: lumenflow init --framework {{FRAMEWORK_NAME}}\n\nframework: "{{FRAMEWORK_NAME}}"\nslug: "{{FRAMEWORK_SLUG}}"\n`;
 // Template for docs/04-operations/_frameworks/<framework>/README.md
 const FRAMEWORK_OVERLAY_TEMPLATE = `# {{FRAMEWORK_NAME}} Framework Overlay\n\n**Last updated:** {{DATE}}\n\nThis overlay captures framework-specific conventions, constraints, and references for {{FRAMEWORK_NAME}} projects.\n\n## Scope\n\n- Project structure conventions\n- Framework-specific testing guidance\n- Common pitfalls and mitigations\n\n## References\n\n- Add official docs links here\n`;
+// WU-1083: Agent onboarding docs templates
+const QUICK_REF_COMMANDS_TEMPLATE = `# Quick Reference: LumenFlow Commands
+
+**Last updated:** {{DATE}}
+
+---
+
+## Project Setup
+
+| Command                                       | Description                             |
+| --------------------------------------------- | --------------------------------------- |
+| \`pnpm exec lumenflow init\`                    | Scaffold minimal LumenFlow core         |
+| \`pnpm exec lumenflow init --full\`             | Add docs/04-operations task scaffolding |
+| \`pnpm exec lumenflow init --framework <name>\` | Add framework hint + overlay docs       |
+| \`pnpm exec lumenflow init --force\`            | Overwrite existing files                |
+
+---
+
+## WU Management
+
+| Command                                                                                                                                                                                                               | Description                                   |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| \`pnpm wu:create --id WU-XXX --lane <Lane> --title "Title" --description "..." --acceptance "..." --code-paths "path" --test-paths-unit "path" --exposure backend-only --spec-refs "~/.lumenflow/plans/WU-XXX.md"\` | Create new WU                                 |
+| \`pnpm wu:claim --id WU-XXX --lane <Lane>\`                                                                                                                                                                             | Claim WU (creates worktree)                   |
+| \`pnpm wu:done --id WU-XXX\`                                                                                                                                                                                            | Complete WU (merge, stamp, cleanup)           |
+| \`pnpm wu:block --id WU-XXX --reason "Reason"\`                                                                                                                                                                         | Block a WU                                    |
+| \`pnpm wu:unblock --id WU-XXX\`                                                                                                                                                                                         | Unblock a WU                                  |
+
+---
+
+## Gates
+
+| Command                  | Description                |
+| ------------------------ | -------------------------- |
+| \`pnpm gates\`             | Run all quality gates      |
+| \`pnpm gates --docs-only\` | Run gates for docs changes |
+| \`pnpm format\`            | Format all files           |
+| \`pnpm lint\`              | Run linter                 |
+| \`pnpm typecheck\`         | Run TypeScript check       |
+| \`pnpm test\`              | Run tests                  |
+
+---
+
+## Git (Safe Operations)
+
+| Command                              | Description               |
+| ------------------------------------ | ------------------------- |
+| \`git status\`                         | Check working tree status |
+| \`git add .\`                          | Stage all changes         |
+| \`git commit -m "type: message"\`      | Commit with message       |
+| \`git push origin lane/<lane>/wu-xxx\` | Push to remote            |
+
+---
+
+## Navigation
+
+\`\`\`bash
+# After claiming, go to worktree
+cd worktrees/<lane>-wu-xxx
+
+# Return to main for wu:done
+cd /path/to/main
+\`\`\`
+
+---
+
+## Workflow Sequence
+
+\`\`\`bash
+# 1. Create
+pnpm wu:create --id WU-001 --lane "Framework: Core" --title "Add feature" \\
+  --description "Context: ...\\nProblem: ...\\nSolution: ..." \\
+  --acceptance "Criterion 1" --acceptance "Criterion 2" \\
+  --code-paths "src/example.ts" \\
+  --test-paths-unit "src/__tests__/example.test.ts" \\
+  --exposure backend-only
+
+# 2. Claim
+pnpm wu:claim --id WU-001 --lane "Framework: Core"
+cd worktrees/framework-core-wu-001
+
+# 3. Work (TDD)
+# ... write tests first, then code ...
+
+# 4. Commit
+git add .
+git commit -m "feat: add feature"
+git push origin lane/framework-core/wu-001
+
+# 5. Gates
+pnpm gates
+
+# 6. Complete
+cd /path/to/main
+pnpm wu:done --id WU-001
+\`\`\`
+
+---
+
+## File Paths
+
+| Path                                      | Description          |
+| ----------------------------------------- | -------------------- |
+| \`docs/04-operations/tasks/wu/WU-XXX.yaml\` | WU specification     |
+| \`docs/04-operations/tasks/status.md\`      | Current status board |
+| \`.lumenflow/stamps/WU-XXX.done\`           | Completion stamp     |
+| \`worktrees/<lane>-wu-xxx/\`                | Worktree directory   |
+`;
+const FIRST_WU_MISTAKES_TEMPLATE = `# First WU Mistakes
+
+**Last updated:** {{DATE}}
+
+Common mistakes agents make on their first WU, and how to avoid them.
+
+---
+
+## Mistake 1: Not Using Worktrees
+
+### Wrong
+
+\`\`\`bash
+# Working directly in main
+vim src/feature.ts
+git commit -m "feat: add feature"
+git push origin main
+\`\`\`
+
+### Right
+
+\`\`\`bash
+# Claim first, then work in worktree
+pnpm wu:claim --id WU-123 --lane Core
+cd worktrees/core-wu-123
+vim src/feature.ts
+git commit -m "feat: add feature"
+git push origin lane/core/wu-123
+cd /path/to/main
+pnpm wu:done --id WU-123
+\`\`\`
+
+---
+
+## Mistake 2: Forgetting to Run wu:done
+
+See [troubleshooting-wu-done.md](troubleshooting-wu-done.md) for the full explanation.
+
+**TL;DR:** After gates pass, ALWAYS run \`pnpm wu:done --id WU-XXX\`.
+
+---
+
+## Mistake 3: Working Outside code_paths
+
+### Wrong
+
+The WU says \`code_paths: [src/api/**]\` but you edit \`src/ui/component.ts\`.
+
+### Right
+
+Only edit files within the specified \`code_paths\`. If you need to edit other files, that's a different WU.
+
+---
+
+## Mistake 4: Skipping TDD
+
+### Wrong
+
+\`\`\`
+1. Write the feature
+2. Maybe write tests later
+3. Tests are hard, skip them
+\`\`\`
+
+### Right
+
+\`\`\`
+1. Write failing test
+2. Run test (confirm RED)
+3. Write minimum code
+4. Run test (confirm GREEN)
+5. Refactor if needed
+\`\`\`
+
+---
+
+## Mistake 5: Using Forbidden Git Commands
+
+### Wrong
+
+\`\`\`bash
+git reset --hard HEAD
+git push --force
+git commit --no-verify
+\`\`\`
+
+### Right
+
+\`\`\`bash
+git add .
+git commit -m "feat: description"
+git push origin lane/core/wu-123
+\`\`\`
+
+---
+
+## Mistake 6: Ignoring Gate Failures
+
+### Wrong
+
+\`\`\`
+Gates failed but I think the code is fine.
+Let me use --skip-gates.
+\`\`\`
+
+### Right
+
+\`\`\`
+Gates failed. Let me read the error:
+- TypeScript error in src/api/handler.ts
+- Missing return type
+
+Fix: Add the return type.
+Re-run: pnpm gates
+\`\`\`
+
+---
+
+## Quick Checklist
+
+Before starting any WU:
+
+- [ ] Read the full WU spec
+- [ ] Understand acceptance criteria
+- [ ] Claim the WU with \`pnpm wu:claim\`
+- [ ] cd to the worktree IMMEDIATELY
+- [ ] Work only in the worktree
+- [ ] Stay within code_paths
+- [ ] Follow TDD
+- [ ] Run gates before wu:done
+- [ ] ALWAYS run wu:done
+`;
+const TROUBLESHOOTING_WU_DONE_TEMPLATE = `# Troubleshooting: wu:done Not Run
+
+**Last updated:** {{DATE}}
+
+This is the most common mistake agents make. This document explains why it happens and how to fix it.
+
+---
+
+## The Problem
+
+Agents complete their work, write "To Complete: pnpm wu:done --id WU-XXX" in their response, and then **stop without actually running the command**.
+
+### Why This Happens
+
+1. **Confusion about scope**: Agent thinks completion is a "next step" for the human
+2. **Fear of overstepping**: Agent hesitates to take "final" actions
+3. **Missing context**: Agent doesn't realize wu:done is expected to be run immediately
+4. **Token limits**: Agent runs out of context and summarizes remaining steps
+
+---
+
+## The Fix
+
+### Rule: ALWAYS Run wu:done
+
+After gates pass, you MUST run:
+
+\`\`\`bash
+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"
+
+---
+
+## Correct Completion Flow
+
+\`\`\`bash
+# 1. In worktree, run gates
+pnpm gates
+
+# 2. If gates pass, return to main
+cd /path/to/main
+
+# 3. IMMEDIATELY run wu:done
+pnpm wu:done --id WU-XXX
+
+# 4. Report success with the wu:done output
+\`\`\`
+
+---
+
+## What wu:done Does
+
+When you run \`pnpm wu:done --id WU-XXX\`:
+
+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
+
+**This is the ONLY way to complete a WU.** Manual steps will leave things in an inconsistent state.
+
+---
+
+## Symptoms of Incomplete WU
+
+If wu:done wasn't run, you'll see:
+
+- Worktree still exists: \`ls worktrees/\`
+- No stamp: \`ls .lumenflow/stamps/WU-XXX.done\` returns nothing
+- Status unchanged: WU still shows as \`in_progress\`
+- Branch not merged: Changes only on lane branch
+
+---
+
+## Recovery
+
+If a previous agent forgot to run wu:done:
+
+\`\`\`bash
+# 1. Check worktree exists
+ls worktrees/
+
+# 2. If it does, run wu:done
+pnpm wu:done --id WU-XXX
+\`\`\`
+
+---
+
+## 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:done --id WU-XXX\`?
+- [ ] Did wu:done complete successfully?
+
+If any answer is "no", you're not done yet.
+`;
+const AGENT_SAFETY_CARD_TEMPLATE = `# Agent Safety Card
+
+**Last updated:** {{DATE}}
+
+Quick reference for AI agents working in LumenFlow projects.
+
+---
+
+## Stop and Ask When
+
+- Same error repeats 3 times
+- Auth or permissions changes needed
+- PII/PHI/secrets involved
+- Cloud spend decisions
+- Policy changes required
+- Anything feels irreversible
+
+---
+
+## Never Do
+
+| Action                   | Why              |
+| ------------------------ | ---------------- |
+| \`git reset --hard\`       | Data loss        |
+| \`git push --force\`       | History rewrite  |
+| \`--no-verify\`            | Bypasses safety  |
+| \`git stash\` (on main)    | Hides work       |
+| \`git clean -fd\`          | Deletes files    |
+| Work in main after claim | Breaks isolation |
+| Skip wu:done             | Incomplete WU    |
+
+---
+
+## Always Do
+
+| Action                     | Why              |
+| -------------------------- | ---------------- |
+| Read WU spec first         | Understand scope |
+| cd to worktree after claim | Isolation        |
+| Write tests before code    | TDD              |
+| Run gates before wu:done   | Quality          |
+| Run wu:done                | Complete WU      |
+| Stay within code_paths     | Scope discipline |
+
+---
+
+## Error Handling
+
+### Max 3 Attempts
+
+If same error happens 3 times:
+
+1. Stop trying
+2. Document what happened
+3. Ask for help
+
+### Gate Failures
+
+1. Read the error message
+2. Fix the underlying issue
+3. Re-run gates
+4. Never use \`--skip-gates\` for new failures
+
+---
+
+## Quick Commands
+
+\`\`\`bash
+# Check lane availability
+cat docs/04-operations/tasks/status.md
+
+# Claim a WU
+pnpm wu:claim --id WU-XXX --lane <Lane>
+
+# Work in worktree
+cd worktrees/<lane>-wu-xxx
+
+# Run gates
+pnpm gates          # Code changes
+pnpm gates --docs-only  # Docs changes
+
+# Complete WU
+cd /path/to/main
+pnpm wu:done --id WU-XXX
+\`\`\`
+
+---
+
+## Completion Checklist
+
+- [ ] Gates pass
+- [ ] cd to main
+- [ ] Run wu:done
+- [ ] Verify success output
+- [ ] Report completion
+
+---
+
+## When Uncertain
+
+Choose the safer path:
+
+- Don't modify files outside code_paths
+- Don't bypass hooks
+- Don't skip gates
+- Ask rather than assume
+`;
+const WU_CREATE_CHECKLIST_TEMPLATE = `# WU Creation Checklist
+
+**Last updated:** {{DATE}}
+
+Before running \`pnpm wu:create\`, verify these items.
+
+---
+
+## Step 1: Check Valid Lanes
+
+\`\`\`bash
+grep -A 30 "lanes:" .lumenflow.config.yaml
+\`\`\`
+
+**Format:** \`"Parent: Sublane"\` (colon + single space)
+
+Examples:
+- \`"Framework: CLI"\`
+- \`"Framework: Core"\`
+- \`"Operations: CI/CD"\`
+- \`"Content: Documentation"\`
+
+---
+
+## Step 2: Required Fields
+
+| Field | Required For | Example |
+|-------|--------------|---------|
+| \`--id\` | All | \`WU-1234\` |
+| \`--lane\` | All | \`"Experience: Chat"\` |
+| \`--title\` | All | \`"Add feature"\` |
+| \`--description\` | All | \`"Context: ... Problem: ... Solution: ..."\` |
+| \`--acceptance\` | All | \`--acceptance "Works"\` (repeatable) |
+| \`--exposure\` | All | \`ui\`, \`api\`, \`backend-only\`, \`documentation\` |
+| \`--code-paths\` | Code WUs | \`"src/a.ts,src/b.ts"\` |
+| \`--test-paths-unit\` | Code WUs | \`"src/__tests__/a.test.ts"\` |
+| \`--spec-refs\` | Feature WUs | \`"~/.lumenflow/plans/WU-XXX.md"\` |
+
+---
+
+## Step 3: Plan Storage
+
+Plans go in \`~/.lumenflow/plans/\` (NOT in project):
+
+\`\`\`bash
+mkdir -p ~/.lumenflow/plans
+# Create your plan
+vim ~/.lumenflow/plans/WU-XXX-plan.md
+\`\`\`
+
+Reference in wu:create:
+\`\`\`bash
+--spec-refs "~/.lumenflow/plans/WU-XXX-plan.md"
+\`\`\`
+
+---
+
+## Step 4: Validate First
+
+\`\`\`bash
+pnpm wu:create --id WU-XXX ... --validate
+\`\`\`
+
+Fix errors, then remove \`--validate\` to create.
+
+---
+
+## Complete Example
+
+\`\`\`bash
+pnpm wu:create \\
+  --id WU-1234 \\
+  --lane "Framework: CLI" \\
+  --title "Add feature X" \\
+  --description "Context: Users need X. Problem: X doesn't exist. Solution: Add X." \\
+  --acceptance "Feature X works as specified" \\
+  --acceptance "Unit tests pass with >90% coverage" \\
+  --code-paths "packages/@lumenflow/cli/src/x.ts" \\
+  --test-paths-unit "packages/@lumenflow/cli/__tests__/x.test.ts" \\
+  --exposure backend-only \\
+  --spec-refs "~/.lumenflow/plans/WU-1234-plan.md"
+\`\`\`
+
+---
+
+## Common Errors
+
+### "Lane format invalid"
+
+**Cause:** Missing colon or space in lane format.
+
+**Fix:** Use \`"Parent: Sublane"\` format (colon + space).
+
+### "Missing required field"
+
+**Cause:** Required field not provided.
+
+**Fix:** Add the missing \`--field\` argument.
+
+### "WU already exists"
+
+**Cause:** WU with this ID already exists.
+
+**Fix:** Use a different ID or check existing WUs.
+
+---
+
+## After Creation
+
+1. Review the created YAML: \`cat docs/04-operations/tasks/wu/WU-XXX.yaml\`
+2. Claim the WU: \`pnpm wu:claim --id WU-XXX --lane "Lane"\`
+3. cd to worktree: \`cd worktrees/<lane>-wu-xxx\`
+`;
+// WU-1083: Claude skills templates
+const WU_LIFECYCLE_SKILL_TEMPLATE = `---
+name: wu-lifecycle
+description: Work Unit claim/block/done workflow automation.
+version: 1.0.0
+---
+
+# WU Lifecycle Skill
+
+## When to Use
+
+Activate this skill when:
+
+- Claiming a WU (\`pnpm wu:claim\`)
+- Blocking/unblocking WUs due to dependencies
+- Running \`wu:done\` completion workflow
+- Understanding WU state machine transitions
+
+## State Machine
+
+\`\`\`
+ready -> in_progress -> waiting/blocked -> done
+\`\`\`
+
+## Core Commands
+
+\`\`\`bash
+# Claim WU
+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
+
+# Block/Unblock
+pnpm wu:block --id WU-XXX --reason "..."
+pnpm wu:unblock --id WU-XXX
+
+# Create (full spec)
+pnpm wu:create --id WU-999 --lane "Operations" --title "Add feature" \\
+  --description "Context: ... Problem: ... Solution: ..." \\
+  --acceptance "Feature works" --code-paths "src/a.ts" --validate
+\`\`\`
+
+## wu:done Workflow
+
+1. Runs gates in worktree
+2. Fast-forward merge to main
+3. Creates \`.lumenflow/stamps/WU-XXX.done\`
+4. Updates backlog.md + status.md
+5. Removes worktree
+
+## Worktree Discipline
+
+After \`wu:claim\`:
+
+- \`cd worktrees/<lane>-wu-xxx\` immediately
+- Use relative paths (never absolute)
+- Main is read-only
+`;
+const WORKTREE_DISCIPLINE_SKILL_TEMPLATE = `---
+name: worktree-discipline
+description: Prevents the "absolute path trap" in Write/Edit/Read tools.
+version: 1.0.0
+---
+
+# Worktree Discipline: Absolute Path Trap Prevention
+
+**Purpose**: Prevent AI agents from bypassing worktree isolation via absolute file paths.
+
+## The Absolute Path Trap
+
+**Problem**: AI agents using Write/Edit/Read tools can bypass worktree isolation by passing absolute paths. Even when your shell is in the worktree, absolute paths target the main checkout.
+
+### Example
+
+\`\`\`typescript
+// Shell: cd worktrees/operations-wu-427
+
+// WRONG - Absolute path bypasses worktree
+Write({
+  file_path: '/home/user/source/project/apps/web/src/validator.ts',
+  content: '...',
+});
+// Result: Written to MAIN checkout, not worktree!
+
+// RIGHT - Relative path respects worktree
+Write({
+  file_path: 'apps/web/src/validator.ts',
+  content: '...',
+});
+// Result: Written to worktree correctly
+\`\`\`
+
+## Pre-Operation Checklist
+
+**Before ANY Write/Edit/Read operation:**
+
+1. **Verify working directory**:
+
+   \`\`\`bash
+   pwd
+   # Must show: .../worktrees/<lane>-wu-xxx
+   \`\`\`
+
+2. **Check file path format**:
+
+   | Pattern                           | Safe? | Example                  |
+   | --------------------------------- | ----- | ------------------------ |
+   | Starts with \`/home/\` or \`/Users/\` | NO    | \`/home/user/.../file.ts\` |
+   | Contains full repo path           | NO    | \`/source/project/...\`    |
+   | Starts with package name          | YES   | \`apps/web/src/...\`       |
+   | Starts with \`./\` or \`../\`         | YES   | \`./src/lib/...\`          |
+   | Just filename                     | YES   | \`README.md\`              |
+
+3. **Use relative paths for ALL file operations**
+
+## Golden Rules
+
+1. **Always verify pwd** before file operations
+2. **Never use absolute paths** in Write/Edit/Read tools
+3. **When in doubt, use relative paths**
+`;
+const LUMENFLOW_GATES_SKILL_TEMPLATE = `---
+name: lumenflow-gates
+description: Quality gates troubleshooting (format, lint, typecheck, tests).
+version: 1.0.0
+---
+
+# LumenFlow Gates Skill
+
+## 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)
+
+## 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
+exhaustive-deps -> Add missing dependencies
+\`\`\`
+
+## Validation Commands
+
+\`\`\`bash
+pnpm gates                # All gates
+pnpm gates -- --docs-only # Docs WUs
+pnpm format               # Fix formatting
+pnpm lint:fix             # Fix lint issues
+pnpm typecheck            # Check types
+\`\`\`
+`;
 /**
  * Detect default client from environment
  */
@@ -232,6 +999,38 @@ async function scaffoldFullDocs(targetDir, options, result, tokens) {
     await createFile(path.join(tasksDir, 'backlog.md'), BACKLOG_TEMPLATE, options.force, result, targetDir);
     await createFile(path.join(tasksDir, 'status.md'), STATUS_TEMPLATE, options.force, result, targetDir);
     await createFile(path.join(templatesDir, 'wu-template.yaml'), processTemplate(WU_TEMPLATE_YAML, tokens), options.force, result, targetDir);
+    // WU-1083: Scaffold agent onboarding docs with --full
+    await scaffoldAgentOnboardingDocs(targetDir, options, result, tokens);
+}
+/**
+ * WU-1083: Scaffold agent onboarding documentation
+ */
+async function scaffoldAgentOnboardingDocs(targetDir, options, result, tokens) {
+    const onboardingDir = path.join(targetDir, 'docs', '04-operations', '_frameworks', 'lumenflow', 'agent', 'onboarding');
+    await createDirectory(onboardingDir, result, targetDir);
+    await createFile(path.join(onboardingDir, 'quick-ref-commands.md'), processTemplate(QUICK_REF_COMMANDS_TEMPLATE, tokens), options.force, result, targetDir);
+    await createFile(path.join(onboardingDir, 'first-wu-mistakes.md'), processTemplate(FIRST_WU_MISTAKES_TEMPLATE, tokens), options.force, result, targetDir);
+    await createFile(path.join(onboardingDir, 'troubleshooting-wu-done.md'), processTemplate(TROUBLESHOOTING_WU_DONE_TEMPLATE, tokens), options.force, result, targetDir);
+    await createFile(path.join(onboardingDir, 'agent-safety-card.md'), processTemplate(AGENT_SAFETY_CARD_TEMPLATE, tokens), options.force, result, targetDir);
+    await createFile(path.join(onboardingDir, 'wu-create-checklist.md'), processTemplate(WU_CREATE_CHECKLIST_TEMPLATE, tokens), options.force, result, targetDir);
+}
+/**
+ * WU-1083: Scaffold Claude skills
+ */
+async function scaffoldClaudeSkills(targetDir, options, result, tokens) {
+    const skillsDir = path.join(targetDir, '.claude', 'skills');
+    // wu-lifecycle skill
+    const wuLifecycleDir = path.join(skillsDir, 'wu-lifecycle');
+    await createDirectory(wuLifecycleDir, result, targetDir);
+    await createFile(path.join(wuLifecycleDir, 'SKILL.md'), processTemplate(WU_LIFECYCLE_SKILL_TEMPLATE, tokens), options.force, result, targetDir);
+    // worktree-discipline skill
+    const worktreeDir = path.join(skillsDir, 'worktree-discipline');
+    await createDirectory(worktreeDir, result, targetDir);
+    await createFile(path.join(worktreeDir, 'SKILL.md'), processTemplate(WORKTREE_DISCIPLINE_SKILL_TEMPLATE, tokens), options.force, result, targetDir);
+    // lumenflow-gates skill
+    const gatesDir = path.join(skillsDir, 'lumenflow-gates');
+    await createDirectory(gatesDir, result, targetDir);
+    await createFile(path.join(gatesDir, 'SKILL.md'), processTemplate(LUMENFLOW_GATES_SKILL_TEMPLATE, tokens), options.force, result, targetDir);
 }
 async function scaffoldFrameworkOverlay(targetDir, options, result, tokens) {
     if (!options.framework) {
@@ -258,6 +1057,10 @@ async function scaffoldVendorFiles(targetDir, options, result, tokens, vendor) {
         await createDirectory(path.join(targetDir, CLAUDE_AGENTS_DIR), result, targetDir);
         await createFile(path.join(targetDir, CLAUDE_AGENTS_DIR, '.gitkeep'), '', options.force, result, targetDir);
         await createFile(path.join(targetDir, CLAUDE_DIR, 'settings.json'), CLAUDE_SETTINGS_TEMPLATE, options.force, result, targetDir);
+        // WU-1083: Scaffold Claude skills
+        await scaffoldClaudeSkills(targetDir, options, result, tokens);
+        // WU-1083: Scaffold agent onboarding docs for Claude vendor (even without --full)
+        await scaffoldAgentOnboardingDocs(targetDir, options, result, tokens);
     }
     // Cursor
     if (vendor === 'cursor' || vendor === 'all') {

package/dist/wu-done.js

@@ -534,6 +534,32 @@ async function ensureCleanWorkingTree() {
             `  - Leftover changes from previous session`);
     }
 }
+/**
+ * WU-1084: Check for uncommitted changes on main after merge completes.
+ *
+ * This catches cases where pnpm format (or other tooling) touched files
+ * outside the WU's code_paths during worktree work. These changes survive
+ * the merge and would be silently left behind when the worktree is removed.
+ *
+ * @param gitStatus - Output from git status (porcelain format)
+ * @param wuId - The WU ID for error messaging
+ * @returns Object with isDirty flag and optional error message
+ */
+export function checkPostMergeDirtyState(gitStatus, wuId) {
+    const trimmedStatus = gitStatus.trim();
+    if (!trimmedStatus) {
+        return { isDirty: false };
+    }
+    const error = `Main branch has uncommitted changes after merge:\n\n${trimmedStatus}\n\n` +
+        `This indicates files were modified outside the WU's code_paths.\n` +
+        `Common cause: pnpm format touched files outside the WU scope.\n\n` +
+        `The worktree has NOT been removed to allow investigation.\n\n` +
+        `Options:\n` +
+        `  1. Review and commit the changes: git add . && git commit -m "format: fix formatting"\n` +
+        `  2. Discard if unwanted: git checkout -- .\n` +
+        `  3. Then re-run: pnpm wu:done --id ${wuId} --skip-worktree-completion`;
+    return { isDirty: true, error };
+}
 /**
  * Extract completed WU IDs from git log output.
  * @param {string} logOutput - Git log output (one commit per line)
@@ -2033,6 +2059,13 @@ async function main() {
     else {
         await ensureNoAutoStagedOrNoop([WU_PATH, STATUS_PATH, BACKLOG_PATH, STAMPS_DIR]);
     }
+    // WU-1084: Check for uncommitted changes on main after merge
+    // This catches cases where pnpm format touched files outside code_paths
+    const postMergeStatus = await getGitForCwd().getStatus();
+    const dirtyCheck = checkPostMergeDirtyState(postMergeStatus, id);
+    if (dirtyCheck.isDirty) {
+        die(dirtyCheck.error);
+    }
     // Step 6 & 7: Cleanup (remove worktree, delete branch) - WU-1215
     // WU-1811: Only run cleanup if all completion steps succeeded
     if (completionResult.cleanupSafe !== false) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "1.3.6",
+  "version": "1.4.0",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -70,7 +70,8 @@
     "lumenflow-gates": "./dist/gates.js",
     "lumenflow-init": "./dist/init.js",
     "lumenflow": "./dist/init.js",
-    "lumenflow-release": "./dist/release.js"
+    "lumenflow-release": "./dist/release.js",
+    "lumenflow-docs-sync": "./dist/docs-sync.js"
   },
   "files": [
     "dist",
@@ -87,11 +88,11 @@
     "pretty-ms": "^9.2.0",
     "simple-git": "^3.30.0",
     "yaml": "^2.8.2",
-    "@lumenflow/core": "1.3.6",
-    "@lumenflow/metrics": "1.3.6",
-    "@lumenflow/memory": "1.3.6",
-    "@lumenflow/initiatives": "1.3.6",
-    "@lumenflow/agent": "1.3.6"
+    "@lumenflow/core": "1.4.0",
+    "@lumenflow/metrics": "1.4.0",
+    "@lumenflow/memory": "1.4.0",
+    "@lumenflow/initiatives": "1.4.0",
+    "@lumenflow/agent": "1.4.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",