Quickstart (Agents)

Architecture context

LumenFlow is a runtime kernel with pluggable domain packs. The CLI commands you’ll use below (like wu:create and wu:claim) are tools in the Software Delivery Pack — they route through the kernel’s execution pipeline for scope enforcement, policy evaluation, and evidence recording.

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. Ask only for client type; defer stack choices to a WU.
• ❌ Do not proceed past setup without explicit user approval

Setup ends after LumenFlow init

Do not write feature code. Implementation begins only after a Work Unit is claimed.

Running setup yourself?

Use the Manual Quickstart (Humans) if you are not an AI agent.

Setup Exit Criteria (Must be true)

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

Supported clients: claude, cursor, windsurf, codex, cline, aider, all, none

If you don’t know the user’s client, ask before running init. If their client isn’t listed, use --client none for generic files only.

Enforcement errors = setup incomplete

If lumenflow-doctor reports errors, setup is incomplete. Do not proceed to work.

If lumenflow-doctor reports errors

lumenflow init automatically scaffolds scripts/safe-git and .husky/pre-commit. If doctor still reports errors:

1. Check if Husky is installed: Run pnpm add -D husky && pnpm exec husky if missing
2. Check node_modules: Run pnpm install to ensure dependencies are set up
3. 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.

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:

1. Multi-phase vision or roadmap → Create an Initiative first, then a Discovery WU to translate it into a small backlog.
2. Clear single task → Create one concrete WU for that task.
3. Unclear or exploratory → Create a Discovery WU: “Define next steps after LumenFlow setup.”
4. 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 INIT-001 \
  --slug "project-name" \
  --title "Project Name" \
  --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: 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 ≥22)
pnpm --version	Verify toolchain (require ≥9)
git --version	Verify toolchain (require ≥2)
git init	New project only
pnpm init	Only if no package.json and user approved
pnpm add -D @lumenflow/cli	Install LumenFlow CLI
pnpm lumenflow --client <client>	Initialize LumenFlow (new repos)
pnpm lumenflow --client <client> --merge	Initialize LumenFlow (existing repos)
pnpm lumenflow:doctor	Verify enforcement (errors block)
pnpm lumenflow:doctor --deep	Optional: extended WU validation
pnpm wu:create --help	Verify scripts were injected
pnpm lumenflow:integrate --client claude-code	Regenerate enforcement hooks (auto-run by init)
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.

Private package access required

@lumenflow/cli is distributed through private package channels. Ensure your registry auth is configured before running pnpm add -D @lumenflow/cli. See Licensing & Access.

Setup: New project

1. Verify toolchain

   node --version   # Requires ≥22
   pnpm --version   # Requires ≥9
   git --version    # Requires ≥2

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

2. Initialize the repo (only if empty)

   git init

3. Ensure package.json exists

   If there is no package.json, create one. LumenFlow needs it to install the CLI and register scripts.

   pnpm init

   Non-Node projects still need a package.json

   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.

4. 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"

5. Install LumenFlow

   pnpm add -D @lumenflow/cli

6. Initialize LumenFlow

   pnpm lumenflow --client claude
   # or: pnpm lumenflow --client codex
   # or: pnpm lumenflow --client cursor
   # or: pnpm lumenflow --client windsurf
   # or: pnpm lumenflow --client cline
   # or: pnpm lumenflow --client aider
   # or: pnpm lumenflow --client none  # generic files only

   This is the canonical bootstrap-all path. It writes workspace.yaml and bootstraps Software Delivery settings under workspace.yaml > software_delivery.

   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.

   Enforcement hooks (automatic for Claude Code)

   When using --client claude, init automatically runs lumenflow-integrate and includes enforcement hooks (worktree discipline, WU requirement, session warnings) in the initial commit. No separate step is needed.

   To regenerate hooks later (e.g., after config changes):

   pnpm lumenflow:integrate --client claude-code

   Other clients will gain enforcement support in future releases.

7. Verify scripts were injected

   pnpm wu:create --help

8. Commit LumenFlow setup

   git add -A && git commit -m "chore: add lumenflow"

9. Create initiative (only if a vision doc exists)

   pnpm initiative:create \
     --id INIT-001 \
     --slug "project-name" \
     --title "Project Name" \
     --owner "team@example.com"
   
   pnpm initiative:edit --id INIT-001 --add-phase "Phase 1: Foundation"
   pnpm initiative:edit --id INIT-001 --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

10. Configure lane lifecycle

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

11. 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>"

    --spec-refs is optional; add it when a plan file exists (e.g., --spec-refs "lumenflow://plans/my-plan.md").

    If you created an initiative, add: --initiative INIT-001.

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

Setup: Existing project

1. Verify toolchain

   node --version   # Requires ≥22
   pnpm --version   # Requires ≥9
   git --version    # Requires ≥2

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

2. Install LumenFlow

   pnpm add -D @lumenflow/cli

3. Initialize with merge mode

   pnpm lumenflow --client claude --merge
   # Supported: claude, cursor, windsurf, codex, cline, aider, none

   Merge mode still uses bootstrap-all semantics and keeps workspace.yaml as canonical config.

   Enforcement hooks (automatic for Claude Code)

   With --client claude, init automatically generates enforcement hooks. To regenerate after config changes: pnpm lumenflow:integrate --client claude-code

4. Verify scripts were injected

   pnpm wu:create --help

5. Commit LumenFlow setup

   git add -A && git commit -m "chore: add lumenflow"

6. Create initiative (optional)

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

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

7. Configure lane lifecycle

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

8. 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>"

   If you created an initiative, add: --initiative INIT-001.

   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: INIT-001 "Project Name" (if created)
- Current WU: WU-0001 "Your task title" (created, not claimed)
- Repo: /path/to/repo

### Next Session Instructions

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

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

Setup stops here

Do not write feature code during setup. Wait for explicit approval before claiming a WU.

---

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	Ask only for client; defer stack choices to 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:

1. pnpm wu:create
2. pnpm wu:claim → enter worktree
3. Implement acceptance criteria
4. pnpm wu:prep
5. pnpm wu:done

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