@lumenflow/cli 3.13.2 → 3.15.0

package/templates/core/ai/onboarding/agent-invocation-guide.md.template

@@ -38,7 +38,7 @@ Use Tier 1 after `/clear` to stay lean, then load more only if needed.
 ## 2) Session Management (Start Fresh)
 
 When approaching context limits, **start a fresh agent instead of compaction**.
-The handoff prompt is the bridge between sessions. `wu:brief` can either generate this prompt (delegation path) or just record evidence with `--evidence-only` (self-implementation path).
+The handoff prompt is the bridge between sessions. `wu:brief` always outputs full WU context AND records evidence -- there is no separate evidence-only mode.
 
 **Mandatory triggers:**
 
@@ -119,16 +119,17 @@ It does **not** by itself prove pickup or execution. Pickup/execution confirmati
 
 ---
 
-## 2c) Self-Implementation Evidence-Only Flow (WU-2222)
+## 2c) Self-Implementation Flow
 
-Use this when you are **not** delegating and will implement the WU in the current session:
+When you are **not** delegating and will implement the WU in the current session, run `wu:brief` to record evidence and then continue working:
 
 ```bash
-pnpm wu:brief --id WU-XXX --evidence-only
+pnpm wu:brief --id WU-XXX --client <client>
+# wu:brief always outputs full WU context AND records evidence.
 # Then continue implementation directly in this session (no Task spawn).
 ```
 
-Use delegation flow (`wu:brief` or `wu:delegate`) only when handing the WU to another agent.
+Use `wu:delegate` instead of `wu:brief` only when you need explicit delegation lineage recording for audit trails.
 
 ---
 

package/templates/core/ai/onboarding/first-15-mins.md.template

@@ -77,4 +77,4 @@ cd <project-root> && pnpm wu:done --id WU-XXX
 - Stay in the claimed worktree.
 - Run `pnpm lumenflow:commands` for public CLI discovery, then `--help` before first use.
 - Use `pnpm wu:prep` before `pnpm wu:done`; do not jump straight to `wu:done`.
-- If context starts getting heavy, read `./wu-sizing-guide.md` before pushing further.
+- If context starts getting heavy, ask whether the WU is still one coherent outcome. If yes, checkpoint and hand off. If no, split it.

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

@@ -148,6 +148,16 @@ The WU says "Add user profile endpoint" but you also:
 
 Implement exactly what the acceptance criteria specify. If you discover other needed changes, create new WUs for them.
 
+Do not over-correct by splitting one coherent change into tiny WUs. One endpoint plus its tests and docs is still one WU if it lands as one outcome.
+
+Before splitting, ask:
+
+1. Can these parts ship independently?
+2. Can they be reviewed independently?
+3. Can they be rolled back independently?
+
+If any answer is "no", keep one WU and use checkpoint-resume or orchestrator-worker instead.
+
 ---
 
 ## Mistake 9: Not Reading the WU Spec

package/templates/core/ai/onboarding/initiative-orchestration.md.template

@@ -45,7 +45,7 @@ Before accepting the wave plan, sanity-check the decomposition. If several WUs s
 | Checkpoint-per-wave   | `pnpm orchestrate:initiative -i INIT-XXX -c`         | Large initiatives (>3 WUs or >2 waves) |
 | Continuous            | `pnpm orchestrate:initiative -i INIT-XXX`            | Small initiatives (<=3 WUs, 1-2 waves) |
 | Manual brief/delegate | `pnpm wu:brief --id WU-XXX --client <client>` per WU | Testing individual WUs, debugging      |
-| Manual self-implement | `pnpm wu:brief --id WU-XXX --evidence-only` per WU   | You are implementing without sub-agent |
+| Manual self-implement | `pnpm wu:brief --id WU-XXX --client <client>` per WU | Self-implementation (records evidence) |
 
 Checkpoint-per-wave is recommended for most initiatives. It processes one wave at a time and writes a manifest before exiting, giving you control between waves.
 
@@ -59,18 +59,17 @@ pnpm wu:brief --id WU-100 --client claude-code
 
 # Option B: Generate prompt + record delegation lineage (for audit)
 pnpm wu:delegate --id WU-100 --parent-wu WU-050 --client claude-code
-
-# Option C: Record evidence only, then implement in current session (no spawn prompt output)
-pnpm wu:brief --id WU-100 --evidence-only
 ```
 
+`wu:brief` always outputs full WU context AND records evidence. Use it for both delegation and self-implementation.
+
 **Use `wu:delegate` (not `wu:brief`) when:**
 
 - You are the orchestrator agent managing the initiative
 - You need an audit trail of who-delegated-what
 - The initiative has more than one wave
 
-**Use `wu:brief --evidence-only` when:**
+**Use `wu:brief` for self-implementation when:**
 
 - You are not handing WU ownership to a sub-agent
 - You still need `wu:brief` evidence for `wu:done` policy
@@ -383,8 +382,7 @@ pnpm delegation:list --initiative INIT-XXX --json
 | `pnpm orchestrate:initiative -i INIT-XXX`           | Execute all waves continuously                                |
 | `pnpm orchestrate:init-status -i INIT-XXX`          | Compact progress view                                         |
 | `pnpm orchestrate:monitor`                          | Detect stuck agents and zombie locks                          |
-| `pnpm wu:brief --id WU-XXX --client <client>`       | Generate handoff prompt + evidence (claimed workspace/branch) |
-| `pnpm wu:brief --id WU-XXX --evidence-only`         | Record evidence only (self-implementation path)               |
+| `pnpm wu:brief --id WU-XXX --client <client>`       | Generate handoff prompt + record evidence                     |
 | `pnpm wu:delegate --id WU-XXX --parent-wu <P>`      | Generate prompt + record delegation                           |
 | `pnpm delegation:list --initiative INIT-XXX`        | View delegation tree                                          |
 | `pnpm mem:signal "msg" --wu WU-XXX`                 | Broadcast coordination signal                                 |

package/templates/core/ai/onboarding/quick-ref-commands.md.template

@@ -68,7 +68,7 @@ Run `--help` first, then run the real command with explicit flags.
 | `pnpm exec lumenflow init`                         | Scaffold LumenFlow in a project                                |
 | `pnpm exec lumenflow init --docs-structure simple` | Use simple docs structure (`docs/tasks`)                       |
 | `pnpm exec lumenflow init --docs-structure arc42`  | Use arc42 docs structure (`{{DOCS_OPERATIONS_PATH}}`)                |
-| `pnpm docs:sync --force`                           | Refresh scaffolded onboarding docs and supported vendor assets |
+| `pnpm docs:sync --force`                           | Refresh core docs, onboarding docs, and supported vendor assets |
 | `pnpm sync:templates`                              | Sync repo docs into bundled templates                          |
 | `pnpm lumenflow:upgrade`                           | Upgrade LumenFlow packages                                     |
 | `pnpm lumenflow:doctor`                            | Diagnose LumenFlow configuration                               |
@@ -106,18 +106,19 @@ commit and push atomically. Do NOT wrap them in a WU or use raw `pnpm update`/`g
 | `pnpm config:set --key <dotpath> --value <value>` | Set workspace.yaml config (Zod-validated)        |
 | `pnpm config:get --key <dotpath>`                 | Read workspace.yaml config                       |
 | `pnpm cloud:connect`                              | Configure cloud control-plane access             |
-| `pnpm docs:sync --force`                          | Refresh scaffolded onboarding docs after upgrade |
+| `pnpm docs:sync --force`                          | Refresh core docs, onboarding docs, and vendor assets after upgrade |
 | `pnpm sync:templates`                             | Sync repo docs into bundled templates            |
 
 **Key principle:** If a LumenFlow CLI command exists for the operation, use it instead of
 raw pnpm/git. These tooling commands commit directly to main via micro-worktree — no dirty
 files, no manual git, no WU ceremony. Only actual **code changes** need WUs.
 
-`docs:sync` refreshes the scaffolded onboarding set plus supported vendor assets. Existing
-tracked docs are skipped by default; use `--force` when you intentionally want the refresh.
+`docs:sync` refreshes core docs (LUMENFLOW.md, AGENTS.md, constraints.md), the scaffolded
+onboarding set, and supported vendor assets. Existing docs are skipped by default; use `--force`
+when you intentionally want the refresh.
 
 For existing installs, upgrade packages first with `pnpm lumenflow:upgrade --latest`, then run
-`pnpm docs:sync --force` if you want refreshed onboarding docs and vendor assets. The improved
+`pnpm docs:sync --force` if you want refreshed core docs, onboarding docs, and vendor assets. The improved
 default `wu:brief` behavior comes from the package upgrade itself. New installs get those defaults
 automatically, and `.lumenflow/templates/` remains optional unless you want custom overrides.
 
@@ -147,7 +148,6 @@ automatically, and `.lumenflow/templates/` remains optional unless you want cust
 | `pnpm wu:release --id WU-XXX`                                  | Release orphaned WU (in_progress to ready)                            |
 | `pnpm wu:status --id WU-XXX`                                   | Show WU status, location, valid commands                              |
 | `pnpm wu:brief --id WU-XXX --client <client>`                  | Generate handoff prompt + record evidence (claimed workspace/branch)  |
-| `pnpm wu:brief --id WU-XXX --evidence-only`                    | Record wu:brief evidence only (self-implementation, no prompt output) |
 | `pnpm wu:brief --id WU-XXX --no-context`                       | Generate prompt without memory context injection                      |
 | `pnpm wu:delegate --id WU-XXX --parent-wu <P>`                 | Generate prompt, record lineage, and store brief hash attestation     |
 | `pnpm wu:sandbox --id WU-XXX -- <cmd>`                         | Run command through hardened WU sandbox backend                       |
@@ -330,9 +330,11 @@ stub in `$LUMENFLOW_HOME/plans/` and automatically set the WU's `plan` field to
 | ------------------------------------------------------------------------ | ------------------------------------------------------------------- |
 | `pnpm plan:create --id INIT-XXX --title "..."`                           | Create a repo-native plan file in configured `directories.plansDir` |
 | `pnpm plan:create --id INIT-XXX --title "..." --from <path>`             | Import external plan file into repo plansDir                        |
-| `pnpm plan:edit --id INIT-XXX --section Goal --content "..."`            | Edit a section in a plan file                                       |
-| `pnpm plan:link --id INIT-XXX --plan lumenflow://plans/INIT-XXX-plan.md` | Link plan URI to initiative or WU                                   |
-| `pnpm plan:promote --id INIT-XXX`                                        | Promote plan status to approved                                     |
+| `pnpm plan:edit --id INIT-XXX --section Goal --content "..."`                 | Edit plan section (auto-resolves file from initiative metadata)     |
+| `pnpm plan:edit --id WU-XXX --file my-plan.md --section Goal --content "..."` | Edit plan by explicit filename                                     |
+| `pnpm plan:link --id INIT-XXX --plan lumenflow://plans/INIT-XXX-plan.md`      | Link plan URI to initiative or WU                                  |
+| `pnpm plan:promote --id INIT-XXX`                                             | Promote plan to approved (auto-resolves from initiative metadata)  |
+| `pnpm plan:promote --id WU-XXX --file my-plan.md`                             | Promote plan by explicit filename                                  |
 | `pnpm initiative:plan --initiative INIT-XXX --plan <path>`               | Link plan to initiative (auto-imports external files into repo)     |
 | `pnpm initiative:plan --initiative INIT-XXX --create`                    | Create blank plan template and link to initiative                   |
 | `pnpm initiative:plan --initiative INIT-XXX --create --plan <path>`      | Import external plan content into new template and link             |

package/templates/core/ai/onboarding/release-process.md.template

@@ -350,7 +350,7 @@ rm packages/@lumenflow/packs/software-delivery/lumenflow-packs-software-delivery
 | `web`             | registry.lumenflow.dev   | Pack registry + web app |
 | `docs`            | lumenflow.dev            | Starlight documentation |
 | `lumenflow-dev`   | lumenflow-dev.vercel.app | Monorepo preview        |
-| `lumenflow-cloud` | cloud.lumenflow.dev      | Control plane           |
+| `cloud`           | cloud.lumenflow.dev      | Control plane           |
 
 ### Troubleshooting Pack Publishing
 

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

@@ -488,7 +488,7 @@ Use `wu:brief` to create parallel sub-agent handoff prompts for complex WUs. Use
 ### Choose the Correct Flow
 
 - **Delegating to a sub-agent:** Run `wu:brief` (or `wu:delegate` for lineage), then pass the generated prompt to Task tool.
-- **Implementing in current session:** Run `wu:brief --evidence-only` to satisfy evidence policy, then do the WU yourself (no spawn prompt output).
+- **Implementing in current session:** Run `wu:brief --client <client>` to record evidence, then do the WU yourself. `wu:brief` always outputs full context AND records evidence.
 
 ### How to Use wu:brief / wu:delegate
 
@@ -496,8 +496,8 @@ Use `wu:brief` to create parallel sub-agent handoff prompts for complex WUs. Use
 # Generate a handoff prompt + evidence (no lineage side effect)
 pnpm wu:brief --id WU-XXXX --client <client-type>
 
-# Record required evidence without generating handoff prompt output (self-implementation)
-pnpm wu:brief --id WU-XXXX --evidence-only
+# Self-implementation: wu:brief always outputs full context AND records evidence
+pnpm wu:brief --id WU-XXXX --client <client>
 
 # Generate + record explicit delegation lineage
 pnpm wu:delegate --id WU-XXXX --parent-wu WU-YYYY --client <client-type>
@@ -520,7 +520,7 @@ 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
+- Run `pnpm docs:sync --force` when you also want refreshed core docs, onboarding docs, and
   supported vendor assets.
 
 Default profiles:
@@ -556,8 +556,7 @@ Domain-specific commands must come from local configuration, not core framework
 | `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:brief --id WU-XXX --client <client>`  | Generate handoff prompt + record evidence        | Delegation or self-impl     |
 | `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            |

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

@@ -12,11 +12,14 @@ Bias toward **one coherent outcome = one WU**.
 
 Do not split a WU just because it has multiple implementation steps, tests, or docs, or because it may need another session. Split only when the work is no longer one coherent deliverable.
 
+Before splitting, ask: **Can these parts ship, review, and roll back independently?** If no, keep one WU and choose a better execution strategy.
+
 Keep one WU when:
 
 - The acceptance criteria describe one user-visible or operator-visible outcome
 - One agent can still complete it with `single-session`, `checkpoint-resume`, or `orchestrator-worker`
 - The touched files support the same change, even if there are several of them
+- Code, tests, and docs all support the same change
 
 Split when:
 
@@ -25,6 +28,12 @@ Split when:
 - Risk isolation matters, such as tracer-bullet, feature-flag, or adapter-first rollout
 - The work keeps widening and no longer has a clean stopping point
 
+Anti-patterns that should usually stay one WU:
+
+- One API endpoint split into backend, tests, and docs WUs
+- One shippable feature split into backend and frontend WUs even though neither stands alone
+- One refactor split into "step 1", "step 2", and "cleanup" WUs with no independent ship point
+
 ---
 
 ## Baseline Heuristics
@@ -33,8 +42,8 @@ Split when:
 | ---------- | ----- | ---------- | ------------------------------------------------------- |
 | Simple     | <20   | <50        | Single session                                          |
 | Medium     | 20-50 | 50-100     | Checkpoint and resume                                   |
-| Complex    | 50+   | 100+       | Orchestrate or split only if the WU is non-atomic       |
-| Oversized  | 100+  | 200+       | Split before implementation unless an exception applies |
+| Complex    | 50+   | 100+       | Orchestrate or checkpoint first; split only if the WU is non-atomic |
+| Oversized  | 100+  | 200+       | Re-check cohesion; split only if no exception applies and the work cannot land coherently |
 
 These are guardrails for session strategy, not a license to multiply WUs that still belong together.
 

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

@@ -135,12 +135,12 @@ pnpm wu:delegate --id WU-1502 --parent-wu WU-1500  # Prompt + lineage recording
 pnpm wu:delegate --id WU-1503 --parent-wu WU-1500
 
 # For WUs implemented in current session:
-pnpm wu:brief --id WU-1504 --evidence-only         # Evidence only, no prompt output
+pnpm wu:brief --id WU-1504 --client <client>       # Full context + evidence (self-implementation)
 ```
 
 ### Orchestration Pattern
 
-1. **Choose execution path per WU**: delegation (`wu:brief`/`wu:delegate`) or self-implementation (`wu:brief --evidence-only`)
+1. **Choose execution path per WU**: delegation (`wu:brief`/`wu:delegate`) or self-implementation (`wu:brief --client <client>`)
 2. **Spawn only delegated WUs**: Use Task tool with `run_in_background: true`
 3. **Monitor delegated progress**: Use `pnpm mem:inbox --since 30m` (NOT TaskOutput - causes context explosion)
 4. **Synthesise**: Combine results from sub-agents and self-implemented WUs

package/templates/vendors/claude/.claude/skills/multi-agent-coordination/SKILL.md.template

@@ -35,10 +35,10 @@ pnpm wu:brief --id WU-XXX --client claude-code      # Generate prompt only
 pnpm wu:delegate --id WU-XXX --parent-wu WU-YYY     # Generate prompt + record lineage
 ```
 
-**Use wu:brief --evidence-only** when you are implementing the WU yourself:
+**Use wu:brief** when you are implementing the WU yourself (it always outputs full context AND records evidence):
 
 ```bash
-pnpm wu:brief --id WU-XXX --evidence-only           # Record required evidence, no prompt output
+pnpm wu:brief --id WU-XXX --client <client>         # Full context + evidence recording
 ```
 
 **DON'T use wu:brief/wu:delegate** for helper agents (code-reviewer, test-engineer) on YOUR WU.

package/templates/vendors/claude/.claude/skills/orchestration/SKILL.md.template

@@ -33,8 +33,8 @@ pnpm wu:brief --id WU-XXX --client claude-code
 # ✅ CORRECT: Use wu:delegate for lineage-tracked delegation
 pnpm wu:delegate --id WU-XXX --parent-wu WU-YYY
 
-# ✅ CORRECT: Use evidence-only when implementing the WU yourself
-pnpm wu:brief --id WU-XXX --evidence-only
+# ✅ CORRECT: wu:brief always outputs full context AND records evidence
+pnpm wu:brief --id WU-XXX --client <client>
 ```
 
 **❌ NEVER do this:**
@@ -46,7 +46,7 @@ pnpm wu:brief --id WU-XXX --evidence-only
 **Why this matters:**
 
 1. `wu:brief` generates prompts with context loading preamble, TDD directives, and constraints block
-2. `wu:brief --evidence-only` satisfies `wu:done` evidence policy when you are not delegating
+2. `wu:brief` always records evidence AND outputs full context (no separate evidence-only mode)
 3. Sub-agents need `wu:claim` (inside generated prompts) to create proper lane locks and event tracking
 4. Direct Task spawns bypass all safety mechanisms, coordination signals, and spawn registry tracking
 
@@ -223,7 +223,7 @@ pnpm wu:brief --id WU-XXX
 Starting WU?
 ├── Delegating to sub-agent?
 │   ├── Yes: pnpm wu:brief --id WU-XXX --client <client> (or wu:delegate for lineage)
-│   └── No:  pnpm wu:brief --id WU-XXX --evidence-only, then implement directly
+│   └── No:  pnpm wu:brief --id WU-XXX --client <client>, then implement directly
 └── If delegated, review generated prompt with agent recommendations
 
 Initiative with multiple WUs?

package/templates/vendors/cursor/.cursor/rules/lumenflow.md.template

@@ -1,6 +1,14 @@
 # Cursor LumenFlow Rules
 
-This project uses LumenFlow workflow. See [LUMENFLOW.md](../../LUMENFLOW.md) for complete documentation.
+**Read first:** [AGENTS.md](../../AGENTS.md) for universal startup rules, then [LUMENFLOW.md](../../LUMENFLOW.md) for the canonical workflow, commands, and safety rules.
+
+This file contains Cursor-specific overrides only. Do not duplicate workflow rules from LUMENFLOW.md here.
+
+## Command Discovery (MANDATORY)
+
+1. Run `pnpm lumenflow:commands` to discover all available commands
+2. Run `<command> --help` before first use of any command — do not guess flags or subcommands
+3. **Never truncate** CLI output (`| head`, `| tail`, `| head -n`) — read the full output
 
 ## Critical Rules
 

package/templates/vendors/windsurf/.windsurf/rules/lumenflow.md.template

@@ -1,6 +1,14 @@
 # Windsurf LumenFlow Rules
 
-This project uses LumenFlow workflow. See [LUMENFLOW.md](../../LUMENFLOW.md) for complete documentation.
+**Read first:** [AGENTS.md](../../AGENTS.md) for universal startup rules, then [LUMENFLOW.md](../../LUMENFLOW.md) for the canonical workflow, commands, and safety rules.
+
+This file contains Windsurf-specific overrides only. Do not duplicate workflow rules from LUMENFLOW.md here.
+
+## Command Discovery (MANDATORY)
+
+1. Run `pnpm lumenflow:commands` to discover all available commands
+2. Run `<command> --help` before first use of any command — do not guess flags or subcommands
+3. **Never truncate** CLI output (`| head`, `| tail`, `| head -n`) — read the full output
 
 ## Critical Rules