Manual Quickstart (Humans)

Using an AI Agent?

Give your agent the Agent Quickstart link instead. This page is the manual, human-run walkthrough.

Prerequisites and common pitfalls

Before you start, verify your tools and read through the common pitfalls. Each step below assumes you have followed them.

Required tooling:

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

Common pitfalls — avoid these as you go:

Do	Don’t
Install @lumenflow/cli as a dev dependency	Install globally with -g
Use CLI commands to modify configuration	Hand-edit workspace.yaml or WU YAML files
Work inside the worktree created by wu:claim	Edit files on main or run git worktree add directly
Use relative paths inside the worktree	Use absolute paths that point outside the worktree
Run wu:prep from the worktree, wu:done from main	Run wu:done from inside the worktree
Fix pre-commit hook failures properly	Bypass hooks with --no-verify
Let the CLI manage backlog.md, stamps, and status	Manually edit managed files

---

Step 1: Install the CLI

Run this command in your project root.

pnpm add -D @lumenflow/cli

---

Step 2: Initialize LumenFlow

Run this command. It creates all required configuration files and injects scripts into package.json.

pnpm lumenflow

This creates:

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

AGENTS.md is user-owned

You can add your own content to AGENTS.md. LumenFlow uses bounded markers (<!-- LUMENFLOW:START --> / <!-- LUMENFLOW:END -->) to manage its section without overwriting yours. Use --merge when re-running init on existing projects.

---

Step 3: Verify Scripts Were Injected

pnpm wu:create --help

If this command works, scripts are correctly installed. If not, re-run pnpm lumenflow --force.

---

Step 4: Create an Initiative (Optional)

For multi-phase projects or product visions, create an Initiative first. Skip for single-task work or bug fixes.

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

pnpm initiative:edit --id INIT-001 --add-phase "Phase 1: MVP"
pnpm initiative:edit --id INIT-001 --add-phase "Phase 2: Polish"

---

Step 5: Create Your First Work Unit

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

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

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

---

Step 7: Enter the Worktree

cd worktrees/experience-ui-wu-123

All work happens inside this directory.

---

Step 8: Implement and Commit

Write your code. Write tests. Commit your changes.

git add .
git commit -m "fix: resolve error banner overlap on mobile"

---

Step 9: Run Gates in Worktree

From inside the worktree:

pnpm wu:prep --id WU-123

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

---

Step 10: Complete the Work Unit

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

After wu:done completes, verify:

• 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

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

File/Directory	Owner	Action
workspace.yaml	LumenFlow	Do not edit manually. Use CLI commands.
LUMENFLOW.md	LumenFlow	Do not edit. Regenerated on init.
AGENTS.md	You	User-owned. LumenFlow manages section via markers.
.lumenflow/constraints.md	LumenFlow	Do not edit. Contains workflow rules.
.lumenflow/stamps/	LumenFlow	Do not create manually. Created by wu:done.
docs/tasks/wu/*.yaml	LumenFlow	Do not create/edit manually. Use wu:create/wu:edit.
docs/tasks/backlog.md	LumenFlow	Do not edit. Regenerated from state.
docs/tasks/status.md	LumenFlow	Do not edit. Regenerated from state.
worktrees/	LumenFlow	Do not create manually. Created by wu:claim.
Your source code	You	Edit freely inside worktrees.
Your tests	You	Edit freely inside worktrees.
package.json scripts	LumenFlow	Auto-injected during init. Re-run with --force if missing.

---

Command Reference

Command	Description
pnpm lumenflow	Initialize 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-XXX	Run gates in worktree
pnpm wu:done --id WU-XXX	Complete WU, merge, cleanup
pnpm wu:edit --id WU-XXX --field value	Edit WU fields
pnpm gates	Run quality gates (standalone)

Run any command with --help for all options.

---

Next Steps

• Work Units — Understand WU lifecycle and fields
• Gates — Learn about quality gates
• Configuration — Full configuration reference