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/`
|
||||
Reference in New Issue
Block a user