@lumenflow/cli 2.5.0 → 2.5.1

package/templates/core/ai/onboarding/docs-generation.md.template

@@ -0,0 +1,277 @@
+# Automatic CLI/Config Documentation Generation
+
+**Last updated:** {{DATE}}
+
+This document explains LumenFlow's automatic documentation generation system, which keeps Starlight docs in sync with code using a single-source-of-truth pattern.
+
+---
+
+## Overview
+
+LumenFlow automatically generates CLI and configuration reference documentation from source code. This ensures documentation never drifts from implementation.
+
+| Component        | Source                                                    | Output                                            |
+| ---------------- | --------------------------------------------------------- | ------------------------------------------------- |
+| CLI Reference    | `packages/@lumenflow/cli/src/**`                          | `apps/docs/src/content/docs/reference/cli.mdx`    |
+| Config Reference | `packages/@lumenflow/core/src/lumenflow-config-schema.ts` | `apps/docs/src/content/docs/reference/config.mdx` |
+
+---
+
+## Single-Source-of-Truth Pattern
+
+The documentation generator imports directly from built packages rather than parsing source files with regex:
+
+```typescript
+// tools/generate-cli-docs.ts
+import {
+  WU_OPTIONS,
+  DirectoriesSchema,
+  GatesConfigSchema,
+  // ... other schemas
+} from '../packages/@lumenflow/core/dist/index.js';
+```
+
+**Benefits:**
+
+- **No regex parsing**: Uses proper TypeScript imports
+- **Type safety**: Schemas validate at build time
+- **Consistent**: Same definitions used by CLI and docs
+- **Maintainable**: Update code once, docs follow automatically
+
+---
+
+## Trigger Files
+
+Changes to these files trigger documentation regeneration:
+
+| File/Directory                                            | Description                           |
+| --------------------------------------------------------- | ------------------------------------- |
+| `tools/generate-cli-docs.ts`                              | The generator script itself           |
+| `packages/@lumenflow/core/src/arg-parser.ts`              | CLI argument definitions (WU_OPTIONS) |
+| `packages/@lumenflow/core/src/lumenflow-config-schema.ts` | Config schema definitions             |
+| `packages/@lumenflow/core/src/index.ts`                   | Core exports                          |
+| `packages/@lumenflow/cli/package.json`                    | CLI bin entries                       |
+| `packages/@lumenflow/cli/src/**`                          | All CLI command sources               |
+
+These pathspecs are defined in `DOC_SOURCE_PATHSPECS` within `packages/@lumenflow/core/src/wu-done-docs-generate.ts`.
+
+---
+
+## wu:done Auto-Detection Flow
+
+When you run `pnpm wu:done`, the system automatically detects if docs need regeneration:
+
+```mermaid
+flowchart TD
+    A[wu:done starts] --> B[Run gates in worktree]
+    B --> C{Gates pass?}
+    C -->|No| D[Fix gates first]
+    C -->|Yes| E[Check doc-source changes]
+    E --> F{Any trigger files changed?}
+    F -->|No| G[Skip docs:generate]
+    F -->|Yes| H[Run turbo docs:generate]
+    H --> I[Format doc outputs]
+    I --> J[Stage doc files]
+    J --> K[Continue with metadata commit]
+    G --> K
+```
+
+### Detection Logic
+
+The detection uses efficient `git diff` with pathspecs:
+
+```bash
+git diff main...HEAD --name-only -- <pathspecs>
+```
+
+- **Zero overhead** when no doc-source files changed (~0ms)
+- **Turbo caching** when docs:generate runs (incremental builds)
+
+### Integration Point
+
+In `executeWorktreeCompletion()` (after gates pass, before metadata commit):
+
+```typescript
+await maybeRegenerateAndStageDocs({
+  baseBranch: 'main',
+  repoRoot: repoRoot,
+});
+```
+
+This ensures regenerated docs are included in the single atomic completion commit.
+
+---
+
+## Manual Commands
+
+### Generate Documentation
+
+Regenerate all CLI/config documentation:
+
+```bash
+pnpm docs:generate
+```
+
+This runs `tools/generate-cli-docs.ts` which:
+
+1. Extracts command metadata from CLI package.json bin entries
+2. Imports WU_OPTIONS from `@lumenflow/core` for option definitions
+3. Extracts config schemas using Zod 4's native `toJSONSchema()`
+4. Generates MDX files with tables and code blocks
+5. Formats output with Prettier
+
+### Validate Documentation
+
+Check if documentation is in sync with code (useful for CI):
+
+```bash
+pnpm docs:validate
+```
+
+- **Exit 0**: Documentation is up to date
+- **Exit 1**: Documentation drift detected, run `pnpm docs:generate`
+
+### Turbo Integration
+
+The generator is integrated into Turbo for caching:
+
+```json
+// turbo.json
+"docs:generate": {
+  "dependsOn": ["@lumenflow/core#build"],
+  "inputs": [
+    "tools/generate-cli-docs.ts",
+    "packages/@lumenflow/core/src/arg-parser.ts",
+    "packages/@lumenflow/core/src/lumenflow-config-schema.ts",
+    "packages/@lumenflow/core/src/index.ts",
+    "packages/@lumenflow/cli/src/**/*.ts",
+    "packages/@lumenflow/cli/package.json"
+  ],
+  "outputs": [
+    "apps/docs/src/content/docs/reference/cli.mdx",
+    "apps/docs/src/content/docs/reference/config.mdx"
+  ]
+}
+```
+
+**Key points:**
+
+- Depends on `@lumenflow/core#build` (requires built packages for imports)
+- Inputs match `DOC_SOURCE_PATHSPECS` for consistent detection
+- Outputs are cached; unchanged inputs skip regeneration
+
+---
+
+## Output Files
+
+The generator produces two MDX files:
+
+### CLI Reference (`cli.mdx`)
+
+- Generated from CLI package.json bin entries
+- Options extracted from WU_OPTIONS in `@lumenflow/core`
+- Grouped by category (Work Units, Memory Layer, Initiatives, etc.)
+- Includes required/optional flags and descriptions
+
+### Config Reference (`config.mdx`)
+
+- Generated from Zod schemas in `@lumenflow/core`
+- Each config section documented with fields, types, defaults
+- Environment variable overrides documented
+- Validation command shown
+
+---
+
+## Adding New CLI Commands
+
+When you add a new CLI command:
+
+1. **Add bin entry** to `packages/@lumenflow/cli/package.json`
+2. **Add options** to `WU_OPTIONS` in `packages/@lumenflow/core/src/arg-parser.ts`
+3. **Run** `pnpm docs:generate` to update documentation
+4. **Verify** the command appears in `cli.mdx`
+
+The generator automatically:
+
+- Discovers the new command from package.json
+- Extracts options from WU_OPTIONS references in source
+- Categorizes based on command prefix (wu-, mem-, etc.)
+
+---
+
+## Adding New Config Options
+
+When you add new configuration options:
+
+1. **Add to schema** in `packages/@lumenflow/core/src/lumenflow-config-schema.ts`
+2. **Export** from `packages/@lumenflow/core/src/index.ts`
+3. **Add to SCHEMA_DEFINITIONS** in `tools/generate-cli-docs.ts`
+4. **Run** `pnpm docs:generate` to update documentation
+
+---
+
+## Troubleshooting
+
+### Documentation Drift in CI
+
+If CI fails with documentation drift:
+
+```bash
+# Regenerate and commit
+pnpm docs:generate
+git add apps/docs/src/content/docs/reference/
+git commit -m "docs: regenerate CLI/config reference"
+```
+
+### Import Errors in Generator
+
+If `tools/generate-cli-docs.ts` fails with import errors:
+
+```bash
+# Ensure packages are built
+pnpm build
+# Then regenerate
+pnpm docs:generate
+```
+
+### Turbo Cache Issues
+
+If docs aren't regenerating when they should:
+
+```bash
+# Clear Turbo cache and regenerate
+pnpm clean
+pnpm build
+pnpm docs:generate
+```
+
+---
+
+## Architecture Summary
+
+```
+Source Code                    Generator                      Output
+────────────────────────────────────────────────────────────────────────
+@lumenflow/core
+  └── arg-parser.ts      ─┐
+  └── lumenflow-config-  ─┼── tools/generate-cli-docs.ts ──┬─► cli.mdx
+      schema.ts          ─┤       (imports from dist/)      │
+@lumenflow/cli             │                                  │
+  └── package.json       ─┤                                  └─► config.mdx
+  └── src/**/*.ts        ─┘
+```
+
+**Key design decisions:**
+
+- **Library imports over regex**: Reliable, type-safe extraction
+- **Turbo integration**: Caching, dependency management
+- **wu:done integration**: Zero-effort doc updates
+- **CI validation**: Drift detection prevents stale docs
+
+---
+
+## Related Documentation
+
+- [Release Process](./release-process.md) - Deployment workflow including docs
+- [LumenFlow Complete Guide](../../lumenflow-complete.md) - Full framework reference
+- [Quick Reference Commands](./quick-ref-commands.md) - Command cheat sheet

package/templates/core/ai/onboarding/first-wu-mistakes.md.template

@@ -26,17 +26,20 @@ 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
+pnpm wu:prep --id WU-123  # WU-1223: runs gates, prints copy-paste instruction
+cd /path/to/main && pnpm wu:done --id WU-123  # Copy-paste from wu:prep output
 ```
 
 ---
 
-## Mistake 2: Forgetting to Run wu:done
+## Mistake 2: Forgetting to Run wu:prep and 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`.
+**TL;DR (WU-1223):**
+
+1. From worktree: `pnpm wu:prep --id WU-XXX` (runs gates)
+2. From main: `pnpm wu:done --id WU-XXX` (copy-paste from wu:prep output)
 
 ---
 
@@ -159,7 +162,8 @@ Start coding immediately based on the title.
 2. Understand acceptance criteria
 3. Review code_paths
 4. Check dependencies
-5. Then start
+5. Check spec_refs for linked plans (if present, read the plan document)
+6. Then start
 
 ---
 
@@ -183,16 +187,54 @@ vim src/feature.ts  # Now it's safe
 
 ---
 
+## Mistake 11: "Quick Fixing" on Main
+
+### Wrong
+
+```bash
+# On main, see failing format check
+pnpm gates
+# Output: format:check failed
+
+# Instinct: "I should help fix this!"
+pnpm prettier --write apps/docs/src/content/docs/concepts/lanes.mdx
+# Files modified on main - BAD!
+```
+
+### Right
+
+```bash
+# On main, see failing format check
+pnpm gates
+# Output: format:check failed
+
+# Report to user or create a WU
+# "Format check is failing on main. Should I create a WU to fix it?"
+
+# If yes:
+pnpm wu:create --lane "Content: Documentation" --title "Fix format issues" ...
+pnpm wu:claim --id WU-XXX --lane "Content: Documentation"
+cd worktrees/content-documentation-wu-xxx
+pnpm prettier --write <files>  # Safe in worktree
+```
+
+**Why:** The "helpful fix" instinct is dangerous. Even small fixes (format, typos, lint) must go through a worktree. Commits are blocked by hooks, but files are still modified, requiring cleanup with `git checkout -- <files>`.
+
+**Rule:** If you're on main and want to change something—STOP. Create a WU first.
+
+---
+
 ## Quick Checklist
 
 Before starting any WU:
 
 - [ ] Read the full WU spec
 - [ ] Understand acceptance criteria
+- [ ] Check spec_refs for plans (read linked plans if present)
 - [ ] 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
+- [ ] Run wu:prep from worktree (runs gates)
+- [ ] Run wu:done from main (copy-paste from wu:prep output)