---
id: flowpilot
name: FlowPilot
manual: true
description: The autonomous AI operator at the heart of FlowWink. Soul + objectives + skills + memory + heartbeat + reflection — modeled after OpenClaw.
---

# FlowPilot

> **Status:** Flagship module — manually maintained.
> **Source of truth:** `src/lib/modules/flowpilot-module.ts` + this file.
> _The auto-generator skips this file because of `manual: true`._

FlowPilot is **the agent that runs the business**. It is not a chatbot, not a copilot, not a workflow engine. It is a continuously-running operator that perceives the platform, reasons about objectives, executes skills, and reflects on outcomes — modeled after the [OpenClaw](mem://philosophy/openclaw-law) reference architecture.

Where most "AI features" are stitched into individual buttons, FlowPilot is the **single reasoning layer** every business action flows through. Blocks, automations, slash commands, and federated peers all converge on `chat-completion`. See [Law 3](mem://philosophy/flowpilot-development-laws).

---

## The five pillars (OpenClaw model)

| Pillar | What it is | Where it lives |
|---|---|---|
| **Soul** | Personality, voice, values, refusal policies | `agent_memory` (bootstrap files) |
| **Objectives** | Ranked goals with progress + KPIs | `agent_objectives` |
| **Skills** | Self-describing capabilities (MCP-exposed) | `agent_skills` |
| **Memory** | Working + episodic + semantic | `agent_memory`, `agent_messages`, `agent_events` |
| **Heartbeat** | Autonomous loop driving continuous operation | `flowpilot-heartbeat` edge function |
| **Reflection** | Post-action critique + memory updates | `agent_reflections` |

See `mem://architecture/openclaw-workspace-prompt-architecture` for the 6-layer bootstrap.

---

## The reasoning loop

```
Trigger (event / cron / user message / slash command)
   ↓
chat-completion (the ONLY reasoning entry point)
   ↓
ReAct loop:
   1. Perceive  — load context (briefing, KB, recent events)
   2. Reason    — pick objective, score skills against intent
   3. Act       — invoke skill via agent-execute
   4. Observe   — capture result + side effects
   5. Reflect   — update memory, escalate if needed
   ↓
Response (to user, automation, peer, or silent log)
```

**Skill selection is metadata-driven.** No regex, no keyword routing, no `if (msg.includes('order'))`. The scoring algorithm reads `description`, `Use when:`, and `NOT for:` markers from `agent_skills` and ranks candidates. See [Law 1 & 2](mem://philosophy/flowpilot-development-laws).

---

## The heartbeat engine

A 7-step loop runs on cron (default: every 5 minutes when objectives are pending):

1. **Wake** — load active soul + open objectives
2. **Scan briefing** — pull `flowwink://briefing` MCP resource (sales, ops, alerts)
3. **Pick objective** — highest-priority unfulfilled goal
4. **Plan** — decompose into skill calls
5. **Execute** — through `agent-execute` (one skill per heartbeat to keep latency bounded)
6. **Reflect** — write to `agent_reflections`, update objective progress
7. **Sleep** — schedule next heartbeat or yield to event-driven triggers

Hard limit: **5-minute timeout per heartbeat** (Supabase edge constraint). Long-running work uses fire-and-forget patterns. See `mem://architecture/flowpilot-heartbeat-engine` and `mem://constraints/supabase-edge-function-timeouts`.

---

## Trust & gating

Every skill has a trust level on `agent_skills.trust_level`:

| Level | Behavior |
|---|---|
| `auto` | Executes immediately. Logged. |
| `notify` | Executes, then sends a notification card. |
| `approve` | Pauses and creates an HIL (human-in-the-loop) card. Awaits click. |
| `blocked` | Disabled. Will not appear in skill scoring. |

Trust is per-deployment policy. New customers default to `notify` for write-skills, `auto` for reads. See `mem://architecture/agent-trust-and-gating-logic`.

---

## Federation

FlowPilot is a **peer**, not a hub. It can:
- Receive tasks from external Architects (Claude, OpenClaw instances) via `delegate_task`
- Delegate tasks to peers via `proactive-peer-delegation`
- Expose its skills via MCP (`/mcp` endpoint, group-filterable)
- Call peers via A2A (bidirectional) or `/v1/responses` (outbound)

See `mem://federation/directional-connections-model`, `mem://philosophy/federated-agent-roles`, `mem://federation/single-architect-policy`.

---

## Cockpit & Engine Room

The UI splits into two surfaces:

| Surface | Audience | Path |
|---|---|---|
| **Cockpit** | Day-to-day ops — briefing, HIL cards, slash commands, conversation | `/admin/flowpilot` |
| **Engine Room** | Internals — soul, objectives, skills, memory, reflections, autonomy tests | `/admin/flowpilot/engine` |

See `mem://architecture/flowpilot-cockpit-and-engine-room-ui`.

The `/admin/developer` area owns skills inspection (skills are platform-level, not FlowPilot-only). See `mem://architecture/mcp-as-platform-not-flowpilot-feature`.

---

## Module manifest

FlowPilot is itself a module — opt-in, with a manifest like every other module. See `mem://architecture/flowpilot-unified-module-manifest` and `mem://architecture/flowpilot-opt-in-module-strategy`.

When disabled:
- The reasoning hub (`chat-completion`) still works for utilities (text transforms, workspace chat).
- Automations with `executor='flowpilot'` are skipped (or fall back to `executor='platform'` if defined).
- Skills remain registered + MCP-exposed (skills are platform). External peers can still call them.
- The Cockpit + Engine Room UI are hidden.

See `mem://architecture/automations-as-platform-layer`.

---

## Development laws (inviolable)

1. **No hardcoded intent detection.** Improve skill metadata, not routing logic.
2. **Skills are self-describing.** If FlowPilot picks the wrong skill, fix the description.
3. **Blocks are interfaces, not pipelines.** All AI flows through `chat-completion`.
4. **Fail forward, don't gate.** If credentials exist, the feature works.

See `mem://philosophy/flowpilot-development-laws` (full canonical version with examples).

---

## Extending FlowPilot

### Add a new skill
1. Create the handler — either an `edge:` function or `internal:` action in `agent-execute`.
2. Register in module's `skillSeeds` (or seed directly into `agent_skills` for cross-cutting skills).
3. Write description with explicit `Use when:` and `NOT for:` markers.
4. Run `bun run lint:skills` (Agent Contract Integrity check). See `mem://architecture/skill-linter`.
5. Set initial `trust_level` — default `notify` for writes, `auto` for reads.

### Add a new objective type
1. Insert into `agent_objectives` with KPI definition.
2. Define progress-update trigger (event-based or cron).
3. Soul bootstrap automatically references active objectives in every reasoning turn.

### Add a new bootstrap layer
The 6-layer `agent_memory` bootstrap (identity → constraints → objectives → skills index → recent events → working notes) is appended to every system prompt. To add a layer:
1. Create the resource (file, view, or computed bundle).
2. Register in soul-loader sequence.
3. Test token budget — bootstrap is the largest cost driver.

---

## Development context

- **`chat-completion` is the only reasoning entry point.** Never call OpenAI/Gemini directly from a module. See `mem://architecture/unified-ai-orchestration-and-fallback`.
- **`resolveAiConfig()` resolves provider + model + key** — supports OpenAI, Gemini, local AI, n8n. No Lovable AI in self-hosted builds (per project policy).
- **One skill per heartbeat.** Multi-step plans become multiple heartbeats with state in `agent_objectives.progress_json`.
- **Reflections are mandatory after write-skills.** Drives the feedback loop. See `mem://architecture/proactive-conversational-intelligence-ux`.
- **MCP exposure is opt-in via module activation.** A skill from a disabled module is invisible to external peers. See `mem://architecture/mcp-module-aware-filtering`.

See also: `mem://persona/autonomous-digital-operator-protocols`, `mem://philosophy/always-in-the-loop-architecture`, `mem://architecture/sensors-vs-reasoning-vision-boundary`.
