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

@@ -251,7 +251,7 @@ This capability implements the **feedback pattern** - a lightweight, unstructure
### Overview
The feedback system consists of:
- **`.feedback/` directory**: Stores all feedback with minimal organization
- **`feedback/` directory**: Stores all feedback with minimal organization
- **`.capability/feedback` CLI tool**: Standalone tool for submitting and managing feedback
- **No structure imposement**: Accept any text/markdown format
- **Capability-owned**: Maintainers organize and prioritize feedback
@@ -285,7 +285,7 @@ Users of issue-facade (master projects integrating it) can submit feedback in mu
**Option 2: Direct file drop (no CLI needed)**
```bash
# Just create a markdown file in inbound/
cat > .feedback/inbound/$(date +%Y%m%d)-sync-issue.md << 'EOF'
cat > feedback/inbound/$(date +%Y%m%d)-sync-issue.md << 'EOF'
The sync is taking 10+ minutes with our 5000-issue repo.
Would love to see progress indicators or batch processing.
EOF
@@ -295,7 +295,7 @@ EOF
```bash
cd my-master-project
echo "Feedback about issue-facade..." > feedback.md
cp feedback.md capabilities/issue-facade/.feedback/inbound/$(date +%Y%m%d)-feedback.md
cp feedback.md capabilities/issue-facade/feedback/inbound/$(date +%Y%m%d)-feedback.md
```
### For Maintainers: Processing Feedback
@@ -327,18 +327,18 @@ cp feedback.md capabilities/issue-facade/.feedback/inbound/$(date +%Y%m%d)-feedb
**Manual workflow (without CLI):**
```bash
# 1. List new feedback
ls -lt .feedback/inbound/
ls -lt feedback/inbound/
# 2. Read feedback
cat .feedback/inbound/20251217-103045-sync-issue.md
cat feedback/inbound/20251217-103045-sync-issue.md
# 3. Take action (create issue, fix, document)
issue create "Feature: Show sync progress" \
--description "$(cat .feedback/inbound/20251217-103045-sync-issue.md)" \
--description "$(cat feedback/inbound/20251217-103045-sync-issue.md)" \
--label=feedback --label=feature
# 4. Move to reviewed
mv .feedback/inbound/20251217-103045-sync-issue.md .feedback/reviewed/
mv feedback/inbound/20251217-103045-sync-issue.md feedback/reviewed/
```
### Integration with Development Workflow
@@ -360,20 +360,20 @@ The feedback system is **capability-agnostic** and can be copied to any markitec
1. **Copy the pattern:**
```bash
mkdir -p .feedback/inbound .feedback/reviewed .feedback/archived
mkdir -p feedback/inbound feedback/reviewed feedback/archived
cp /path/to/feedback-template/README.md .feedback/
cp /path/to/feedback-template/feedback .capability/
chmod +x .capability/feedback
```
2. **Document in CAPABILITY.yaml:**
2. **Document in CAPABILITY-issue-tracking.yaml:**
```yaml
feedback:
enabled: true
method: feedback-capability
submission:
cli: ".capability/feedback submit 'Your feedback'"
directory: ".feedback/inbound/"
directory: "feedback/inbound/"
```
3. **Add to Makefile (optional):**
@@ -384,7 +384,7 @@ The feedback system is **capability-agnostic** and can be copied to any markitec
**Future Evolution:**
- When capability becomes a service, add API endpoint: `POST /api/feedback`
- API writes to same `.feedback/inbound/` directory
- API writes to same `feedback/inbound/` directory
- Maintains consistency across CLI, file drop, and API submission
### Why This Pattern?
@@ -397,4 +397,4 @@ The feedback system is **capability-agnostic** and can be copied to any markitec
- **Scalable**: Works for 1 user or 1000 users
- **Future-proof**: Can evolve to CLI/API while maintaining structure
See `.feedback/README.md` for complete documentation.
See `feedback/README.md` for complete documentation.