Connect an AI Coding Assistant

One managed agent contract

LUMENFLOW.md is the only agent-instruction document LumenFlow installs or upgrades. If LUMENFLOW.local.md exists, agents read it immediately afterwards for project-specific additions.

LumenFlow does not support or maintain tool-specific instruction formats. Agent products change their filenames and rule systems independently, so duplicating the workflow for each one would create multiple drifting authorities.

What LumenFlow owns

Surface	Behavior
LUMENFLOW.md	Sole universal contract; refreshed on install and upgrade
LUMENFLOW.local.md	Optional project additions; never overwritten
.lumenflow/skills/**	Canonical, host-neutral skills
.lumenflow/constraints.md, .lumenflow/rules/**	Managed policy details
workspace.yaml, CLI, briefs, memory, evidence	Public workflow interfaces

Every instruction, rule, skill mirror, hook, or configuration file shaped for a particular agent tool is project-owned. LumenFlow never creates, merges, updates, validates, or deletes it.

Connect your agent

1. Install and initialize LumenFlow:

   pnpm add -D @hellmai/lumenflow-cli
   pnpm lumenflow

2. In the project instruction structure supported by your chosen agent, add a short pointer:

   Read LUMENFLOW.md in full before working.
   If LUMENFLOW.local.md exists, read it afterwards.
   Load required skills from .lumenflow/skills/ through the host's available mechanism.

3. Keep project-specific LumenFlow additions in LUMENFLOW.local.md, not in the managed file.

4. Verify setup:

   pnpm lumenflow:doctor

The pointer file belongs to your repository and chosen tool. Consult that tool’s current documentation for its discovery filename and syntax; LumenFlow does not publish a compatibility matrix.

Skills

Canonical skills live at .lumenflow/skills/<name>/SKILL.md. Load that file directly when your host allows it. If the host requires another location, the repository may own a wrapper, link, or copied snapshot:

• a wrapper should read the canonical skill at use time;
• a link is a repository portability choice;
• a copied skill is not synchronized by LumenFlow and must be maintained by the repository.

Canonical skills avoid host-specific paths and invocation syntax so this transposition remains mechanical.

Older projects

Historical releases may have generated tool-specific files. Current install, upgrade, docs-sync, force, merge, disable, and uninstall paths leave those files byte-for-byte unchanged. Replace duplicated LumenFlow guidance with the short pointer above, keep genuine project configuration, or remove obsolete files through normal version control.

The historical tool-selection flags are rejected with migration guidance. lumenflow:integrate is an inert deprecation command and creates no files.

Hooks and optional integrations

Optional editor callbacks, event hooks, and fast-feedback wiring are owned by the repository and the selected host. LumenFlow does not maintain a portable hook adapter. Regardless of optional host integration, wu:prep and wu:done remain the completion authority.

Repository-owned lifecycle delegators protect the integrity manifest, receipts, journals, hooks, and managed CI block; only an enforced lumenflow:doctor state 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.

See AI Agent Integration for the runtime workflow and Custom Skills for the canonical skill format.