coulomb/issue-core
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Projects Releases Wiki Activity

feat: rename to issue-core and add task ingestion endpoint

Browse Source 
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:
Bernd Worsch
2026-05-17 05:16:27 +02:00
parent 99ea1fbc45
commit b605d970e3
38 changed files with 1324 additions and 361 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
.capability/README.md
View File

@@ -1,6 +1,6 @@
# Capability Bootstrap System
**How coding agents discover and integrate the issue-facade capability.**
**How coding agents discover and integrate the issue-core capability.**
## Design Philosophy
@@ -44,7 +44,7 @@ Comprehensive guide for coding agents:
- Error handling
- Examples
**Injected into:** `.claude/capabilities/issue-facade.md` in main project
**Injected into:** `.claude/capabilities/issue-core.md` in main project
### 3. Integration Automation
@@ -61,7 +61,7 @@ Interactive script that:
```bash
make integrate
# or
cd capabilities/issue-facade && ./.capability/integrate.sh
cd capabilities/issue-core && ./.capability/integrate.sh
```
### 4. Integration Checklist
@@ -81,7 +81,7 @@ Step-by-step checklist for humans integrating the capability:
```
Main Project Setup
├── 1. Human runs: cd capabilities/issue-facade && make integrate
├── 1. Human runs: cd capabilities/issue-core && make integrate
├── 2. Script installs capability
├── 3. Script configures backend (prompts for credentials)
├── 4. Script copies agent-context.md → .claude/capabilities/
@@ -101,13 +101,13 @@ Main Project Setup
Agent Workflow
├── 1. Agent receives task involving issues
├── 2. Agent checks .claude/capabilities/ for relevant docs
├── 3. Agent finds issue-facade.md with comprehensive guide
├── 3. Agent finds issue-core.md with comprehensive guide
├── 4. Agent uses Python API or CLI as documented
└── 5. Agent avoids direct API calls (warned in docs)
```
**Key Files Agent Reads:**
- `.claude/capabilities/issue-facade.md` - Complete usage guide
- `.claude/capabilities/issue-core.md` - Complete usage guide
- `.claude/context/capabilities.md` - High-level capability list
- `.claude/commands/use-issues.md` - Slash command for context injection
@@ -116,18 +116,18 @@ Agent Workflow
```
project-root/
├── capabilities/
│ └── issue-facade/ # Capability code
│ └── issue-core/ # Capability code
│ ├── CAPABILITY-issue-tracking.yaml # Machine-readable metadata
│ ├── .capability/
│ │ ├── agent-context.md # Agent guide (source)
│ │ ├── integrate.sh # Integration script
│ │ └── README.md # This file
│ ├── issue_tracker/ # Python package
│ ├── issue_core/ # Python package
│ └── ...
│
├── .claude/ # Claude Code configuration
│ ├── capabilities/ # Capability docs for agents
│ │ └── issue-facade.md # Agent guide (copy)
│ │ └── issue-core.md # Agent guide (copy)
│ │
│ ├── commands/ # Slash commands
│ │ └── use-issues.md # /use-issues command
@@ -135,7 +135,7 @@ project-root/
│ └── context/ # Always-available context
│ └── capabilities.md # List of all capabilities
│
└── .issue-facade/ # Capability config (gitignored)
└── .issue-core/ # Capability config (gitignored)
├── config.json # Backend configuration
└── issues.db # Local cache/backup
```
@@ -150,13 +150,13 @@ import os
from pathlib import Path
def has_issue_capability(project_root: Path) -> bool:
"""Check if issue-facade capability is available."""
capability_guide = project_root / ".claude/capabilities/issue-facade.md"
"""Check if issue-core capability is available."""
capability_guide = project_root / ".claude/capabilities/issue-core.md"
return capability_guide.exists()
if has_issue_capability(Path.cwd()):
# Use capability
from issue_tracker.backends.gitea import GiteaBackend
from issue_core.backends.gitea import GiteaBackend
backend = GiteaBackend()
else:
# Fall back or prompt human
@@ -173,15 +173,15 @@ def get_capability_docs(capability_name: str) -> str:
return None
# Agent can read and understand the guide
docs = get_capability_docs("issue-facade")
docs = get_capability_docs("issue-core")
# Parse docs for API usage patterns...
```
**3. Use the API as documented:**
```python
# Example from agent-context.md
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
backend = GiteaBackend()
backend.connect(config)
@@ -204,8 +204,8 @@ response = requests.post(
**Good (Uses capability):**
```python
# ✅ Uses capability
from issue_tracker.backends.gitea import GiteaBackend
from issue_tracker.core.models import Issue, IssueState
from issue_core.backends.gitea import GiteaBackend
from issue_core.core.models import Issue, IssueState
from datetime import datetime, timezone
backend = GiteaBackend()
@@ -302,7 +302,7 @@ make integrate
make discover-capabilities
# Output:
# Found capabilities:
# - issue-facade (v1.0.0) - Issue tracking coordination
# - issue-core (v1.0.0) - Issue tracking coordination
# - ... (other capabilities)
# Auto-integrate all
@@ -318,7 +318,7 @@ Capabilities have priority scores (0-100) indicating importance:
- **50-69 (Medium):** Use when available
- **Below 50 (Low):** Optional convenience
**issue-facade priority: 95 (Critical)**
**issue-core priority: 95 (Critical)**
Agents should check priority when deciding whether to use a capability or fall back to alternatives.
@@ -367,7 +367,7 @@ Agents should check priority when deciding whether to use a capability or fall b
## FAQ
**Q: Why not just document "use issue-facade" in README?**
**Q: Why not just document "use issue-core" in README?**
A: Agents often skip general docs. Putting it in `.claude/capabilities/` makes it part of their working context.
**Q: What if agent bypasses capability anyway?**
@@ -405,10 +405,10 @@ response = requests.post(gitea_url + "/issues", ...)
**With capability (properly integrated):**
```python
# Agent checks .claude/capabilities/issue-facade.md
# Agent checks .claude/capabilities/issue-core.md
# Reads: "Use this API, don't use direct requests"
# Agent follows documented pattern:
from issue_tracker.backends.gitea import GiteaBackend
from issue_core.backends.gitea import GiteaBackend
backend = GiteaBackend()
backend.connect(config)
backend.create_issue(issue)

20
.capability/agent-context.md
View File

@@ -1,4 +1,4 @@
# Issue Facade - Agent Integration Context
# Issue Core - Agent Integration Context
**🤖 For Coding Agents: Read this to understand how to use issue tracking in this project.**
@@ -25,15 +25,15 @@
# Verify installation
issue --version
# or
python -c "from issue_tracker.backends.gitea import GiteaBackend; print('OK')"
python -c "from issue_core.backends.gitea import GiteaBackend; print('OK')"
```
### Basic Usage (Python)
```python
from issue_tracker.backends.gitea import GiteaBackend
from issue_tracker.core.models import Issue, Label, IssueState, User, Comment
from issue_tracker.core.interfaces import IssueFilter
from issue_core.backends.gitea import GiteaBackend
from issue_core.core.models import Issue, Label, IssueState, User, Comment
from issue_core.core.interfaces import IssueFilter
from datetime import datetime, timezone
import os
@@ -228,7 +228,7 @@ if not verify_issue_backend():
## Error Handling
```python
from issue_tracker.backends.gitea.backend import GiteaAPIError
from issue_core.backends.gitea.backend import GiteaAPIError
try:
issue = backend.get_issue_by_number(42)
@@ -317,7 +317,7 @@ If you're unsure whether to use this capability for something:
- **NO** → You can use other methods
**Example:**
- "Create an issue for the bug I found" → **Use issue-facade**
- "Read the project README" → Don't need issue-facade
- "Check if issue #42 exists" → **Use issue-facade**
- "Clone the repository" → Don't need issue-facade
- "Create an issue for the bug I found" → **Use issue-core**
- "Read the project README" → Don't need issue-core
- "Check if issue #42 exists" → **Use issue-core**
- "Clone the repository" → Don't need issue-core

48
.capability/integrate.sh
View File

@@ -1,14 +1,14 @@
#!/bin/bash
# Integration script for issue-facade capability
# Integration script for issue-core capability
# This script helps the main project discover and integrate the capability
set -e
CAPABILITY_NAME="issue-facade"
CAPABILITY_NAME="issue-core"
CAPABILITY_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$CAPABILITY_DIR/../.." && pwd)}"
echo "🔧 Issue Facade Capability Integration"
echo "🔧 Issue Core Capability Integration"
echo " Capability: $CAPABILITY_DIR"
echo " Project: $PROJECT_ROOT"
echo ""
@@ -90,7 +90,7 @@ case $choice in
echo "📝 Adding to Claude Code context..."
mkdir -p "$PROJECT_ROOT/.claude/capabilities"
cp "$CAPABILITY_DIR/.capability/agent-context.md" \
"$PROJECT_ROOT/.claude/capabilities/issue-facade.md"
"$PROJECT_ROOT/.claude/capabilities/issue-core.md"
# Create or update context file
CONTEXT_FILE="$PROJECT_ROOT/.claude/context/capabilities.md"
@@ -102,10 +102,10 @@ case $choice in
This project uses specialized capabilities. Always check for existing capabilities before implementing similar functionality.
## Issue Tracking: issue-facade
## Issue Tracking: issue-core
**Location:** `capabilities/issue-facade/`
**Documentation:** `.claude/capabilities/issue-facade.md`
**Location:** `capabilities/issue-core/`
**Documentation:** `.claude/capabilities/issue-core.md`
**Priority:** CRITICAL (always use for issue operations)
**MUST USE FOR:**
@@ -120,13 +120,13 @@ This project uses specialized capabilities. Always check for existing capabiliti
**Quick Start:**
```python
from issue_tracker.backends.gitea import GiteaBackend
from issue_core.backends.gitea import GiteaBackend
backend = GiteaBackend()
backend.connect(config)
issues = backend.list_issues()
```
**Full Documentation:** See `.claude/capabilities/issue-facade.md`
**Full Documentation:** See `.claude/capabilities/issue-core.md`
EOF
echo "✓ Created $CONTEXT_FILE"
else
@@ -138,7 +138,7 @@ EOF
echo "✓ Added to Claude Code context"
echo ""
echo "Files created:"
echo " - $PROJECT_ROOT/.claude/capabilities/issue-facade.md"
echo " - $PROJECT_ROOT/.claude/capabilities/issue-core.md"
echo " - $CONTEXT_FILE"
;;
@@ -148,15 +148,15 @@ EOF
mkdir -p "$PROJECT_ROOT/.claude/commands"
cat > "$PROJECT_ROOT/.claude/commands/use-issues.md" << 'EOF'
You are working with issue tracking. Use the **issue-facade capability**:
You are working with issue tracking. Use the **issue-core capability**:
## Available API
**Python (Recommended):**
```python
from issue_tracker.backends.gitea import GiteaBackend
from issue_tracker.core.models import Issue, Label, IssueState
from issue_tracker.core.interfaces import IssueFilter
from issue_core.backends.gitea import GiteaBackend
from issue_core.core.models import Issue, Label, IssueState
from issue_core.core.interfaces import IssueFilter
backend = GiteaBackend()
backend.connect(config)
@@ -193,7 +193,7 @@ issue close 42 --comment="Fixed"
## Full Documentation
See `capabilities/issue-facade/AGENT_INTEGRATION.md` for:
See `capabilities/issue-core/AGENT_INTEGRATION.md` for:
- Complete API reference
- Coordination patterns
- Error handling
@@ -206,7 +206,7 @@ EOF
echo "Usage in Claude Code:"
echo " /use-issues"
echo ""
echo "This will inject issue-facade context into the conversation."
echo "This will inject issue-core context into the conversation."
;;
5)
@@ -250,7 +250,7 @@ EOF
mkdir -p "$PROJECT_ROOT/.claude/context"
cp "$CAPABILITY_DIR/.capability/agent-context.md" \
"$PROJECT_ROOT/.claude/capabilities/issue-facade.md"
"$PROJECT_ROOT/.claude/capabilities/issue-core.md"
# Create context file if not exists
CONTEXT_FILE="$PROJECT_ROOT/.claude/context/capabilities.md"
@@ -258,21 +258,21 @@ EOF
cat > "$CONTEXT_FILE" << 'EOF'
# Available Capabilities
## Issue Tracking: issue-facade
## Issue Tracking: issue-core
**CRITICAL:** Always use this for issue operations. Never bypass with direct API calls.
**Docs:** `.claude/capabilities/issue-facade.md`
**Docs:** `.claude/capabilities/issue-core.md`
**Usage:** `/use-issues`
EOF
fi
# Create slash command
cat > "$PROJECT_ROOT/.claude/commands/use-issues.md" << 'EOF'
Use the issue-facade capability for all issue tracking operations.
Use the issue-core capability for all issue tracking operations.
**Quick reference:** See `.claude/capabilities/issue-facade.md`
**Examples:** See `capabilities/issue-facade/examples/agents/`
**Quick reference:** See `.claude/capabilities/issue-core.md`
**Examples:** See `capabilities/issue-core/examples/agents/`
**DO NOT use direct API calls or platform CLIs!**
EOF
@@ -285,7 +285,7 @@ EOF
echo ""
issue --version && echo "✓ CLI works" || echo "❌ CLI not working"
issue backend list | grep -q "default" && echo "✓ Backend configured" || echo "⚠️ Backend not configured"
[ -f "$PROJECT_ROOT/.claude/capabilities/issue-facade.md" ] && echo "✓ Claude context exists" || echo "❌ Claude context missing"
[ -f "$PROJECT_ROOT/.claude/capabilities/issue-core.md" ] && echo "✓ Claude context exists" || echo "❌ Claude context missing"
[ -f "$PROJECT_ROOT/.claude/commands/use-issues.md" ] && echo "✓ Slash command exists" || echo "❌ Slash command missing"
echo ""
@@ -294,7 +294,7 @@ EOF
echo "Next steps:"
echo " 1. Test: issue list --limit=5"
echo " 2. In Claude Code: /use-issues"
echo " 3. See examples: capabilities/issue-facade/examples/agents/"
echo " 3. See examples: capabilities/issue-core/examples/agents/"
;;
0)

50
.capability/integration-checklist.md
View File

@@ -1,4 +1,4 @@
# Issue Facade Integration Checklist
# Issue Core Integration Checklist
**For project maintainers integrating this capability into their codebase.**
@@ -13,7 +13,7 @@
- [ ] **Install capability:**
```bash
pip install -e capabilities/issue-facade/
pip install -e capabilities/issue-core/
```
- [ ] **Verify installation:**
@@ -42,8 +42,8 @@
- [ ] **Copy agent context to project:**
```bash
mkdir -p .claude/capabilities/
cp capabilities/issue-facade/.capability/agent-context.md \
.claude/capabilities/issue-facade.md
cp capabilities/issue-core/.capability/agent-context.md \
.claude/capabilities/issue-core.md
```
- [ ] **Add to Claude Code context:**
@@ -53,17 +53,17 @@
This project uses specialized capabilities. Always check these before implementing similar functionality.
## Issue Tracking: issue-facade
## Issue Tracking: issue-core
**Location:** `capabilities/issue-facade/`
**Documentation:** `.claude/capabilities/issue-facade.md`
**Location:** `capabilities/issue-core/`
**Documentation:** `.claude/capabilities/issue-core.md`
**CRITICAL:** Always use this capability for issue operations. Never use:
- Direct API calls (requests to /api/v1/repos/...)
- Platform CLIs (gh, glab)
- Platform libraries (PyGithub, python-gitlab)
See `.claude/capabilities/issue-facade.md` for usage patterns.
See `.claude/capabilities/issue-core.md` for usage patterns.
```
### Option 2: Slash Command
@@ -71,11 +71,11 @@
- [ ] **Create slash command:**
Create `.claude/commands/use-issues.md`:
```markdown
You are working with issue tracking. Use the issue-facade capability:
You are working with issue tracking. Use the issue-core capability:
**Python API:**
```python
from issue_tracker.backends.gitea import GiteaBackend
from issue_core.backends.gitea import GiteaBackend
backend = GiteaBackend()
backend.connect(config)
```
@@ -86,7 +86,7 @@
issue create "Title" --label=bug
```
**Full docs:** See `capabilities/issue-facade/AGENT_INTEGRATION.md`
**Full docs:** See `capabilities/issue-core/AGENT_INTEGRATION.md`
**DO NOT use direct API calls or platform CLIs!**
```
@@ -106,7 +106,7 @@
## Agent Configuration
- [ ] **Set agent identity:**
Add to `.issue-facade/config.json`:
Add to `.issue-core/config.json`:
```json
{
"agent": {
@@ -126,8 +126,8 @@
- [ ] **Test basic operations:**
```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
backend = GiteaBackend()
backend.connect({'base_url': '...', 'token': '...', 'owner': '...', 'repo': '...'})
@@ -153,26 +153,26 @@
```markdown
## Issue Tracking
This project uses the issue-facade capability for unified issue tracking.
This project uses the issue-core capability for unified issue tracking.
**Setup:**
```bash
pip install -e capabilities/issue-facade/
pip install -e capabilities/issue-core/
export GITEA_API_TOKEN="your-token"
issue backend add myproject gitea
```
**Usage:** See `capabilities/issue-facade/AGENT_INTEGRATION.md`
**Usage:** See `capabilities/issue-core/AGENT_INTEGRATION.md`
```
- [ ] **Add to CONTRIBUTING.md:**
```markdown
### Issue Tracking
Always use the `issue` command or Python API from `issue_tracker` package.
Always use the `issue` command or Python API from `issue_core` package.
Never make direct API calls to Gitea/GitHub/GitLab.
Examples: `capabilities/issue-facade/examples/agents/`
Examples: `capabilities/issue-core/examples/agents/`
```
## Security Review
@@ -180,9 +180,9 @@
- [ ] **Verify tokens are not in code:** `git grep GITEA_TOKEN` (should be empty)
- [ ] **Check .gitignore includes:**
```
.issue-facade/config.json
.issue-facade/issues.db
.issue-facade/credentials.json
.issue-core/config.json
.issue-core/issues.db
.issue-core/credentials.json
```
- [ ] **Audit token permissions:** Read-only for bots, write for implementation
@@ -192,7 +192,7 @@
- [ ] **Run capability tests:**
```bash
cd capabilities/issue-facade/
cd capabilities/issue-core/
make test
```
@@ -210,7 +210,7 @@
- [ ] **Schedule regular updates:**
```bash
cd capabilities/issue-facade/
cd capabilities/issue-core/
git pull origin main
pip install -e . --upgrade
```
@@ -232,7 +232,7 @@ If capability causes issues:
- [ ] **Keep backup config:**
```bash
cp ~/.config/issue-facade/backends.json ~/.config/issue-facade/backends.json.backup
cp ~/.config/issue-core/backends.json ~/.config/issue-core/backends.json.backup
```
- [ ] **Document rollback steps in project wiki/docs**