@lumenflow/cli 3.10.0 → 3.11.0

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

@@ -13,10 +13,12 @@ This is the complete onboarding document for AI agents working with LumenFlow. R
 Before concluding a command doesn't exist, **always check what's available**:
 
 ```bash
-pnpm lumenflow:commands    # List ALL available CLI commands (100+)
+pnpm lumenflow:commands    # List public CLI commands, aliases, and legacy surfaces
 ```
 
 LumenFlow has commands for WU lifecycle, maintenance, memory, initiatives, orchestration, metrics, packs, and more. Never guess or assume — run `pnpm lumenflow:commands` first.
+Repo-only scripts such as `pnpm docs:validate` and `pnpm pre-release:check` are monorepo scripts,
+not part of that public command list.
 
 ### Help-First Rule
 
@@ -102,7 +104,9 @@ If work spans multiple WUs or multiple days, create an initiative first.
 When creating WUs or scoping initiatives, always evaluate whether the assigned lane fits the actual work:
 
 - **Check code_paths alignment**: Compare the WU's `code_paths` against lane definitions in `workspace.yaml`. If the majority of paths belong to a different lane, propose a lane change.
-- **Use lane:suggest**: Run `pnpm lane:suggest --paths "src/file.ts"` to get a recommendation.
+- **Use lane inference tooling correctly**:
+  - For a WU lane recommendation, run `pnpm wu:infer-lane --id WU-XXXX`.
+  - To regenerate derived lane taxonomy metadata, run `pnpm lane:suggest --output .lumenflow.lane-inference.yaml`.
 - **Propose changes proactively**: If scope expansion during implementation pushes a WU beyond its lane's boundaries, flag the mismatch to the user and suggest either a lane change or a WU split.
 - **Initiative-level review**: When planning an initiative with multiple WUs, ensure each WU is assigned to the lane whose `code_paths` best cover the work. Systematic mismatches signal that lane taxonomy may need updating.
 
@@ -112,7 +116,7 @@ When creating WUs or scoping initiatives, always evaluate whether the assigned l
 
 ```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"
@@ -125,13 +129,12 @@ pnpm bootstrap
 
 # 4. Do your work here (not in main!)
 
-# 5. Run gates before completion
-pnpm gates              # For code changes
-pnpm gates --docs-only  # For documentation changes
+# 5. Prep from the worktree (runs the correct gates)
+pnpm wu:prep --id WU-XXXX
+# This prints the copy-paste completion command
 
 # 6. Return to main and complete
-cd /path/to/main/checkout
-pnpm wu:done --id WU-XXXX
+cd /path/to/main/checkout && pnpm wu:done --id WU-XXXX
 ```
 
 ## Quick Start -- Cloud / Branch-PR (Copy This)
@@ -140,7 +143,7 @@ For cloud agents (Codex, Claude web, CI bots) that cannot create local worktrees
 
 ```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 in cloud mode (no worktree, sets claimed_mode: branch-pr)
 pnpm wu:claim --id WU-XXXX --lane "Lane Name" --cloud
@@ -158,28 +161,28 @@ pnpm wu:done --id WU-XXXX
 pnpm wu:cleanup --id WU-XXXX
 ```
 
-**Cloud activation methods (in precedence order):**
+**Activation is explicit-only:**
 
 1. `--cloud` flag on `wu:claim` (explicit, always wins)
 2. `LUMENFLOW_CLOUD=1` environment variable (explicit, always wins)
-3. Config-driven auto-detection when `cloud.auto_detect: true` in `workspace.yaml`
 
-**Auto-detection configuration:**
+Runtime identity env vars such as `CLAUDECODE`, `CODEX`, or `CI` do not activate cloud mode.
+The `cloud.auto_detect` and `env_signals` config keys remain schema-supported metadata,
+but they do not change runtime activation behavior.
 
 ```yaml
 # workspace.yaml
 cloud:
-  auto_detect: true # default: false (opt-in)
-  env_signals: # checked only when auto_detect is true
-    - name: CI # presence check (any non-empty value)
-    - name: CODEX
-    - name: GITHUB_ACTIONS
-      equals: 'true' # exact match required
+  auto_detect: false
+  env_signals: []
 ```
 
-When `auto_detect` is enabled, `wu:claim` checks the listed environment signals
-and activates cloud mode if any match. No vendor-specific signals are hardcoded;
-all signals are user-configured.
+Use explicit activation instead:
+
+```bash
+pnpm wu:claim --id WU-XXXX --lane "Lane Name" --cloud
+LUMENFLOW_CLOUD=1 pnpm wu:claim --id WU-XXXX --lane "Lane Name"
+```
 
 ---
 
@@ -237,21 +240,26 @@ pnpm wu:claim --id WU-123 --lane "Framework: CLI" --cloud
 
 **Why:** Worktrees isolate your changes. Main checkout is protected by git hooks. Branch-PR mode is the valid exception for cloud agents that cannot create local worktrees.
 
-### Rule 2: ALWAYS Run wu:done
+### Rule 2: Use wu:prep Then wu:done
 
-After gates pass, you MUST run `pnpm wu:done --id WU-XXXX` from the main checkout. Do not just write "To complete: run wu:done" - actually run it.
+Completion is a two-step flow:
+
+1. From the worktree, run `pnpm wu:prep --id WU-XXXX`
+2. From main, copy-paste the printed `pnpm wu:done --id WU-XXXX` command
+
+Do not just write "to complete: run wu:done" and stop.
 
 ```bash
 # WRONG
 "Work complete. Next step: run pnpm wu:done --id WU-123"
 
 # RIGHT
-cd /path/to/main
-pnpm wu:done --id WU-123
+pnpm wu:prep --id WU-123
+cd /path/to/main && pnpm wu:done --id WU-123
 # Then report: "WU-123 completed. Changes merged to main."
 ```
 
-**Why:** wu:done merges your changes, creates the completion stamp, and releases the lane lock.
+**Why:** `wu:prep` runs the correct gates in the claimed workspace. `wu:done` then merges or opens the PR, writes the completion metadata, and releases the lane lock.
 
 ### Rule 3: Use Relative Paths Only
 
@@ -333,6 +341,16 @@ pnpm config:set --key gates.minCoverage --value 85
 pnpm config:set --key agents.methodology.principles --value Library-First,KISS
 ```
 
+For lanes:
+
+- `workspace.yaml` (`software_delivery.lanes.definitions`) is the source of truth for lane validation and claim-time lane checks.
+- `.lumenflow.lane-inference.yaml` is derived metadata for suggestion/classification workflows.
+- After lane definition changes, regenerate taxonomy metadata with:
+
+```bash
+pnpm lane:suggest --output .lumenflow.lane-inference.yaml
+```
+
 ### Modifying WU YAML Specs
 
 ```bash
@@ -384,7 +402,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
 ```
 
@@ -490,6 +508,33 @@ pnpm wu:delegate --id WU-XXXX --parent-wu WU-YYYY --client <client-type>
 
 **IMPORTANT:** The `--client` flag identifies your IDE/tool environment, NOT the underlying AI model. Use `--client windsurf` even if Windsurf is running a Claude agent.
 
+### Guidance Profiles (WU-2309 / WU-2329)
+
+`wu:brief` verification guidance is profile-aware and ships with sensible built-in defaults.
+Project-local `.lumenflow/templates` is optional and only needed when you want different wording,
+extra project commands, or client-specific overrides.
+
+- New installs get the current defaults automatically.
+- Existing installs get the runtime defaults after `pnpm lumenflow:upgrade --latest`.
+- Run `pnpm docs:sync --force` when you also want refreshed scaffolded onboarding docs and
+  supported vendor assets.
+
+Default profiles:
+
+- Behavior/logic changes: follow project policy (`methodology.testing`: `tdd`, `test-after`, or `none`).
+- Structured-content-only changes (`.yaml/.yml/.json/.md/.mdx`): use parse/schema/lint/eval evidence; TDD checkpoint is omitted.
+- UI presentation hints: prefer smoke/manual/integration/E2E verification and use unit tests for pure logic or explicitly required checks.
+
+Common override points include `visual-directive`, `structured-content-directive`,
+`verification-requirements`, and `design-context-ui`.
+
+Domain-specific commands must come from local configuration, not core framework code:
+
+- Template manifest: `.lumenflow/templates/manifest.yaml`
+- Base templates: `.lumenflow/templates/spawn-prompt/*.md`
+- Client overrides: `.lumenflow/templates.{client}/spawn-prompt/*.md`
+- Client config: `workspace.yaml` under `software_delivery.agents.clients.*`
+
 ### Sub-Agent Coordination
 
 - Sub-agents work in isolated micro-worktrees
@@ -501,23 +546,22 @@ pnpm wu:delegate --id WU-XXXX --parent-wu WU-YYYY --client <client-type>
 
 ## WU Lifecycle Commands
 
-| Command                                        | Description                              | When to Use                 |
-| ---------------------------------------------- | ---------------------------------------- | --------------------------- |
-| `pnpm wu:status --id WU-XXX`                   | Show WU state and valid commands         | Check current state         |
-| `pnpm wu:claim --id WU-XXX --lane "Lane"`      | Claim WU and create worktree (default)   | Start working (local)       |
-| `pnpm wu:claim --id WU-XXX --lane "L" --cloud` | Claim WU in branch-pr mode (no worktree) | Start working (cloud)       |
-| `pnpm wu:edit --id WU-XXX --field value`       | Edit WU spec fields                      | Update notes/desc           |
-| `pnpm wu:brief --id WU-XXX --client X`         | Generate handoff prompt + evidence       | Complex WUs                 |
-| `pnpm wu:brief --id WU-XXX --evidence-only`    | Record evidence only (no prompt output)  | Self-implementation path    |
-| `pnpm wu:delegate --id WU-XXX --parent-wu P`   | Generate prompt + record delegation      | Auditable delegation flows  |
-| `pnpm gates`                                   | Run quality gates                        | Before wu:done              |
-| `pnpm gates --docs-only`                       | Run docs-only gates                      | For documentation WUs       |
-| `pnpm wu:done --id WU-XXX`                     | Complete WU (merge or PR, cleanup)       | After gates pass            |
-| `pnpm wu:cleanup --id WU-XXX`                  | Post-merge cleanup (branch-pr)           | After PR merge (cloud only) |
-| `pnpm wu:escalate --id WU-XXX`                 | Show or resolve escalation status        | Escalation-triggered WUs    |
-| `pnpm wu:escalate --resolve --id WU-XXX`       | Resolve human escalation                 | Before wu:done (escalation) |
-| `pnpm wu:delete --id WU-XXX`                   | Delete WU spec and cleanup               | Cancel stale/throwaway WUs  |
-| `pnpm wu:recover --id WU-XXX`                  | Fix inconsistent WU state                | When state is broken        |
+| Command                                        | Description                                     | When to Use                 |
+| ---------------------------------------------- | ----------------------------------------------- | --------------------------- |
+| `pnpm wu:status --id WU-XXX`                   | Show WU state and valid commands                | Check current state         |
+| `pnpm wu:claim --id WU-XXX --lane "Lane"`      | Claim WU and create worktree (default)          | Start working (local)       |
+| `pnpm wu:claim --id WU-XXX --lane "L" --cloud` | Claim WU in branch-pr mode (no worktree)        | Start working (cloud)       |
+| `pnpm wu:edit --id WU-XXX --field value`       | Edit WU spec fields                             | Update notes/desc           |
+| `pnpm wu:brief --id WU-XXX --client X`         | Generate handoff prompt + evidence              | Complex WUs                 |
+| `pnpm wu:brief --id WU-XXX --evidence-only`    | Record evidence only (no prompt output)         | Self-implementation path    |
+| `pnpm wu:delegate --id WU-XXX --parent-wu P`   | Generate prompt + record delegation             | Auditable delegation flows  |
+| `pnpm wu:prep --id WU-XXX`                     | Run gates in claimed workspace, prep completion | Before wu:done              |
+| `pnpm wu:done --id WU-XXX`                     | Complete WU (merge or PR, cleanup)              | After gates pass            |
+| `pnpm wu:cleanup --id WU-XXX`                  | Post-merge cleanup (branch-pr)                  | After PR merge (cloud only) |
+| `pnpm wu:escalate --id WU-XXX`                 | Show or resolve escalation status               | Escalation-triggered WUs    |
+| `pnpm wu:escalate --resolve --id WU-XXX`       | Resolve human escalation                        | Before wu:done (escalation) |
+| `pnpm wu:delete --id WU-XXX`                   | Delete WU spec and cleanup                      | Cancel stale/throwaway WUs  |
+| `pnpm wu:recover --id WU-XXX`                  | Fix inconsistent WU state                       | When state is broken        |
 
 ---
 
@@ -525,7 +569,7 @@ pnpm wu:delegate --id WU-XXXX --parent-wu WU-YYYY --client <client-type>
 
 ```
 /path/to/repo/
-├── docs/04-operations/tasks/
+├── {{DOCS_TASKS_PATH}}/
 │   ├── backlog.md              # All WUs listed here (auto-generated, don't edit)
 │   └── wu/WU-XXXX.yaml         # Individual WU specs
 ├── worktrees/
@@ -544,7 +588,7 @@ pnpm wu:delegate --id WU-XXXX --parent-wu WU-YYYY --client <client-type>
 Before reporting a WU complete, verify:
 
 - [ ] All acceptance criteria in WU YAML are satisfied
-- [ ] Gates pass (`pnpm gates` or `pnpm gates --docs-only`)
+- [ ] `pnpm wu:prep --id WU-XXX` ran successfully in the claimed workspace
 - [ ] `pnpm wu:done --id WU-XXX` ran successfully
 - [ ] Output shows "Marked done, pushed, and cleaned up"
 - [ ] Worktree was removed (check `ls worktrees/`)
@@ -685,4 +729,5 @@ rm -rf /tmp/nextjs-scaffold
 - [troubleshooting-wu-done.md](troubleshooting-wu-done.md) - Why agents forget wu:done
 - [first-wu-mistakes.md](first-wu-mistakes.md) - Common mistakes to avoid
 - [quick-ref-commands.md](quick-ref-commands.md) - Command reference
+- [wu-sizing-guide.md](wu-sizing-guide.md) - Context safety and WU sizing
 - [initiative-orchestration.md](initiative-orchestration.md) - Initiative orchestration, delegation, recovery

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

@@ -187,31 +187,25 @@ pnpm wu:claim --id WU-XXX --lane "<Lane>" --cloud
 LUMENFLOW_CLOUD=1 pnpm wu:claim --id WU-XXX --lane "<Lane>"
 ```
 
-Explicit activation (`--cloud` or `LUMENFLOW_CLOUD=1`) always takes precedence over
-auto-detection.
+Cloud activation is explicit-only. `--cloud` and `LUMENFLOW_CLOUD=1` are the only
+runtime activation paths.
 
-### Config-Driven Auto-Detection (Opt-In)
+### Cloud Config Compatibility Fields
 
-For environments where agents should automatically enter cloud mode, enable
-auto-detection in `workspace.yaml`:
+The workspace schema still carries `cloud.auto_detect` and `env_signals`, but they do
+not activate cloud mode at runtime:
 
 ```yaml
 cloud:
-  auto_detect: true # default: false
-  env_signals:
-    - name: CI # presence check (any non-empty value)
-    - name: CODEX
-    - name: GITHUB_ACTIONS
-      equals: 'true' # exact match required
+  auto_detect: false
+  env_signals: []
 ```
 
 **Key design decisions:**
 
-- `auto_detect` defaults to `false` (opt-in, not opt-out)
-- No vendor-specific signals are hardcoded; all signals are user-configured
-- Each signal supports either presence checks (`name` only) or exact-value
-  matches (`name` + `equals`)
-- Explicit activation always wins over auto-detection
+- Runtime identity signals are intentionally ignored for activation
+- Explicit activation always wins because it is the only activation path
+- Config fields remain for compatibility, migration, and future policy metadata
 
 ### Cloud Lifecycle
 
@@ -225,10 +219,10 @@ cloud:
 
 ### Vendor-Specific Notes
 
-- **Codex**: Set `LUMENFLOW_CLOUD=1` in the environment or configure auto-detection with `name: CODEX`
-- **Claude web**: Use `--cloud` flag explicitly or configure `name: CLAUDE_CODE` in env_signals
-- **GitHub Actions**: Configure `name: GITHUB_ACTIONS, equals: 'true'` in env_signals
-- **Antigravity**: Expected to work with explicit `--cloud` flag; auto-detection signals TBD
+- **Codex**: Set `LUMENFLOW_CLOUD=1` or pass `--cloud`
+- **Claude web**: Use `--cloud` explicitly
+- **GitHub Actions**: Set `LUMENFLOW_CLOUD=1` in the job environment
+- **Antigravity**: Use explicit `--cloud` activation
 
 ---
 

package/templates/core/ai/onboarding/wu-create-checklist.md.template

@@ -2,116 +2,65 @@
 
 **Last updated:** {{DATE}}
 
-Before running `pnpm wu:create`, verify these items.
+Use this checklist before running `pnpm wu:create`.
 
 ---
 
-## Step 1: Check Valid Lanes
+## Step 1: Confirm the Lane
 
 ```bash
-grep -A 30 "lanes:" workspace.yaml
+pnpm lane:status
+pnpm wu:infer-lane --paths "packages/@lumenflow/cli/src/init.ts" --desc "Fix init docs drift"
 ```
 
-**Format:** `"Parent: Sublane"` (colon + single space)
-
-Examples:
-
-- `"Framework: CLI"`
-- `"Framework: Core"`
-- `"Operations: CI/CD"`
-- `"Content: Documentation"`
+The lane should match the real implementation scope, not just the first file you noticed.
 
 ---
 
-## Step 2: Required Fields
+## Step 2: Gather the 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-plan.md"`             |
-
----
+| Field                 | Required For          | Example                                                |
+| --------------------- | --------------------- | ------------------------------------------------------ |
+| `--lane`              | All WUs               | `"Framework: CLI"`                                     |
+| `--title`             | All WUs               | `"Eliminate onboarding docs drift"`                    |
+| `--description`       | All WUs               | `"Context: ... Problem: ... Solution: ..."`            |
+| `--acceptance`        | All WUs               | `--acceptance "Docs and templates stay aligned"`       |
+| `--exposure`          | All WUs               | `documentation`                                        |
+| `--code-paths`        | Non-documentation WUs | `"packages/@lumenflow/cli/src/init.ts"`                |
+| `--test-paths-manual` | Non-documentation WUs | `"Run focused init/docs-sync tests"`                   |
+| `--test-paths-unit`   | Code WUs              | `"packages/@lumenflow/cli/src/__tests__/init.test.ts"` |
+| `--spec-refs`         | Feature WUs           | `"lumenflow://plans/WU-XXXX-plan.md"`                  |
 
-## Step 3: Plan Storage
-
-Plans go in `$LUMENFLOW_HOME/plans/` (NOT in project):
-
-```bash
-mkdir -p $LUMENFLOW_HOME/plans
-# or if LUMENFLOW_HOME is not set:
-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"
-```
+`--id` is optional. If omitted, `wu:create` allocates the next WU ID automatically.
 
 ---
 
-## Step 4: Validate First
+## Step 3: Decide Plan Storage
+
+If the work needs a plan, prefer repo-native or `lumenflow://plans/` references:
 
 ```bash
-pnpm wu:create --id WU-XXX ... --validate
+pnpm plan:create --id INIT-XXX --title "Plan title"
+pnpm wu:create --lane "Framework: CLI" --title "..." --plan
 ```
 
-Fix errors, then remove `--validate` to create.
+Avoid pointing `--spec-refs` at random local filesystem notes that other agents cannot resolve.
 
 ---
 
-## Complete Example
+## Step 4: Validate Before Creating
 
 ```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"
+pnpm wu:create --lane "Framework: CLI" --title "..." --description "..." \
+  --acceptance "..." --exposure documentation --validate
 ```
 
----
-
-## 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.
+Let validation tell you which fields are still missing before you create the real spec.
 
 ---
 
 ## 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`
+1. Review `{{DOCS_TASKS_PATH}}/wu/WU-XXX.yaml`.
+2. Claim it with `pnpm wu:claim --id WU-XXX --lane "<Lane>"`.
+3. Move into the worktree immediately.

package/templates/core/ai/onboarding/wu-sizing-guide.md.template

@@ -0,0 +1,48 @@
+# Work Unit Sizing Guide
+
+**Last updated:** {{DATE}}
+
+Use this summary when deciding whether a WU still fits in a single agent session.
+
+---
+
+## Baseline Heuristics
+
+| Complexity | Files | Tool Calls | Suggested Strategy          |
+| ---------- | ----- | ---------- | --------------------------- |
+| Simple     | <20   | <50        | Single session              |
+| Medium     | 20-50 | 50-100     | Checkpoint and resume       |
+| Complex    | 50+   | 100+       | Decompose or orchestrate    |
+| Oversized  | 100+  | 200+       | Split before implementation |
+
+These are guardrails, not a license to keep pushing once context is clearly degrading.
+
+---
+
+## Context Safety Triggers
+
+Checkpoint and hand off when any of these happen:
+
+- Context usage approaches 50% and is still climbing
+- Tool calls exceed roughly 50 in one session
+- File churn keeps widening without clear closure
+- You have to repeatedly rediscover the same repo rules
+
+---
+
+## Recovery Pattern
+
+```bash
+pnpm mem:checkpoint "state before handoff" --wu WU-XXX
+pnpm wu:brief --id WU-XXX --client codex-cli
+```
+
+If the WU is clearly too large, split it instead of relying on a heroic handoff.
+
+---
+
+## Docs-Only Exception
+
+Documentation WUs can tolerate broader file counts when the change pattern is shallow and mechanical, but they still need to stay understandable in one session.
+
+If the docs work starts spilling into CLI, core, or packaging changes, treat it like a normal cross-code WU again.

package/templates/vendors/claude/.claude/skills/bug-classification/SKILL.md.template

@@ -2,7 +2,7 @@
 name: bug-classification
 description: Classify bugs (P0-P3) and determine fix-in-place vs separate Bug WU. Use when bug discovered mid-WU, deciding bug priority, or handling production issues.
 version: 1.0.0
-source: docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md
+source: {{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/lumenflow-agent-capsule.md
 source_sections: §8 (Bug Handling Mid-WU)
 last_updated: {{DATE}}
 allowed-tools: Read, Grep
@@ -189,4 +189,4 @@ blocking: []
 
 ## Reference
 
-See [LumenFlow Agent Capsule](../../../docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md) for complete bug handling guide.
+See [LumenFlow Agent Capsule](../../../{{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/lumenflow-agent-capsule.md) for complete bug handling guide.

package/templates/vendors/claude/.claude/skills/code-quality/SKILL.md.template

@@ -2,7 +2,7 @@
 name: code-quality
 description: Shared patterns for SOLID/DRY code review, hexagonal architecture compliance, TypeScript best practices, and performance anti-patterns. Use when reviewing code quality, checking architecture boundaries, or validating TypeScript patterns.
 version: 1.1.0
-source: docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md
+source: {{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/lumenflow-agent-capsule.md
 source_sections: Core Principles, Hexagonal Architecture
 last_updated: {{DATE}}
 allowed-tools: Read, Grep, Glob
@@ -10,7 +10,7 @@ allowed-tools: Read, Grep, Glob
 
 # Code Quality Skill
 
-**Source**: `docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md` (canonical)
+**Source**: `{{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/lumenflow-agent-capsule.md` (canonical)
 
 ## When to Use
 

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

@@ -2,7 +2,7 @@
 name: context-management
 description: Session checkpoint patterns, output bypass for large results, when to spawn fresh sub-agents. Use for long-running sessions, context exhaustion, or agent coordination.
 version: 1.4.0
-source: docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-invocation-guide.md
+source: {{DOCS_ONBOARDING_PATH}}/agent-invocation-guide.md
 source_sections: Context Tiers, Session Management, Wave Orchestration
 last_updated: {{DATE}}
 allowed-tools: Read, Write, Bash
@@ -10,7 +10,7 @@ allowed-tools: Read, Write, Bash
 
 # Context Management Skill
 
-**Source**: `docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-invocation-guide.md`
+**Source**: `{{DOCS_ONBOARDING_PATH}}/agent-invocation-guide.md`
 
 Patterns for managing context in long-running AI coding sessions.
 
@@ -56,7 +56,7 @@ pnpm wu:brief --id WU-XXX --client claude-code
 - Recovery mechanisms are complex and vendor-specific
 - Prevention (fresh agent) is simpler and more reliable than recovery
 
-**This is not failure—it's disciplined execution.** See [wu-sizing-guide.md](../../../docs/04-operations/_frameworks/lumenflow/wu-sizing-guide.md) for complete sizing thresholds.
+**This is not failure—it's disciplined execution.** See [wu-sizing-guide.md](../../../{{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/wu-sizing-guide.md) for complete sizing thresholds.
 
 ---
 

package/templates/vendors/claude/.claude/skills/execution-memory/SKILL.md.template

@@ -2,7 +2,7 @@
 name: execution-memory
 description: Memory layer for session tracking, context recovery, and agent coordination. Use when resuming work after /clear, coordinating with parallel agents, or managing long-running sessions.
 version: 1.2.0
-source: docs/04-operations/_frameworks/lumenflow/agent/onboarding/quick-ref-commands.md
+source: {{QUICK_REF_LINK}}
 source_sections: Memory Commands
 last_updated: {{DATE}}
 allowed-tools: Read, Bash, Grep

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

@@ -94,7 +94,7 @@ Edits initiative YAML fields atomically using micro-worktree isolation:
 
 ## Initiative Structure
 
-Initiatives are defined in `docs/04-operations/tasks/initiatives/INIT-001.yaml`:
+Initiatives are defined in `{{DOCS_TASKS_PATH}}/initiatives/INIT-001.yaml`:
 
 ```yaml
 id: INIT-001
@@ -157,7 +157,7 @@ pnpm wu:brief --id WU-1504 --evidence-only         # Evidence only, no prompt ou
 - Validation agents checking orchestrator's work
 - Explore agents for codebase research
 
-See [agent-invocation-guide.md](../../../docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-invocation-guide.md) for decision tree.
+See [agent-invocation-guide.md](../../../{{DOCS_ONBOARDING_PATH}}/agent-invocation-guide.md) for decision tree.
 
 ## Best Practices
 

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

@@ -2,7 +2,7 @@
 name: library-first
 description: Validate well-known libraries solve your problem before custom code. Use when implementing parsing, dates, validation, or any non-trivial logic.
 version: 1.0.0
-source: docs/04-operations/_frameworks/lumenflow/agent/onboarding/library-first-toolkit.md
+source: {{DOCS_ONBOARDING_PATH}}/library-first-toolkit.md
 source_sections: Validation Protocol, Decision Tree, Context7 Query Templates
 last_updated: {{DATE}}
 allowed-tools: Read, mcp__context7__*
@@ -10,7 +10,7 @@ allowed-tools: Read, mcp__context7__*
 
 # Library-First Skill
 
-**Source**: `docs/04-operations/_frameworks/lumenflow/agent/onboarding/library-first-toolkit.md` (canonical)
+**Source**: `{{DOCS_ONBOARDING_PATH}}/library-first-toolkit.md` (canonical)
 
 Search for libraries BEFORE writing custom code. Custom implementations create debt, violate DRY/SOLID, and introduce bugs that libraries have already solved.
 

package/templates/vendors/claude/.claude/skills/lumenflow-gates/SKILL.md.template

@@ -2,7 +2,7 @@
 name: lumenflow-gates
 description: Quality gates troubleshooting (format, lint, typecheck, tests). Use when gates fail, debugging format/lint/typecheck errors, or determining if failure is from your changes vs pre-existing.
 version: 2.1.0
-source: docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md
+source: {{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/lumenflow-agent-capsule.md
 source_sections: Validation & Gates
 last_updated: {{DATE}}
 allowed-tools: Read, Bash, Grep
@@ -10,7 +10,7 @@ allowed-tools: Read, Bash, Grep
 
 # LumenFlow Gates Skill
 
-**Source**: `docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md` (canonical)
+**Source**: `{{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/lumenflow-agent-capsule.md` (canonical)
 
 ## When to Use
 
@@ -84,4 +84,4 @@ pnpm tasks:validate       # WU YAML validation
 
 ---
 
-**Full spec**: [LumenFlow Agent Capsule](../../../docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md)
+**Full spec**: [LumenFlow Agent Capsule](../../../{{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/lumenflow-agent-capsule.md)