generated from coulomb/repo-seed
tegwick
91a9073448
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>
225 lines
9.9 KiB
Markdown
225 lines
9.9 KiB
Markdown
---
|
|
domain: capabilities
|
|
repo: activity-core
|
|
updated: "2026-05-14"
|
|
---
|
|
|
|
# SCOPE
|
|
|
|
> This file helps you quickly understand what this repository is about,
|
|
> when it is relevant, and when it is not.
|
|
|
|
---
|
|
|
|
## One-liner
|
|
|
|
activity-core is the org-wide Event Bridge for the Coulomb organization — a
|
|
rule-governed event loop that receives time-based and domain events, evaluates
|
|
declarative rules and LLM instructions against current org context, and emits
|
|
structured task sets to issue-core.
|
|
|
|
---
|
|
|
|
## Core Idea
|
|
|
|
An `ActivityDefinition` (a markdown file checked into a repo) declares a trigger
|
|
(cron, one-off scheduled datetime, or named event type), context sources to
|
|
resolve before evaluation, and a set of rules and instructions that determine
|
|
what tasks to create. When triggered, a durable Temporal workflow loads the
|
|
definition, resolves context, evaluates the rule/instruction set, and emits task
|
|
creation requests to issue-core. Everything is auditable: the spawn log records
|
|
the triggering event, matched rule, and resulting task references.
|
|
|
|
The two evaluation modes:
|
|
- **Rule** — deterministic condition (sandboxed Python-like DSL) → fixed task
|
|
templates. Fast, testable, no LLM cost.
|
|
- **Instruction** — optional pre-filter condition → LLM prompt with trusted
|
|
fields only → structured task list. For cases where the right tasks depend
|
|
on context that is easier to describe than to enumerate.
|
|
|
|
---
|
|
|
|
## In Scope
|
|
|
|
- **ActivityDefinition model**: trigger config (cron / scheduled / event),
|
|
context sources, rules (condition + action), instructions (trusted-field
|
|
prompt + model + output schema).
|
|
- **Event type registry**: publisher-declared markdown definitions with
|
|
attribute schemas, example payloads, and intent documentation.
|
|
Curator-gating configurable per runtime environment.
|
|
- **Trigger types**: 5-field cron with timezone and misfire policy; one-off
|
|
scheduled datetime; event-type subscription via NATS.
|
|
- **Context resolution adapters**: repo-scoping (repository capability queries),
|
|
state hub (domain and workstream state), extensible for other sources.
|
|
- **Rule evaluator**: sandboxed AST walker for Python-like boolean expressions
|
|
over event attributes and resolved context. No `exec()`.
|
|
- **Instruction executor**: trusted-field prompt rendering, LLM call via
|
|
llm-connect, structured output validation, optional curator review queue.
|
|
- **Task emission adapter**: abstraction over issue-core; current transport is
|
|
REST; designed to migrate to NATS subscription without code changes.
|
|
- **Spawn audit log**: every task emission recorded with rule/instruction id,
|
|
triggering event id, model and prompt hash (instructions), issue-core task ref.
|
|
- **Webhook receiver**: HTTP endpoint normalising inbound Gitea/GitHub webhook
|
|
payloads to EventEnvelope format and publishing to NATS.
|
|
- **Worker and workflow infrastructure**: Temporal-based durable execution —
|
|
`RunActivityWorkflow` orchestrates load → resolve → evaluate → emit.
|
|
- **REST admin API** (FastAPI): CRUD for ActivityDefinitions, manual trigger,
|
|
event type registry queries.
|
|
- **Prometheus metrics**: Temporal SDK metrics exposed for scraping.
|
|
- **Operational runbook**: `docs/runbook.md`.
|
|
|
|
---
|
|
|
|
## Out of Scope
|
|
|
|
- **Task lifecycle** — creating, assigning, tracking, and closing tasks is
|
|
issue-core's responsibility. activity-core holds a spawn audit trail only.
|
|
- **Project and initiative management** — phased, completion-gated, multi-step
|
|
coordinated changes belong to project-core (future).
|
|
- **Execution of automatable tasks** — Temporal Activities that do real work
|
|
(run a scan, apply a patch, call an API) live in per-repo workers, not here.
|
|
- **Event broker hosting** — NATS JetStream is org infrastructure; activity-core
|
|
consumes it but does not own its lifecycle.
|
|
- **Temporal server hosting** — activity-core uses the Temporal SDK; the server
|
|
runs on Railiance infrastructure (or Docker Compose for dev).
|
|
- **End-user task UI** — tasks land in issue-core; presentation is separate.
|
|
- **Synchronous request-response patterns** — Temporal is async-first.
|
|
|
|
---
|
|
|
|
## Relevant When
|
|
|
|
- You need org-wide recurring maintenance automation (dependency scans, SBOM
|
|
checks, staleness audits) without bespoke per-service cron jobs.
|
|
- You need reactive task generation: "when X happens across the org, create
|
|
structured tasks in the right repos."
|
|
- You need one-off future task scheduling without a separate reminder system.
|
|
- You want an auditable record of what triggered what and why.
|
|
- You are replacing scattered bespoke cron jobs and manual coordination with
|
|
a governed, observable automation layer.
|
|
|
|
---
|
|
|
|
## Not Relevant When
|
|
|
|
- You need to track whether a task is done, blocked, or reassigned → issue-core.
|
|
- You need to coordinate a multi-phase project with dependencies → project-core.
|
|
- You need a simple system cron with no durability requirement.
|
|
- You need synchronous request-response patterns.
|
|
|
|
---
|
|
|
|
## Current State
|
|
|
|
- **Status**: active — WP-0001 (Foundation) and WP-0002 (Triggers & Ops) complete.
|
|
- **Implementation**: core is functional. `RunActivityWorkflow`, `TaskExecutorWorkflow`
|
|
(stub), PostgreSQL schema (activity_definitions, activity_runs, task_instances),
|
|
Temporal Schedules (cron), NATS Event Router, FastAPI admin API, Prometheus
|
|
metrics, and operational runbook are all implemented.
|
|
- **Next**: WP-0003 — event type registry, rule/instruction model, task emission
|
|
adapter, webhook receiver, one-off `scheduled` trigger type, INTENT.md and
|
|
SCOPE.md rewrite (this file). Architecture established in ACT-ADR-001/002/003.
|
|
- **Stability**: core workflow is stable; the rule/instruction layer and registry
|
|
are not yet implemented.
|
|
|
|
---
|
|
|
|
## How It Fits
|
|
|
|
```
|
|
[NATS JetStream] ← publishers: state hub, Gitea webhooks, Temporal signals, cron
|
|
↓
|
|
[activity-core] ← event type registry, rule evaluator, instruction executor
|
|
↓
|
|
[issue-core] ← task lifecycle, assignment, tracking (Gitea / SQLite / GitHub)
|
|
↓
|
|
[repos/services] ← execution: actual code changes, scans, operations
|
|
```
|
|
|
|
- **Upstream**: NATS (event bus), Temporal (durable workflow engine), PostgreSQL
|
|
(definitions and audit log), repo-scoping (context adapter), state hub (context
|
|
adapter and event publisher).
|
|
- **Downstream**: issue-core (task management). Agents and humans pick up tasks
|
|
from issue-core and do the actual work.
|
|
- **Coordinates with**: the state hub delegates maintenance automations to
|
|
activity-core by publishing lifecycle events; activity-core never writes to
|
|
the state hub directly.
|
|
|
|
---
|
|
|
|
## Terminology
|
|
|
|
- **ActivityDefinition** — a markdown file declaring trigger, context sources,
|
|
rules, and instructions. The unit of automation policy.
|
|
- **EventEnvelope** — the canonical internal event format; normalises all inbound
|
|
events (NATS, webhooks, cron signals) to a common structure.
|
|
- **Rule** — deterministic condition expression + task template action. Evaluated
|
|
by a sandboxed AST walker.
|
|
- **Instruction** — LLM-evaluated task generation with trusted-field prompt
|
|
interpolation and structured output schema enforcement.
|
|
- **Event type** — a registered, schema-documented category of event (e.g.
|
|
`org.repo.registered`). Publisher-declared; curator-gated per environment.
|
|
- **Spawn audit trail** — activity-core's local record of what tasks were emitted,
|
|
to which issue-core backend, and under which rule/instruction. Not the
|
|
authoritative task record.
|
|
- Potentially confusing: **Activity** (Temporal concept — a single executable
|
|
step in a workflow) vs. **ActivityDefinition** (app concept — the policy record
|
|
that governs what gets spawned). These are different things.
|
|
|
|
---
|
|
|
|
## Related / Overlapping
|
|
|
|
- `issue-core` (formerly issue-facade) — downstream task management; receives
|
|
all task emission from activity-core.
|
|
- `repo-scoping` — context adapter for repository capability queries.
|
|
- `the-custodian` / state hub — context adapter for domain state; delegates
|
|
maintenance automation to activity-core via NATS events.
|
|
- `rules-core` (future extraction) — the rule evaluator and instruction executor
|
|
module, currently in `src/activity_core/rules/`.
|
|
- `project-core` (future) — project and initiative management; will use
|
|
activity-core to generate per-phase task sets.
|
|
- `ops-bridge` — SSH tunnel to remote Temporal server on Railiance.
|
|
|
|
---
|
|
|
|
## Architecture Decisions
|
|
|
|
- `docs/adr/adr-001-event-bridge-architecture.md` — overall Event Bridge pattern,
|
|
boundaries, state hub relationship, domain assignment.
|
|
- `docs/adr/adr-002-definition-format.md` — markdown-as-definition format,
|
|
governance model, event type schema, ActivityDefinition structure.
|
|
- `docs/adr/adr-003-rule-instruction-model.md` — Rule DSL, Instruction safety
|
|
model, evaluation semantics, audit trail, testing strategy.
|
|
|
|
---
|
|
|
|
## Getting Oriented
|
|
|
|
- Start with: `INTENT.md` (why), this file (what), `docs/adr/` (decisions).
|
|
- Key source files: `src/activity_core/models.py` (domain model),
|
|
`src/activity_core/workflows.py` (RunActivityWorkflow),
|
|
`src/activity_core/activities.py` (Temporal activities),
|
|
`src/activity_core/event_router.py` (NATS → Temporal),
|
|
`src/activity_core/schedule_manager.py` (Temporal Schedules),
|
|
`src/activity_core/api.py` (FastAPI admin).
|
|
- Definition files (WP-0003): `event-types/` and `activity-definitions/`
|
|
(not yet created — coming in WP-0003).
|
|
- Dev environment: `docker-compose.dev.yml` (Temporal + PostgreSQL + NATS).
|
|
- Entry points: `uv run python -m activity_core.worker` (Temporal worker),
|
|
`uv run uvicorn activity_core.api:app --port 8010` (admin API).
|
|
|
|
---
|
|
|
|
## Provided Capabilities
|
|
|
|
```capability
|
|
type: data
|
|
title: Durable event-triggered task factory
|
|
description: >
|
|
Org-wide Event Bridge that receives time-based and domain events, evaluates
|
|
declarative rules and LLM instructions against current org context, and emits
|
|
structured task sets to issue-core with a full spawn audit trail.
|
|
keywords: [temporal, workflow, event-bridge, task, cron, event, rule, instruction, org-automation]
|
|
```
|