Skip to content
LumenFlow

Manual Quickstart (Humans)

Prerequisites

Section titled “Prerequisites”

Verify these tools are installed before proceeding.

node --version   # Requires 22.0.0+
pnpm --version   # Requires 9.0.0+
git --version    # Requires 2.0.0+

Step 1: Install the CLI

Section titled “Step 1: Install the CLI”

Run this command in your project root.

pnpm add -D @lumenflow/cli

Step 2: Initialize LumenFlow

Section titled “Step 2: Initialize LumenFlow”

Run this command. It creates all required configuration files.

pnpm exec lumenflow

This creates:

  • .lumenflow.config.yaml — Configuration (managed)
  • LUMENFLOW.md — Workflow entry point (managed)
  • AGENTS.md — Universal AI agent entry point (user-owned, LumenFlow inserts managed section)
  • .lumenflow/constraints.md — Non-negotiable constraints (managed)
  • docs/tasks/ — Task storage (default path, or docs/04-operations/tasks/ for arc42 projects)

Step 3: Verify Scripts Were Injected

Section titled “Step 3: Verify Scripts Were Injected”

LumenFlow automatically adds scripts to your package.json during initialization. Verify they exist.

pnpm wu:create --help

If this command works, scripts are correctly installed. If not, re-run initialization.

pnpm exec lumenflow --force

Step 4: Create an Initiative (Optional)

Section titled “Step 4: Create an Initiative (Optional)”

For multi-phase projects or product visions, create an Initiative first.

pnpm initiative:create \
  --id INIT-001 \
  --slug "my-project" \
  --title "My Project" \
  --owner "team@example.com"

# Add phases after creation
pnpm initiative:edit --id INIT-001 --add-phase "Phase 1: MVP"
pnpm initiative:edit --id INIT-001 --add-phase "Phase 2: Polish"

Skip this step for single-task work or bug fixes.

Step 5: Create Your First Work Unit

Section titled “Step 5: Create Your First Work Unit”

Run this command. Replace the values with your actual task details.

pnpm wu:create \
  --title "Fix login error banner" \
  --lane "Experience: UI" \
  --type bug \
  --exposure ui \
  --description "Fix error banner overlap on small screens" \
  --acceptance "Error banner no longer overlaps the form on mobile widths" \
  --code-paths "src/components/LoginError.tsx" \
  --test-paths-unit "src/components/__tests__/LoginError.test.tsx"

The CLI prints a WU ID (example: WU-123). Use this ID in subsequent commands.

Step 6: Claim the Work Unit

Section titled “Step 6: Claim the Work Unit”

Run this command with the ID from Step 5.

pnpm wu:claim --id WU-123 --lane "Experience: UI"

This creates a worktree at worktrees/experience-ui-wu-123/.

Step 7: Enter the Worktree

Section titled “Step 7: Enter the Worktree”

Run this command immediately after claiming.

cd worktrees/experience-ui-wu-123

All work happens inside this directory.

Step 8: Implement and Commit

Section titled “Step 8: Implement and Commit”

Write your code. Write tests. Commit your changes.

# Write code and tests, then commit
git add .
git commit -m "fix: resolve error banner overlap on mobile"

Step 9: Run Gates in Worktree

Section titled “Step 9: Run Gates in Worktree”

Run this command from inside the worktree.

pnpm wu:prep --id WU-123

This runs all quality gates (format, lint, typecheck, test). It prints the next command to run.

Step 10: Complete the Work Unit

Section titled “Step 10: Complete the Work Unit”

Run this command from the main checkout (not the worktree).

cd /path/to/your/repo
pnpm wu:done --id WU-123

This merges your work to main, creates a completion stamp, and removes the worktree.

Verify Success

Section titled “Verify Success”

After wu:done completes, verify these conditions.

  • WU YAML status is done
  • Stamp file exists at .lumenflow/stamps/WU-123.done
  • Worktree directory is removed
  • Changes are on main branch

File Ownership

Section titled “File Ownership”

LumenFlow manages certain files automatically. Understand which files you own.

File/DirectoryOwnerAction
.lumenflow.config.yamlLumenFlowDo not edit manually. Use CLI commands.
LUMENFLOW.mdLumenFlowDo not edit. Regenerated on init.
AGENTS.mdYouUser-owned. LumenFlow manages section via markers.
.lumenflow/constraints.mdLumenFlowDo not edit. Contains workflow rules.
.lumenflow/stamps/LumenFlowDo not create manually. Created by wu:done.
docs/tasks/wu/*.yamlLumenFlowDo not create/edit manually. Use wu:create/wu:edit.
docs/tasks/backlog.mdLumenFlowDo not edit. Regenerated from state.
docs/tasks/status.mdLumenFlowDo not edit. Regenerated from state.
worktrees/LumenFlowDo not create manually. Created by wu:claim.
Your source codeYouEdit freely inside worktrees.
Your testsYouEdit freely inside worktrees.
package.json scriptsLumenFlowAuto-injected during init. Re-run with --force if missing.

Common Mistakes

Section titled “Common Mistakes”

Avoid these errors. The left column shows correct behavior. The right column shows mistakes.

CorrectMistake
pnpm wu:create --title "..."Manually creating WU YAML files
pnpm wu:claim --id WU-123Using git worktree add directly
cd worktrees/experience-ui-wu-123Editing files on main branch
pnpm wu:prep --id WU-123 (from worktree)Skipping gates
pnpm wu:done --id WU-123 (from main)Running wu:done from inside worktree
Use relative paths inside worktreeUsing absolute paths to main checkout
Fix hook failuresUsing --no-verify to skip hooks
pnpm wu:edit --id WU-123 --status blockedManually editing WU YAML status field
Let CLI manage backlog.mdManually editing backlog.md
Let CLI manage stampsManually creating .done stamp files

Command Reference

Section titled “Command Reference”
CommandDescription
pnpm exec lumenflowInitialize LumenFlow
pnpm wu:create --title "..." ...Create a new Work Unit
pnpm wu:claim --id WU-XXX --lane "..."Claim WU and create worktree
pnpm wu:prep --id WU-XXXRun gates in worktree
pnpm wu:done --id WU-XXXComplete WU, merge, cleanup
pnpm wu:edit --id WU-XXX --field valueEdit WU fields
pnpm gatesRun quality gates (standalone)

Run any command with --help for all options.

pnpm wu:create --help
pnpm gates --help

Next Steps

Section titled “Next Steps”