@lumenflow/cli 1.3.6 → 1.5.0

package/dist/init.js

@@ -3,13 +3,58 @@
  * LumenFlow project scaffolding command (WU-1045)
  * WU-1006: Library-First - use core defaults for config generation
  * WU-1028: Vendor-agnostic core + vendor overlays
+ * WU-1085: Added createWUParser for proper --help support
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'yaml';
-import { getDefaultConfig } from '@lumenflow/core';
+import { getDefaultConfig, createWUParser, WU_OPTIONS } from '@lumenflow/core';
 // WU-1067: Import GATE_PRESETS for --preset support
 import { GATE_PRESETS } from '@lumenflow/core/dist/gates-config.js';
+/**
+ * WU-1085: CLI option definitions for init command
+ */
+const INIT_OPTIONS = {
+    full: {
+        name: 'full',
+        flags: '--full',
+        description: 'Add docs + agent onboarding + task scaffolding',
+    },
+    framework: {
+        name: 'framework',
+        flags: '--framework <name>',
+        description: 'Add framework hint + overlay docs',
+    },
+    vendor: {
+        name: 'vendor',
+        flags: '--vendor <type>',
+        description: 'Vendor type (claude, cursor, aider, all, none)',
+    },
+    preset: {
+        name: 'preset',
+        flags: '--preset <preset>',
+        description: 'Gate preset for config (node, python, go, rust, dotnet)',
+    },
+    force: WU_OPTIONS.force,
+};
+/**
+ * WU-1085: Parse init command options using createWUParser
+ * Provides proper --help, --version, and option parsing
+ */
+export function parseInitOptions() {
+    const opts = createWUParser({
+        name: 'lumenflow-init',
+        description: 'Initialize LumenFlow in a project',
+        options: Object.values(INIT_OPTIONS),
+    });
+    return {
+        force: opts.force ?? false,
+        full: opts.full ?? false,
+        framework: opts.framework,
+        vendor: opts.vendor,
+        preset: opts.preset,
+    };
+}
 const CONFIG_FILE_NAME = '.lumenflow.config.yaml';
 const FRAMEWORK_HINT_FILE = '.lumenflow.framework.yaml';
 const LUMENFLOW_DIR = '.lumenflow';
@@ -118,6 +163,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 +1044,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 +1102,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') {
@@ -297,26 +1145,22 @@ async function createFile(filePath, content, force, result, targetDir) {
 }
 /**
  * CLI entry point
+ * WU-1085: Updated to use parseInitOptions for proper --help support
  */
 export async function main() {
-    const args = process.argv.slice(2);
-    const force = args.includes('--force') || args.includes('-f');
-    const full = args.includes('--full');
-    const vendor = parseVendorArg(args);
-    const framework = parseFrameworkArg(args);
-    const gatePreset = parsePresetArg(args); // WU-1067
+    const opts = parseInitOptions();
     const targetDir = process.cwd();
     console.log('[lumenflow init] Scaffolding LumenFlow project...');
-    console.log(`  Mode: ${full ? 'full' : 'minimal'}`);
-    console.log(`  Framework: ${framework ?? 'none'}`);
-    console.log(`  Vendor overlays: ${vendor ?? 'auto'}`);
-    console.log(`  Gate preset: ${gatePreset ?? 'none (manual config)'}`);
+    console.log(`  Mode: ${opts.full ? 'full' : 'minimal'}`);
+    console.log(`  Framework: ${opts.framework ?? 'none'}`);
+    console.log(`  Vendor overlays: ${opts.vendor ?? 'auto'}`);
+    console.log(`  Gate preset: ${opts.preset ?? 'none (manual config)'}`);
     const result = await scaffoldProject(targetDir, {
-        force,
-        full,
-        vendor,
-        framework,
-        gatePreset,
+        force: opts.force,
+        full: opts.full,
+        vendor: opts.vendor,
+        framework: opts.framework,
+        gatePreset: opts.preset,
     });
     if (result.created.length > 0) {
         console.log('\nCreated:');