@lumenflow/cli 2.2.1 → 2.3.1

package/templates/core/LUMENFLOW.md.template

@@ -0,0 +1,255 @@
+# LumenFlow Workflow Guide
+
+**Last updated:** {{DATE}}
+
+LumenFlow is a vendor-agnostic workflow framework for AI-native software development.
+
+> **Context Safety**: When approaching context limits (80% usage, 50+ tool calls), spawn a fresh agent instead of continuing after compaction. See [wu-sizing-guide.md](docs/04-operations/_frameworks/lumenflow/wu-sizing-guide.md).
+
+---
+
+## Critical Rule: ALWAYS Run wu:done
+
+**After completing work on a WU, you MUST run `pnpm wu:done --id WU-XXXX` from the main checkout.**
+
+This is the single most forgotten step. Do NOT:
+
+- Write "To Complete: pnpm wu:done" and stop
+- Ask if you should run wu:done
+- Forget to run wu:done
+
+**DO**: Run `pnpm wu:done --id WU-XXXX` immediately after gates pass.
+
+See: [docs/04-operations/\_frameworks/lumenflow/agent/onboarding/troubleshooting-wu-done.md](docs/04-operations/_frameworks/lumenflow/agent/onboarding/troubleshooting-wu-done.md)
+
+---
+
+## Quick Start
+
+```bash
+# 1. Setup (first time only)
+pnpm setup
+
+# 2. Create a WU (default: creates spec/wu-xxxx branch, never writes to main)
+pnpm wu:create --id WU-XXXX --lane <Lane> --title "Title" \
+  --description "..." --acceptance "..." --code-paths "..." \
+  --test-paths-unit "..." --exposure backend-only \
+  --spec-refs "lumenflow://plans/WU-XXXX-plan.md"
+
+# 3. Claim (auto-merges spec branch to main if needed)
+pnpm wu:claim --id WU-XXXX --lane <Lane>
+cd worktrees/<lane>-wu-xxxx
+
+# 4. Implement in worktree
+
+# 5. Run gates
+pnpm gates --docs-only  # for docs changes
+pnpm gates              # for code changes
+
+# 6. Complete (from main checkout)
+cd /path/to/main
+pnpm wu:done --id WU-XXXX
+```
+
+---
+
+## Core Principles
+
+1. **TDD**: Failing test -> implementation -> passing test (>=90% coverage on new code)
+2. **Library-First**: Search existing libraries before custom code
+3. **DRY/SOLID/KISS/YAGNI**: No magic numbers, no hardcoded strings
+4. **Worktree Discipline**: After `wu:claim`, work ONLY in the worktree
+5. **Branch Safety**: NEVER edit files on main branch. Run `git branch --show-current` before edits.
+6. **Gates Before Done**: All gates must pass before `wu:done`
+7. **Do Not Bypass Hooks**: No `--no-verify`, fix issues properly
+8. **Always wu:done**: Complete every WU by running `pnpm wu:done`
+
+---
+
+## Global State
+
+Canonical global state is defined by:
+
+- `origin/main` (WU YAML + status.md + backlog.md + state store)
+- Remote lane branches (e.g., `origin/lane/<lane>/wu-<id>`)
+
+`wu:claim` updates canonical claim state on `origin/main` using a push-only micro-worktree, then
+creates the lane branch and pushes it by default for global visibility. Use `--no-push` only for
+air-gapped/offline work; it creates a local-only claim and warns explicitly.
+
+---
+
+## Documentation Structure
+
+### Core (Vendor-Agnostic)
+
+- **LUMENFLOW.md** - This file, main entry point
+- **.lumenflow/constraints.md** - Non-negotiable workflow constraints
+- **.lumenflow/rules/** - Workflow rules (git-safety.md, wu-workflow.md, etc.)
+- **docs/04-operations/\_frameworks/lumenflow/agent/onboarding/** - Agent onboarding documentation
+
+### Vendor Integrations
+
+- **.claude/** - Claude Code (settings.json, hooks, .claude/CLAUDE.md)
+- **.cursor/** - Cursor (rules, settings)
+- **.aider.conf.yml** - Aider configuration
+- **.continue/** - Continue configuration
+
+---
+
+## Worktree Discipline (IMMUTABLE LAW)
+
+After claiming a WU, you MUST work in its worktree:
+
+```bash
+# 1. Claim creates worktree
+pnpm wu:claim --id WU-XXX --lane <lane>
+
+# 2. IMMEDIATELY cd to worktree
+cd worktrees/<lane>-wu-xxx
+
+# 3. ALL work happens here (edits, git add/commit/push, tests, gates)
+
+# 4. Return to main ONLY to complete
+cd /path/to/main
+pnpm wu:done --id WU-XXX
+```
+
+Main checkout becomes read-only after claim. Hooks will block WU commits from main.
+
+---
+
+## Definition of Done
+
+- Acceptance criteria satisfied
+- Gates green (`pnpm gates` or `pnpm gates --docs-only`)
+- WU YAML status = `done`
+- `.lumenflow/stamps/WU-<id>.done` exists
+- **wu:done has been run** (not just documented as "to do")
+
+---
+
+## Core Commands
+
+> **Complete CLI reference (60+ commands):** See [quick-ref-commands.md](ai/onboarding/quick-ref-commands.md)
+
+| Command                         | Description                                            |
+| ------------------------------- | ------------------------------------------------------ |
+| `pnpm wu:create`                | Create new WU spec                                     |
+| `pnpm wu:claim`                 | Claim WU, update canonical state, create worktree      |
+| `pnpm wu:done`                  | Complete WU (merge, stamp, cleanup)                    |
+| `pnpm wu:block`                 | Block WU (transitions to blocked, frees lane)          |
+| `pnpm wu:unblock`               | Unblock WU (transitions to in_progress)                |
+| `pnpm wu:release`               | Release orphaned WU (in_progress to ready for reclaim) |
+| `pnpm wu:status`                | Show WU status, location, and valid commands           |
+| `pnpm wu:recover`               | Analyze and fix WU state inconsistencies               |
+| `pnpm gates`                    | Run quality gates                                      |
+| `pnpm mem:checkpoint`           | Save memory checkpoint                                 |
+| `pnpm exec lumenflow docs:sync` | Sync agent docs after upgrading LumenFlow packages     |
+
+### Context-Aware Validation (WU-1090)
+
+WU lifecycle commands include context-aware validation that automatically checks:
+
+- **Location**: Whether you are in main checkout or a worktree
+- **WU Status**: Whether the WU is in the correct state for the command
+- **Git State**: Uncommitted changes, commits ahead/behind
+
+When validation fails, commands provide copy-paste ready fix commands:
+
+```
+ERROR: WRONG_LOCATION - wu:done must be run from main checkout
+
+FIX: Run this command:
+  cd {{PROJECT_ROOT}} && pnpm wu:done --id WU-1090
+```
+
+Configure validation behavior in `.lumenflow.config.yaml`:
+
+```yaml
+experimental:
+  context_validation: true # Enable/disable validation
+  validation_mode: 'warn' # 'off' | 'warn' | 'error'
+  show_next_steps: true # Show guidance after command success
+```
+
+### Recovery Commands
+
+If WU state becomes inconsistent (e.g., worktree exists but status is 'ready'), use recovery:
+
+```bash
+# Analyze issues
+pnpm wu:recover --id WU-XXX
+
+# Apply suggested fix
+pnpm wu:recover --id WU-XXX --action resume   # Reconcile state, preserve work
+pnpm wu:recover --id WU-XXX --action reset    # Reset to ready, discard worktree
+pnpm wu:recover --id WU-XXX --action cleanup  # Remove leftover worktree
+```
+
+---
+
+## Constraints
+
+See [.lumenflow/constraints.md](.lumenflow/constraints.md) for the 6 non-negotiable rules:
+
+1. Worktree discipline and git safety
+2. WUs are specs, not code
+3. Docs-only vs code WUs
+4. LLM-first, zero-fallback inference
+5. Gates and skip-gates
+6. Safety and governance
+
+---
+
+## Agent Onboarding
+
+If you're an AI agent, read the onboarding docs:
+
+1. [docs/04-operations/\_frameworks/lumenflow/agent/onboarding/troubleshooting-wu-done.md](docs/04-operations/_frameworks/lumenflow/agent/onboarding/troubleshooting-wu-done.md) - Most common mistake
+2. [docs/04-operations/\_frameworks/lumenflow/agent/onboarding/first-wu-mistakes.md](docs/04-operations/_frameworks/lumenflow/agent/onboarding/first-wu-mistakes.md) - First WU pitfalls
+3. [docs/04-operations/\_frameworks/lumenflow/agent/onboarding/agent-safety-card.md](docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-safety-card.md) - Safety guardrails
+4. [docs/04-operations/\_frameworks/lumenflow/agent/onboarding/quick-ref-commands.md](docs/04-operations/_frameworks/lumenflow/agent/onboarding/quick-ref-commands.md) - Command reference
+
+---
+
+## Skills & Agents
+
+LumenFlow provides modular skills and agent definitions for AI assistants.
+
+### Skills
+
+Skills are knowledge bundles in `.claude/skills/` (Claude Code) or `.lumenflow/skills/` (vendor-agnostic):
+
+| Skill                 | Purpose                                     |
+| --------------------- | ------------------------------------------- |
+| `wu-lifecycle`        | WU claim/block/done automation              |
+| `worktree-discipline` | Prevent absolute path trap                  |
+| `tdd-workflow`        | RED-GREEN-REFACTOR, test-driven development |
+| `lumenflow-gates`     | Gate troubleshooting                        |
+| `bug-classification`  | P0-P3 triage, fix-in-place decisions        |
+
+Load skills in Claude Code: `/skill wu-lifecycle`
+
+### Agents
+
+Pre-configured agent definitions in `.claude/agents/`:
+
+| Agent             | Purpose                    |
+| ----------------- | -------------------------- |
+| `general-purpose` | Standard WU implementation |
+| `lumenflow-pm`    | Backlog & lifecycle        |
+| `test-engineer`   | TDD, coverage              |
+| `code-reviewer`   | Quality checks             |
+| `bug-triage`      | Bug classification         |
+
+Generate spawn prompts: `pnpm wu:spawn --id WU-XXX --client claude-code`
+
+---
+
+## References
+
+- [LumenFlow Complete Guide](docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md)
+- [WU Sizing Guide](docs/04-operations/_frameworks/lumenflow/wu-sizing-guide.md)
+- [Skills Index](.claude/skills/INDEX.md)
+- [Agents README](.claude/agents/README.md)

package/templates/core/UPGRADING.md.template

@@ -0,0 +1,121 @@
+# Upgrading LumenFlow
+
+This guide covers upgrading LumenFlow packages in your project.
+
+## Quick Upgrade
+
+```bash
+# Check for available updates
+pnpm outdated @lumenflow/*
+
+# Update all LumenFlow packages
+pnpm update @lumenflow/cli @lumenflow/core @lumenflow/memory @lumenflow/agent @lumenflow/initiatives
+
+# Sync documentation and templates
+pnpm exec lumenflow docs:sync
+```
+
+## Version Compatibility
+
+LumenFlow follows semantic versioning:
+
+- **Major versions** (e.g., 1.x to 2.x): Breaking changes, require migration steps
+- **Minor versions** (e.g., 1.1 to 1.2): New features, backwards compatible
+- **Patch versions** (e.g., 1.1.0 to 1.1.1): Bug fixes, backwards compatible
+
+All `@lumenflow/*` packages are versioned together. Always upgrade them as a group.
+
+## Step-by-Step Upgrade Process
+
+### 1. Check Current Versions
+
+```bash
+pnpm list @lumenflow/*
+```
+
+### 2. Review Changelog
+
+Before upgrading, review the changelog for breaking changes:
+
+- [GitHub Releases](https://github.com/hellmai/os/releases)
+- [lumenflow.dev/changelog](https://lumenflow.dev/changelog)
+
+### 3. Update Packages
+
+```bash
+# Update to latest versions
+pnpm update @lumenflow/cli @lumenflow/core @lumenflow/memory @lumenflow/agent @lumenflow/initiatives
+
+# Or update to a specific version
+pnpm add @lumenflow/cli@^1.2.0 @lumenflow/core@^1.2.0
+```
+
+### 4. Sync Documentation
+
+After upgrading, sync agent onboarding documentation:
+
+```bash
+pnpm exec lumenflow docs:sync
+```
+
+This updates:
+
+- `.lumenflow/` - Workflow rules and constraints
+- `.claude/` - Claude Code skills and settings (if used)
+- `.cursor/` - Cursor rules (if used)
+- Agent onboarding documentation
+
+### 5. Verify Installation
+
+```bash
+# Run gates to verify everything works
+pnpm gates
+
+# Check CLI version
+pnpm exec lumenflow --version
+```
+
+## Troubleshooting
+
+### Package Resolution Errors
+
+If you encounter dependency resolution errors:
+
+```bash
+# Clear pnpm cache and reinstall
+pnpm store prune
+rm -rf node_modules pnpm-lock.yaml
+pnpm install
+```
+
+### CLI Not Found
+
+If `lumenflow` command is not found after upgrade:
+
+```bash
+# Rebuild CLI
+pnpm --filter @lumenflow/cli build
+
+# Or reinstall
+pnpm install
+```
+
+### Template Conflicts
+
+If `docs:sync` reports conflicts:
+
+1. Review the diff for each conflicting file
+2. Merge manually or accept incoming changes
+3. Run `pnpm gates` to verify
+
+## Migration Guides
+
+For major version upgrades, see version-specific migration guides:
+
+- [Migrating to v2.0](https://lumenflow.dev/migration/v2)
+- [Migrating to v1.0](https://lumenflow.dev/migration/v1)
+
+## Getting Help
+
+- [GitHub Issues](https://github.com/hellmai/os/issues)
+- [lumenflow.dev/docs](https://lumenflow.dev/docs)

package/templates/core/ai/onboarding/agent-safety-card.md.template

@@ -0,0 +1,106 @@
+# 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

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

@@ -0,0 +1,198 @@
+# 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: Working After Hours on Same WU
+
+If you need to pause:
+
+```bash
+# Commit your work
+git add .
+git commit -m "wip: partial progress"
+git push origin lane/core/wu-123
+```
+
+Do NOT leave uncommitted changes in the worktree.
+
+---
+
+## Mistake 7: 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
+```
+
+---
+
+## Mistake 8: Scope Creep
+
+### Wrong
+
+The WU says "Add user profile endpoint" but you also:
+
+- Refactor the database schema
+- Add email notifications
+- Redesign the UI
+
+### Right
+
+Implement exactly what the acceptance criteria specify. If you discover other needed changes, create new WUs for them.
+
+---
+
+## Mistake 9: Not Reading the WU Spec
+
+### Wrong
+
+Start coding immediately based on the title.
+
+### Right
+
+1. Read the full WU YAML
+2. Understand acceptance criteria
+3. Review code_paths
+4. Check dependencies
+5. Then start
+
+---
+
+## Mistake 10: Editing Main After Claim
+
+### Wrong
+
+```bash
+pnpm wu:claim --id WU-123 --lane Core
+# Still in main directory
+vim src/feature.ts  # WRONG!
+```
+
+### Right
+
+```bash
+pnpm wu:claim --id WU-123 --lane Core
+cd worktrees/core-wu-123  # IMMEDIATELY
+vim src/feature.ts  # Now it's safe
+```
+
+---
+
+## 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