tegwick
f88e9a28fe
Add MappingService (work_record_uuid ↔ external id), project/map CLI with outward push-status, optional TaskSpec work_record fields, boundary-sync policy, and packaging/capability framing cleanup. Mark WP-0005 finished.
276 lines
8.6 KiB
YAML
276 lines
8.6 KiB
YAML
# Issue Core Capability Manifest
|
|
# This file describes the capability to coding agents and integration systems
|
|
|
|
metadata:
|
|
name: issue-core
|
|
version: 0.2.1
|
|
type: connector
|
|
description: >
|
|
Backend-agnostic connector to external issue trackers (Gitea/Forgejo, SQLite).
|
|
Maps work-record UUIDs to external issue ids. Not the origin of fleet work records.
|
|
|
|
# What problems this capability solves
|
|
purpose:
|
|
primary: External tracker projection and ops (work-record-aware connector)
|
|
problems_solved:
|
|
- Direct API calls to Gitea/GitHub/GitLab (credential sprawl)
|
|
- No durable link from work-record UUID to tracker issue
|
|
- Platform-specific agent code for tracker CRUD
|
|
- Offline SQLite cache / backend sync for tracker data
|
|
|
|
# When agents should use this capability
|
|
usage_rules:
|
|
MUST_USE_INSTEAD_OF:
|
|
- "Direct Gitea API calls (requests.post to /api/v1/repos/...)"
|
|
- "GitHub CLI (gh issue create/list/...)"
|
|
- "GitLab CLI (glab issue create/list/...)"
|
|
- "Python libraries (PyGithub, python-gitlab) for routine tracker ops"
|
|
|
|
PREFER_OVER:
|
|
- "Ad hoc curl scripts against tracker APIs"
|
|
- "Fire-and-forget Forgejo issues with no work-record mapping"
|
|
|
|
USE_WHEN:
|
|
- "Projecting or linking a work record to an external issue"
|
|
- "Creating, updating, or querying issues on a tracker backend"
|
|
- "Offline tracker work with backend sync"
|
|
- "Intentional external issues (not fleet intake origin)"
|
|
|
|
DO_NOT_USE_WHEN:
|
|
- "Spawning fleet tasks/intake (use work records + promotion)"
|
|
- "Default sink for internal automation findings (see ACTIVITY-WP-0022)"
|
|
|
|
# How to integrate this capability
|
|
integration:
|
|
methods:
|
|
python_api:
|
|
available: true
|
|
import: "from issue_core.backends.gitea import GiteaBackend"
|
|
docs: "AGENT_INTEGRATION.md"
|
|
|
|
cli:
|
|
available: true
|
|
command: "issue"
|
|
subcommands: ["list", "create", "show", "edit", "close", "comment"]
|
|
json_output: true
|
|
|
|
mcp_server:
|
|
available: false # Future: Phase 2
|
|
status: planned
|
|
|
|
installation:
|
|
method: pip
|
|
command: "pip install -e capabilities/issue-core/"
|
|
verify: "issue --version"
|
|
|
|
configuration:
|
|
required: true
|
|
method: manual # v1.0 - auto in v1.1
|
|
steps:
|
|
- "Export GITEA_API_TOKEN environment variable"
|
|
- "Run: issue backend add myproject gitea"
|
|
- "Provide: URL, owner, repo when prompted"
|
|
- "Run: issue backend set-default myproject"
|
|
|
|
# API surface for agents
|
|
api:
|
|
core_operations:
|
|
- name: list_issues
|
|
description: Query issues with filtering
|
|
python: "backend.list_issues(IssueFilter(state='open', labels=['bug']))"
|
|
cli: "issue list --state=open --label=bug --format=json"
|
|
|
|
- name: create_issue
|
|
description: Create new issue
|
|
python: "backend.create_issue(Issue(...))"
|
|
cli: "issue create 'Title' --label=bug --assignee=agent"
|
|
|
|
- name: update_issue
|
|
description: Update existing issue
|
|
python: "backend.update_issue(issue)"
|
|
cli: "issue edit 42 --state=in_progress"
|
|
|
|
- name: add_comment
|
|
description: Add comment to issue
|
|
python: "backend.add_comment(issue.id, comment)"
|
|
cli: "issue comment 42 'Progress update'"
|
|
|
|
- name: close_issue
|
|
description: Close issue
|
|
python: "issue.state = IssueState.CLOSED; backend.update_issue(issue)"
|
|
cli: "issue close 42 --comment='Done'"
|
|
|
|
# Performance and efficiency
|
|
efficiency:
|
|
local_caching: true
|
|
offline_mode: true
|
|
batch_operations: false # v1.0 limitation
|
|
rate_limiting: automatic
|
|
|
|
token_savings:
|
|
vs_direct_api: "~70% fewer tokens (uses local cache + structured models)"
|
|
vs_cli_tools: "~50% fewer tokens (JSON output vs parsing text)"
|
|
|
|
# Credential management
|
|
credentials:
|
|
method: environment_variables
|
|
variables:
|
|
- GITEA_API_TOKEN
|
|
- GITEA_URL (optional with config)
|
|
|
|
security:
|
|
- "Tokens never in code or logs"
|
|
- "Config stored in ~/.config/issue-core/"
|
|
- "Per-repo config in .issue-core/ (gitignored)"
|
|
|
|
best_practices:
|
|
- "Use read-only tokens for monitoring agents"
|
|
- "Use write tokens only for implementation agents"
|
|
- "Rotate tokens regularly"
|
|
|
|
# Agent integration guidance
|
|
agent_guidance:
|
|
quick_start: |
|
|
# For Python agents:
|
|
from issue_core.backends.gitea import GiteaBackend
|
|
from issue_core.core.interfaces import IssueFilter
|
|
|
|
backend = GiteaBackend()
|
|
backend.connect(config)
|
|
issues = backend.list_issues(IssueFilter(state='open'))
|
|
|
|
# For CLI/shell agents:
|
|
issue list --format=json | jq '.[] | {number, title, state}'
|
|
|
|
coordination_pattern: |
|
|
# Claim issue to prevent race conditions
|
|
issue edit 42 --assignee=my-agent-id --state=in_progress
|
|
issue comment 42 "Starting work..."
|
|
|
|
# Do work...
|
|
|
|
issue comment 42 "Completed: <summary>"
|
|
issue close 42 --comment="Done"
|
|
|
|
error_handling: |
|
|
# Check exit codes
|
|
if ! issue backend test myproject; then
|
|
echo "Backend not configured or unavailable"
|
|
exit 1
|
|
fi
|
|
|
|
# Feedback and continuous improvement
|
|
feedback:
|
|
enabled: true
|
|
method: feedback-capability
|
|
description: >
|
|
This capability integrates the feedback pattern for continuous improvement
|
|
based on real-world usage from master projects.
|
|
|
|
submission:
|
|
cli: ".capability/feedback submit 'Your feedback here'"
|
|
file: ".capability/feedback submit path/to/feedback.md"
|
|
directory: "feedback/inbound/"
|
|
|
|
organization:
|
|
inbound: "New feedback awaiting review"
|
|
reviewed: "Feedback that's been reviewed by maintainers"
|
|
archived: "Resolved or outdated feedback"
|
|
|
|
for_users: |
|
|
Submit feedback about issue-core:
|
|
./.capability/feedback submit "Feedback text"
|
|
./.capability/feedback submit detailed-feedback.md
|
|
|
|
Or drop a file directly:
|
|
echo "Feedback..." > feedback/inbound/$(date +%Y%m%d)-feedback.md
|
|
|
|
for_maintainers: |
|
|
Review feedback:
|
|
./.capability/feedback list
|
|
./.capability/feedback show <filename>
|
|
./.capability/feedback review <filename> --create-issue
|
|
./.capability/feedback stats
|
|
|
|
integration_notes:
|
|
- "Feedback capability is reusable across all markitect capabilities"
|
|
- "No structure imposement - accepts any text/markdown format"
|
|
- "Capability owns feedback organization and prioritization"
|
|
- "Can evolve to API endpoint when capability becomes a service"
|
|
|
|
# Documentation references
|
|
documentation:
|
|
integration: "AGENT_INTEGRATION.md"
|
|
development: "CLAUDE.md"
|
|
roadmap: "ROADMAP.md"
|
|
examples: "examples/agents/"
|
|
feedback: "feedback/README.md"
|
|
|
|
# Dependencies and requirements
|
|
requirements:
|
|
runtime:
|
|
python: ">=3.8"
|
|
packages:
|
|
- "click>=8.0.0"
|
|
- "requests>=2.25.0"
|
|
- "python-dateutil>=2.8.0"
|
|
|
|
optional:
|
|
- "jq (for JSON parsing in shell)"
|
|
- "sqlite3 (usually pre-installed)"
|
|
|
|
# Current limitations (v1.0)
|
|
limitations:
|
|
- "Manual backend configuration required (auto-detect in v1.1)"
|
|
- "No built-in issue locking (workaround via assignee + comment)"
|
|
- "Basic conflict resolution (advanced in v2.0)"
|
|
- "Hardcoded user context (agent identity in v1.2)"
|
|
|
|
# Roadmap for capability evolution
|
|
roadmap:
|
|
v1.1:
|
|
- "Auto-detection from git remotes"
|
|
- "Environment-only configuration"
|
|
- "Zero-setup for common platforms"
|
|
v1.2:
|
|
- "Agent identity management"
|
|
- "Native issue claiming/locking"
|
|
- "Webhook support"
|
|
v2.0:
|
|
- "Issue dependencies"
|
|
- "Query DSL"
|
|
- "Distributed locking"
|
|
|
|
# Testing and validation
|
|
testing:
|
|
test_command: "make test"
|
|
coverage: 61%
|
|
test_count: 109
|
|
|
|
verify_installation: |
|
|
# Verify capability is working
|
|
issue backend list # Should show configured backends
|
|
issue list --format=json | jq 'length' # Should return issue count
|
|
|
|
# Support and troubleshooting
|
|
support:
|
|
common_issues:
|
|
- problem: "Backend not configured"
|
|
solution: "Run: issue backend add <name> <type>"
|
|
|
|
- problem: "Authentication failed"
|
|
solution: "Check GITEA_API_TOKEN is set and valid"
|
|
|
|
- problem: "Command not found: issue"
|
|
solution: "Run: pip install -e capabilities/issue-core/"
|
|
|
|
# Integration priority score (higher = more important for agent to use)
|
|
priority:
|
|
score: 95 # 0-100, where 100 = critical
|
|
reasoning: >
|
|
Critical for agent coordination. Bypassing this capability leads to:
|
|
- Credential management issues
|
|
- Inconsistent issue state
|
|
- Token waste
|
|
- Platform lock-in
|
|
- Race conditions in multi-agent scenarios
|