AI Agent Integration

LumenFlow treats AI agents as workflow participants without making lifecycle authority depend on a provider, model, editor, or extension system.

Start with LUMENFLOW.md

Every agent reads LUMENFLOW.md in full, then LUMENFLOW.local.md when present. LUMENFLOW.md is the sole managed agent contract; any tool discovery file is a project-owned pointer.

Lifecycle authority

WU IDs, lane locks, sessions and leases, lane branches, worktree paths, done stamps, gates, and audit records determine recovery, cleanup, orchestration, and completion. Tool and model names are metadata only.

Repository-owned pre-commit, pre-push, and CI delegators protect the lifecycle manifest, receipts, journals, hooks, and managed CI block. lumenflow:doctor reports their compliance state and only enforced is certifying. Lifecycle front doors independently reject no-verify, raw-git, forged/replayed-receipt, and synthetic-brief bypasses.

A hostile unsandboxed process with the same OS-user authority can replace local code, hooks, or receipts. Preventing that requires an OS sandbox or protected remote/server authority. Disabled and uninstalled consumers cannot claim lifecycle certification.

Agent workflow

1. Discover the live CLI and read command help:

   pnpm lumenflow:commands
   pnpm wu:claim --help

2. Claim the WU and enter its governed worktree:

   pnpm wu:claim --id WU-123 --lane "Framework: Core"
   cd worktrees/framework-core-wu-123

3. Record the universal brief evidence and load required canonical skills:

   pnpm wu:brief --id WU-123 --client <client-identity>

4. Implement and capture discoveries in shared memory:

   pnpm mem:create --type discovery --wu WU-123 --tags architecture --title '<finding>'
   pnpm mem:checkpoint --wu WU-123 --note '<progress>' --next-steps '<next>'

5. Verify in the worktree and complete from main:

   pnpm wu:prep --id WU-123
   cd <project-root> && pnpm wu:done --id WU-123

--client records caller identity for evidence. It does not choose a different prompt format or instruction policy.

Shared memory and signals

Use .lumenflow/memory/ and mem:* for facts another agent would need:

• discoveries and known issues;
• architecture decisions;
• cross-WU scope or coordination state;
• checkpoints and handoff context.

Personal preferences and host invocation mechanics stay outside shared memory. Agents read directed signals at session start and before checkpoints, prep, or handoff. A host may provide its own notification mechanism; otherwise mem:inbox is the portable polling path.

Host-native memory and caches are advisory context only. They must not define LumenFlow policy or write replacement briefs; canonical .lumenflow/ files and the rendered wu:brief handoff outrank conflicting host memory. Report stale or malicious memory without deleting unrelated user-owned files.

Canonical skills

Skills live only under .lumenflow/skills/ as self-contained SKILL.md files. Load a relevant skill before the work it governs. Common examples include:

Skill	Use
wu-lifecycle	Claim, brief, prep, and completion flow
worktree-discipline	Safe file operations in claimed worktrees
design-first	Requirement and design validation
tdd-workflow	Runtime behavior changes under TDD policy
lumenflow-gates	Gate failure diagnosis
orchestration	Multi-WU initiative execution
security-review	Security review methodology

Canonical skills contain no required host-specific path or invocation syntax. If a host needs a transposed copy, use a project-owned discovery adapter that points to the canonical file and carries its content digest. It is not an independent methodology source and is not synchronized by LumenFlow.

Programmatic access

The CLI works in every environment that can run subprocesses. The optional MCP server exposes the same workflow capabilities over Model Context Protocol; it does not introduce a second lifecycle or agent policy.

Tool discovery and optional hooks

See Connect an AI Coding Assistant for the project-owned pointer pattern. LumenFlow deliberately does not maintain per-tool filenames, rules, plugins, hook formats, or capability matrices.

Optional host hooks are advisory repository infrastructure. They never replace the governed wu:prep and wu:done gates.