Quickstart

This guide gets you from zero to a working LumenFlow setup in under 5 minutes.

Free (GitHub App Only)

Quick Setup (No CLI Required)

The fastest way to start using LumenFlow is with just the GitHub App.

1. Install the GitHub App

   Go to the GitHub Marketplace and click Install. Select your repository and authorize.

2. Add configuration file

   Create .lumenflow.config.yaml in your repo root:

   version: 1
   project:
     name: my-project
     tasksDir: docs/tasks
     stampsDir: .beacon/stamps
   
   lanes:
     - id: Core
       description: Core application features
     - id: Ops
       description: DevOps and infrastructure
   
   gates:
     lint: npm run lint
     typecheck: npm run typecheck
     test: npm test

3. Create the tasks directory

   Create docs/tasks/backlog.md:

   # Backlog
   
   ## Ready
   
   - [WU-001 — My first task](wu/WU-001.yaml)
   
   ## In Progress
   
   ## Done

4. Create your first Work Unit

   Create docs/tasks/wu/WU-001.yaml:

   id: WU-001
   title: My first task
   lane: Core
   type: feature
   status: ready
   priority: P2
   description: |
     A simple task to test LumenFlow.
   acceptance:
     - The feature works
   code_paths:
     - src/

5. Open a Pull Request

   Create a branch, make changes, and open a PR. The LumenFlow GitHub App will:

   • Validate your WU spec
   • Run your configured gates
   • Add status checks to the PR

Note

With the Free tier, you manage WU YAML files manually. The GitHub App handles PR validation and gate enforcement.

Pro (With CLI)

Full Setup with CLI

For the complete experience with automated workflows:

Prerequisites

• Node.js 18+ or 22+
• pnpm (recommended) or npm
• A Git repository

1. Install the CLI

   pnpm
   bash pnpm add -D @lumenflow/cli
   npm
   bash npm install -D @lumenflow/cli

2. Initialize LumenFlow

   npx lumenflow init

   This creates:

   • .lumenflow.config.yaml – Your configuration
   • docs/tasks/backlog.md – Your task board
   • docs/tasks/wu/ – Where WU specs live
   • .beacon/stamps/ – Completion proofs

3. Add scripts to package.json

   {
     "scripts": {
       "wu:create": "wu-create",
       "wu:claim": "wu-claim",
       "wu:done": "wu-done",
       "gates": "gates"
     }
   }

4. Create your first Work Unit

   npx wu-create \
     --id WU-001 \
     --title "Add user authentication" \
     --lane Core

5. Claim and start work

   npx wu-claim --id WU-001 --lane Core
   cd worktrees/core-wu-001

CLI Workflow

Once set up, your daily workflow is:

# 1. Claim a WU from the backlog
npx wu-claim --id WU-XXX --lane Core

# 2. Work in the worktree (isolated branch)
cd worktrees/core-wu-xxx
# ... make changes ...

# 3. Run gates (checks your work)
npx gates

# 4. Complete the WU (merges to main)
cd ../..
npx wu-done --id WU-XXX

Verify It’s Working

After your first PR or wu:done, you should see:

• ✅ WU status changed to done
• ✅ Stamp file created in .beacon/stamps/
• ✅ PR checks pass (if using GitHub App)
• ✅ Backlog updated

Sample Configuration

Here’s a complete .lumenflow.config.yaml for reference:

version: 1

project:
  name: my-project
  tasksDir: docs/tasks
  stampsDir: .beacon/stamps

lanes:
  - id: Core
    description: Core application features
    gates: [lint, typecheck, test]
  - id: UI
    description: Frontend components
    gates: [lint, typecheck, test]
  - id: Ops
    description: DevOps and infrastructure
    gates: [lint]

gates:
  lint: npm run lint
  typecheck: npm run typecheck
  test: npm test
  build: npm run build

defaults:
  requiresReview: true
  exposure: backend-only

Next Steps

• Install GitHub App – PR validation and team enforcement
• Work Units – Deep dive on WUs
• Gates – Understanding quality gates
• Configuration – Full config reference