generated from coulomb/repo-seed
docs: write INTENT.md and rewrite SCOPE.md for Event Bridge architecture
INTENT.md: articulates why activity-core exists, the governing three-question principle (when/what/where), what it is and is not, and the design values (markdown-as-definition, rules before instructions, no task state ownership, publisher-declared governance). SCOPE.md: rewritten from stale pre-alpha state to reflect WP-0001/0002 completion and the ACT-ADR-001/002/003 architecture. Adds rule/instruction model, event type registry, task emission adapter, webhook receiver, and updated current state, terminology, and architecture decision references. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
130
INTENT.md
Normal file
130
INTENT.md
Normal file
@@ -0,0 +1,130 @@
|
||||
---
|
||||
domain: capabilities
|
||||
repo: activity-core
|
||||
updated: "2026-05-14"
|
||||
---
|
||||
|
||||
# INTENT
|
||||
|
||||
> This file explains why activity-core exists — the problem it solves, the
|
||||
> principle that governs its boundaries, and what it must never become.
|
||||
|
||||
---
|
||||
|
||||
## Why it exists
|
||||
|
||||
As the Coulomb organization grows — more repositories, services, deployments,
|
||||
and domains — coordination work that used to happen informally in one person's
|
||||
head needs a structural home. Recurring maintenance tasks (dependency scans,
|
||||
SBOM audits, consistency checks) get forgotten or implemented as bespoke cron
|
||||
jobs scattered across services. Cross-domain events (a new repo registered, a
|
||||
CVE published, a deployment completed) need coordinated responses that no single
|
||||
repo is positioned to own.
|
||||
|
||||
activity-core exists so that **the Coulomb org can respond to what is happening
|
||||
in a structured, auditable, and automation-ready way** — without Bernd being
|
||||
the manual coordination layer.
|
||||
|
||||
---
|
||||
|
||||
## The governing principle
|
||||
|
||||
activity-core answers three questions and only three:
|
||||
|
||||
1. **When** — what triggers coordination work? (time, event, or one-off schedule)
|
||||
2. **What** — given current org context, what work must be created?
|
||||
3. **Where** — which repo, service, or agent should each work item land?
|
||||
|
||||
It does not execute the work. It does not track task lifecycle. It does not
|
||||
manage projects or campaigns. Those belong to other systems.
|
||||
|
||||
This constraint is intentional and load-bearing. An orchestrator that also
|
||||
stores task state, manages project phases, or executes work becomes a God object
|
||||
— the thing everything depends on and nobody can safely change. activity-core
|
||||
stays small and focused by refusing those responsibilities.
|
||||
|
||||
---
|
||||
|
||||
## What it is
|
||||
|
||||
**activity-core is the org-wide Event Bridge for the Coulomb organization.**
|
||||
|
||||
It is an event loop governed by declarative rules and LLM instructions:
|
||||
|
||||
- **Event sources**: cron schedules, one-off future datetimes, NATS domain
|
||||
events (from the state hub, Gitea, Temporal, and other publishers), and
|
||||
inbound webhooks from external systems.
|
||||
- **Context resolution**: before evaluating what to create, activity-core
|
||||
resolves current org state — repository profiles from repo-scoping, domain
|
||||
state from the state hub, and other context adapters.
|
||||
- **Rules and instructions**: deterministic rules (Python-like expression DSL,
|
||||
evaluated by a sandboxed AST walker) handle cases where the right action is
|
||||
fully specifiable. LLM instructions handle cases where human-like judgement
|
||||
is needed to decide what tasks are appropriate. Both are defined as markdown
|
||||
files, co-located with their intent and debugging guidance (see ACT-ADR-002,
|
||||
ACT-ADR-003).
|
||||
- **Task emission**: the output of every activation is a set of task creation
|
||||
requests sent to issue-core via a task emission adapter. activity-core records
|
||||
the spawn event (what was created, when, referencing the issue-core task ID)
|
||||
as an audit trail — not as the authoritative task record.
|
||||
|
||||
---
|
||||
|
||||
## What it is not
|
||||
|
||||
| Concern | Owner |
|
||||
|---|---|
|
||||
| Task lifecycle (create, assign, track, close) | issue-core |
|
||||
| Project and initiative management | project-core (future) |
|
||||
| Repository capability profiling | repo-scoping |
|
||||
| Cross-domain coordination state | state hub |
|
||||
| Execution of automatable tasks | Temporal workers (per-repo) |
|
||||
| Event broker infrastructure | NATS (org infrastructure) |
|
||||
|
||||
activity-core does not compete with the state hub — it extends it. The state
|
||||
hub is a read model of what is and has been; activity-core is the automation
|
||||
layer that reacts to that state and creates new work. The state hub delegates
|
||||
maintenance automation to activity-core by publishing lifecycle events on NATS.
|
||||
|
||||
---
|
||||
|
||||
## What it enables
|
||||
|
||||
When activity-core is in place, Bernd can:
|
||||
|
||||
- Define a rule once — "every Monday, scan all Python repos for dependency
|
||||
drift and create a task for each one" — and trust it will run without manual
|
||||
intervention.
|
||||
- Register an instruction — "when a new repo is registered in the `railiance`
|
||||
domain, determine the appropriate onboarding tasks based on its profile and
|
||||
domain standards" — and have an LLM agent make that judgement reproducibly.
|
||||
- Set up a one-off reminder — "on 2026-09-01, create a review task for the
|
||||
Q3 architecture retrospective" — without managing a separate reminder system.
|
||||
- Observe a complete audit trail of every activation: what triggered it, what
|
||||
rules matched, what tasks were created, and (for instructions) what prompt
|
||||
and model produced the output.
|
||||
|
||||
The Coulomb org gains **structured, auditable automation** that scales with the
|
||||
number of repos and domains without scaling the coordination burden on Bernd.
|
||||
|
||||
---
|
||||
|
||||
## Design values
|
||||
|
||||
**Markdown-as-definition.** Event types, ActivityDefinitions, and task templates
|
||||
are markdown files checked into repositories. Intent, schema, logic, and
|
||||
debugging notes live together. Agents and humans can read, write, and review
|
||||
them without specialist tooling.
|
||||
|
||||
**Rules before instructions.** Deterministic rules are always preferred over LLM
|
||||
instructions when the condition is fully expressible. Instructions are reserved
|
||||
for genuine judgement cases. This keeps most automation fast, cheap, testable,
|
||||
and auditable.
|
||||
|
||||
**No task state ownership.** activity-core holds a spawn audit trail, not task
|
||||
state. The moment it starts tracking whether tasks are complete, blocked, or
|
||||
re-assigned, it has become a task database — and that is issue-core's job.
|
||||
|
||||
**Publisher-declared event governance.** Producers of org events register their
|
||||
event types by committing definition files. Curator review is a configurable
|
||||
gate per environment — never a permanent bottleneck.
|
||||
Reference in New Issue
Block a user