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

pnpm lumenflow scaffolds universal surfaces only (AGENTS.md, LUMENFLOW.md, .lumenflow/skills, workspace.yaml). There is no per-client variant to choose — every consumer environment adapts these same universal files into its own tool via that tool’s native config/rules/instruction mechanism. See AI Coding Assistant Integrations for how to adapt them yourself.

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

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

   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 are your own

   pnpm lumenflow scaffolds universal surfaces only — it does not generate or project any vendor-specific enforcement hooks (Claude Code, Cursor, Codex, Windsurf, etc.). If you want hook-driven enforcement (worktree discipline, WU requirement, session warnings, fast-feedback checks) in your tool, wire it yourself using the copyable adapter example in AI Coding Assistant Integrations. wu:prep and wu:done enforce completion regardless of whether any hooks are configured.

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

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

   Enforcement hooks are your own

   LumenFlow does not generate or project vendor-specific enforcement hooks. If you want hook-driven enforcement or fast-feedback checks in your tool, wire it yourself using the copyable adapter example in AI Coding Assistant Integrations.

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

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.