Files
archie/docs/guides/first-playbook.md
T
sam e95a77c2f7 docs: delete ARCHITECTURE.md, move its normative content into docs/architecture
ARCHITECTURE.md duplicated the docs/architecture tree and had drifted badly
against it: "internal/ holds ~36" against 112 packages, two of the seven
binaries listed, a Forge table listing `RepliesAfter` (deleted from the tree),
and a stated invariant ("No daemon-internal cron") contradicted by the
scheduling engine that internal/app/archied/scheduling.go composes and
main.go starts.

It was also the sole home of three pieces of still-authoritative content, so
those move rather than disappear:

- plugin engine rule (strict), the memory engine family, and the
  internal/plugin/architecture_test.go enforcement note ->
  docs/architecture/plugins-and-extensions.md
- intake provenance: forge poll/webhook dedup through
  TaskEnvelope.IdempotencyKey, binding-stamped chat/playbook enqueue, and the
  single-identity webhook-intake rejection ->
  docs/architecture/messaging-and-work-intake.md

Live references are repointed from CLAUDE.md (AGENTS.md is a symlink to it),
docs/architecture, docs/guides, seven PRDs, and four .agents skills. The
heading "## Plugin engine rule (strict)" is preserved in its new home so the
existing #plugin-engine-rule-strict citations keep resolving. Generated docs
artifacts regenerated.
2026-09-22 23:49:53 +10:00

4.3 KiB

Building your first playbook binding

This walks through the whole no-code path the event-capture epic promises: point an external app's webhook at archie, see the real payload it sends, map the fields you care about, bind them to a workflow, and watch the next matching event turn into a task -- no code, no redeploy, no restart. See docs/architecture/bindings.md for the model and threat model behind each step below.

1. Send a test event

Point whatever external app you want archie to react to at:

POST http://<your-archied-host>:8484/webhooks/capture/<source>

<source> is a name you choose for this sender (e.g. sentry, github-ci, stripe) -- it's just a URL path segment, not a preset list. Send one real event however is easiest for a first test, e.g.:

curl -X POST http://localhost:8484/webhooks/capture/sentry \
  -H "Content-Type: application/json" \
  -d '{"issue": {"title": "NullPointerException in checkout"}, "level": "error"}'

This event isn't signed yet, so it's captured but marked unauthenticated -- visible for you to design against, but incapable of triggering anything (docs/architecture/bindings.md's threat-model section explains why: an unauthenticated event can never match a binding, no matter how it looks).

2. Inspect the captured payload

Open the dashboard's Event inspector (/captures). Your test event appears there with its real body -- this is schema-by-example: you're looking at an actual payload from the actual sender, not guessing at a schema in advance.

3. Map the fields you care about

Open Field mappings (/mappings) → New mapping. Pick your captured event from the dropdown, then click through its payload tree on the right -- every key and value is clickable. Clicking a value binds it as a field (name, JSON path, and an inferred type you can change). Add whichever fields your workflow needs (e.g. the issue title), mark the ones that must be present as Required, hit Preview to confirm they resolve correctly against the real payload, then Save.

4. Create the binding

Open Playbook bindings (/bindings) → New binding:

  • Name -- anything descriptive.
  • Source -- the same <source> segment from step 1 (e.g. sentry).
  • Field mapping -- the one you just saved.
  • Workflow -- which registered workflow should run on a match.
  • Repo pin (optional) -- leave both blank to use the single configured repo; set owner/repo explicitly if you run a multi-repo deployment.
  • Shared secret -- a real secret (16+ bytes), never test1234. The sender signs every request body with this via HMAC-SHA256 so archie can tell a genuine event from anyone who finds the URL.

Save. The binding starts in draft -- nothing fires yet.

5. Approve it

A draft or freshly-edited binding needs an explicit human approval before it can ever match a live event -- this is deliberate, not a missing step: an operator authoring a binding is a considered act, an event arriving is not, and nothing should self-arm (docs/architecture/bindings.md's threat-model section, point 2). Click Approve. Status becomes armed.

6. Fire it for real

Send the same kind of event again, this time signed with the binding's secret:

BODY='{"issue": {"title": "NullPointerException in checkout"}, "level": "error"}'
SECRET="the-secret-you-set-in-step-4"
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

curl -X POST http://localhost:8484/webhooks/capture/sentry \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256=$SIG" \
  -d "$BODY"

This event is captured as authenticated, matched against your armed binding, and dispatched into a new task through the exact same gate/worktree/sandbox pipeline every other task goes through -- see docs/architecture/messaging-and-work-intake.md's "Intake provenance". Check the Tasks page; a new task should appear, its body built from the fields your mapping resolved.

Editing a live binding

Any edit to an armed binding -- even a typo fix -- drops it back to pending_approval automatically. This can't be bypassed by editing; it has to be re-approved. When editing, leave the Shared secret field blank to keep the existing secret; only fill it in if you're deliberately rotating it.