docs: align issue-core with work-record connector role (ISSUE-WP-0004)
Retarget INTENT, SCOPE, README, ROADMAP, and agent docs from "task landing zone" to external-tracker connector per work-record canon and architecture draft §4.2. Add UUID↔external-id mapping design; mark ISSUE-WP-0004 finished and cross-file activity-core ACTIVITY-WP-0022 for IssueSink policy.
This commit is contained in:
parent
5e556028ab
commit
d60175c354
9 changed files with 760 additions and 226 deletions
153
README.md
153
README.md
|
|
@ -1,20 +1,30 @@
|
|||
# Issue Core - Agent Coordination via Issue Tracking
|
||||
# Issue Core — External Tracker Connector
|
||||
|
||||
**A unified interface for autonomous coding agents to coordinate project implementation through issue tracking systems.**
|
||||
**A backend-agnostic connector to third-party issue trackers (Gitea/Forgejo, GitHub, …), not the fleet's internal work-origin or coordination substrate.**
|
||||
|
||||
## Purpose
|
||||
|
||||
The **Issue Core** provides a standardized abstraction layer for coding agents to interact with issue tracking backends (Gitea, GitHub, GitLab, local SQLite). Instead of each agent implementing platform-specific API integrations, they use one consistent interface that works across all backends.
|
||||
**issue-core** is a standardized abstraction layer for talking to external issue-tracking backends (Gitea, GitHub, GitLab, local SQLite cache). Instead of each agent or automation implementing platform-specific APIs, they use one consistent CLI and Python interface — and, going forward, a durable **work-record UUID ↔ external issue id** mapping when a tracker projection is switched on.
|
||||
|
||||
### Why Issue Tracking for Agent Coordination?
|
||||
### Fleet coordination vs external trackers
|
||||
|
||||
Issue tracking provides natural coordination primitives for multi-agent software development:
|
||||
Internal fleet work is **not** originated here. Work records (workplans, tasks, intake, decisions, …) live as **repo files** (ADR-001) and are indexed by state-hub under the work-record types canon — see `the-custodian/canon/standards/work-record-types_v0.1.md` and `the-custodian/research/WorkOrchestrationArchitectureDraft.md` §4.2.
|
||||
|
||||
- **Task Distribution**: Issues represent discrete work units agents can claim and execute
|
||||
- **Progress Tracking**: States (open → in_progress → closed) track work across the team
|
||||
- **Communication**: Comments enable agent-to-agent and agent-to-human communication
|
||||
- **Visibility**: Labels, assignees, and milestones provide real-time project status
|
||||
- **Human Integration**: Humans can seamlessly participate in agent-driven development
|
||||
issue-core's role (founder-reviewed, 2026-07-20):
|
||||
|
||||
- **Connector** to external issue-tracking systems when collaboration requires them
|
||||
- **Mapping** between internal work-record UUIDs and external issue ids (design: `docs/uuid-external-id-mapping.md`)
|
||||
- **Two-way boundary sync** when a third-party tracker is actually in use
|
||||
- **Zero load** on the internal loop until an external integration is switched on
|
||||
|
||||
External trackers remain useful for:
|
||||
|
||||
- **Human / open-source collaboration** on GitHub, Forgejo, Jira, etc.
|
||||
- **Communication** via comments when the counterparty lives in that UI
|
||||
- **Visibility** for people who only watch the tracker, not the fleet hub
|
||||
- **Optional projection** of a work record outward (not birth of the work record)
|
||||
|
||||
For agent coordination *inside* the Coulomb fleet, use work records + state-hub, not Forgejo as the default task board. See `INTENT.md` and `SCOPE.md`.
|
||||
|
||||
## Current Status
|
||||
|
||||
|
|
@ -45,10 +55,13 @@ pip install -e . # CLI only
|
|||
pip install -e ".[api]" # CLI + REST ingestion server
|
||||
```
|
||||
|
||||
### REST Ingestion Server
|
||||
### REST Server (intentional external issues)
|
||||
|
||||
issue-core exposes `POST /issues/` for upstream emitters (primarily
|
||||
activity-core's `IssueSink`). Launch with:
|
||||
issue-core exposes `POST /issues/` for **authenticated clients that deliberately
|
||||
create external tracker issues**. This is not the primary fleet path for
|
||||
originating work (work records start as repo files). activity-core's
|
||||
`IssueSink` may call this only when an external issue is intentional policy —
|
||||
not as an always-on landing zone for internal findings.
|
||||
|
||||
```bash
|
||||
export ISSUE_CORE_API_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
|
||||
|
|
@ -109,14 +122,16 @@ issue close 42 --comment="Ready for review"
|
|||
|
||||
## Agent Integration
|
||||
|
||||
**For autonomous coding agents**, see **[AGENT_INTEGRATION.md](AGENT_INTEGRATION.md)** for:
|
||||
**Prefer work records + state-hub for fleet task lifecycle.** Use issue-core when
|
||||
an agent must operate on an **external tracker** (project a task, update a
|
||||
Forgejo/GitHub issue, sync comments at the boundary).
|
||||
|
||||
See **[AGENT_INTEGRATION.md](AGENT_INTEGRATION.md)** for:
|
||||
|
||||
- Programmatic Python API usage
|
||||
- Multi-agent coordination patterns
|
||||
- Agent workflow examples
|
||||
- Label-based role assignment
|
||||
- State machine workflows
|
||||
- Comment-based communication protocols
|
||||
- Multi-agent patterns **against tracker backends** (not as the fleet board)
|
||||
- Label-based filters and state machine workflows on external issues
|
||||
- Comment-based communication when the counterparty is in the tracker UI
|
||||
- Workarounds for current limitations
|
||||
- Performance optimization tips
|
||||
|
||||
|
|
@ -192,42 +207,31 @@ for issue in issues:
|
|||
|
||||
## Use Cases
|
||||
|
||||
### 1. Multi-Agent Project Implementation
|
||||
### 1. External tracker ops (when a backend is in use)
|
||||
|
||||
Multiple specialized agents coordinate via issues:
|
||||
Agents or humans work issues that already live in Gitea/GitHub (e.g. OSS
|
||||
inbound, customer Jira, or an intentional projection):
|
||||
|
||||
```bash
|
||||
# Agent 1 (Coder): Claims and implements features
|
||||
issue list --label=needs-implementation --format=json | \
|
||||
jq -r '.[0].number' | \
|
||||
xargs -I {} issue edit {} --assignee=agent-coder --state=in_progress
|
||||
# List open external issues for a label
|
||||
issue list --label=needs-implementation --format=json
|
||||
|
||||
# Agent 2 (Reviewer): Reviews completed work
|
||||
issue list --label=needs-review --format=json | \
|
||||
jq -r '.[0].number' | \
|
||||
xargs -I {} issue comment {} "Code review: Approved"
|
||||
|
||||
# Agent 3 (Tester): Runs tests
|
||||
issue list --label=reviewed --format=json | \
|
||||
jq -r '.[0].number' | \
|
||||
xargs -I {} issue comment {} "Tests passing: 100%"
|
||||
# Claim and update state on the tracker
|
||||
issue edit 42 --assignee=agent-coder --state=in_progress
|
||||
issue comment 42 "Implementation complete, tests passing"
|
||||
issue close 42 --comment="Ready for review"
|
||||
```
|
||||
|
||||
### 2. Agent-Human Collaboration
|
||||
Fleet-internal task claim/execute should use workplan task status in the repo
|
||||
+ state-hub, not Forgejo by default.
|
||||
|
||||
Agents propose implementations, humans approve:
|
||||
### 2. Human collaboration through a tracker UI
|
||||
|
||||
```python
|
||||
# Agent creates subtasks from human requirements
|
||||
feature = backend.get_issue_by_number(100)
|
||||
for subtask in agent.break_down_feature(feature):
|
||||
backend.create_issue(subtask)
|
||||
When the counterparty only uses GitHub/Gitea, project or update the external
|
||||
issue and keep comments there. Mapping design (UUID ↔ external id) will tie
|
||||
that projection back to the work record — see `docs/uuid-external-id-mapping.md`.
|
||||
|
||||
# Human reviews and approves via comments
|
||||
# Agent monitors and proceeds with implementation
|
||||
```
|
||||
|
||||
### 3. Offline Development with Sync
|
||||
### 3. Offline development with sync
|
||||
|
||||
Work offline with local backend, sync when online:
|
||||
|
||||
|
|
@ -238,7 +242,7 @@ issue sync pull gitea-production backup
|
|||
|
||||
# Work offline
|
||||
issue backend set-default backup
|
||||
issue create "Offline implementation" --label=offline
|
||||
issue create "Offline tracker note" --label=offline
|
||||
|
||||
# Sync back
|
||||
issue sync push backup gitea-production
|
||||
|
|
@ -329,40 +333,35 @@ issue-core/
|
|||
|
||||
## Documentation
|
||||
|
||||
- **[AGENT_INTEGRATION.md](AGENT_INTEGRATION.md)** - Comprehensive guide for autonomous agents
|
||||
- Programmatic API usage
|
||||
- Multi-agent coordination patterns
|
||||
- Workflow examples and strategies
|
||||
- Performance optimization
|
||||
- Current workarounds
|
||||
- **[INTENT.md](INTENT.md)** — why issue-core exists (connector, not landing zone)
|
||||
- **[SCOPE.md](SCOPE.md)** — in/out of scope and integration boundaries
|
||||
- **[docs/uuid-external-id-mapping.md](docs/uuid-external-id-mapping.md)** — mapping design (not implemented yet)
|
||||
- **[AGENT_INTEGRATION.md](AGENT_INTEGRATION.md)** — programmatic API for tracker backends
|
||||
- **[ROADMAP.md](ROADMAP.md)** — feature trajectory (connector-aligned)
|
||||
- Work-record canon: `the-custodian/canon/standards/work-record-types_v0.1.md`
|
||||
- Architecture §4.2: `the-custodian/research/WorkOrchestrationArchitectureDraft.md`
|
||||
|
||||
- **[CLAUDE.md](CLAUDE.md)** - Development guide for working on this codebase
|
||||
- Architecture deep-dive
|
||||
- Testing strategy
|
||||
- Adding new backends
|
||||
- Common development tasks
|
||||
## Roadmap (summary)
|
||||
|
||||
- **[ROADMAP.md](ROADMAP.md)** - Planned features and implementation timeline
|
||||
### Connector alignment (docs — ISSUE-WP-0004)
|
||||
- INTENT / SCOPE / README framing as external connector
|
||||
- UUID ↔ external-id mapping design
|
||||
|
||||
## Roadmap
|
||||
|
||||
### v1.1 - Auto-Configuration (Next)
|
||||
### v1.1 - Auto-Configuration
|
||||
- Automatic git remote detection
|
||||
- Environment-variable-only setup
|
||||
- Per-repository configuration files
|
||||
- `issue config detect` command
|
||||
|
||||
### v1.2 - Agent Features
|
||||
- Agent identity management
|
||||
- Issue claiming/locking API
|
||||
- Webhook support for reactive agents
|
||||
- Structured metadata for agent state
|
||||
### Mapping + boundary sync (stage-3 work-record architecture)
|
||||
- Persist work-record UUID ↔ backend issue id
|
||||
- Optional two-way sync when a tracker is switched on
|
||||
- No load when integrations are off
|
||||
|
||||
### v2.0 - Advanced Coordination
|
||||
- Issue dependency tracking
|
||||
- Query DSL for complex filters
|
||||
- Activity streams and event logs
|
||||
- Distributed locking for concurrent operations
|
||||
### Further backends / agent helpers
|
||||
- GitHub, GitLab, Jira backends
|
||||
- Claiming helpers for external issues
|
||||
- Webhooks for tracker-side events
|
||||
|
||||
## Comparison with Platform CLIs
|
||||
|
||||
|
|
@ -396,19 +395,15 @@ The Issue Core is designed to be extensible:
|
|||
|
||||
See existing backends (Gitea, Local) as reference implementations.
|
||||
|
||||
## Why "Facade"?
|
||||
## Why "Facade" / connector?
|
||||
|
||||
The **Facade Pattern** describes this tool's purpose:
|
||||
The **Facade Pattern** still describes the *implementation* style:
|
||||
|
||||
> *"Provide a unified interface to a set of interfaces in a subsystem."*
|
||||
> — Gang of Four, Design Patterns
|
||||
|
||||
Instead of coding agents learning different APIs for GitHub (`gh`), GitLab (`glab`), Gitea, JIRA, etc., they use one consistent interface. The facade doesn't replace issue trackers—it makes them easier to use uniformly.
|
||||
Instead of agents learning different APIs for GitHub (`gh`), GitLab (`glab`), Gitea, JIRA, etc., they use one consistent interface. The facade does not replace issue trackers — and it does **not** replace work records as the origin of fleet work. It connects the fleet to trackers at the boundary.
|
||||
|
||||
## License
|
||||
|
||||
MIT License - See LICENSE file
|
||||
|
||||
## Part of MarkiTect
|
||||
|
||||
This capability is part of the [MarkiTect Project](https://github.com/markitect), a collection of tools for agent-driven software development.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue