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+ (root engines minimum)
pnpm --version   # 11.4.0+ (doctor minimum; the repo pins pnpm 12.3.4 in packageManager)
git --version    # 2.22.0+ (doctor minimum)

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: Configure Private Registry Access

Windows with nvm for Windows 2.0

Run nvm config set mode=link once, before any command below. In its default shim mode, nvm-windows launches npm, npx and pnpm through cmd /d /c; when the install path contains a space (the default AppData\Local\Author Software) and an argument also contains a space, cmd splits the path and the command fails with 'C:\Users\...\AppData\Local\Author' is not recognized (nvm-windows issue #1408). Link mode avoids the shim and this failure entirely.

@hellmai/lumenflow-cli is distributed through the private licence registry.

In the project folder, add the non-secret routing line to the project’s .npmrc (safe to commit):

@hellmai:registry=<registry-url>

Windows (PowerShell):

Add-Content -Path .npmrc -Value '@hellmai:registry=<registry-url>'

Also, with pnpm 10.26 or newer, allow the CLI’s native SQLite dependency to build by merging this into the project’s root pnpm-workspace.yaml (keep existing settings):

allowBuilds:
  better-sqlite3: true

Windows (PowerShell):

Add-Content -Path pnpm-workspace.yaml -Value "`nallowBuilds:`n  better-sqlite3: true"

If pnpm-workspace.yaml already has an allowBuilds key, add the better-sqlite3: true line under that existing key instead of appending a second allowBuilds block.

On pnpm 10.0-10.25, add better-sqlite3 to the existing onlyBuiltDependencies list instead of introducing allowBuilds. Do not configure both forms.

In your home folder, sign in once at the user level — never from inside this or any pnpm project. Inside a pnpm project, npm stops with EBADDEVENGINES. The owner gives you a one-line credential to run:

cd ~
npm config set //<registry-host>/:_authToken <token-from-owner> --location=user

Windows (PowerShell):

Set-Location ~
npm config set //<registry-host>/:_authToken <token-from-owner> --location=user

Never --location=global, never overwrite the whole file

--location=user merges one line into your personal ~/.npmrc. Never use --location=global for this credential, and never hand-write or overwrite ~/.npmrc wholesale — either destroys any token already in that file.

Still from your home folder, verify the credential can read real package metadata:

npm view @hellmai/lumenflow-cli@latest version --registry <registry-url>

Windows (PowerShell):

npm view @hellmai/lumenflow-cli@latest version --registry <registry-url>

This prints a version number. A 401/403 means the credential is missing or wrong — fix it before continuing.

Then return to the project folder before the next step:

cd -

Windows (PowerShell):

Set-Location -Path <path-to-your-project>

See Installing and upgrading with a LumenFlow licence for the full authentication options, including the licence-key (username/_password) form.

---

Step 2: Install the CLI

Run this command in your project root.

pnpm add -D @hellmai/lumenflow-cli

---

Step 3: 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)

The first governed command on a machine also prompts you to accept the LumenFlow licence terms (type accept, or set LUMENFLOW_EULA_ACCEPTED=1 on a non-interactive host).

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 4: Verify Scripts Were Injected

pnpm wu:create --help

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

---

Step 5: Verify and, if Needed, Repair Lifecycle Enforcement

pnpm lumenflow:doctor

lumenflow:doctor classifies enforcement evidence as enforced, non-compliant-disabled, missing, stale, or tampered. If it reports anything other than enforced for a remediable state, repair it and confirm:

pnpm lumenflow:enable
pnpm lumenflow:doctor

lumenflow:enable commits workspace.yaml and the enforcement files only; it never writes LUMENFLOW.md (Step 3 does). A repository enabled without it can still claim WUs: each claim pins the fact that LUMENFLOW.md is not committed, so committing it later counts as a policy change, and any active claim then asks for the governed policy refresh. See Scoped integration targets.

On Windows, Git for Windows defaults to core.autocrlf=true. The managed .gitattributes block that lumenflow writes keeps LumenFlow’s hooks and state files LF on every checkout. If lumenflow:doctor shows a Line Endings warning, the block predates those rules: run pnpm lumenflow:upgrade to add them.

---

Step 6: 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 <initiative-id> \
  --slug "my-project" \
  --title "My Project" \
  --owner "team@example.com"

pnpm initiative:edit --id <initiative-id> --add-phase "Phase 1: MVP"
pnpm initiative:edit --id <initiative-id> --add-phase "Phase 2: Polish"

---

Step 7: Configure Lane Lifecycle

Run before creating the first delivery WU:

pnpm lane:setup
pnpm lane:validate
pnpm lane:lock

---

Step 8: 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-id>). Use this ID in subsequent commands.

---

Step 9: Claim the Work Unit

pnpm wu:claim --id <wu-id> --lane "Experience: UI"

This creates a worktree at worktrees/experience-ui-<wu-id>/.

---

Step 10: Enter the Worktree

cd worktrees/experience-ui-<wu-id>

All work happens inside this directory.

---

Step 11: Implement and Commit

Write your code. Write tests. Commit your changes.

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

---

Step 12: Run Gates in Worktree

From inside the worktree:

pnpm wu:prep --id <wu-id>

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

---

Step 13: Complete the Work Unit

From the main checkout (not the worktree):

cd /path/to/your/repo
pnpm wu:done --id <wu-id>

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-id>

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/state/packs/software-delivery/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