@lumenflow/cli 3.2.1 → 3.2.2

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

@@ -33,6 +33,7 @@ Run `--help` first, then run the real command with explicit flags.
 | Metrics & Flow      | `pnpm flow:report --help`             | `pnpm flow:report`                                                       |
 | Documentation       | `pnpm docs:validate --help`           | `pnpm docs:validate`                                                     |
 | Release             | `pnpm pre-release:check --help`       | `pnpm pre-release:check`                                                 |
+| Configuration       | `pnpm config:set --help`              | `pnpm config:set --key methodology.testing --value test-after`           |
 | Agent Utilities     | `pnpm agent:issues-query --help`      | `pnpm agent:issues-query`                                                |
 
 ---
@@ -77,21 +78,21 @@ pnpm exec lumenflow --client all      # All clients
 
 ## WU Lifecycle
 
-| Command                                        | Description                                      |
-| ---------------------------------------------- | ------------------------------------------------ |
-| `pnpm wu:create --id WU-XXX --lane <Lane> ..`  | Create new WU spec (see required fields below)   |
-| `pnpm wu:claim --id WU-XXX --lane <Lane>`      | Claim WU and create worktree (default)           |
-| `pnpm wu:claim --id WU-XXX --lane <L> --cloud` | Claim WU in cloud/branch-pr mode (no worktree)   |
-| `pnpm wu:prep --id WU-XXX [--full-tests]`      | Run gates, prep for wu:done (`tests.unit` scoped by default) |
-| `pnpm wu:done --id WU-XXX`                     | Complete WU (merge or PR, stamp, cleanup)        |
-| `pnpm wu:edit --id WU-XXX --description "..."` | Edit WU spec fields (run --help for all flags)   |
-| `pnpm wu:block --id WU-XXX --reason "..."`     | Block WU with reason                             |
-| `pnpm wu:unblock --id WU-XXX`                  | Unblock WU                                       |
-| `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 (does not execute)       |
-| `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 and record delegation lineage    |
+| Command                                         | Description                                                  |
+| ----------------------------------------------- | ------------------------------------------------------------ |
+| `pnpm wu:create --lane <Lane> --title "..." ..` | Create new WU spec (ID auto-generated; see fields below)     |
+| `pnpm wu:claim --id WU-XXX --lane <Lane>`       | Claim WU and create worktree (default)                       |
+| `pnpm wu:claim --id WU-XXX --lane <L> --cloud`  | Claim WU in cloud/branch-pr mode (no worktree)               |
+| `pnpm wu:prep --id WU-XXX [--full-tests]`       | Run gates, prep for wu:done (`tests.unit` scoped by default) |
+| `pnpm wu:done --id WU-XXX`                      | Complete WU (merge or PR, stamp, cleanup)                    |
+| `pnpm wu:edit --id WU-XXX --description "..."`  | Edit WU spec fields (run --help for all flags)               |
+| `pnpm wu:block --id WU-XXX --reason "..."`      | Block WU with reason                                         |
+| `pnpm wu:unblock --id WU-XXX`                   | Unblock WU                                                   |
+| `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 (does not execute)                   |
+| `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 and record delegation lineage                |
 
 ### WU Maintenance
 
@@ -112,18 +113,22 @@ pnpm exec lumenflow --client all      # All clients
 
 ## Gates & Quality
 
-| Command                           | Description                      |
-| --------------------------------- | -------------------------------- |
-| `pnpm gates`                      | Run all quality gates            |
-| `pnpm gates --docs-only`          | Run gates for docs changes       |
-| `pnpm format`                     | Format all files (Prettier)      |
-| `pnpm format:check`               | Check formatting without changes |
-| `pnpm lint`                       | Run ESLint                       |
-| `pnpm typecheck`                  | Run TypeScript type checking     |
-| `pnpm test`                       | Run all tests (Vitest)           |
-| `pnpm spec:linter`                | Validate WU specs (all) ¹        |
-| `pnpm lane:health`                | Check lane config health         |
-| `pnpm lane:suggest --paths "..."` | Suggest lane for code paths      |
+| Command                           | Description                       |
+| --------------------------------- | --------------------------------- |
+| `pnpm gates`                      | Run all quality gates             |
+| `pnpm gates --docs-only`          | Run gates for docs changes        |
+| `pnpm format`                     | Format all files (Prettier)       |
+| `pnpm format:check`               | Check formatting without changes  |
+| `pnpm lint`                       | Run ESLint                        |
+| `pnpm typecheck`                  | Run TypeScript type checking      |
+| `pnpm test`                       | Run all tests (Vitest)            |
+| `pnpm spec:linter`                | Validate WU specs (all) ¹         |
+| `pnpm lane:health`                | Check lane config health          |
+| `pnpm lane:suggest --paths "..."` | Suggest lane for code paths       |
+| `pnpm lane:status`                | Show lane lifecycle status        |
+| `pnpm lane:setup`                 | Create/update draft lane config   |
+| `pnpm lane:validate`              | Validate lane draft artifacts     |
+| `pnpm lane:lock`                  | Lock lane lifecycle for WU create |
 
 ¹ **Script aliases:** `spec:linter` and `tasks:validate` are pnpm script aliases
 for `wu:validate --all`. They are not standalone CLI commands.
@@ -211,6 +216,30 @@ Supported mismatch fixes:
 
 ---
 
+## Configuration
+
+| Command                                           | Description                                     |
+| ------------------------------------------------- | ----------------------------------------------- |
+| `pnpm config:get --key <dotpath>`                 | Read a value from `workspace.yaml`              |
+| `pnpm config:set --key <dotpath> --value <value>` | Set a value in `workspace.yaml` (Zod-validated) |
+
+`config:set` validates against the Zod schema before writing and uses the micro-worktree
+pattern for atomic commits. Always use these commands instead of raw Write/Edit on
+`workspace.yaml`. See [Constraint 9](../../../../../.lumenflow/constraints.md)
+and [YAML editing policy](../../../../../.lumenflow/rules/yaml-editing-policy.md).
+
+**Common dotpaths:**
+
+| Dotpath                           | Type    | Example Values              |
+| --------------------------------- | ------- | --------------------------- |
+| `methodology.testing`             | enum    | `tdd`, `test-after`, `none` |
+| `gates.minCoverage`               | number  | `0`-`100`                   |
+| `gates.enableCoverage`            | boolean | `true`, `false`             |
+| `experimental.context_validation` | boolean | `true`, `false`             |
+| `git.requireRemote`               | boolean | `true`, `false`             |
+
+---
+
 ## Dependencies
 
 | Command                         | Description                    |
@@ -222,15 +251,15 @@ Supported mismatch fixes:
 
 ## Plans
 
-Plans are markdown documents that capture goals, scope, approach, and success criteria before implementation begins. They link to WUs (via `spec_refs`) and initiatives (via `related_plan`).
+Plans are markdown documents that capture goals, scope, approach, and success criteria before implementation begins. They link to WUs (via the `plan` field, WU-1683) and initiatives (via `related_plan`).
 
 ### Plan Storage
 
 Plans are stored in the repo at `docs/04-operations/plans/` by default (configurable via `directories.plansDir` in `workspace.yaml`).
 
 If the plan exists only in conversation, use `--plan` on `wu:create` to generate a lightweight
-stub in `$LUMENFLOW_HOME/plans/`, then summarize the conversation there and reference it via
-`spec_refs`. Feature WUs require `spec_refs`; notes do not replace the plan link.
+stub in `$LUMENFLOW_HOME/plans/` and automatically set the WU's `plan` field to the
+`lumenflow://plans/` URI. Feature WUs should have a `plan` field; notes do not replace the plan link.
 
 | Command                                                                  | Description                                                   |
 | ------------------------------------------------------------------------ | ------------------------------------------------------------- |
@@ -263,15 +292,17 @@ pnpm initiative:plan --initiative INIT-001 --create
 pnpm initiative:plan --initiative INIT-001 --plan docs/04-operations/plans/my-plan.md
 ```
 
-**To a WU (via spec_refs):**
+**To a WU (via `plan` field, WU-1683):**
 
 ```bash
-# When creating a WU
-pnpm wu:create --id WU-123 --lane "Framework: Core" --title "Feature" \
-  --spec-refs "lumenflow://plans/WU-123-plan.md"
+# When creating a WU (--plan auto-generates and links)
+pnpm wu:create --lane "Framework: Core" --title "Feature" --plan
+
+# Or edit an existing WU with a specific plan URI
+pnpm wu:edit --id WU-123 --plan "lumenflow://plans/WU-123-plan.md"
 
-# Or edit an existing WU
-pnpm wu:edit --id WU-123 --spec-refs "lumenflow://plans/WU-123-plan.md"
+# Or use plan:link
+pnpm plan:link --id WU-123 --plan lumenflow://plans/WU-123-plan.md
 ```
 
 ### Plan URI Format
@@ -396,18 +427,18 @@ pnpm gates              # Now works
 # 0. Check available options (do this before first use of any command)
 pnpm wu:create --help
 
-# 1. Create WU
-pnpm wu:create --id WU-XXX --lane "Framework: Core" --title "Add feature" \
+# 1. Create WU (ID auto-generated)
+pnpm wu:create --lane "Framework: Core" --title "Add feature" \
   --description "Context: ... Problem: ... Solution: ..." \
   --acceptance "Criterion 1" --acceptance "Criterion 2" \
   --code-paths "src/file.ts" \
   --test-paths-unit "src/__tests__/file.test.ts" \
-  --exposure backend-only \
-  --spec-refs "~/.lumenflow/plans/WU-XXX-plan.md"
+  --exposure backend-only
+# Output: Created WU-1990 at docs/.../wu/WU-1990.yaml
 
-# 2. Claim (creates worktree)
-pnpm wu:claim --id WU-XXX --lane "Framework: Core"
-cd worktrees/framework-core-wu-xxx
+# 2. Claim (creates worktree) -- use the ID from wu:create output
+pnpm wu:claim --id WU-1990 --lane "Framework: Core"
+cd worktrees/framework-core-wu-1990
 
 # 2b. Bootstrap (build CLI for dist-backed commands)
 pnpm bootstrap
@@ -419,10 +450,10 @@ pnpm bootstrap
 git add . && git commit -m "feat: description"
 
 # 5. Prep (runs gates in worktree)
-pnpm wu:prep --id WU-XXX
+pnpm wu:prep --id WU-1990
 
 # 6. Complete (from main - copy from wu:prep output)
-cd /path/to/main && pnpm wu:done --id WU-XXX
+cd /path/to/main && pnpm wu:done --id WU-1990
 ```
 
 ---
@@ -437,9 +468,24 @@ For code changes, you must include **all** of the following (or wu:create will f
 - `--test-paths-unit` or `--test-paths-e2e` (automated tests required)
 - `--exposure` (ui | api | backend-only | documentation)
 - `--spec-refs` (required for type: feature)
+- `--plan` (optional, auto-generates plan file and sets `plan` field — WU-1683)
 
 Documentation WUs can omit code/test paths but should set `--type documentation` and `--exposure documentation`.
 
+**Auto-generated IDs (recommended):** Omit `--id` and let `wu:create` assign the next sequential ID. Capture the output for dependency chaining:
+
+```bash
+# Create first WU (ID auto-generated)
+pnpm wu:create --lane "Framework: Core" --title "First WU" ...
+# Output: Created WU-1990
+
+# Create second WU blocked by the first
+pnpm wu:create --lane "Framework: Core" --title "Second WU" --blocked-by WU-1990 ...
+# Output: Created WU-1991
+```
+
+> **Note:** Use `--id` only when re-creating a specific WU or for migration tooling.
+
 ---
 
 ## Strict WU Validation (WU-1329)
@@ -498,14 +544,27 @@ Agents should:
 
 ---
 
-## Lane Inference Requirement (Sub-Lanes)
+## Lane Lifecycle Requirement
 
-If you use a sub-lane like `Experience: UI`, you **must** have a lane taxonomy:
+Before the first delivery WU, complete lane lifecycle once per project:
 
-- Ensure `.lumenflow.lane-inference.yaml` exists, or
-- Generate it with `pnpm lane:suggest --output .lumenflow.lane-inference.yaml`
+```bash
+pnpm lane:setup
+pnpm lane:validate
+pnpm lane:lock
+```
 
-Without this file, sub-lane validation will fail.
+Lifecycle states:
+
+- `unconfigured` -> next step `pnpm lane:setup`
+- `draft` -> next step `pnpm lane:lock`
+- `locked` -> delivery WUs can be created
+
+Check current lifecycle state any time:
+
+```bash
+pnpm lane:status
+```
 
 ---
 

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

@@ -56,6 +56,10 @@ If you are starting a new project or feature from a product vision (e.g., "Build
 3. **Create WUs under the Initiative**: Each WU belongs to a phase
 
    ```bash
+   pnpm lane:setup
+   pnpm lane:validate
+   pnpm lane:lock
+
    pnpm wu:create --lane "Core: Platform" --title "Add task model" \
      --description "..." --acceptance "..." --code-paths "..." \
      && pnpm initiative:add-wu --initiative INIT-001 --wu WU-XXX --phase 1
@@ -168,10 +172,15 @@ all signals are user-configured.
 
 ## Before Creating WUs
 
-If you plan to use sub-lanes like `Experience: UI`, make sure lane inference is configured:
+Before the first delivery WU in a project, complete lane lifecycle:
+
+```bash
+pnpm lane:setup
+pnpm lane:validate
+pnpm lane:lock
+```
 
-- `.lumenflow.lane-inference.yaml` must exist for sub-lane validation, or
-- Generate it with `pnpm lane:suggest --output .lumenflow.lane-inference.yaml`
+Use `pnpm lane:status` to verify lifecycle state and recommended next step.
 
 **No remote yet?** `wu:create` expects `origin/main`. If your repo is local-only, add a remote
 before running `wu:create`. `wu:claim` supports `--no-push` for local-only work.
@@ -274,6 +283,55 @@ LUMENFLOW_FORCE=1 LUMENFLOW_FORCE_REASON="backlog corruption recovery" git push
 
 ---
 
+## Safe Configuration Modification (Constraint 9)
+
+**Never use Write or Edit tools to modify YAML configuration files.** Always use the dedicated CLI commands.
+
+### Modifying workspace.yaml
+
+```bash
+# Read a config value
+pnpm config:get --key methodology.testing
+
+# Set a config value (validates against Zod schema, uses atomic commit)
+pnpm config:set --key methodology.testing --value test-after
+
+# Set a boolean
+pnpm config:set --key gates.enableCoverage --value false
+
+# Set a number
+pnpm config:set --key gates.minCoverage --value 85
+
+# Append to an array
+pnpm config:set --key agents.methodology.principles --value Library-First,KISS
+```
+
+### Modifying WU YAML Specs
+
+```bash
+# Edit WU fields (run --help for all available flags)
+pnpm wu:edit --id WU-XXX --description "Updated description"
+
+# Create new WU (never manually Write a YAML file)
+pnpm wu:create --lane "Framework: Core" --title "Add feature" \
+  --description "..." --acceptance "..."
+```
+
+### Why This Matters
+
+Raw-editing YAML files with Write/Edit tools bypasses:
+
+1. **Schema validation** -- `config:set` validates against the Zod schema
+2. **Atomic commits** -- `config:set` uses micro-worktree for safe writes
+3. **Audit trail** -- CLI commands produce structured log entries
+4. **Type coercion** -- Automatic boolean/number/array handling
+
+**Exception:** Reading YAML files with the Read tool is acceptable for inspection.
+
+For the full policy, see [.lumenflow/rules/yaml-editing-policy.md](../../../../../.lumenflow/rules/yaml-editing-policy.md) and Constraint 9 in [.lumenflow/constraints.md](../../../../../.lumenflow/constraints.md).
+
+---
+
 ## Common Failure Scenarios and Recovery
 
 ### Scenario 1: "BLOCKED: Direct commit to main"
@@ -565,7 +623,7 @@ rm -rf /tmp/nextjs-scaffold
 
 - [LUMENFLOW.md](../../../../../LUMENFLOW.md) - Main workflow documentation
 - [AGENTS.md](../../../../../AGENTS.md) - Universal agent entry point
-- [.lumenflow/constraints.md](../../../../../.lumenflow/constraints.md) - The 8 non-negotiable rules
+- [.lumenflow/constraints.md](../../../../../.lumenflow/constraints.md) - The 9 non-negotiable rules
 - [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

package/templates/vendors/claude/.claude/skills/wu-lifecycle/SKILL.md.template

@@ -50,10 +50,12 @@ cd /path/to/main && pnpm wu:done --id WU-XXX
 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" \
+# Create (full spec -- ID auto-generated)
+pnpm wu:create --lane "Operations" --title "Add feature" \
   --description "Context: ... Problem: ... Solution: ..." \
   --acceptance "Feature works" --code-paths "src/a.ts" --validate
+# Output: Created WU-999
+# Note: Use --id only when re-creating a specific WU or for migration tooling.
 
 # Edit spec
 pnpm wu:edit --id WU-XXX --description "..." --acceptance "..."