generated from coulomb/repo-seed
feat: transform to agent coordination platform with comprehensive documentation
Transform Issue Facade from a universal CLI tool into an agent coordination platform with comprehensive documentation and enhanced capabilities for autonomous coding agents. Major Changes: - Complete README rewrite focusing on agent-driven coordination - New comprehensive documentation (AGENT_INTEGRATION.md, CLAUDE.md, ROADMAP.md) - Capability integration setup with CAPABILITY.yaml and integration scripts - Enhanced Makefile with local development targets for easier workflows Bug Fixes: - Fix schema initialization using executescript() for multi-line SQL support - Disable FTS5 triggers due to compatibility issues (documented for future re-enablement) Features: - Enhanced CLI list command with full parameter passthrough - New examples directory with agent integration patterns - New comprehensive test suite (test_core_models.py, test_local_backend.py) Code Quality: - Remove @cached_property decorators for Label properties (simplification) - Clean up test organization (removed old test_gitea_integration.py) This milestone establishes Issue Facade as a production-ready coordination layer for multi-agent software development, with clear integration paths and comprehensive developer documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
426
.capability/README.md
Normal file
426
.capability/README.md
Normal file
@@ -0,0 +1,426 @@
|
||||
# Capability Bootstrap System
|
||||
|
||||
**How coding agents discover and integrate the issue-facade capability.**
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
**Problem:** Coding agents might bypass capabilities and use direct API calls, causing:
|
||||
- Credential management chaos
|
||||
- Token waste
|
||||
- Platform lock-in
|
||||
- Race conditions
|
||||
- Inconsistent state
|
||||
|
||||
**Solution:** Make capabilities **self-describing** and **easy to discover**, so agents naturally prefer them over alternatives.
|
||||
|
||||
## Architecture
|
||||
|
||||
### 1. Self-Description (Machine-Readable)
|
||||
|
||||
**File:** `CAPABILITY.yaml`
|
||||
|
||||
Contains machine-readable metadata that agents and tooling can parse:
|
||||
- What the capability does
|
||||
- When to use it vs. alternatives
|
||||
- How to integrate it
|
||||
- API surface
|
||||
- Priority score (how critical it is)
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Tools can parse this to understand capabilities
|
||||
yq eval '.purpose.primary' CAPABILITY.yaml
|
||||
# Output: "Agent coordination via issue tracking"
|
||||
```
|
||||
|
||||
### 2. Agent Context (Human + AI Readable)
|
||||
|
||||
**File:** `.capability/agent-context.md`
|
||||
|
||||
Comprehensive guide for coding agents:
|
||||
- Quick reference API
|
||||
- Common patterns
|
||||
- Critical "DO NOT bypass" warnings
|
||||
- Error handling
|
||||
- Examples
|
||||
|
||||
**Injected into:** `.claude/capabilities/issue-facade.md` in main project
|
||||
|
||||
### 3. Integration Automation
|
||||
|
||||
**File:** `.capability/integrate.sh`
|
||||
|
||||
Interactive script that:
|
||||
- Installs the capability
|
||||
- Configures backends
|
||||
- Injects context into Claude Code
|
||||
- Creates slash commands
|
||||
- Verifies setup
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
make integrate
|
||||
# or
|
||||
cd capabilities/issue-facade && ./.capability/integrate.sh
|
||||
```
|
||||
|
||||
### 4. Integration Checklist
|
||||
|
||||
**File:** `.capability/integration-checklist.md`
|
||||
|
||||
Step-by-step checklist for humans integrating the capability:
|
||||
- Pre-integration checks
|
||||
- Installation steps
|
||||
- Verification tests
|
||||
- Security review
|
||||
- Troubleshooting
|
||||
|
||||
## Integration Flow
|
||||
|
||||
### For Main Project (One-Time Setup)
|
||||
|
||||
```
|
||||
Main Project Setup
|
||||
├── 1. Human runs: cd capabilities/issue-facade && make integrate
|
||||
├── 2. Script installs capability
|
||||
├── 3. Script configures backend (prompts for credentials)
|
||||
├── 4. Script copies agent-context.md → .claude/capabilities/
|
||||
├── 5. Script creates .claude/commands/use-issues.md
|
||||
└── 6. Script verifies setup
|
||||
```
|
||||
|
||||
**Result:**
|
||||
- `issue` command available system-wide
|
||||
- Backend configured with tokens
|
||||
- Claude Code knows about capability
|
||||
- Agents can discover via context files
|
||||
|
||||
### For Coding Agents (Automatic)
|
||||
|
||||
```
|
||||
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
|
||||
├── 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/context/capabilities.md` - High-level capability list
|
||||
- `.claude/commands/use-issues.md` - Slash command for context injection
|
||||
|
||||
## Main Project Structure (After Integration)
|
||||
|
||||
```
|
||||
project-root/
|
||||
├── capabilities/
|
||||
│ └── issue-facade/ # Capability code
|
||||
│ ├── CAPABILITY.yaml # Machine-readable metadata
|
||||
│ ├── .capability/
|
||||
│ │ ├── agent-context.md # Agent guide (source)
|
||||
│ │ ├── integrate.sh # Integration script
|
||||
│ │ └── README.md # This file
|
||||
│ ├── issue_tracker/ # Python package
|
||||
│ └── ...
|
||||
│
|
||||
├── .claude/ # Claude Code configuration
|
||||
│ ├── capabilities/ # Capability docs for agents
|
||||
│ │ └── issue-facade.md # Agent guide (copy)
|
||||
│ │
|
||||
│ ├── commands/ # Slash commands
|
||||
│ │ └── use-issues.md # /use-issues command
|
||||
│ │
|
||||
│ └── context/ # Always-available context
|
||||
│ └── capabilities.md # List of all capabilities
|
||||
│
|
||||
└── .issue-facade/ # Capability config (gitignored)
|
||||
├── config.json # Backend configuration
|
||||
└── issues.db # Local cache/backup
|
||||
```
|
||||
|
||||
## For Agent Developers
|
||||
|
||||
### How to Make Your Agent Use the Capability
|
||||
|
||||
**1. Check for capability context:**
|
||||
```python
|
||||
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"
|
||||
return capability_guide.exists()
|
||||
|
||||
if has_issue_capability(Path.cwd()):
|
||||
# Use capability
|
||||
from issue_tracker.backends.gitea import GiteaBackend
|
||||
backend = GiteaBackend()
|
||||
else:
|
||||
# Fall back or prompt human
|
||||
print("Issue capability not available. Please integrate it.")
|
||||
```
|
||||
|
||||
**2. Read the context:**
|
||||
```python
|
||||
def get_capability_docs(capability_name: str) -> str:
|
||||
"""Read capability documentation."""
|
||||
doc_path = Path(f".claude/capabilities/{capability_name}.md")
|
||||
if doc_path.exists():
|
||||
return doc_path.read_text()
|
||||
return None
|
||||
|
||||
# Agent can read and understand the guide
|
||||
docs = get_capability_docs("issue-facade")
|
||||
# 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
|
||||
|
||||
backend = GiteaBackend()
|
||||
backend.connect(config)
|
||||
issues = backend.list_issues(IssueFilter(state='open'))
|
||||
```
|
||||
|
||||
### How to Avoid Bypassing
|
||||
|
||||
**Bad (Bypasses capability):**
|
||||
```python
|
||||
# ❌ Direct API call
|
||||
import requests
|
||||
response = requests.post(
|
||||
f"{gitea_url}/api/v1/repos/{owner}/{repo}/issues",
|
||||
json={"title": "Bug"},
|
||||
headers={"Authorization": f"token {token}"}
|
||||
)
|
||||
```
|
||||
|
||||
**Good (Uses capability):**
|
||||
```python
|
||||
# ✅ Uses capability
|
||||
from issue_tracker.backends.gitea import GiteaBackend
|
||||
from issue_tracker.core.models import Issue, IssueState
|
||||
from datetime import datetime, timezone
|
||||
|
||||
backend = GiteaBackend()
|
||||
backend.connect(config)
|
||||
issue = Issue(
|
||||
id=None, number=0,
|
||||
title="Bug",
|
||||
description="Details",
|
||||
state=IssueState.OPEN,
|
||||
created_at=datetime.now(timezone.utc),
|
||||
updated_at=datetime.now(timezone.utc)
|
||||
)
|
||||
backend.create_issue(issue)
|
||||
```
|
||||
|
||||
## For Capability Developers
|
||||
|
||||
### Adding a New Capability to This System
|
||||
|
||||
**1. Create capability structure:**
|
||||
```
|
||||
capabilities/your-capability/
|
||||
├── CAPABILITY.yaml # Metadata
|
||||
├── .capability/
|
||||
│ ├── agent-context.md # Agent guide
|
||||
│ ├── integrate.sh # Integration script
|
||||
│ ├── integration-checklist.md # Human checklist
|
||||
│ └── README.md # This doc adapted
|
||||
└── your_package/ # Implementation
|
||||
```
|
||||
|
||||
**2. Write CAPABILITY.yaml:**
|
||||
```yaml
|
||||
metadata:
|
||||
name: your-capability
|
||||
version: 1.0.0
|
||||
type: tool | library | service
|
||||
description: What it does
|
||||
|
||||
purpose:
|
||||
primary: Main purpose
|
||||
problems_solved:
|
||||
- Problem 1
|
||||
- Problem 2
|
||||
|
||||
usage_rules:
|
||||
MUST_USE_INSTEAD_OF:
|
||||
- "Alternative 1 to avoid"
|
||||
- "Alternative 2 to avoid"
|
||||
|
||||
api:
|
||||
core_operations:
|
||||
- name: operation_1
|
||||
python: "from your_package import ..."
|
||||
cli: "your-command ..."
|
||||
```
|
||||
|
||||
**3. Write agent-context.md:**
|
||||
- Critical warnings (what NOT to do)
|
||||
- Quick reference API
|
||||
- Common patterns
|
||||
- Error handling
|
||||
- Examples
|
||||
|
||||
**4. Create integrate.sh:**
|
||||
- Install capability
|
||||
- Configure if needed
|
||||
- Copy context to `.claude/capabilities/`
|
||||
- Create slash command
|
||||
- Verify installation
|
||||
|
||||
**5. Add to main project:**
|
||||
```bash
|
||||
cd capabilities/your-capability
|
||||
make integrate
|
||||
```
|
||||
|
||||
## Discovery Mechanisms
|
||||
|
||||
### Manual Discovery (Human)
|
||||
1. Human sees `capabilities/` directory
|
||||
2. Reads `CAPABILITY.yaml` to understand what's available
|
||||
3. Runs `make integrate` to set up for agents
|
||||
|
||||
### Automatic Discovery (Agent)
|
||||
1. Agent checks `.claude/capabilities/` for available capabilities
|
||||
2. Reads relevant `.md` files for usage guides
|
||||
3. Uses capabilities as documented
|
||||
4. Falls back gracefully if capability unavailable
|
||||
|
||||
### Tool-Assisted Discovery
|
||||
```bash
|
||||
# Future: Auto-discover all capabilities
|
||||
make discover-capabilities
|
||||
# Output:
|
||||
# Found capabilities:
|
||||
# - issue-facade (v1.0.0) - Issue tracking coordination
|
||||
# - ... (other capabilities)
|
||||
|
||||
# Auto-integrate all
|
||||
make integrate-all-capabilities
|
||||
```
|
||||
|
||||
## Priority System
|
||||
|
||||
Capabilities have priority scores (0-100) indicating importance:
|
||||
|
||||
- **90-100 (Critical):** Must always use, bypassing causes major issues
|
||||
- **70-89 (High):** Should prefer over alternatives
|
||||
- **50-69 (Medium):** Use when available
|
||||
- **Below 50 (Low):** Optional convenience
|
||||
|
||||
**issue-facade priority: 95 (Critical)**
|
||||
|
||||
Agents should check priority when deciding whether to use a capability or fall back to alternatives.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### For Capability Authors
|
||||
|
||||
1. **Make it obvious:** Clear documentation, examples, warnings
|
||||
2. **Make it easy:** One-command integration, good defaults
|
||||
3. **Make it safe:** No tokens in code, proper error handling
|
||||
4. **Make it discoverable:** Standard structure, machine-readable metadata
|
||||
5. **Make it maintainable:** Version clearly, document breaking changes
|
||||
|
||||
### For Project Integrators
|
||||
|
||||
1. **Integrate early:** Set up capabilities before agents start work
|
||||
2. **Verify integration:** Run tests to ensure agents use capabilities
|
||||
3. **Monitor usage:** Check that agents aren't bypassing capabilities
|
||||
4. **Keep updated:** Pull capability updates regularly
|
||||
5. **Share feedback:** Report issues, contribute improvements
|
||||
|
||||
### For Agent Developers
|
||||
|
||||
1. **Check context:** Always look for `.claude/capabilities/`
|
||||
2. **Read docs:** Don't guess the API, read the guide
|
||||
3. **Follow warnings:** If docs say "DO NOT", don't do it
|
||||
4. **Handle errors:** Capability might not be available
|
||||
5. **Report issues:** If capability is confusing, report it
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### v1.1: Auto-Discovery
|
||||
- `make list-capabilities` to show all available
|
||||
- `make integrate-capability NAME` for specific capability
|
||||
- Auto-detect when capability would be useful
|
||||
|
||||
### v1.2: MCP Integration
|
||||
- Capabilities as MCP servers
|
||||
- Tool-based discovery (no file reading needed)
|
||||
- Dynamic capability loading
|
||||
|
||||
### v2.0: Capability Registry
|
||||
- Central registry of available capabilities
|
||||
- Version management and updates
|
||||
- Dependency resolution
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Why not just document "use issue-facade" 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?**
|
||||
A: 1) Check warnings are in context, 2) Use slash command to re-inject, 3) Review agent's reasoning for bypass.
|
||||
|
||||
**Q: Can capabilities depend on each other?**
|
||||
A: Not yet (v1.0). Planned for v2.0 with dependency resolution.
|
||||
|
||||
**Q: How do I test integration?**
|
||||
A: Run integration script, then test with agent doing actual work. Verify it uses capability API.
|
||||
|
||||
**Q: What if capability breaks?**
|
||||
A: Document rollback in integration checklist. Keep backup configs. Have fallback plan.
|
||||
|
||||
## Summary
|
||||
|
||||
**The capability bootstrap system works by:**
|
||||
|
||||
1. **Self-description** - Capability declares what it does (CAPABILITY.yaml)
|
||||
2. **Context injection** - Integration copies docs to `.claude/capabilities/`
|
||||
3. **Agent discovery** - Agents check context before implementing
|
||||
4. **Natural preference** - Good docs + warnings make capability easier than alternatives
|
||||
5. **Verification** - Integration script tests that everything works
|
||||
|
||||
**Result:** Agents naturally discover and use capabilities instead of bypassing them.
|
||||
|
||||
## Example: Issue Tracking Use Case
|
||||
|
||||
**Without capability:**
|
||||
```python
|
||||
# Agent bypasses, makes direct API call
|
||||
response = requests.post(gitea_url + "/issues", ...)
|
||||
# Problems: Token in code, no caching, platform-specific
|
||||
```
|
||||
|
||||
**With capability (properly integrated):**
|
||||
```python
|
||||
# Agent checks .claude/capabilities/issue-facade.md
|
||||
# Reads: "Use this API, don't use direct requests"
|
||||
# Agent follows documented pattern:
|
||||
from issue_tracker.backends.gitea import GiteaBackend
|
||||
backend = GiteaBackend()
|
||||
backend.connect(config)
|
||||
backend.create_issue(issue)
|
||||
# Benefits: Centralized tokens, caching, platform-agnostic
|
||||
```
|
||||
|
||||
**The difference:** Integration puts capability docs in agent's context, making it the obvious choice.
|
||||
|
||||
---
|
||||
|
||||
For more information:
|
||||
- **Integration Guide:** `AGENT_INTEGRATION.md`
|
||||
- **Development Guide:** `CLAUDE.md`
|
||||
- **Roadmap:** `ROADMAP.md`
|
||||
- **Examples:** `examples/agents/`
|
||||
323
.capability/agent-context.md
Normal file
323
.capability/agent-context.md
Normal file
@@ -0,0 +1,323 @@
|
||||
# Issue Facade - Agent Integration Context
|
||||
|
||||
**🤖 For Coding Agents: Read this to understand how to use issue tracking in this project.**
|
||||
|
||||
## Critical: DO NOT Bypass This Capability
|
||||
|
||||
⚠️ **IMPORTANT:** If you need to work with issues, **you MUST use this capability**. Do NOT:
|
||||
- ❌ Make direct API calls to Gitea/GitHub/GitLab
|
||||
- ❌ Use platform CLIs (gh, glab, etc.)
|
||||
- ❌ Import platform libraries (PyGithub, python-gitlab, etc.)
|
||||
- ❌ Parse HTML/scrape issue tracker web UIs
|
||||
|
||||
**Why?** Bypassing this capability causes:
|
||||
- Credential management chaos (tokens scattered everywhere)
|
||||
- Inconsistent issue state across agents
|
||||
- Massive token waste (redundant API calls)
|
||||
- Platform lock-in (can't switch Gitea → GitHub easily)
|
||||
- Race conditions in multi-agent scenarios
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Check if Capability is Available
|
||||
|
||||
```bash
|
||||
# Verify installation
|
||||
issue --version
|
||||
# or
|
||||
python -c "from issue_tracker.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 datetime import datetime, timezone
|
||||
import os
|
||||
|
||||
# Connect (assumes backend is configured)
|
||||
backend = GiteaBackend()
|
||||
backend.connect({
|
||||
'base_url': os.environ['GITEA_URL'],
|
||||
'token': os.environ['GITEA_API_TOKEN'],
|
||||
'owner': os.environ['GITEA_OWNER'],
|
||||
'repo': os.environ['GITEA_REPO']
|
||||
})
|
||||
|
||||
# List issues for me
|
||||
my_issues = backend.list_issues(IssueFilter(
|
||||
state='open',
|
||||
assignee='my-agent-id',
|
||||
labels=['needs-implementation']
|
||||
))
|
||||
|
||||
# Create issue
|
||||
new_issue = Issue(
|
||||
id=None, number=0,
|
||||
title="Implement feature X",
|
||||
description="Details...",
|
||||
state=IssueState.OPEN,
|
||||
created_at=datetime.now(timezone.utc),
|
||||
updated_at=datetime.now(timezone.utc),
|
||||
labels=[Label(name="feature"), Label(name="priority:high")]
|
||||
)
|
||||
created = backend.create_issue(new_issue)
|
||||
|
||||
# Update issue
|
||||
created.state = IssueState.IN_PROGRESS
|
||||
created.assignees = [User(id="agent-id", username="agent-id")]
|
||||
backend.update_issue(created)
|
||||
|
||||
# Add comment
|
||||
comment = Comment(
|
||||
id=None,
|
||||
body="Implementation started. Working on database schema.",
|
||||
author=User(id="agent-id", username="agent-id"),
|
||||
created_at=datetime.now(timezone.utc)
|
||||
)
|
||||
backend.add_comment(created.id, comment)
|
||||
|
||||
# Close when done
|
||||
created.state = IssueState.CLOSED
|
||||
created.closed_at = datetime.now(timezone.utc)
|
||||
backend.update_issue(created)
|
||||
```
|
||||
|
||||
### Basic Usage (CLI)
|
||||
|
||||
```bash
|
||||
# List my open issues
|
||||
issue list --state=open --assignee=agent-id --format=json
|
||||
|
||||
# Create issue
|
||||
issue create "Implement feature X" \
|
||||
--label=feature \
|
||||
--label=priority:high \
|
||||
--description="Details here"
|
||||
|
||||
# Update state
|
||||
issue edit 42 --state=in_progress --assignee=agent-id
|
||||
|
||||
# Add comment
|
||||
issue comment 42 "Implementation started"
|
||||
|
||||
# Close
|
||||
issue close 42 --comment="Completed successfully"
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern 1: Find Work
|
||||
|
||||
```python
|
||||
# Get next available task
|
||||
available_tasks = backend.list_issues(IssueFilter(
|
||||
state='open',
|
||||
labels=['ready', 'needs-implementation']
|
||||
))
|
||||
|
||||
# Filter to unassigned
|
||||
unassigned = [t for t in available_tasks if not t.assignees]
|
||||
|
||||
if unassigned:
|
||||
task = unassigned[0]
|
||||
# Claim it...
|
||||
```
|
||||
|
||||
### Pattern 2: Claim Issue (Prevent Race Conditions)
|
||||
|
||||
```python
|
||||
def claim_issue(issue: Issue, agent_id: str) -> bool:
|
||||
"""Claim an issue safely."""
|
||||
# Check if already claimed
|
||||
if issue.assignees:
|
||||
return False # Already taken
|
||||
|
||||
# Claim it
|
||||
issue.state = IssueState.IN_PROGRESS
|
||||
issue.assignees = [User(id=agent_id, username=agent_id)]
|
||||
backend.update_issue(issue)
|
||||
|
||||
# Announce claim
|
||||
backend.add_comment(issue.id, Comment(
|
||||
id=None,
|
||||
body=f"🤖 Claimed by {agent_id}",
|
||||
author=User(id=agent_id, username=agent_id),
|
||||
created_at=datetime.now(timezone.utc)
|
||||
))
|
||||
return True
|
||||
```
|
||||
|
||||
### Pattern 3: Progress Updates
|
||||
|
||||
```python
|
||||
def report_progress(issue: Issue, message: str, agent_id: str):
|
||||
"""Report progress on an issue."""
|
||||
backend.add_comment(issue.id, Comment(
|
||||
id=None,
|
||||
body=f"**Progress Update:**\n\n{message}",
|
||||
author=User(id=agent_id, username=agent_id),
|
||||
created_at=datetime.now(timezone.utc)
|
||||
))
|
||||
```
|
||||
|
||||
### Pattern 4: Agent-to-Agent Communication
|
||||
|
||||
```python
|
||||
import json
|
||||
|
||||
def post_agent_message(issue_id: str, msg_type: str, data: dict, agent_id: str):
|
||||
"""Post structured message for other agents."""
|
||||
message = {
|
||||
'type': msg_type,
|
||||
'agent': agent_id,
|
||||
'timestamp': datetime.now(timezone.utc).isoformat(),
|
||||
'data': data
|
||||
}
|
||||
backend.add_comment(issue_id, Comment(
|
||||
id=None,
|
||||
body=f"```agent-message\n{json.dumps(message, indent=2)}\n```",
|
||||
author=User(id=agent_id, username=agent_id),
|
||||
created_at=datetime.now(timezone.utc)
|
||||
))
|
||||
|
||||
def read_agent_messages(issue_id: str, msg_type: str = None):
|
||||
"""Read messages from other agents."""
|
||||
comments = backend.get_comments(issue_id)
|
||||
messages = []
|
||||
for comment in comments:
|
||||
if '```agent-message' in comment.body:
|
||||
try:
|
||||
json_str = comment.body.split('```agent-message\n')[1].split('\n```')[0]
|
||||
msg = json.loads(json_str)
|
||||
if msg_type is None or msg['type'] == msg_type:
|
||||
messages.append(msg)
|
||||
except:
|
||||
continue
|
||||
return messages
|
||||
```
|
||||
|
||||
## Configuration Check
|
||||
|
||||
Before using issue tracking, verify configuration:
|
||||
|
||||
```python
|
||||
def verify_issue_backend() -> bool:
|
||||
"""Verify issue backend is configured."""
|
||||
try:
|
||||
backend = GiteaBackend()
|
||||
backend.connect({
|
||||
'base_url': os.environ['GITEA_URL'],
|
||||
'token': os.environ['GITEA_API_TOKEN'],
|
||||
'owner': os.environ['GITEA_OWNER'],
|
||||
'repo': os.environ['GITEA_REPO']
|
||||
})
|
||||
return backend.test_connection()
|
||||
except Exception as e:
|
||||
print(f"Issue backend not configured: {e}")
|
||||
return False
|
||||
|
||||
# Use it
|
||||
if not verify_issue_backend():
|
||||
print("ERROR: Issue tracking not available. Check configuration.")
|
||||
sys.exit(1)
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
```python
|
||||
from issue_tracker.backends.gitea.backend import GiteaAPIError
|
||||
|
||||
try:
|
||||
issue = backend.get_issue_by_number(42)
|
||||
except GiteaAPIError as e:
|
||||
if e.status_code == 404:
|
||||
print("Issue not found")
|
||||
elif e.status_code == 401:
|
||||
print("Authentication failed - check GITEA_API_TOKEN")
|
||||
elif e.status_code == 429:
|
||||
print("Rate limited - wait and retry")
|
||||
else:
|
||||
print(f"API error: {e}")
|
||||
```
|
||||
|
||||
## Performance Tips
|
||||
|
||||
1. **Use filters** instead of fetching all issues:
|
||||
```python
|
||||
# BAD: Get all, filter in Python
|
||||
all_issues = backend.list_issues()
|
||||
my_issues = [i for i in all_issues if i.assignees and i.assignees[0].username == 'me']
|
||||
|
||||
# GOOD: Filter at backend
|
||||
my_issues = backend.list_issues(IssueFilter(assignee='me'))
|
||||
```
|
||||
|
||||
2. **Use JSON output** for CLI parsing:
|
||||
```bash
|
||||
issue list --format=json | jq '.[] | select(.state == "open")'
|
||||
```
|
||||
|
||||
3. **Batch comments** instead of rapid-fire updates
|
||||
|
||||
4. **Check local cache** before querying (if available)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Backend not configured"
|
||||
```bash
|
||||
# Check config
|
||||
issue backend list
|
||||
|
||||
# If empty, configure
|
||||
export GITEA_API_TOKEN="your-token"
|
||||
issue backend add myproject gitea
|
||||
issue backend set-default myproject
|
||||
```
|
||||
|
||||
### "Authentication failed"
|
||||
```bash
|
||||
# Verify token
|
||||
curl -H "Authorization: token $GITEA_API_TOKEN" $GITEA_URL/api/v1/user
|
||||
```
|
||||
|
||||
### "Issue not found"
|
||||
```python
|
||||
# Use get_issue_by_number, not get_issue
|
||||
issue = backend.get_issue_by_number(42) # Correct
|
||||
# issue = backend.get_issue("42") # Wrong - needs backend_id
|
||||
```
|
||||
|
||||
## Full Documentation
|
||||
|
||||
- **Integration Guide:** `AGENT_INTEGRATION.md` (comprehensive patterns and strategies)
|
||||
- **API Reference:** `CLAUDE.md` (for developers extending the capability)
|
||||
- **Examples:** `examples/agents/` (working agent implementations)
|
||||
- **Roadmap:** `ROADMAP.md` (upcoming features)
|
||||
|
||||
## Current Limitations (v1.0)
|
||||
|
||||
Be aware of these limitations:
|
||||
|
||||
1. **Manual Configuration:** Backend must be configured before use (auto-detect in v1.1)
|
||||
2. **User Context:** Uses hardcoded user for CLI operations (agent identity in v1.2)
|
||||
3. **No Built-in Locking:** Use assignee + comment workaround for claiming (native in v1.2)
|
||||
4. **Basic Conflicts:** Manual resolution required for complex sync conflicts (advanced in v2.0)
|
||||
|
||||
Workarounds are documented in `AGENT_INTEGRATION.md`.
|
||||
|
||||
## Questions?
|
||||
|
||||
If you're unsure whether to use this capability for something:
|
||||
|
||||
**ASK:** "Does this involve creating, reading, updating, or searching issues?"
|
||||
- **YES** → Use this capability
|
||||
- **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
|
||||
316
.capability/integrate.sh
Executable file
316
.capability/integrate.sh
Executable file
@@ -0,0 +1,316 @@
|
||||
#!/bin/bash
|
||||
# Integration script for issue-facade capability
|
||||
# This script helps the main project discover and integrate the capability
|
||||
|
||||
set -e
|
||||
|
||||
CAPABILITY_NAME="issue-facade"
|
||||
CAPABILITY_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$CAPABILITY_DIR/../.." && pwd)}"
|
||||
|
||||
echo "🔧 Issue Facade Capability Integration"
|
||||
echo " Capability: $CAPABILITY_DIR"
|
||||
echo " Project: $PROJECT_ROOT"
|
||||
echo ""
|
||||
|
||||
# Function to check if something exists
|
||||
check_exists() {
|
||||
[ -e "$1" ] && echo "✓" || echo "✗"
|
||||
}
|
||||
|
||||
# Show current status
|
||||
echo "📊 Current Status:"
|
||||
echo " Issue command installed: $(check_exists "$(command -v issue)")"
|
||||
echo " Backend configured: $(issue backend list 2>/dev/null | grep -q "default" && echo "✓" || echo "✗")"
|
||||
echo " Claude config dir: $(check_exists "$PROJECT_ROOT/.claude")"
|
||||
echo ""
|
||||
|
||||
# Ask what to do
|
||||
echo "🎯 Integration Options:"
|
||||
echo " 1) Install capability (pip install -e)"
|
||||
echo " 2) Configure backend"
|
||||
echo " 3) Add to Claude Code context"
|
||||
echo " 4) Create slash command"
|
||||
echo " 5) Show integration checklist"
|
||||
echo " 6) Full setup (all of the above)"
|
||||
echo " 0) Exit"
|
||||
echo ""
|
||||
|
||||
read -p "Choose option [1-6, 0]: " choice
|
||||
|
||||
case $choice in
|
||||
1)
|
||||
echo ""
|
||||
echo "📦 Installing capability..."
|
||||
pip install -e "$CAPABILITY_DIR"
|
||||
echo "✓ Installed"
|
||||
echo ""
|
||||
echo "Verify with: issue --version"
|
||||
;;
|
||||
|
||||
2)
|
||||
echo ""
|
||||
echo "🔑 Configuring backend..."
|
||||
echo ""
|
||||
echo "You'll need:"
|
||||
echo " - Gitea URL (e.g., https://gitea.example.com)"
|
||||
echo " - Repository owner"
|
||||
echo " - Repository name"
|
||||
echo " - API token (set GITEA_API_TOKEN environment variable)"
|
||||
echo ""
|
||||
|
||||
if [ -z "$GITEA_API_TOKEN" ]; then
|
||||
echo "⚠️ GITEA_API_TOKEN not set"
|
||||
read -p "Enter token (or press Enter to skip): " token
|
||||
if [ -n "$token" ]; then
|
||||
export GITEA_API_TOKEN="$token"
|
||||
fi
|
||||
else
|
||||
echo "✓ Using GITEA_API_TOKEN from environment"
|
||||
fi
|
||||
|
||||
read -p "Backend name (e.g., myproject): " backend_name
|
||||
if [ -n "$backend_name" ]; then
|
||||
issue backend add "$backend_name" gitea
|
||||
echo ""
|
||||
read -p "Set as default? [y/N]: " set_default
|
||||
if [ "$set_default" = "y" ] || [ "$set_default" = "Y" ]; then
|
||||
issue backend set-default "$backend_name"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "✓ Backend configured"
|
||||
echo ""
|
||||
echo "Test with: issue list --limit=5"
|
||||
fi
|
||||
;;
|
||||
|
||||
3)
|
||||
echo ""
|
||||
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"
|
||||
|
||||
# Create or update context file
|
||||
CONTEXT_FILE="$PROJECT_ROOT/.claude/context/capabilities.md"
|
||||
mkdir -p "$(dirname "$CONTEXT_FILE")"
|
||||
|
||||
if [ ! -f "$CONTEXT_FILE" ]; then
|
||||
cat > "$CONTEXT_FILE" << 'EOF'
|
||||
# Available Capabilities
|
||||
|
||||
This project uses specialized capabilities. Always check for existing capabilities before implementing similar functionality.
|
||||
|
||||
## Issue Tracking: issue-facade
|
||||
|
||||
**Location:** `capabilities/issue-facade/`
|
||||
**Documentation:** `.claude/capabilities/issue-facade.md`
|
||||
**Priority:** CRITICAL (always use for issue operations)
|
||||
|
||||
**MUST USE FOR:**
|
||||
- Creating, reading, updating, searching issues
|
||||
- Multi-agent coordination via issue tracking
|
||||
- Querying issue state or assigning issues
|
||||
|
||||
**NEVER USE:**
|
||||
- Direct API calls to Gitea/GitHub/GitLab (`requests.post("/api/v1/repos/...")`)
|
||||
- Platform CLIs (`gh issue`, `glab issue`)
|
||||
- Platform libraries (`from github import Github`)
|
||||
|
||||
**Quick Start:**
|
||||
```python
|
||||
from issue_tracker.backends.gitea import GiteaBackend
|
||||
backend = GiteaBackend()
|
||||
backend.connect(config)
|
||||
issues = backend.list_issues()
|
||||
```
|
||||
|
||||
**Full Documentation:** See `.claude/capabilities/issue-facade.md`
|
||||
EOF
|
||||
echo "✓ Created $CONTEXT_FILE"
|
||||
else
|
||||
echo "✓ Context file exists: $CONTEXT_FILE"
|
||||
echo " (Review and update manually if needed)"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "✓ Added to Claude Code context"
|
||||
echo ""
|
||||
echo "Files created:"
|
||||
echo " - $PROJECT_ROOT/.claude/capabilities/issue-facade.md"
|
||||
echo " - $CONTEXT_FILE"
|
||||
;;
|
||||
|
||||
4)
|
||||
echo ""
|
||||
echo "⚡ Creating slash command..."
|
||||
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**:
|
||||
|
||||
## 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
|
||||
|
||||
backend = GiteaBackend()
|
||||
backend.connect(config)
|
||||
|
||||
# Query issues
|
||||
issues = backend.list_issues(IssueFilter(state='open', labels=['bug']))
|
||||
|
||||
# Create issue
|
||||
issue = Issue(...)
|
||||
backend.create_issue(issue)
|
||||
|
||||
# Update
|
||||
issue.state = IssueState.CLOSED
|
||||
backend.update_issue(issue)
|
||||
```
|
||||
|
||||
**CLI:**
|
||||
```bash
|
||||
issue list --state=open --label=bug --format=json
|
||||
issue create "Title" --label=bug --description="Details"
|
||||
issue edit 42 --state=in_progress
|
||||
issue close 42 --comment="Fixed"
|
||||
```
|
||||
|
||||
## Critical Reminders
|
||||
|
||||
**DO NOT:**
|
||||
- ❌ Make direct API calls to Gitea/GitHub/GitLab
|
||||
- ❌ Use `gh` or `glab` CLI tools
|
||||
- ❌ Import PyGithub, python-gitlab, or similar libraries
|
||||
- ❌ Parse HTML or scrape web UIs
|
||||
|
||||
**WHY:** Bypassing the capability causes credential sprawl, token waste, and race conditions.
|
||||
|
||||
## Full Documentation
|
||||
|
||||
See `capabilities/issue-facade/AGENT_INTEGRATION.md` for:
|
||||
- Complete API reference
|
||||
- Coordination patterns
|
||||
- Error handling
|
||||
- Performance tips
|
||||
- Working examples
|
||||
|
||||
EOF
|
||||
echo "✓ Created slash command: /use-issues"
|
||||
echo ""
|
||||
echo "Usage in Claude Code:"
|
||||
echo " /use-issues"
|
||||
echo ""
|
||||
echo "This will inject issue-facade context into the conversation."
|
||||
;;
|
||||
|
||||
5)
|
||||
echo ""
|
||||
cat "$CAPABILITY_DIR/.capability/integration-checklist.md"
|
||||
;;
|
||||
|
||||
6)
|
||||
echo ""
|
||||
echo "🚀 Full Setup"
|
||||
echo "=============="
|
||||
echo ""
|
||||
|
||||
# Step 1: Install
|
||||
echo "Step 1/4: Installing capability..."
|
||||
pip install -e "$CAPABILITY_DIR" || { echo "❌ Installation failed"; exit 1; }
|
||||
echo "✓ Installed"
|
||||
echo ""
|
||||
|
||||
# Step 2: Configure
|
||||
echo "Step 2/4: Configuring backend..."
|
||||
echo ""
|
||||
if [ -z "$GITEA_API_TOKEN" ]; then
|
||||
echo "⚠️ GITEA_API_TOKEN not set"
|
||||
echo " Please set it and run this script again,"
|
||||
echo " or configure manually with: issue backend add <name> gitea"
|
||||
echo ""
|
||||
else
|
||||
read -p "Backend name [myproject]: " backend_name
|
||||
backend_name="${backend_name:-myproject}"
|
||||
issue backend add "$backend_name" gitea || true
|
||||
issue backend set-default "$backend_name" || true
|
||||
echo "✓ Backend configured"
|
||||
echo ""
|
||||
fi
|
||||
|
||||
# Step 3: Claude context
|
||||
echo "Step 3/4: Adding to Claude Code..."
|
||||
mkdir -p "$PROJECT_ROOT/.claude/capabilities"
|
||||
mkdir -p "$PROJECT_ROOT/.claude/commands"
|
||||
mkdir -p "$PROJECT_ROOT/.claude/context"
|
||||
|
||||
cp "$CAPABILITY_DIR/.capability/agent-context.md" \
|
||||
"$PROJECT_ROOT/.claude/capabilities/issue-facade.md"
|
||||
|
||||
# Create context file if not exists
|
||||
CONTEXT_FILE="$PROJECT_ROOT/.claude/context/capabilities.md"
|
||||
if [ ! -f "$CONTEXT_FILE" ]; then
|
||||
cat > "$CONTEXT_FILE" << 'EOF'
|
||||
# Available Capabilities
|
||||
|
||||
## Issue Tracking: issue-facade
|
||||
|
||||
**CRITICAL:** Always use this for issue operations. Never bypass with direct API calls.
|
||||
|
||||
**Docs:** `.claude/capabilities/issue-facade.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.
|
||||
|
||||
**Quick reference:** See `.claude/capabilities/issue-facade.md`
|
||||
**Examples:** See `capabilities/issue-facade/examples/agents/`
|
||||
|
||||
**DO NOT use direct API calls or platform CLIs!**
|
||||
EOF
|
||||
|
||||
echo "✓ Claude Code configured"
|
||||
echo ""
|
||||
|
||||
# Step 4: Verify
|
||||
echo "Step 4/4: Verifying setup..."
|
||||
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/commands/use-issues.md" ] && echo "✓ Slash command exists" || echo "❌ Slash command missing"
|
||||
|
||||
echo ""
|
||||
echo "✅ Setup complete!"
|
||||
echo ""
|
||||
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/"
|
||||
;;
|
||||
|
||||
0)
|
||||
echo "Exiting."
|
||||
exit 0
|
||||
;;
|
||||
|
||||
*)
|
||||
echo "Invalid option"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
echo ""
|
||||
echo "📚 Additional Resources:"
|
||||
echo " - Integration guide: $CAPABILITY_DIR/AGENT_INTEGRATION.md"
|
||||
echo " - Checklist: $CAPABILITY_DIR/.capability/integration-checklist.md"
|
||||
echo " - Examples: $CAPABILITY_DIR/examples/agents/"
|
||||
echo ""
|
||||
293
.capability/integration-checklist.md
Normal file
293
.capability/integration-checklist.md
Normal file
@@ -0,0 +1,293 @@
|
||||
# Issue Facade Integration Checklist
|
||||
|
||||
**For project maintainers integrating this capability into their codebase.**
|
||||
|
||||
## Pre-Integration
|
||||
|
||||
- [ ] **Verify Python version:** >= 3.8
|
||||
- [ ] **Check issue tracker platform:** Gitea (✅), GitHub (🚧 v1.1), GitLab (🚧 v1.2)
|
||||
- [ ] **Obtain API token:** Read-only for monitoring, write for implementation
|
||||
- [ ] **Document token storage:** Environment variable or secure secret manager
|
||||
|
||||
## Installation
|
||||
|
||||
- [ ] **Install capability:**
|
||||
```bash
|
||||
pip install -e capabilities/issue-facade/
|
||||
```
|
||||
|
||||
- [ ] **Verify installation:**
|
||||
```bash
|
||||
issue --version
|
||||
```
|
||||
|
||||
- [ ] **Configure backend (one-time):**
|
||||
```bash
|
||||
export GITEA_API_TOKEN="your-token"
|
||||
issue backend add myproject gitea
|
||||
# Provide: URL, owner, repo when prompted
|
||||
issue backend set-default myproject
|
||||
```
|
||||
|
||||
- [ ] **Test connection:**
|
||||
```bash
|
||||
issue backend test myproject
|
||||
issue list --limit=5
|
||||
```
|
||||
|
||||
## Project Integration
|
||||
|
||||
### Option 1: Agent Context File (Recommended)
|
||||
|
||||
- [ ] **Copy agent context to project:**
|
||||
```bash
|
||||
mkdir -p .claude/capabilities/
|
||||
cp capabilities/issue-facade/.capability/agent-context.md \
|
||||
.claude/capabilities/issue-facade.md
|
||||
```
|
||||
|
||||
- [ ] **Add to Claude Code context:**
|
||||
Create `.claude/context/capabilities.md`:
|
||||
```markdown
|
||||
# Available Capabilities
|
||||
|
||||
This project uses specialized capabilities. Always check these before implementing similar functionality.
|
||||
|
||||
## Issue Tracking: issue-facade
|
||||
|
||||
**Location:** `capabilities/issue-facade/`
|
||||
**Documentation:** `.claude/capabilities/issue-facade.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.
|
||||
```
|
||||
|
||||
### Option 2: Slash Command
|
||||
|
||||
- [ ] **Create slash command:**
|
||||
Create `.claude/commands/use-issues.md`:
|
||||
```markdown
|
||||
You are working with issue tracking. Use the issue-facade capability:
|
||||
|
||||
**Python API:**
|
||||
```python
|
||||
from issue_tracker.backends.gitea import GiteaBackend
|
||||
backend = GiteaBackend()
|
||||
backend.connect(config)
|
||||
```
|
||||
|
||||
**CLI:**
|
||||
```bash
|
||||
issue list --format=json
|
||||
issue create "Title" --label=bug
|
||||
```
|
||||
|
||||
**Full docs:** See `capabilities/issue-facade/AGENT_INTEGRATION.md`
|
||||
|
||||
**DO NOT use direct API calls or platform CLIs!**
|
||||
```
|
||||
|
||||
- [ ] **Test slash command:**
|
||||
```bash
|
||||
# In Claude Code
|
||||
/use-issues
|
||||
```
|
||||
|
||||
### Option 3: MCP Server (Future - v1.2)
|
||||
|
||||
- [ ] **Configure MCP server** (when available)
|
||||
- [ ] **Register tools in Claude Code**
|
||||
- [ ] **Test tool discovery**
|
||||
|
||||
## Agent Configuration
|
||||
|
||||
- [ ] **Set agent identity:**
|
||||
Add to `.issue-facade/config.json`:
|
||||
```json
|
||||
{
|
||||
"agent": {
|
||||
"identity": "agent-coder",
|
||||
"type": "implementation"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Or use environment variables:**
|
||||
```bash
|
||||
export ISSUE_AGENT_ID="agent-coder"
|
||||
export ISSUE_AGENT_TYPE="coder"
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
- [ ] **Test basic operations:**
|
||||
```python
|
||||
from issue_tracker.backends.gitea import GiteaBackend
|
||||
from issue_tracker.core.interfaces import IssueFilter
|
||||
|
||||
backend = GiteaBackend()
|
||||
backend.connect({'base_url': '...', 'token': '...', 'owner': '...', 'repo': '...'})
|
||||
|
||||
# Should return issues
|
||||
issues = backend.list_issues(IssueFilter(state='open', limit=5))
|
||||
print(f"Found {len(issues)} issues")
|
||||
```
|
||||
|
||||
- [ ] **Test CLI:**
|
||||
```bash
|
||||
issue list --state=open --format=json | jq 'length'
|
||||
```
|
||||
|
||||
- [ ] **Verify agents use capability:**
|
||||
- Create test issue via agent
|
||||
- Check it appears in tracker
|
||||
- Verify token from environment was used (not hardcoded)
|
||||
|
||||
## Documentation Updates
|
||||
|
||||
- [ ] **Update project README:**
|
||||
```markdown
|
||||
## Issue Tracking
|
||||
|
||||
This project uses the issue-facade capability for unified issue tracking.
|
||||
|
||||
**Setup:**
|
||||
```bash
|
||||
pip install -e capabilities/issue-facade/
|
||||
export GITEA_API_TOKEN="your-token"
|
||||
issue backend add myproject gitea
|
||||
```
|
||||
|
||||
**Usage:** See `capabilities/issue-facade/AGENT_INTEGRATION.md`
|
||||
```
|
||||
|
||||
- [ ] **Add to CONTRIBUTING.md:**
|
||||
```markdown
|
||||
### Issue Tracking
|
||||
|
||||
Always use the `issue` command or Python API from `issue_tracker` package.
|
||||
Never make direct API calls to Gitea/GitHub/GitLab.
|
||||
|
||||
Examples: `capabilities/issue-facade/examples/agents/`
|
||||
```
|
||||
|
||||
## Security Review
|
||||
|
||||
- [ ] **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
|
||||
```
|
||||
|
||||
- [ ] **Audit token permissions:** Read-only for bots, write for implementation
|
||||
- [ ] **Document token rotation:** How often, who has access
|
||||
|
||||
## Testing
|
||||
|
||||
- [ ] **Run capability tests:**
|
||||
```bash
|
||||
cd capabilities/issue-facade/
|
||||
make test
|
||||
```
|
||||
|
||||
- [ ] **Test agent workflows:**
|
||||
```bash
|
||||
python examples/agents/simple_task_executor.py --once
|
||||
```
|
||||
|
||||
- [ ] **Verify multi-agent coordination:**
|
||||
```bash
|
||||
python examples/agents/multi_agent_pipeline.py --mode=roundrobin --max-iterations=1
|
||||
```
|
||||
|
||||
## Maintenance
|
||||
|
||||
- [ ] **Schedule regular updates:**
|
||||
```bash
|
||||
cd capabilities/issue-facade/
|
||||
git pull origin main
|
||||
pip install -e . --upgrade
|
||||
```
|
||||
|
||||
- [ ] **Monitor capability roadmap:** Check `ROADMAP.md` for new features
|
||||
- [ ] **Subscribe to updates:** Watch the capability repository
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If capability causes issues:
|
||||
|
||||
- [ ] **Document how to disable:**
|
||||
```bash
|
||||
# Temporarily use direct API
|
||||
export ISSUE_FACADE_DISABLED=1
|
||||
# Or
|
||||
issue backend remove myproject
|
||||
```
|
||||
|
||||
- [ ] **Keep backup config:**
|
||||
```bash
|
||||
cp ~/.config/issue-facade/backends.json ~/.config/issue-facade/backends.json.backup
|
||||
```
|
||||
|
||||
- [ ] **Document rollback steps in project wiki/docs**
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Agents successfully create/update issues via capability
|
||||
- [ ] No direct API calls in agent code (verified via code review)
|
||||
- [ ] Token management centralized (one env var, not scattered)
|
||||
- [ ] Multi-agent coordination works (no race conditions)
|
||||
- [ ] Offline/online sync works (if using local backend)
|
||||
|
||||
## Post-Integration
|
||||
|
||||
- [ ] **Share integration experience:** Document what worked, what didn't
|
||||
- [ ] **Contribute improvements:** PRs to capability for common patterns
|
||||
- [ ] **Update capability docs:** Add project-specific examples
|
||||
- [ ] **Monitor agent usage:** Are they using capability correctly?
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Agents bypass capability
|
||||
|
||||
**Problem:** Agent makes direct API call instead of using capability.
|
||||
|
||||
**Solution:**
|
||||
1. Check Claude Code context includes capability docs
|
||||
2. Add explicit reminder in `.claude/context/`
|
||||
3. Use slash command `/use-issues` before agent work
|
||||
4. Review agent logs for why it chose direct API
|
||||
|
||||
### Configuration not found
|
||||
|
||||
**Problem:** `issue backend list` shows empty.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
issue backend add myproject gitea
|
||||
issue backend set-default myproject
|
||||
issue backend test myproject
|
||||
```
|
||||
|
||||
### Authentication failures
|
||||
|
||||
**Problem:** "401 Unauthorized" errors.
|
||||
|
||||
**Solution:**
|
||||
1. Verify token: `echo $GITEA_API_TOKEN`
|
||||
2. Test token: `curl -H "Authorization: token $GITEA_API_TOKEN" $GITEA_URL/api/v1/user`
|
||||
3. Check token hasn't expired
|
||||
4. Verify token has correct permissions
|
||||
|
||||
## Questions?
|
||||
|
||||
- **Technical:** See `CLAUDE.md` (development guide)
|
||||
- **Agent patterns:** See `AGENT_INTEGRATION.md` (comprehensive guide)
|
||||
- **Examples:** See `examples/agents/` (working code)
|
||||
- **Issues:** Create issue in capability repository
|
||||
Reference in New Issue
Block a user