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