Docs: document playbooks, bindings and the intake threat model #474

Closed
opened 2026-10-27 13:36:28 +00:00 by sam · 0 comments
Owner

Separate so it is not lost when the feature lands.

  • The playbook/binding model in docs/architecture/: what a binding is, where it is persisted, how matchers resolve, how versioning works.
  • The threat model, written down plainly: this is a public intake surface that can start agents. Record what protects it and what does not.
  • ARCHITECTURE.md task lifecycle: a task started by a playbook binding has a different provenance from a forge-issue task, and the lifecycle section should say so.
  • Operator docs: how to point an external app at archie and build a first playbook, end to end.

CLAUDE.md's rule: a doc that contradicts its code is worse than none.

PROGRESS 2026-09-03: three of four items done.

  • Binding model + threat model: docs/architecture/bindings.md (commit 41dffe3), every claim verified against actual code, not assumed.
  • ARCHITECTURE.md task lifecycle: provenance addendum landed (commit edb90e1), cross-referencing bindings.md. Also fixed a second, related staleness in the same section (the Routing table no longer reflects hardcoded-only behavior post t2db.9/.10).
  • Remaining (BLOCKED, not just unstarted): the end-to-end operator walkthrough. The epic's own pitch is a no-code, DASHBOARD-based flow ('point a webhook at archie, open the dashboard, map fields, bind, save'). Verified 2026-09-03: ui/src/ has zero binding-related files -- t2db.8's UI editor does not exist yet. Writing a walkthrough describing dashboard clicks that don't exist would itself be exactly the 'doc that contradicts its code' problem this ticket exists to prevent, just prospectively. Added a formal dependency on t2db.8 rather than write a curl-based workaround doc that misrepresents the intended no-code experience -- do the walkthrough after t2db.8's UI lands, describing what actually exists.

Acceptance criteria

Operator walkthrough exists, end to end, describing the real dashboard UI (blocked on t2db.8). The other three acceptance items (binding model + threat model documented, ARCHITECTURE.md covers playbook-originated tasks) are done.

Close reason

All four items done: binding model + threat model (bindings.md, 41dffe3), ARCHITECTURE.md task-lifecycle addendum (edb90e1), operator walkthrough (this commit). Unblocked once t2db.8's UI landed.


Imported from beads archie-core-t2db.6 · GitHub #553 · type task · priority P2 · created 2026-08-21 · closed 2026-09-02

Separate so it is not lost when the feature lands. - The playbook/binding model in docs/architecture/: what a binding is, where it is persisted, how matchers resolve, how versioning works. - The threat model, written down plainly: this is a public intake surface that can start agents. Record what protects it and what does not. - ARCHITECTURE.md task lifecycle: a task started by a playbook binding has a different provenance from a forge-issue task, and the lifecycle section should say so. - Operator docs: how to point an external app at archie and build a first playbook, end to end. CLAUDE.md's rule: a doc that contradicts its code is worse than none. PROGRESS 2026-09-03: three of four items done. - Binding model + threat model: docs/architecture/bindings.md (commit 41dffe3), every claim verified against actual code, not assumed. - ARCHITECTURE.md task lifecycle: provenance addendum landed (commit edb90e1), cross-referencing bindings.md. Also fixed a second, related staleness in the same section (the Routing table no longer reflects hardcoded-only behavior post t2db.9/.10). - Remaining (BLOCKED, not just unstarted): the end-to-end operator walkthrough. The epic's own pitch is a no-code, DASHBOARD-based flow ('point a webhook at archie, open the dashboard, map fields, bind, save'). Verified 2026-09-03: ui/src/ has zero binding-related files -- t2db.8's UI editor does not exist yet. Writing a walkthrough describing dashboard clicks that don't exist would itself be exactly the 'doc that contradicts its code' problem this ticket exists to prevent, just prospectively. Added a formal dependency on t2db.8 rather than write a curl-based workaround doc that misrepresents the intended no-code experience -- do the walkthrough after t2db.8's UI lands, describing what actually exists. ### Acceptance criteria Operator walkthrough exists, end to end, describing the real dashboard UI (blocked on t2db.8). The other three acceptance items (binding model + threat model documented, ARCHITECTURE.md covers playbook-originated tasks) are done. ### Close reason All four items done: binding model + threat model (bindings.md, 41dffe3), ARCHITECTURE.md task-lifecycle addendum (edb90e1), operator walkthrough (this commit). Unblocked once t2db.8's UI landed. --- _Imported from beads `archie-core-t2db.6` · GitHub #553 · type task · priority P2 · created 2026-08-21 · closed 2026-09-02_
sam added the mediumtask labels 2026-10-27 13:36:28 +00:00
sam self-assigned this 2026-10-27 13:36:28 +00:00
sam closed this issue 2026-10-27 13:36:28 +00:00
sam added a new dependency 2026-10-27 13:42:06 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#474