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
• [ ] Run pnpm wu:brief --id WU-XXX --client <client> (required — canonical handoff source of truth + evidence)
• [ ] Read the ## Memory Context block in your wu:brief output before coding
• [ ] Work only in the worktree
• [ ] Stay within code_paths
• [ ] Follow TDD (failing test first)
• [ ] Triage memory discoveries before wu:done
• [ ] Run wu:prep before wu:done
• [ ] ALWAYS run wu:done

Before You Code: Read the Auto-Loaded Memory Context

Previous agents on this WU may have already captured bugs, architecture decisions, and coordination signals. After wu:claim, wu:brief is the singular canonical handoff source of truth. It auto-embeds those records into the generated prompt under a ## Memory Context section — read it before writing code, or you will rewrite work that is already done.

The section includes:

• WU-scoped memory nodes (discoveries, decisions, notes left by prior sessions on this WU)
• Coordination signals broadcast by parallel agents since wu:claim (24h window if no claim event found)

If the section surfaces something non-obvious, act on it before coding. If it’s empty, carry on — but capture your own discoveries during the WU with mem:create.

For ad-hoc lookups mid-WU (rarely needed; the brief is normally sufficient):

pnpm mem:context --wu WU-XXX    # WU-scoped discoveries, signals, known-issues
pnpm mem:inbox                   # unread coordination signals

See Memory Layer concepts for the full workflow cadence and the shared-vs-vendor-personal classification rule.

Eval-Gated Skill Hints

wu:brief always includes baseline skill guidance such as lifecycle, worktree, and TDD/bug/context hints. It can also include a ### Generated Skill Hints section derived from the work classifier and the active client’s capabilities_map.

Generated hints are measured before they are injected. The section token tells you how to treat them:

• LUMENFLOW_SKILL_HINTS_INJECTED means the configured mapping met the precision/recall threshold and the listed skills are usable recommendations.
• LUMENFLOW_SKILL_HINTS_REPORT_ONLY means candidates were measured but not injected because quality was below threshold or report_only is enabled. Do not load skills from candidate names in this mode.
• LUMENFLOW_SKILL_HINTS_DISABLED means generated hints are disabled for the client.

Configure this per client:

agents:
  clients:
    codex-cli:
      capabilities_map:
        ui-design-awareness: frontend-design
        component-reuse-check: library-first
        documentation-structure: docs-structure
        link-validation: docs-link-check
        infrastructure-review: ops-maintenance
        security-check: security-audit
        cross-domain-awareness: multi-agent-coordination
      features:
        skill_hints:
          enabled: true
          threshold: 0.9
          report_only: false

Skill-hint evaluation results are rendered directly into the generated prompt body (the ### Generated Skill Hints section) — they are not currently persisted to any NDJSON telemetry file.

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
pnpm wu:brief --id WU-123 --client <client>
vim src/feature.ts
git commit -m "feat: add feature"
git push origin lane/core/wu-123
pnpm wu:prep --id 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 ignore the result and continue.

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

If the failing gate is migration verification:

• Read the message to find the configured project command, for example pnpm db:preflight
• Apply or verify pending migrations using the project’s documented process
• Re-run pnpm wu:prep --id WU-123
• Do not bypass the gate unless the WU owner has explicitly documented a valid exception

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 skip a gate for failures introduced by the current WU

Quick Commands

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

# Claim a WU
pnpm wu:claim --id WU-XXX --lane <Lane>
# Work in worktree
cd worktrees/<lane>-wu-xxx
pnpm wu:brief --id WU-XXX --client <client>

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

Adapting Safety Rules to Your AI Client

The safety mechanisms above (git wrapper, Husky hooks, LUMENFLOW_FORCE audit trail) are enforced at the repository level and work identically regardless of which AI client you use. lumenflow init no longer scaffolds any client-specific overlay (CLAUDE.md, .claude/skills/, .claude/agents/, .cursor/rules/lumenflow.md, .windsurf/rules/lumenflow.md, or similar) — that projection was retired in WU-3543. Folding AGENTS.md/LUMENFLOW.md into your tool’s own instruction mechanism is now a repo-owner task; see AI Coding Assistant Integrations for the integration depths and a copyable enforcement-hook example.

lumenflow init

Verify: Ask your AI assistant “What are the LumenFlow safety rules?” - once you’ve adapted the universal files into your client’s own mechanism, it should mention worktree discipline, forbidden git commands, and LUMENFLOW_FORCE.

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