Agent Onboarding Guide

Software Delivery Pack onboarding

This guide covers agent onboarding for the Software Delivery Pack. The commands, safety mechanisms, and WU lifecycle described here are pack-specific tools that operate through the kernel.

This guide helps AI agents get productive with LumenFlow quickly, covering common mistakes and essential safety practices.

Quick Start Checklist

Before starting any WU:

• Read the full WU spec (not just the title)
• Understand all acceptance criteria
• Claim the WU with pnpm wu:claim
• cd to the worktree IMMEDIATELY
• Work only in the worktree
• Stay within code_paths
• Follow TDD (failing test first)
• Run wu:prep before wu:done
• ALWAYS run wu:done

Fast Bootstrap (Recommended)

For a fresh setup, use one command:

pnpm onboard --yes --domain software-delivery

This flow creates workspace.yaml, installs the default pack, and pins its integrity automatically. Re-running onboard is non-destructive and updates the existing workspace flow instead of blindly overwriting.

The Most Common Mistake

Not Running wu:done

The single most common mistake agents make is completing work, then stopping without running pnpm wu:done. This leaves the WU incomplete.

Why This Happens

1. Confusion about scope - Agent thinks completion is a “next step” for humans
2. Fear of overstepping - Agent hesitates to take “final” actions
3. Token limits - Agent runs out of context and summarizes remaining steps
4. Missing context - Agent doesn’t realize wu:done should run immediately

The Fix

After wu:prep passes, you MUST run:

cd /path/to/main
pnpm wu:done --id WU-XXX

Do NOT:

• Ask “Should I run wu:done?”
• Write “To Complete: pnpm wu:done”
• Wait for permission
• Treat it as a “future step”

Correct Flow

# 1. In worktree, run gates via wu:prep
pnpm wu:prep --id WU-XXX

# 2. If wu:prep passes, return to main
cd /path/to/main

# 3. IMMEDIATELY run wu:done
pnpm wu:done --id WU-XXX

# 4. Report success with the wu:done output

Top 10 First WU Mistakes

Mistake 1: Not Using Worktrees

Wrong:

# Working directly in main
vim src/feature.ts
git commit -m "feat: add feature"
git push origin main

Right:

# Claim first, then work in worktree
pnpm wu:claim --id WU-123 --lane Core
cd worktrees/core-wu-123
vim src/feature.ts
git commit -m "feat: add feature"
git push origin lane/core/wu-123
cd /path/to/main
pnpm wu:done --id WU-123

Mistake 2: Working Outside code_paths

The WU says code_paths: [src/api/**] but you edit src/ui/component.ts.

Fix: Only edit files within the specified code_paths. If you need other files, that’s a different WU.

Mistake 3: Skipping TDD

Wrong:

1. Write the feature
2. Maybe write tests later
3. Tests are hard, skip them

Right:

1. Write failing test
2. Run test (confirm RED)
3. Write minimum code
4. Run test (confirm GREEN)
5. Refactor if needed

Mistake 4: Using Forbidden Git Commands

Wrong:

git reset --hard HEAD
git push --force
git commit --no-verify

Right:

git add .
git commit -m "feat: description"
git push origin lane/core/wu-123

Mistake 5: Scope Creep

The WU says “Add user profile endpoint” but you also:

• Refactor the database schema
• Add email notifications
• Redesign the UI

Fix: Implement exactly what the acceptance criteria specify. Create new WUs for other changes.

Mistake 6: Not Reading the WU Spec

Wrong: Start coding immediately based on the title.

Right:

1. Read the full WU YAML
2. Understand acceptance criteria
3. Review code_paths
4. Check dependencies
5. Then start

Mistake 7: Editing Main After Claim

Wrong:

pnpm wu:claim --id WU-123 --lane Core
# Still in main directory
vim src/feature.ts  # WRONG!

Right:

pnpm wu:claim --id WU-123 --lane Core
cd worktrees/core-wu-123  # IMMEDIATELY
vim src/feature.ts  # Now it's safe

Mistake 8: Ignoring Gate Failures

Wrong:

Gates failed but I think the code is fine.
Let me use --skip-gates.

Right:

Gates failed. Let me read the error:
- TypeScript error in src/api/handler.ts
- Missing return type

Fix: Add the return type.
Re-run: pnpm wu:prep --id WU-123

Mistake 9: Working After Hours Without Committing

If you need to pause:

# Commit your work
git add .
git commit -m "wip: partial progress"
git push origin lane/core/wu-123

Do NOT leave uncommitted changes in the worktree.

Mistake 10: Using Absolute Paths

Wrong:

// Using absolute paths bypasses worktree isolation
Write({
  file_path: '$HOME/project/src/feature.ts', // WRONG!
  content: '...',
});

Right:

// Relative paths respect worktree context
Write({
  file_path: 'src/feature.ts', // Correct
  content: '...',
});

Universal Safety Mechanisms

LumenFlow enforces safety at the repository level, protecting all agents (Claude, Cursor, Windsurf, etc.) and humans.

Git Safety Wrapper

Use scripts/safe-git instead of system git to block destructive operations:

# Use the safe wrapper
./scripts/safe-git status
./scripts/safe-git commit -m "feat: add feature"

# These are blocked automatically:
./scripts/safe-git worktree remove ...  # BLOCKED
./scripts/safe-git reset --hard         # BLOCKED
./scripts/safe-git clean -fd            # BLOCKED
./scripts/safe-git push --force         # BLOCKED

Repository Hooks (Husky)

These run for everyone on every commit:

Hook	What It Does
Secret scanning	Blocks commits containing AWS/GitHub/OpenAI keys
Absolute path scanning	Blocks common home-dir absolute paths (use ~ or relative paths instead)
Lockfile sync	Blocks dependency changes without lockfile update
Worktree discipline	Blocks main commits when worktrees exist

Audit Logs

All blocked actions are logged for visibility:

• .lumenflow/safety-blocks.log – Blocked safety violations
• .lumenflow/force-bypasses.log – Emergency LUMENFLOW_FORCE bypasses

Tip

These mechanisms work regardless of which AI agent or IDE you use. They’re enforced at the git/hook level, not the agent level.

Agent Safety Card

Quick reference for safe LumenFlow operation.

Stop and Ask When

Trigger	Action
Same error repeats 3 times	Stop, ask
Auth or permissions changes	Stop, ask
PII/secrets involved	Stop, ask
Cloud spend decisions	Stop, ask
Policy changes required	Stop, ask
Anything feels irreversible	Stop, ask

Never Do

Action	Why
git reset --hard	Data loss risk
git push --force	History rewrite
--no-verify	Bypasses safety
git stash (on main)	Hides work
git clean -fd	Deletes files
Work in main after claim	Breaks isolation
Skip wu:done	Incomplete WU
Use absolute paths	Bypasses worktree

Always Do

Action	Why
Read WU spec first	Understand scope
cd to worktree after claim	Isolation
Write tests before code	TDD
Run wu:prep before wu:done	Quality
Run wu:done	Complete WU
Stay within code_paths	Scope discipline
Use relative paths	Respect worktree
Verify pwd before file ops	Avoid path trap

Error Handling

Max 3 Attempts Rule:

If the same error happens 3 times:

1. Stop trying
2. Document what happened
3. Ask for help

Gate Failures:

1. Read the error message
2. Fix the underlying issue
3. Re-run wu:prep
4. Never use --skip-gates for new failures

Quick Commands

# Check lane availability
cat docs/04-operations/tasks/status.md

# Claim a WU
pnpm wu:claim --id WU-XXX --lane <Lane>

# Work in worktree
cd worktrees/<lane>-wu-xxx

# Run gates in worktree
pnpm wu:prep --id WU-XXX          # Code changes
pnpm wu:prep --id WU-XXX --docs-only  # Docs changes

# Complete WU
cd /path/to/main
pnpm wu:done --id WU-XXX

When Uncertain

Choose the safer path:

• Don’t modify files outside code_paths
• Don’t bypass hooks
• Don’t skip gates
• Ask rather than assume

Completion Checklist

Before ending any session, verify:

• Did I run pnpm wu:prep --id WU-XXX in the worktree?
• Did wu:prep pass?
• Did I cd back to main?
• Did I run pnpm wu:done --id WU-XXX?
• Did wu:done complete successfully?

If any answer is “no”, you’re not done yet.

Symptoms of Incomplete WU

If wu:done wasn’t run, you’ll see:

• Worktree still exists: ls worktrees/
• No stamp: ls .lumenflow/stamps/WU-XXX.done returns nothing
• Status unchanged: WU still shows as in_progress
• Branch not merged: Changes only on lane branch

Recovery

If a previous session forgot to run wu:done:

# 1. Check worktree exists
ls worktrees/

# 2. If it does, run wu:done
pnpm wu:done --id WU-XXX

# 3. If worktree was deleted but branch exists
# This is a bad state - may need manual recovery
pnpm wu:recover --id WU-XXX

What wu:done Does

When you run pnpm wu:done --id WU-XXX (after a successful wu:prep):

1. Validates the worktree exists and has commits
2. Fast-forward merges to main
3. Creates the done stamp
4. Updates status and backlog docs
5. Removes the worktree
6. Pushes to origin

This is the ONLY way to complete a WU. Manual steps leave things inconsistent.

Emergency Override (LUMENFLOW_FORCE)

Caution

Emergency override bypasses safety mechanisms. AI agents MUST get explicit user approval before using LUMENFLOW_FORCE. All bypasses are logged to .lumenflow/force-bypasses.log.

When Override is Appropriate

• Fixing YAML parsing bugs in WU specs
• Emergency production hotfixes (with user present)
• Recovering from corrupted workflow state
• Bootstrap operations when CLI not yet built

When NOT to Use Override

• Skipping failing tests
• Avoiding code review
• Working around gate failures
• Convenience or speed

How to Use

1. Get user approval - Stop and ask before using LUMENFLOW_FORCE
2. Execute with audit trail - Use LUMENFLOW_FORCE_REASON and LUMENFLOW_FORCE=1 (see example below)
3. Document - Add a note to WU YAML explaining the bypass

LUMENFLOW_FORCE_REASON="user-approved: <reason>" LUMENFLOW_FORCE=1 git <command>

Examples

# Bypass safe-git for reset --hard
LUMENFLOW_FORCE_REASON="user-approved: recovering corrupted state" LUMENFLOW_FORCE=1 git reset --hard HEAD

# Bypass hook for commit with false positive
LUMENFLOW_FORCE_REASON="user-approved: false positive secret detection" LUMENFLOW_FORCE=1 git commit -m "fix: update config"

Audit Log Format

All bypasses are logged:

ISO_TIMESTAMP|BYPASSED|COMMAND_OR_HOOK|USER|BRANCH|REASON|CWD

Note

If LUMENFLOW_FORCE is used without LUMENFLOW_FORCE_REASON, “NO_REASON” is logged and a warning is printed. The command still proceeds.

Setup and Verification

Web Runtime Setup (Dashboard + AG-UI)

To enable management actions and AG-UI run streaming in the web app, configure runtime access in apps/web/.env.local:

LUMENFLOW_WEB_ENABLE_KERNEL_RUNTIME=1
LUMENFLOW_WEB_WORKSPACE_ROOT=/absolute/path/to/your/workspace

Then run the web app and verify the runtime is available:

pnpm --filter @lumenflow/web dev

Runtime routes to know:

• POST /api/ag-ui/v1/run streams RunAgent SSE output
• GET /api/health reports runtime/workspace availability

If runtime is not configured, preview mode returns actionable diagnostics with the exact env vars above.

Claude Code

Claude Code automatically respects LumenFlow safety through:

• CLAUDE.md - Entry point referencing safety rules
• .claude/skills/ - Skills include safety context
• .claude/agents/ - Agent definitions include constraints

No additional setup required.

Cursor

Cursor uses .cursor/rules/lumenflow.md for safety rules.

# Initialize with Cursor overlay
lumenflow init --client cursor

Verify: Ask Cursor AI “What are the LumenFlow safety rules?” - it should mention worktree discipline, forbidden git commands, and LUMENFLOW_FORCE.

Windsurf

Windsurf uses .windsurf/rules/lumenflow.md for safety rules.

# Initialize with Windsurf overlay
lumenflow init --client windsurf

Verify: Ask in Cascade “What safety mechanisms does this project use?” - it should mention safe-git wrapper, Husky hooks, and audit logs.

Manual Verification

Test that safety mechanisms work:

# Verify safe-git blocks dangerous commands
./scripts/safe-git reset --hard HEAD
# Should show: === LUMENFLOW SAFETY BLOCK ===

# Verify hooks are installed
ls -la .husky/

# Verify bypass works with audit
LUMENFLOW_FORCE_REASON="testing" LUMENFLOW_FORCE=1 ./scripts/safe-git --version
# Should succeed and log to .lumenflow/force-bypasses.log

Next Steps

• AI Agent Integration - Full agent capabilities
• Constraints - The 6 non-negotiable rules
• Troubleshooting - Common issue fixes
• Memory Layer - Context recovery