# Spec 005: Loops and integration hooks

Status: draft revision 1 for review
Date: 2026-08-08
Depends on: [Spec 001](spec-001-core-and-live-work.md), [Spec 003](spec-003-agent-orchestration.md), and [Spec 004](spec-004-masterplan-and-context.md)

## Outcome

A useful interactive result can become a reusable Loop without creating another
runner. A Project can subscribe Telegram or a signed webhook to important events
through a small GUI, with every delivery durable and visible.

This spec owns reusable recipes and external event delivery. It does not own
agent execution, Masterplan state, or provider secrets inside a Space.

## One execution engine

A Loop is a declarative recipe that produces ordinary Commands, Executions,
Results, and Events. Interactive chat, FirstMate, scheduled Loops, and manually
triggered Loops all use the same application path.

The first Loop model contains:

```text
name and purpose
project input schema
ordered steps
agent profile, mode, objective template, and expected Result per step
budget and approval gates
trigger policy
version and owner
```

Steps are ordered. A FirstMate step may perform bounded crew fan-out under Spec
003; the Loop format does not add a second DAG engine.

Saving from Work copies explicit accepted inputs and result expectations. It
never stores the whole private transcript, terminal history, credentials, or a
mutable repository snapshot.

## Godloops

A Godloop is an ordered list of versioned Loop references plus an optional
cadence and between-Loop approval gate.

It has no nested Godloops, condition language, arbitrary code, or separate
scheduler. A run advances one Loop at a time through the same command queue.
Reordering changes future positions and never relocates active work silently.

Start with manual trigger. Add cadence only after restart, idempotency, budget,
and approval behavior pass acceptance.

## Minimal editor

The Project UI provides:

- one readable recipe summary;
- ordered step cards with profile, mode, output, budget, and approval;
- manual run and recent Results;
- save-from-result and duplicate actions;
- an ordered Godloop list;
- no node canvas or generic workflow builder.

Raw JSON may be available for diagnosis, but ordinary creation uses plain
language fields. Each edit creates a new recipe version so active and historical
runs remain reproducible.

## Integration connections and hooks

A connection is user-owned capability such as a linked Telegram account or a
webhook destination. Its owner explicitly contributes it to a Project, just as
a Space owner contributes execution capacity.

A project hook selects:

```text
connection
event families
filters such as Loop, severity, or needs-human
enabled state
delivery policy
```

Initial event choices are:

- execution blocked, failed, or completed;
- approval requested;
- Loop or Godloop completed or failed;
- Masterplan item blocked or explicitly completed.

Do not expose every internal event in the GUI.

## Telegram

Telegram first supports outbound project notifications and a test delivery.
Messages contain a short summary and safe Godloop link, never prompts, secrets,
terminal logs, patches, private plans, or collaborator email addresses.

Inbound Telegram may continue the user's current General Chat only after an
explicit account link and project selection. It uses the same message Command
and cannot bypass FirstMate capability or project membership.

Disconnecting the account disables future delivery while retaining redacted
audit receipts.

## Webhooks and outbox

Webhook requests are HTTPS, signed, versioned, bounded, and carry an event ID.
The destination must deduplicate. Godloop also uses an idempotency key so retry
cannot create a second logical delivery.

Canonical state and an outbox row commit together. A small worker in the Go
monolith delivers asynchronously with bounded retry and backoff. Delivery
status is visible as pending, delivered, retrying, or failed.

The GUI shows destination identity in redacted form, selected events, last
attempt, last success, and a test button. Secret material is write-only and
never enters events or agent context.

## Safety

- Project owners manage hooks; connection owners grant or revoke contribution.
- Test and live deliveries are distinct and attributed.
- Disabled, revoked, or unauthorized hooks cannot enqueue new deliveries.
- Loops cannot widen profile, Space, network, secret, or integration authority.
- Publish, push, merge, deploy, external posts, and budget increases keep their
  explicit approval gates.

## Acceptance

1. Finish one FirstMate result and save a two-step Loop from selected inputs.
2. Run it manually; it creates the same commands, Work chats, results, budgets,
   and approvals as interactive work.
3. Compose two versioned Loops into a Godloop and verify ordered execution across
   a server restart.
4. Link Telegram, contribute it to the Project, choose blocked/completed events,
   and send a visibly labeled test.
5. Trigger blocked and completed runs; each safe notification arrives once.
6. Configure a signed webhook, force retries, and verify one logical delivery
   with durable attempt history.
7. Revoke each connection; no new delivery occurs and history remains redacted.
8. Confirm that recipe edits do not change active or historical runs.

## Not in this spec

- a plugin marketplace, arbitrary scripts, Zapier clone, nested workflows, or
  user-authored event code;
- automatic social posting, deployments, merges, or inbound webhook commands;
- a second chat, agent, scheduler, or state engine.