refactor: align with ReusableCapabilitiesArchitecture v0.1

Refactor issue-facade to conform to the new ReusableCapabilitiesArchitecture
specification, improving discoverability and establishing consistent patterns
for capability integration.

Architecture Changes:
- Rename .feedback/ → feedback/ (visible user interface)
- Rename CAPABILITY.yaml → CAPABILITY-issue-tracking.yaml (explicit family)
- Keep .capability/ hidden (evolving implementation infrastructure)

File Updates:
- Updated all documentation references (.feedback → feedback)
- Updated .capability/feedback script paths
- Updated Makefile, README.md, CLAUDE.md, examples
- Fixed CAPABILITY.yaml → CAPABILITY-issue-tracking.yaml references

New Tools:
- Created .capability/detach script for clean capability removal
- Supports git submodule and directory-based integrations
- Generates detachment manifest for re-integration guidance

Rationale:
- feedback/ is visible: encourages user participation, shows capability identity
- .capability/ is hidden: implementation details that will evolve
- CAPABILITY-<family>.yaml: explicit family declaration, supports multiple capabilities per repo
- Underscore prefix pattern: flatter hierarchy, clear signal of integration

This aligns with the principle that capabilities are conceptual units
designed for natural language integration by devhumans and devagents,
not just technical libraries.

See ReusableCapabilitiesArchitecture.md for complete specification.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
2025-12-17 22:22:47 +01:00
parent 1627fd9673
commit 35daa514e5
8 changed files with 1469 additions and 61 deletions

View File

@@ -17,7 +17,7 @@
### 1. Self-Description (Machine-Readable)
**File:** `CAPABILITY.yaml`
**File:** `CAPABILITY-issue-tracking.yaml`
Contains machine-readable metadata that agents and tooling can parse:
- What the capability does
@@ -29,7 +29,7 @@ Contains machine-readable metadata that agents and tooling can parse:
**Usage:**
```bash
# Tools can parse this to understand capabilities
yq eval '.purpose.primary' CAPABILITY.yaml
yq eval '.purpose.primary' CAPABILITY-issue-tracking.yaml
# Output: "Agent coordination via issue tracking"
```
@@ -117,7 +117,7 @@ Agent Workflow
project-root/
├── capabilities/
│ └── issue-facade/ # Capability code
│ ├── CAPABILITY.yaml # Machine-readable metadata
│ ├── CAPABILITY-issue-tracking.yaml # Machine-readable metadata
│ ├── .capability/
│ │ ├── agent-context.md # Agent guide (source)
│ │ ├── integrate.sh # Integration script
@@ -228,7 +228,7 @@ backend.create_issue(issue)
**1. Create capability structure:**
```
capabilities/your-capability/
├── CAPABILITY.yaml # Metadata
├── CAPABILITY-issue-tracking.yaml # Metadata
├── .capability/
│ ├── agent-context.md # Agent guide
│ ├── integrate.sh # Integration script
@@ -237,7 +237,7 @@ capabilities/your-capability/
└── your_package/ # Implementation
```
**2. Write CAPABILITY.yaml:**
**2. Write CAPABILITY-issue-tracking.yaml:**
```yaml
metadata:
name: your-capability
@@ -287,7 +287,7 @@ make integrate
### Manual Discovery (Human)
1. Human sees `capabilities/` directory
2. Reads `CAPABILITY.yaml` to understand what's available
2. Reads `CAPABILITY-issue-tracking.yaml` to understand what's available
3. Runs `make integrate` to set up for agents
### Automatic Discovery (Agent)
@@ -386,7 +386,7 @@ A: Document rollback in integration checklist. Keep backup configs. Have fallbac
**The capability bootstrap system works by:**
1. **Self-description** - Capability declares what it does (CAPABILITY.yaml)
1. **Self-description** - Capability declares what it does (CAPABILITY-issue-tracking.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