generated from coulomb/repo-seed
feat: rename to issue-core and add task ingestion endpoint
Renames the package, distribution, CLI alias, Makefile targets, and working directory from issue-facade to issue-core, signalling its role as the authoritative task lifecycle manager for the Coulomb org (peer to activity-core, rules-core, project-core). Adds POST /issues/ ingestion endpoint for activity-core's IssueSink, under a new optional [api] extra. The endpoint is served by `issue serve`, authenticates via the ISSUE_CORE_API_KEY env var (Bearer or X-API-Key header), and routes the TaskSpec payload to the configured default backend with full traceability metadata embedded in sync_metadata. - T01: Python package issue_tracker -> issue_core, dir rename - T02: registered in state hub under custodian domain - T03: INTENT.md (what it is, what it isn't, how it fits) - T04: SCOPE.md (in/out-of-scope, integration boundaries) - T05: POST /issues/ via FastAPI + Uvicorn, 9 unit tests - T06: docs/nats-task-ingestion.md design stub Closes ISSC-WP-0001. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
43
README.md
43
README.md
@@ -1,10 +1,10 @@
|
||||
# Issue Facade - Agent Coordination via Issue Tracking
|
||||
# Issue Core - Agent Coordination via Issue Tracking
|
||||
|
||||
**A unified interface for autonomous coding agents to coordinate project implementation through issue tracking systems.**
|
||||
|
||||
## Purpose
|
||||
|
||||
The **Issue Facade** 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.
|
||||
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.
|
||||
|
||||
### Why Issue Tracking for Agent Coordination?
|
||||
|
||||
@@ -40,10 +40,25 @@ Issue tracking provides natural coordination primitives for multi-agent software
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
cd capabilities/issue-facade
|
||||
pip install -e .
|
||||
cd capabilities/issue-core
|
||||
pip install -e . # CLI only
|
||||
pip install -e ".[api]" # CLI + REST ingestion server
|
||||
```
|
||||
|
||||
### REST Ingestion Server
|
||||
|
||||
issue-core exposes `POST /issues/` for upstream emitters (primarily
|
||||
activity-core's `IssueSink`). Launch with:
|
||||
|
||||
```bash
|
||||
export ISSUE_CORE_API_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
|
||||
issue serve --host 0.0.0.0 --port 8765
|
||||
```
|
||||
|
||||
Clients authenticate with `Authorization: Bearer <key>` or `X-API-Key: <key>`.
|
||||
See `SCOPE.md` "TaskSpec payload" for the request schema, or visit
|
||||
`http://<host>:<port>/docs` once the server is running for live OpenAPI docs.
|
||||
|
||||
### Configuration (One-Time Setup)
|
||||
|
||||
**For Gitea-backed projects:**
|
||||
@@ -67,7 +82,7 @@ issue backend test myproject
|
||||
|
||||
```bash
|
||||
issue backend add local-work local
|
||||
# Prompts for: database path (.issue-facade/issues.db)
|
||||
# Prompts for: database path (.issue-core/issues.db)
|
||||
|
||||
issue backend set-default local-work
|
||||
```
|
||||
@@ -108,8 +123,8 @@ issue close 42 --comment="Ready for review"
|
||||
Quick example:
|
||||
|
||||
```python
|
||||
from issue_tracker.backends.gitea import GiteaBackend
|
||||
from issue_tracker.core.interfaces import IssueFilter
|
||||
from issue_core.backends.gitea import GiteaBackend
|
||||
from issue_core.core.interfaces import IssueFilter
|
||||
|
||||
# Initialize
|
||||
backend = GiteaBackend()
|
||||
@@ -281,20 +296,20 @@ make test-unit
|
||||
|
||||
```bash
|
||||
# Run linter
|
||||
make issue-facade-lint
|
||||
make issue-core-lint
|
||||
|
||||
# Format code
|
||||
black issue_tracker/ tests/
|
||||
black issue_core/ tests/
|
||||
|
||||
# Type check
|
||||
mypy issue_tracker/
|
||||
mypy issue_core/
|
||||
```
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
issue-facade/
|
||||
├── issue_tracker/
|
||||
issue-core/
|
||||
├── issue_core/
|
||||
│ ├── core/ # Domain models and interfaces
|
||||
│ │ ├── models.py # Issue, Label, User, etc.
|
||||
│ │ └── interfaces.py # IssueBackend, SyncableBackend
|
||||
@@ -351,7 +366,7 @@ issue-facade/
|
||||
|
||||
## Comparison with Platform CLIs
|
||||
|
||||
| Feature | Issue Facade | gh (GitHub) | glab (GitLab) |
|
||||
| Feature | Issue Core | gh (GitHub) | glab (GitLab) |
|
||||
|---------|--------------|-------------|---------------|
|
||||
| Multi-backend support | ✅ Yes | ❌ GitHub only | ❌ GitLab only |
|
||||
| Offline capability | ✅ Local SQLite | ❌ No | ❌ No |
|
||||
@@ -362,7 +377,7 @@ issue-facade/
|
||||
|
||||
## Contributing
|
||||
|
||||
The Issue Facade is designed to be extensible:
|
||||
The Issue Core is designed to be extensible:
|
||||
|
||||
**To add a new backend:**
|
||||
1. Implement the `IssueBackend` interface (see `core/interfaces.py`)
|
||||
|
||||
Reference in New Issue
Block a user