Solo Developer Workflow

LumenFlow uses the same lifecycle for one developer and for a team. Solo work still gets an isolated worktree, explicit evidence, and a clean completion transaction; you do not need a second, weaker workflow to move quickly.

Agent ready

A WU preserves enough context for a human or agent to resume.

Safe by default

Worktrees and gates keep unfinished work off main.

Easy to scale

The same commands continue to work when collaborators arrive.

Install and initialize

1. Verify Node.js 26.0.0 or newer, pnpm 11.4.0 or newer, and Git 2 or newer.

   node --version
   pnpm --version
   git --version

2. Configure an attributable identity for this clone.

   git config --local user.name "Your Name"
   git config --local user.email "you@example.com"

3. Install and initialize LumenFlow locally.

   pnpm add -D @hellmai/lumenflow-cli@latest
   pnpm lumenflow --minimal
   pnpm lumenflow:doctor

4. Configure and lock the lane lifecycle once.

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

Git identity is not repository authorization

LumenFlow requires a non-empty Git name and email so commits and lifecycle evidence are attributable. Repository access is enforced by your Git hosting provider and its permissions. Do not add a shared hook that pins one person, email domain, or GitHub account. If a repository already has such a project-owned hook, remove that policy or replace it with project-specific guidance outside LumenFlow.

Daily lifecycle

Create a fully specified WU, then work only in the generated worktree:

pnpm wu:create \
  --title "Add dark mode" \
  --lane "Experience: UI" \
  --type feature \
  --exposure ui \
  --description "Add a persisted dark-mode preference to settings" \
  --acceptance "Navigate to Settings, toggle dark mode, and retain it after reload" \
  --notes "Use the existing theme tokens and settings route" \
  --code-paths "src/components/ThemeToggle.tsx" \
  --test-paths-unit "src/components/__tests__/ThemeToggle.test.tsx" \
  --test-paths-manual "Navigate to Settings with a keyboard and verify the labelled toggle and persisted theme" \
  --plan

# Use the generated ID printed by wu:create.
pnpm wu:claim --id WU-123 --lane "Experience: UI"
pnpm wu:brief --id WU-123
cd worktrees/experience-ui-wu-123

# Implement and commit in the worktree.
pnpm wu:prep --id WU-123

# Copy the exact main-checkout command printed by wu:prep.
cd /path/to/main
pnpm wu:done --id WU-123
pnpm wu:verify --id WU-123

wu:prep is not optional for a claimed WU. Do not hand-create WU YAML, stamps, worktrees, or status entries; the lifecycle commands own those surfaces.

Smaller tasks

Documentation work still records why the change exists:

pnpm wu:create \
  --title "Correct the install example" \
  --lane "Content: Documentation" \
  --type documentation \
  --exposure documentation \
  --description "Replace an obsolete install command in the README" \
  --acceptance "The README uses the local CLI bootstrap command" \
  --notes "Documentation-only correction; verify the rendered code block"

A bug WU includes automated and manual evidence:

pnpm wu:create \
  --title "Handle an empty auth session" \
  --lane "Framework: Core" \
  --type bug \
  --exposure backend-only \
  --description "Prevent the auth adapter from throwing when no session exists" \
  --acceptance "An empty session returns an anonymous result" \
  --notes "Preserve the existing authenticated-session contract" \
  --code-paths "src/auth/session.ts" \
  --test-paths-unit "src/auth/__tests__/session.test.ts" \
  --test-paths-manual "Run the auth smoke request without a session cookie and verify an anonymous response"

Configuration without hand edits

Use dedicated commands for managed configuration:

# Add a lane.
pnpm lane:create \
  --name "Framework: Core" \
  --wip-limit 1 \
  --add-path "src/**"

# Select a gate preset or adjust a supported pack setting.
pnpm config:set --key software_delivery.gates.execution.preset --value node
pnpm config:set --key software_delivery.gates.minCoverage --value 90

Run pnpm config:set --help and Workspace Spec before changing configuration. Kernel lanes and software_delivery.lanes.definitions are distinct schema surfaces; the lane commands keep them synchronized.

Handoffs and context recovery

# Save progress before a long break.
pnpm mem:checkpoint --wu WU-123

# Rebuild the current handoff context later.
pnpm wu:brief --id WU-123

# Inspect lifecycle truth.
pnpm wu:status --id WU-123

Keep WUs cohesive. Complexity selects single-session, checkpoint-resume, or an orchestrated strategy; it does not automatically require splitting one outcome into several WUs.

Next steps

• Manual Quickstart — first installation and WU
• Work Units — the authoring contract
• Lanes — scope and concurrency
• Configuration — generated Software Delivery settings