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.

Run wu:brief immediately after wu:claim

Run wu:brief immediately after wu:claim, before any implementation. Evidence is bound to the claim, so a brief rendered before the claim exists mints no usable evidence.

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 canonical capability defaults. Client capabilities_map values are execution metadata and cannot replace canonical methodology.

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

Host-native memory and caches are advisory only. They must not become a second LumenFlow policy or replacement brief. Canonical .lumenflow/ skills and the rendered handoff always take precedence; report stale or malicious memory and leave unrelated user-owned files intact.

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.

Fast gates are the default

On supported JavaScript projects, initialization derives test_incremental from an explicit changed-test script or Vitest, Jest, Nx, or Turbo evidence. A declared tests.unit list runs first, followed by one related sweep only for changed code it did not cover. safety-critical-test and test share that execution, and an unchanged successful wu:prep checkpoint is reused by wu:done.

LumenFlow runs test_full only when scope is unsafe or missing, test configuration/untracked files make impact analysis unsafe, change detection fails, a main-snapshot comparison is required, or the operator explicitly passes --full-tests. Commands marked fresh_on_completion: true remain a separate completion check because their external state can change after prep.

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 every agent host and human contributor.

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

LUMENFLOW_WEB_WORKSPACE_ROOT is a path-safety boundary, not an authorization grant. It may be a shared host root containing sibling workspaces, but an authenticated caller can mutate only the selected workspace whose top-level workspace.yaml.id exactly matches the caller’s workspace identity. A mismatch fails before pack generation, registry access, filesystem mutation, subprocess execution, or any other body-driven side effect. Same-workspace requests continue normally.

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

pnpm --filter @hellmai/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.

Connecting Your Agent Host

The safety mechanisms above are repository-level and work regardless of the agent host. lumenflow init manages LUMENFLOW.md, canonical .lumenflow/skills/, configuration, and workflow state. It does not create, modify, delete, require, or treat a host’s instruction, skill, agent, or hook files as authoritative. Compatibility diagnostics may observe a file’s presence without reporting it as health or managed state.

Configure your project-owned host instructions to read LUMENFLOW.md and then LUMENFLOW.local.md when present. Load canonical skills from .lumenflow/skills/ through the host’s own mechanism without maintaining a second LumenFlow-authored copy. See AI Coding Assistant Integrations for the portable connection pattern.

lumenflow init

Verify: Ask your AI assistant “What are the LumenFlow safety rules?” Once its project-owned instructions point to LUMENFLOW.md, 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