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   # 26.0.0+ (26.8.1 Current recommended)
pnpm --version   # 11.4.0+ (12.3.4 Current recommended)
git --version    # 2.0.0+

Configure an attributable identity for this clone. LumenFlow fails closed when Git would otherwise invent an author from the machine hostname.

git config --local user.name "Your Name"
git config --local user.email "you@example.com"

Repository access is enforced by your Git hosting provider and its permissions. LumenFlow does not generate a hook that pins a developer name, email domain, or GitHub account. If your project owns such a hook, remove that project policy rather than adding each developer to a LumenFlow allowlist.

Common pitfalls — avoid these as you go:

Do	Don’t
Install @hellmai/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 @hellmai/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 — Sole universal agent contract (managed)
• .lumenflow/constraints.md — Non-negotiable constraints (managed)
• docs/tasks/ — Task storage (default path, or docs/operations/tasks/ for arc42 projects)

Tool instructions stay project-owned

Init, upgrade, and docs-sync never create or change your tool-specific instruction files. Point one at LUMENFLOW.md and LUMENFLOW.local.md when your agent host needs a discovery file.

---

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 "Context: the login error overlaps the form. Problem: users cannot read it on mobile. Solution: correct the responsive layout." \
  --acceptance "Navigate to Login at a mobile width and verify the labelled error no longer overlaps the form" \
  --notes "Preserve the existing form semantics and responsive tokens" \
  --code-paths "src/components/LoginError.tsx" \
  --test-paths-unit "src/components/__tests__/LoginError.test.tsx" \
  --test-paths-manual "Navigate to Login using a keyboard at 375px width and verify focus order, label association, and non-overlapping error text"

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, run the lifecycle verifier:

pnpm wu:verify --id WU-123

It checks the canonical done state, completion stamp, integration commit, and clean checkout without requiring you to know whether this workspace has migrated its state namespace.

---

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.
Tool instruction files	You	Project-owned. Point to the LumenFlow contract if needed.
.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 --description "..."	Edit a supported WU field
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