INTENT — issue-core

Why it exists

The Coulomb org needs a single, observable place where tasks land — regardless of whether they were created by a human typing a CLI command, by an automation like activity-core acting on a rule, or by an agent acting on instructions.

Without a single landing zone, task creation fragments across:

Per-repo Gitea issue trackers (siloed, no cross-repo view)
Ad hoc files and TODO comments (invisible, unaudited)
Agent-local memory and notebooks (lost when the agent ends)
External SaaS trackers (rate-limited, off-network)

issue-core gives every actor — human or machine — one stable, observable place to file work, and one stable surface to consume work from.

What it is

A task lifecycle manager with a pluggable-backend architecture.

Responsibilities:

Ingestion: accept new tasks via CLI, REST (POST /issues/), and — in the future — NATS subscriptions.
Storage: route each task to the configured backend (Gitea, SQLite, GitHub).
Lifecycle: create → assign → update → close, with state transitions that hold regardless of backend.
Querying: list, search, filter across the active backend.
Synchronization: bidirectional sync between local SQLite (source of truth for offline work) and remote backends.

Backends today: local SQLite, Gitea. Planned: GitHub, GitLab, JIRA.

The CLI entry points are issue (primary) and issue-core (explicit alias).

What it is NOT

issue-core is intentionally narrow. The following live elsewhere:

Not a project manager. Phases, campaigns, milestones spanning multiple tasks, dependency graphs across tasks, gantt-style scheduling — that is the domain of project-core (planned). issue-core deals in individual tasks, not in plans composed of tasks.
Not a spawn audit trail. When activity-core fires a rule that creates a task, the spawn event (who fired, what rule, what triggering event) is recorded in activity-core's task_spawn_log. issue-core only stores the resulting task and its triggering_event_id reference back. The audit-of-creation belongs to the emitter.
Not an event bus. Communication between services flows over NATS (and state-hub progress events). issue-core consumes events, but does not relay them.
Not a notification system. Surfacing "your task changed" to humans is the job of the relevant UI / digest / chatbot layer, not issue-core.
Not a workflow engine. State transitions are simple (open → closed, with a few in-between states). Conditional routing, approvals, multi-step workflows — out of scope.

How it fits

                  +-------------------+
                  |  activity-core    |
                  |  IssueSink (REST) |
                  +---------+---------+
                            |
                  POST /issues/  (TaskSpec payload)
                            |
                            v
+------------+      +-------+--------+      +-----------------+
|  Humans    +----->|                |<-----+ Agents          |
|  CLI:      |      |   issue-core   |      | (CLI or REST)   |
|  $ issue   |      |                |      |                 |
+------------+      +-------+--------+      +-----------------+
                            |
                  +---------+----------+
                  |  Backend router    |
                  +---+------+------+--+
                      |      |      |
                      v      v      v
                 +------+ +-----+ +------+
                 |Gitea | |SQLite| |GitHub|
                 +------+ +-----+ +------+

Upstream of issue-core (emitters):

activity-core — emits tasks via IssueSink when a rule fires or an instruction declares one. Payload: TaskSpec over POST /issues/.
Humans — $ issue create ... from terminals; future web UI.
Agents — same REST surface or CLI.

Downstream of issue-core (consumers):

Humans and agents assigned tasks consume them via $ issue list, web UI, or per-backend native UIs (Gitea web, GitHub PR view, etc.).
state-hub receives progress events as tasks move through their lifecycle.
Status updates flow back to issue-core, not to the original emitter — activity-core does not track what happened to the task it spawned.

Success looks like

Every task in the Coulomb org is discoverable from one query surface.
activity-core can fire a rule and have the resulting task land in the right backend with the right metadata, with no human in the loop.
The CLI experience is identical across SQLite-only laptops and full Gitea- backed servers.
Offline work syncs back cleanly when connectivity returns.

5 KiB Raw Blame History