AI Coding Assistant Integrations

WU-3543: reframed around the Universal Contract

LumenFlow retired vendor-specific scaffolding from the product. lumenflow init no longer accepts --client/--vendor and scaffolds only universal surfaces; lumenflow:integrate is a deprecation no-op. This page is reframed around the Universal Contract — one public contract every AI tool adapts on its own — instead of a per-vendor feature table.

Works with Any AI

LumenFlow is friction-free for any AI coding assistant. If your AI can read project files, it can use LumenFlow.

Universal Entry Points

Every project includes plain markdown files that work with ANY AI: - AGENTS.md — Universal agent instructions - LUMENFLOW.md — Workflow fundamentals - .lumenflow/constraints.md — Non-negotiable rules - .lumenflow/skills/ — Canonical skill catalog

No Vendor Lock-in

Point any AI at these files and it understands the workflow. No special setup, no proprietary formats, no per-vendor feature gap.

lumenflow init

There is no --client/--vendor flag any more — lumenflow init always scaffolds exactly these universal surfaces, for every project, regardless of which AI tool you use.

---

The Neutrality Guarantee

Every consumer of LumenFlow — including LumenFlow’s own first-party desktop app — reads this same public contract. There is no private field, no app-only side-channel, and no vendor-specific capability you are missing out on by adapting the contract yourself instead of waiting for a vendor integration LumenFlow will not ship. Enhanced first-party experiences are built by layering the control plane (@lumenflow/control-plane-sdk, hosted telemetry, hosted A2A transport) on top of the exact same public surfaces documented here — never by reading something a third-party integration cannot also read.

---

Adapting the Contract Yourself

LumenFlow does not generate, own, or maintain any vendor-specific projection (.claude/, .codex/, .cursor/, .windsurf/, .clinerules, .aider.conf.yml, or equivalents). If your repo has one of these from an older LumenFlow version, it is a snapshot — your file now, never touched by LumenFlow again. Three integration depths, in increasing order:

1. Read the universal files directly. Any tool that reads a repo-root instruction file (most agentic CLIs and IDEs do) needs nothing further — point it at AGENTS.md and LUMENFLOW.md.

2. Fold them into your tool’s native mechanism. If your tool expects its own file (a .cursorrules, a CLAUDE.md, a system-prompt include), concatenate or symlink the universal files into it. That file is yours to maintain; LumenFlow will never write to or overwrite it.

3. Wire a hook layer, if your tool supports one, for enforcement or fast feedback. See the copyable example below.

A copyable enforcement-hook example

This is the shape of the hook LumenFlow itself used to generate for Claude Code (WU-1367, retired as a product feature in WU-3543 — the pattern below is now something you own and adapt):

// Example hook-registration format (Claude Code's shape shown — adapt the
// wiring syntax to your own tool; the underlying script logic is portable)
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "./hooks/validate-worktree-path.sh" }],
      },
    ],
  },
}

#!/bin/bash
# Illustrative sketch of the hook script's decision logic.
set -euo pipefail

# 1. Parse the file path your hook mechanism handed you.
FILE_PATH="$(read_file_path_from_hook_payload)"

# 2. Read LumenFlow's own claim state — do not maintain a second source of truth.
if [[ -f ".lumenflow/state/wu-events.jsonl" ]] && grep -q '"claimed_mode":"branch-pr"' .lumenflow/state/wu-events.jsonl; then
  exit 0  # branch-pr mode is exempt
fi

# 3. Graceful degradation: if LumenFlow state can't be determined, allow.
if [[ ! -d ".lumenflow" ]]; then
  exit 0
fi

# 4. Your enforcement decision here (block outside worktree, require a
#    claimed WU, etc.).
exit 0

A legacy agents.clients.<id>.enforcement block in workspace.yaml still parses without error (the schema tolerates it with a deprecation warning) — reuse those same flag names in your own adapter if you want the config surface to stay familiar, or drop the block once you’ve migrated.

---

Semantic Model Routing

Generated agent overlays can be routed through a vendor-neutral model contract:

model_profile: fast | balanced | deep
reasoning_effort: low | medium | high | xhigh

Shared agent definitions express intent with those semantic fields. If you maintain your own vendor-specific overlay, translate model_profile/reasoning_effort into your tool’s native routing fields (e.g. a model + effort pair, or a model_reasoning_effort field) yourself.

Profiles are translations

model_profile is intentionally leaky. A Claude model family, an OpenAI-style reasoning effort knob, and a future client route are not identical capabilities. Treat profiles as routing intent.

Workspace owners can set a per-client profile map in workspace.yaml as a reference for their own adapter to read:

software_delivery:
  agents:
    clients:
      claude-code:
        routing:
          model_profiles:
            fast: haiku
            balanced: inherit
            deep: opus

---

Quick Setup

1. Any AI (universal)

   lumenflow init

   Creates AGENTS.md, LUMENFLOW.md, .lumenflow/, and agent onboarding docs (including CLI command reference) — works with any AI that can read files. Use --minimal to skip onboarding docs.

2. Adapt it to your tool

   Read the Universal Contract section above and fold the universal files into your tool’s native instruction/rules/hook mechanism. There is no --client flag — every project gets the same universal scaffold.

---

Using Another AI?

Tip

If your AI coding assistant isn’t listed anywhere on this page, LumenFlow still works perfectly:

1. Run lumenflow init to create universal entry points
2. Tell your AI to read AGENTS.md and LUMENFLOW.md
3. The workflow commands (wu:claim, wu:prep, wu:done) work the same

---

Adding New Integrations

Want to add support for another AI assistant? There is no registry to update — adapt the contract into your tool following the three integration depths above, then contribute the pattern back:

1. Write up your adapter (hook script, rules-file mapping, or both) as a short guide.
2. Test it against a real project: lumenflow init followed by your own adapter setup.
3. Open a PR adding your guide alongside this page.