Quickstart (Agents)

Read this first: Your purpose

You are here to set up LumenFlow. That is your only job in the setup phase.

✅ Initialize LumenFlow in this repo
✅ Create an Initiative if the user provided a vision doc or multi-phase plan
✅ Complete lane lifecycle and create the first Work Unit (WU)
✅ Stop and hand off
❌ Do not implement features
❌ Do not write schemas/models/components
❌ Do not refactor or optimize code
❌ Do not scaffold project templates (Next.js/Vite/etc.) during setup. If the user wants a stack, create a WU after setup.
❌ Do not ask the user to choose templates/frameworks during setup. Defer stack choices to a WU.
❌ Do not proceed past setup without explicit user approval

Setup Exit Criteria (Must be true)

LumenFlow installed and activated. CLI installed; pnpm lumenflow completed; pnpm wu:create --help works.
LumenFlow enforced. Run pnpm lumenflow:doctor; errors are blockers. Work happens only in claimed WUs; no edits on main; gates run before wu:done.
Lane lifecycle configured. Run pnpm lane:setup, pnpm lane:validate, pnpm lane:lock before first delivery WU.
Next step chosen with the user. Create one of: Discovery WU, concrete task WU, or Initiative for multi-phase vision. Stop after selection.

pnpm lumenflow scaffolds LUMENFLOW.md, LumenFlow-owned .lumenflow/skills, and workspace state. It never creates or changes tool-specific instruction files. Every consumer environment adapts the managed contract through its own project-owned configuration. See AI Coding Assistant Integrations for the migration pattern.

If `lumenflow:doctor` reports errors

lumenflow init automatically scaffolds scripts/safe-git and .husky/pre-commit. It resolves the dependency lock beside the updated manifest, publishes both together, synchronizes local main through the governed Git path, and runs an immutable package-manager install. For Yarn, Classic keeps install --ignore-scripts; Yarn 2 uses install --skip-builds and retains its link step; Yarn 3 and later use install --mode=update-lockfile, which writes the lock without linking packages or running build scripts. Init selects the generation from packageManager or lock metadata, then verifies the published manifest and lock with Yarn 2+‘s install --immutable or Classic’s existing frozen-lockfile install. If lock resolution, synchronization, or installation fails, init prints the concrete error and stops without reporting setup complete. If doctor still reports errors:

Check the pre-commit hook: pnpm lumenflow scaffolds .husky/pre-commit. If doctor reports the file missing, rerun pnpm lumenflow. If it reports the hook is not wired, run pnpm lumenflow:enable
Check node_modules: Resolve any registry or package-manager error, then run the matching immutable install (for example, pnpm install --frozen-lockfile) after the consumer manifest and lock are synchronized
Read the specific error message: Doctor explains what’s wrong and how to fix it

If errors persist after these steps, ask the user for help. Do not proceed to work until doctor passes.

If init reports that local main is dirty or divergent, preserve and reconcile those changes, run pnpm git:sync-main from the clean primary checkout, then retry pnpm lumenflow. Init never repairs or resets the caller’s changes automatically.

Lane overlap warnings: Informational only. Do not edit workspace.yaml manually during setup.

Decide the next step (with the user)

Use this ladder after setup:

Multi-phase vision or roadmap → Create an Initiative first, then a Discovery WU to translate it into a small backlog.
Clear single task → Create one concrete WU for that task.
Unclear or exploratory → Create a Discovery WU: “Define next steps after LumenFlow setup.”
Tech stack or scaffolding request → Create a WU: “Set up <stack> after LumenFlow setup.”

Stop after creating the next artifact. Do not claim a WU without explicit approval.

If the user says the project is multi-phase or shares a vision doc, create an Initiative before any WU:

pnpm initiative:create \
  --id <initiative-id> \
  --slug "project-name" \
  --title "Project Name" \
  --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: Core"

Allowed commands (setup only)

If a command is not listed here, do not run it during setup. If you are unsure about a command, run <command> --help first. Do not guess.

Command	Purpose
`node --version`	Verify toolchain (require ≥26.0.0)
`pnpm --version`	Verify toolchain (require ≥11.4.0)
`git --version`	Verify toolchain (require ≥2)
`git init`	New project only
`pnpm init`	Only if no `package.json` and user approved
`pnpm add -D @hellmai/lumenflow-cli`	Install LumenFlow CLI
`pnpm lumenflow`	Initialize LumenFlow (new repos)
`pnpm lumenflow --merge`	Initialize LumenFlow (existing repos)
`pnpm lumenflow:doctor`	Verify enforcement (errors block)
`pnpm lumenflow:doctor --deep`	Optional: extended WU validation
`pnpm lumenflow:enable`	Repair/install lifecycle enforcement if doctor reports non-enforced
`pnpm wu:create --help`	Verify scripts were injected
`pnpm initiative:create ...`	Create an initiative
`pnpm initiative:edit ...`	Add initiative phases
`pnpm lane:setup`	Create/update draft lane artifacts
`pnpm lane:validate`	Validate lane artifacts
`pnpm lane:lock`	Lock lane lifecycle for WU creation
`pnpm lane:status`	Check lane lifecycle status
`pnpm wu:create ...`	Create first WU
`pnpm wu:status --id WU-XXX`	Confirm WU status
`pnpm wu:claim --id WU-XXX --lane "..."`	Only if user explicitly says “proceed”
`git add -A && git commit -m "..."`	Commit scaffold/LumenFlow setup only

Read-only commands allowed: pwd, ls, cat, rg, git status.

If a script command is not found, rerun pnpm lumenflow:commands and use the current documented command instead of guessing older executable aliases.

Setup: New project

Verify toolchain

node --version   # Requires ≥26.0.0
pnpm --version   # Requires ≥11.4.0
git --version    # Requires ≥2

If any version is below minimum, stop and inform the user.

Initialize the repo (only if empty)
```
git init
```
Ensure package.json exists

If there is no package.json, create one. LumenFlow needs it to install the CLI and register scripts.
```
pnpm init
```
For .NET, Go, Python, etc., LumenFlow uses package.json only to install the CLI and scripts. Do not scaffold a Node stack or change the project’s framework.

Scaffold a tech stack only if the user explicitly asked

Keep this minimal. Do not add feature code.

pnpm create next-app@latest . --typescript --tailwind --eslint --app --yes
# or: pnpm create vite@latest . --template react-ts
# or: pnpm create astro@latest . --template minimal

If you scaffolded, commit the baseline:

git add -A && git commit -m "chore: initial scaffold"

Configure private registry access

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
```
--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.
Install LumenFlow
```
pnpm add -D @hellmai/lumenflow-cli
```
Initialize LumenFlow
```
pnpm lumenflow
```
This is the canonical bootstrap-all path. It writes workspace.yaml and bootstraps Software Delivery settings under workspace.yaml > software_delivery. 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).
```
software_delivery:
  gates:
    minCoverage: 90
```
Treat this as a shape reference for the generated config. Manage it through the CLI and init flow; do not hand-edit workspace.yaml during setup.

pnpm lumenflow creates only LumenFlow-owned surfaces. Tool instruction files and optional host hooks are project-owned and remain untouched. wu:prep and wu:done enforce completion regardless of whether any host hooks are configured.
Verify scripts were injected
```
pnpm wu:create --help
```
Verify and, if needed, repair lifecycle enforcement
```
pnpm lumenflow:doctor
```
If doctor reports anything other than enforced for a remediable state (non-compliant, missing, stale, or tampered), repair it and confirm:
```
pnpm lumenflow:enable
pnpm lumenflow:doctor
```
Commit LumenFlow setup
```
git add -A && git commit -m "chore: add lumenflow"
```
This setup commit goes directly to main. The scaffolded pre-commit hook allows a commit on main only while the lanes recorded in the committed workspace.yaml are unconfigured or draft, so make every setup commit before pnpm lane:lock. After lanes are locked, the hook refuses direct commits to main and all work goes through WUs.

Create initiative (only if a vision doc exists)

pnpm initiative:create \
  --id <initiative-id> \
  --slug "project-name" \
  --title "Project Name" \
  --owner "team@example.com"

pnpm initiative:edit --id <initiative-id> --add-phase "Phase 1: Foundation"
pnpm initiative:edit --id <initiative-id> --add-phase "Phase 2: Core Features"

Optional: connect the workspace to LumenFlow Cloud after bootstrap.

pnpm cloud:connect \
  --endpoint https://control-plane.example.com \
  --org-id <org-id> \
  --project-id <project-id> \
  --token-env LUMENFLOW_CONTROL_PLANE_TOKEN

Configure lane lifecycle

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

Create the first WU (do not implement)

pnpm wu:create \
  --lane "<Lane from workspace.yaml software_delivery.lanes>" \
  --title "<Short task title>" \
  --type feature \
  --exposure backend-only \
  --description "<What this task accomplishes>" \
  --acceptance "<Measurable success criterion>" \
  --notes "<Implementation context and constraints>" \
  --code-paths "<Existing source path>" \
  --test-paths-manual "<Manual verification procedure>" \
  --plan

Feature WUs require a plan or spec reference. --plan creates and links a lightweight repository plan; use --spec-refs "lumenflow://plans/my-plan.md" when one already exists.

If you created an initiative, add: --initiative <initiative-id>.

Do not claim or implement unless the user explicitly says “proceed”.

Setup: Existing project

Verify toolchain

node --version   # Requires ≥26.0.0
pnpm --version   # Requires ≥11.4.0
git --version    # Requires ≥2

If any version is below minimum, stop and inform the user.

Configure private registry access

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
```
--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.
Install LumenFlow
```
pnpm add -D @hellmai/lumenflow-cli
```
Initialize with merge mode
```
pnpm lumenflow --merge
```
Merge mode still uses bootstrap-all semantics and keeps workspace.yaml as canonical config. On an existing workspace, init fills only missing required kernel fields from maintained defaults and preserves explicit identity, namespaces, pack pins, lanes, security, policies, and pack-owned settings. It validates the result before writing; invalid explicit values are left untouched and reported. Do not use --force as a legacy migration because it can replace managed workspace content. 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).

LumenFlow does not generate tool-specific enforcement hooks. Optional host integration is project-owned; wu:prep and wu:done remain authoritative.
Verify scripts were injected
```
pnpm wu:create --help
```
Verify and, if needed, repair lifecycle enforcement
```
pnpm lumenflow:doctor
```
If doctor reports anything other than enforced for a remediable state (non-compliant, missing, stale, or tampered), repair it and confirm:
```
pnpm lumenflow:enable
pnpm lumenflow:doctor
```
Commit LumenFlow setup
```
git add -A && git commit -m "chore: add lumenflow"
```
This setup commit goes directly to main. The scaffolded pre-commit hook allows a commit on main only while the lanes recorded in the committed workspace.yaml are unconfigured or draft, so make every setup commit before pnpm lane:lock. After lanes are locked, the hook refuses direct commits to main and all work goes through WUs.

Create initiative (optional)

If the user provided a vision doc or multi-phase plan:

pnpm initiative:create \
  --id <initiative-id> \
  --slug "project-name" \
  --title "Project Name" \
  --owner "team@example.com"

Configure lane lifecycle

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

Create the first WU (do not implement)

pnpm wu:create \
  --lane "<Lane from workspace.yaml software_delivery.lanes>" \
  --title "<Short task title>" \
  --type feature \
  --exposure backend-only \
  --description "<What this task accomplishes>" \
  --acceptance "<Measurable success criterion>" \
  --notes "<Implementation context and constraints>" \
  --code-paths "<Existing source path>" \
  --test-paths-manual "<Manual verification procedure>" \
  --plan

If you created an initiative, add: --initiative <initiative-id>.

Do not claim or implement unless the user explicitly says “proceed”.

After setup is complete, do not create or modify any files (including notes or docs). The only allowed actions are creating an Initiative/WU and asking clarifying questions. Any real work must happen inside a claimed WU.

Setup handoff template

Copy this template and fill in the values:

## Setup Complete - Handoff

Note: The commands below are for the agent to run in a later session (not the user).

### Current State

- LumenFlow initialized: Yes
- Initiative: <initiative-id> "Project Name" (if created)
- Current WU: <wu-id> "Your task title" (created, not claimed)
- Repo: /path/to/repo

### Next Session Instructions

1. Read `LUMENFLOW.md` in the project root, then `LUMENFLOW.local.md` when present
2. Check status: `pnpm wu:status --id <wu-id>`
3. If user confirms, claim WU: `pnpm wu:claim --id <wu-id> --lane "..."`
4. Enter worktree: `cd worktrees/<lane>-<wu-id>`
5. Implement the WU acceptance criteria
6. Run gates: `pnpm wu:prep --id <wu-id>`
7. Complete (from main): `pnpm wu:done --id <wu-id>`

After setup is complete, do **not** create files or folders on main. If the user
shares new material (docs, specs, notes), capture it in the WU description and
save it only after the WU is claimed and the worktree is active.

### Critical Rules

- ALL implementation work happens in WUs
- NEVER edit files on main branch
- NEVER manually edit WU YAML files
- ALWAYS run `wu:done` to complete work

DO NOT list

These actions will break the workflow.

Do Not	Instead
Work on main branch	Work in a worktree after `wu:claim`
Manually create WU YAML files	Use `pnpm wu:create`
Manually edit WU YAML status	Use `pnpm wu:block`, `pnpm wu:unblock`, or `pnpm wu:release`
Use `git worktree add` directly	Use `pnpm wu:claim`
Run `wu:done` from a worktree	Run from main checkout
Use `--no-verify` to skip hooks	Fix hook failures properly
Manually edit backlog.md or status.md	Let CLI regenerate from state
Manually edit `workspace.yaml`	Use CLI commands and `lumenflow:doctor`
Run `pnpm init` by default	Only if user requested a bare Node project
Run `pnpm lumenflow:doctor`	Use `pnpm lumenflow:doctor`
Fix enforcement without approval	Ask, then apply explicit fixes if approved
Ask more than 2 setup questions	Use defaults; ask only essential questions
Ask user to choose templates/frameworks	Defer stack choices to a WU
Scaffold a tech stack during setup	Create a WU after setup, then scaffold
Create files/folders after setup	Only create files inside a claimed WU
Save user-provided docs during setup	Capture in WU, save in worktree after claim
Write feature code before a WU exists	Create a WU first
Continue after setup	Stop, hand off, and wait

After setup

All work flows through WUs and Initiatives only:

pnpm wu:create
pnpm wu:claim → enter worktree
Implement acceptance criteria
pnpm wu:prep
pnpm wu:done

If a user asks for work outside a WU, create a WU first and wait for approval.