coulomb/issue-core
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Projects Releases Wiki Activity

refactor: align with ReusableCapabilitiesArchitecture v0.1

Browse Source 
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:
Bernd Worsch
2025-12-17 22:22:47 +01:00
parent 1627fd9673
commit 35daa514e5
8 changed files with 1469 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
.capability/README.md
View File

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

226
.capability/detach Executable file
View File

@@ -0,0 +1,226 @@
#!/usr/bin/env bash
# detach - Remove this capability from an integrating project
#
# Usage:
# From the capability root:
# ./.capability/detach
#
# From integrating project:
# _issue-facade/.capability/detach
# # or
# capabilities/issue-facade/.capability/detach
#
# This script helps cleanly remove a capability integration, creating
# a manifest for potential re-integration with updated architecture.
set -e
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'
info() { echo -e "${BLUE}$1${NC}"; }
success() { echo -e "${GREEN}$1${NC}"; }
warn() { echo -e "${YELLOW}$1${NC}"; }
error() { echo -e "${RED}Error: $1${NC}" >&2; exit 1; }
# Detect capability information
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
CAPABILITY_ROOT="$(dirname "$SCRIPT_DIR")"
CAPABILITY_NAME="$(basename "$CAPABILITY_ROOT")"
# Try to read capability metadata
CAPABILITY_FILE=""
if [ -f "$CAPABILITY_ROOT"/CAPABILITY-*.yaml ]; then
CAPABILITY_FILE=$(ls "$CAPABILITY_ROOT"/CAPABILITY-*.yaml | head -1)
CAPABILITY_FAMILY=$(basename "$CAPABILITY_FILE" .yaml | sed 's/^CAPABILITY-//')
else
warn "No CAPABILITY-*.yaml file found, using directory name"
CAPABILITY_FAMILY="$CAPABILITY_NAME"
fi
echo -e "${BLUE}╔════════════════════════════════════════════════╗${NC}"
echo -e "${BLUE}║ Capability Detachment Tool ║${NC}"
echo -e "${BLUE}╔════════════════════════════════════════════════╝${NC}"
echo ""
info "Capability: $CAPABILITY_NAME"
info "Family: $CAPABILITY_FAMILY"
info "Location: $CAPABILITY_ROOT"
echo ""
# Detect parent project
PARENT_DIR="$(dirname "$CAPABILITY_ROOT")"
PARENT_NAME="$(basename "$PARENT_DIR")"
# Determine integration pattern
INTEGRATION_PATTERN="unknown"
if [[ "$CAPABILITY_NAME" == _* ]]; then
INTEGRATION_PATTERN="underscore-prefix"
elif [[ "$PARENT_NAME" == "capabilities" ]]; then
INTEGRATION_PATTERN="capabilities-directory"
elif [[ "$PARENT_NAME" == "c" ]]; then
INTEGRATION_PATTERN="short-alias"
else
INTEGRATION_PATTERN="custom"
fi
info "Integration pattern: $INTEGRATION_PATTERN"
echo ""
# Safety check
warn "⚠️ This will remove the capability integration from the parent project."
echo ""
echo "The following will happen:"
echo " 1. Create detachment manifest (DETACHED-$CAPABILITY_NAME.yaml)"
echo " 2. Remove capability directory: $CAPABILITY_ROOT"
echo " 3. Clean up any integration artifacts"
echo ""
read -p "Continue? (yes/no): " confirm
if [[ "$confirm" != "yes" ]]; then
info "Detachment cancelled."
exit 0
fi
echo ""
info "Creating detachment manifest..."
# Create detachment manifest
MANIFEST_FILE="$PARENT_DIR/DETACHED-$CAPABILITY_NAME.yaml"
cat > "$MANIFEST_FILE" <<EOF
# Detachment Manifest
# This file records the removal of the $CAPABILITY_NAME capability
# Use this information to re-integrate with updated architecture
detachment:
timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)
capability_name: $CAPABILITY_NAME
capability_family: $CAPABILITY_FAMILY
integration_pattern: $INTEGRATION_PATTERN
original_location: $CAPABILITY_ROOT
capability_metadata:
EOF
# Append capability metadata if available
if [ -n "$CAPABILITY_FILE" ]; then
echo " spec_file: $(basename "$CAPABILITY_FILE")" >> "$MANIFEST_FILE"
# Try to extract key metadata
if command -v yq &> /dev/null; then
{
echo " version: $(yq eval '.metadata.version' "$CAPABILITY_FILE" 2>/dev/null || echo 'unknown')"
echo " implementation: $(yq eval '.metadata.implementation' "$CAPABILITY_FILE" 2>/dev/null || echo 'unknown')"
echo " maturity: $(yq eval '.metadata.maturity' "$CAPABILITY_FILE" 2>/dev/null || echo 'unknown')"
} >> "$MANIFEST_FILE"
fi
fi
cat >> "$MANIFEST_FILE" <<EOF
integration_details:
parent_project: $PARENT_NAME
parent_path: $PARENT_DIR
re_integration_guide: |
To re-integrate this capability using the new architecture:
# Option 1: Git submodule (recommended)
cd $PARENT_DIR
git submodule add <repo-url> _$CAPABILITY_NAME
pip install -e _$CAPABILITY_NAME/
# Option 2: Clone directly
cd $PARENT_DIR
git clone <repo-url> _$CAPABILITY_NAME
pip install -e _$CAPABILITY_NAME/
# Option 3: Copy into project
cd $PARENT_DIR
cp -r /path/to/$CAPABILITY_NAME _$CAPABILITY_NAME
pip install -e _$CAPABILITY_NAME/
Note: Use underscore prefix (_$CAPABILITY_NAME) per ReusableCapabilitiesArchitecture
notes:
- The original integration used pattern: $INTEGRATION_PATTERN
- New architecture recommends: underscore-prefix at repo root
- See ReusableCapabilitiesArchitecture.md for details
repository_info:
# Fill in if re-integrating from git
git_url: "" # e.g., https://github.com/markitect/$CAPABILITY_NAME
git_branch: "" # e.g., main
git_commit: "" # Optional: specific commit to use
EOF
success "✓ Created manifest: $MANIFEST_FILE"
echo ""
# Check for git
if git -C "$CAPABILITY_ROOT" rev-parse --git-dir > /dev/null 2>&1; then
REPO_URL=$(git -C "$CAPABILITY_ROOT" config --get remote.origin.url 2>/dev/null || echo "")
BRANCH=$(git -C "$CAPABILITY_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
COMMIT=$(git -C "$CAPABILITY_ROOT" rev-parse HEAD 2>/dev/null || echo "")
if [ -n "$REPO_URL" ]; then
info "Git repository detected:"
echo " URL: $REPO_URL"
echo " Branch: $BRANCH"
echo " Commit: $COMMIT"
echo ""
# Update manifest with git info
sed -i "s|git_url: \"\"|git_url: \"$REPO_URL\"|" "$MANIFEST_FILE"
sed -i "s|git_branch: \"\"|git_branch: \"$BRANCH\"|" "$MANIFEST_FILE"
sed -i "s|git_commit: \"\"|git_commit: \"$COMMIT\"|" "$MANIFEST_FILE"
fi
fi
# Check if this is a git submodule
if [ -f "$PARENT_DIR/.gitmodules" ] && grep -q "$CAPABILITY_NAME" "$PARENT_DIR/.gitmodules"; then
warn "⚠️ This appears to be a git submodule"
echo ""
echo "To properly remove a submodule:"
echo " cd $PARENT_DIR"
echo " git submodule deinit -f $CAPABILITY_ROOT"
echo " git rm -f $CAPABILITY_ROOT"
echo " rm -rf .git/modules/$CAPABILITY_NAME"
echo ""
read -p "Run these commands now? (yes/no): " run_submodule
if [[ "$run_submodule" == "yes" ]]; then
cd "$PARENT_DIR"
git submodule deinit -f "$CAPABILITY_ROOT" || warn "Submodule deinit failed (might not be initialized)"
git rm -f "$CAPABILITY_ROOT" || warn "Git rm failed"
rm -rf .git/modules/"$CAPABILITY_NAME" || warn "Module cleanup failed"
success "✓ Git submodule removed"
else
warn "Skipping submodule removal - you'll need to do this manually"
info "Removing directory anyway..."
rm -rf "$CAPABILITY_ROOT"
fi
else
# Not a submodule, just remove directory
info "Removing capability directory..."
rm -rf "$CAPABILITY_ROOT"
success "✓ Directory removed"
fi
echo ""
success "═══════════════════════════════════════"
success " Capability detached successfully!"
success "═══════════════════════════════════════"
echo ""
info "Manifest saved to: $MANIFEST_FILE"
echo ""
echo "To re-integrate using new architecture:"
echo " 1. Read the manifest: cat $MANIFEST_FILE"
echo " 2. Follow re_integration_guide in the manifest"
echo " 3. Use underscore prefix: _$CAPABILITY_NAME/"
echo ""
info "See ReusableCapabilitiesArchitecture.md for details"

4
.capability/feedback
View File

@@ -12,7 +12,7 @@
set -e set -e
FEEDBACK_DIR=".feedback" FEEDBACK_DIR="feedback"
INBOUND_DIR="${FEEDBACK_DIR}/inbound" INBOUND_DIR="${FEEDBACK_DIR}/inbound"
REVIEWED_DIR="${FEEDBACK_DIR}/reviewed" REVIEWED_DIR="${FEEDBACK_DIR}/reviewed"
ARCHIVED_DIR="${FEEDBACK_DIR}/archived" ARCHIVED_DIR="${FEEDBACK_DIR}/archived"
@@ -300,7 +300,7 @@ Examples:
# Archive (maintainers) # Archive (maintainers)
feedback archive 20251217-103045-abc12345.md feedback archive 20251217-103045-abc12345.md
For more information, see .feedback/README.md For more information, see feedback/README.md
EOF EOF
} }

6
CAPABILITY.yaml → CAPABILITY-issue-tracking.yaml
View File

@@ -169,7 +169,7 @@ feedback:
submission: submission:
cli: ".capability/feedback submit 'Your feedback here'" cli: ".capability/feedback submit 'Your feedback here'"
file: ".capability/feedback submit path/to/feedback.md" file: ".capability/feedback submit path/to/feedback.md"
directory: ".feedback/inbound/" directory: "feedback/inbound/"
organization: organization:
inbound: "New feedback awaiting review" inbound: "New feedback awaiting review"
@@ -182,7 +182,7 @@ feedback:
./.capability/feedback submit detailed-feedback.md ./.capability/feedback submit detailed-feedback.md
Or drop a file directly: Or drop a file directly:
echo "Feedback..." > .feedback/inbound/$(date +%Y%m%d)-feedback.md echo "Feedback..." > feedback/inbound/$(date +%Y%m%d)-feedback.md
for_maintainers: | for_maintainers: |
Review feedback: Review feedback:
@@ -203,7 +203,7 @@ documentation:
development: "CLAUDE.md" development: "CLAUDE.md"
roadmap: "ROADMAP.md" roadmap: "ROADMAP.md"
examples: "examples/agents/" examples: "examples/agents/"
feedback: ".feedback/README.md" feedback: "feedback/README.md"
# Dependencies and requirements # Dependencies and requirements
requirements: requirements:

24
CLAUDE.md
View File

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

1182
ReusableCapabilitiesArchitecture.md Normal file
View File

File diff suppressed because it is too large Load Diff

14
examples/feedback-example.md
View File

@@ -52,8 +52,8 @@ EOF
### Method 2: Direct File Drop (No CLI Required) ### Method 2: Direct File Drop (No CLI Required)
```bash ```bash
# Just create a markdown file directly in .feedback/inbound/ # Just create a markdown file directly in feedback/inbound/
cat > .feedback/inbound/$(date +%Y%m%d-%H%M%S)-performance.md << 'EOF' cat > feedback/inbound/$(date +%Y%m%d-%H%M%S)-performance.md << 'EOF'
## Quick Note ## Quick Note
The JSON output format for `issue list` is fantastic for scripting! The JSON output format for `issue list` is fantastic for scripting!
@@ -92,7 +92,7 @@ EOF
# Copy to capability's feedback directory # Copy to capability's feedback directory
cp feedback-for-issue-facade.md \ cp feedback-for-issue-facade.md \
capabilities/issue-facade/.feedback/inbound/$(date +%Y%m%d)-github-backend.md capabilities/issue-facade/feedback/inbound/$(date +%Y%m%d)-github-backend.md
``` ```
## Feedback Categories ## Feedback Categories
@@ -237,7 +237,7 @@ Thank you!
## What Happens to Your Feedback ## What Happens to Your Feedback
1. **Submission**: Your feedback lands in `.feedback/inbound/` 1. **Submission**: Your feedback lands in `feedback/inbound/`
2. **Review**: Maintainers review it (usually within a week) 2. **Review**: Maintainers review it (usually within a week)
3. **Action**: 3. **Action**:
- Create issue if it needs tracking - Create issue if it needs tracking
@@ -259,10 +259,10 @@ If you're curious whether your feedback was addressed:
```bash ```bash
# Check if it's still in inbound (pending review) # Check if it's still in inbound (pending review)
ls .feedback/inbound/ | grep <keyword> ls feedback/inbound/ | grep <keyword>
# Check if it's been reviewed # Check if it's been reviewed
ls .feedback/reviewed/ | grep <keyword> ls feedback/reviewed/ | grep <keyword>
# Check if an issue was created # Check if an issue was created
issue list --label=feedback --search="<your topic>" issue list --label=feedback --search="<your topic>"
@@ -274,7 +274,7 @@ If you maintain this capability, see the maintainer guide:
- **Review workflow**: `.capability/feedback list` and `review` - **Review workflow**: `.capability/feedback list` and `review`
- **Creating issues**: `.capability/feedback review <id> --create-issue` - **Creating issues**: `.capability/feedback review <id> --create-issue`
- **Statistics**: `.capability/feedback stats` - **Statistics**: `.capability/feedback stats`
- **Full docs**: `.feedback/README.md` - **Full docs**: `feedback/README.md`
## Questions? ## Questions?

60
.feedback/README.md → feedback/README.md
View File

@@ -6,7 +6,7 @@ This capability uses the **feedback pattern** - a simple, reusable approach for
## Philosophy ## Philosophy
**Capability Owns Feedback**: Each capability maintains its own `.feedback/` directory. The capability decides how to organize, prioritize, and act on feedback. **Capability Owns Feedback**: Each capability maintains its own `feedback/` directory. The capability decides how to organize, prioritize, and act on feedback.
**No Structure Imposement**: Users provide feedback in whatever format works for them - quick notes, detailed reports, markdown files. The only requirement is clear communication. **No Structure Imposement**: Users provide feedback in whatever format works for them - quick notes, detailed reports, markdown files. The only requirement is clear communication.
@@ -30,10 +30,10 @@ This capability uses the **feedback pattern** - a simple, reusable approach for
### Option 1: Direct File Drop (Simplest) ### Option 1: Direct File Drop (Simplest)
Just create a markdown file in `.feedback/inbound/`: Just create a markdown file in `feedback/inbound/`:
```bash ```bash
cat > .feedback/inbound/$(date +%Y%m%d-%H%M%S)-my-feedback.md << 'EOF' cat > feedback/inbound/$(date +%Y%m%d-%H%M%S)-my-feedback.md << 'EOF'
## Sync Performance Issue ## Sync Performance Issue
The sync command takes 10+ minutes with 5000 issues. The sync command takes 10+ minutes with 5000 issues.
@@ -68,7 +68,7 @@ cd my-master-project
echo "Feedback about issue-facade..." > feedback.md echo "Feedback about issue-facade..." > feedback.md
# Copy to capability's feedback directory # Copy to capability's feedback directory
cp feedback.md capabilities/issue-facade/.feedback/inbound/$(date +%Y%m%d-%H%M%S)-sync-issue.md cp feedback.md capabilities/issue-facade/feedback/inbound/$(date +%Y%m%d-%H%M%S)-sync-issue.md
``` ```
### What to Include ### What to Include
@@ -88,10 +88,10 @@ Whatever helps communicate your feedback:
```bash ```bash
# 1. List new feedback # 1. List new feedback
ls -lt .feedback/inbound/ ls -lt feedback/inbound/
# 2. Read feedback # 2. Read feedback
cat .feedback/inbound/20251217-103045-sync-issue.md cat feedback/inbound/20251217-103045-sync-issue.md
# 3. Decide action: # 3. Decide action:
# - Create issue if it needs tracking # - Create issue if it needs tracking
@@ -100,48 +100,48 @@ cat .feedback/inbound/20251217-103045-sync-issue.md
# - Archive if not applicable # - Archive if not applicable
# 4. Move to reviewed/ or archived/ # 4. Move to reviewed/ or archived/
mv .feedback/inbound/20251217-103045-sync-issue.md .feedback/reviewed/ mv feedback/inbound/20251217-103045-sync-issue.md feedback/reviewed/
# 5. Optional: Add response/notes # 5. Optional: Add response/notes
echo "## Maintainer Notes\n\nCreated issue #123..." >> .feedback/reviewed/20251217-103045-sync-issue.md echo "## Maintainer Notes\n\nCreated issue #123..." >> feedback/reviewed/20251217-103045-sync-issue.md
``` ```
### Tracking Statistics ### Tracking Statistics
```bash ```bash
# Count feedback by status # Count feedback by status
echo "Pending: $(ls .feedback/inbound/ 2>/dev/null | wc -l)" echo "Pending: $(ls feedback/inbound/ 2>/dev/null | wc -l)"
echo "Reviewed: $(ls .feedback/reviewed/ 2>/dev/null | wc -l)" echo "Reviewed: $(ls feedback/reviewed/ 2>/dev/null | wc -l)"
echo "Archived: $(ls .feedback/archived/ 2>/dev/null | wc -l)" echo "Archived: $(ls feedback/archived/ 2>/dev/null | wc -l)"
# Recent feedback # Recent feedback
ls -lt .feedback/inbound/ | head -5 ls -lt feedback/inbound/ | head -5
``` ```
### Creating Issues from Feedback ### Creating Issues from Feedback
```bash ```bash
# Read feedback # Read feedback
cat .feedback/inbound/20251217-feature-request.md cat feedback/inbound/20251217-feature-request.md
# Create issue with feedback content # Create issue with feedback content
issue create "Feature: Bulk label operations" \ issue create "Feature: Bulk label operations" \
--description "$(cat .feedback/inbound/20251217-feature-request.md)" \ --description "$(cat feedback/inbound/20251217-feature-request.md)" \
--label=feedback --label=feature --label=feedback --label=feature
# Move to reviewed # Move to reviewed
mv .feedback/inbound/20251217-feature-request.md .feedback/reviewed/ mv feedback/inbound/20251217-feature-request.md feedback/reviewed/
``` ```
## Integration Patterns ## Integration Patterns
### Pattern 1: Standalone `.feedback/` Directory ### Pattern 1: Standalone `feedback/` Directory
Each capability maintains its own feedback directory. Users navigate to the capability and submit feedback. Each capability maintains its own feedback directory. Users navigate to the capability and submit feedback.
```bash ```bash
cd capabilities/issue-facade cd capabilities/issue-facade
echo "Feedback..." > .feedback/inbound/$(date +%Y%m%d)-feedback.md echo "Feedback..." > feedback/inbound/$(date +%Y%m%d)-feedback.md
``` ```
**Pros**: Simple, no dependencies, capability-owned **Pros**: Simple, no dependencies, capability-owned
@@ -155,7 +155,7 @@ Create a reusable `feedback` command that works in any capability directory:
#!/bin/bash #!/bin/bash
# feedback - Universal feedback submission tool # feedback - Universal feedback submission tool
FEEDBACK_DIR=".feedback/inbound" FEEDBACK_DIR="feedback/inbound"
TIMESTAMP=$(date +%Y%m%d-%H%M%S) TIMESTAMP=$(date +%Y%m%d-%H%M%S)
HASH=$(echo "$1" | md5sum | cut -c1-8) HASH=$(echo "$1" | md5sum | cut -c1-8)
FILENAME="${FEEDBACK_DIR}/${TIMESTAMP}-${HASH}.md" FILENAME="${FEEDBACK_DIR}/${TIMESTAMP}-${HASH}.md"
@@ -190,14 +190,14 @@ Add feedback commands to capability Makefile:
```makefile ```makefile
.PHONY: feedback .PHONY: feedback
feedback: ## Submit feedback (Usage: make feedback MSG="your feedback") feedback: ## Submit feedback (Usage: make feedback MSG="your feedback")
@mkdir -p .feedback/inbound @mkdir -p feedback/inbound
@echo "$(MSG)" > .feedback/inbound/$$(date +%Y%m%d-%H%M%S)-feedback.md @echo "$(MSG)" > feedback/inbound/$$(date +%Y%m%d-%H%M%S)-feedback.md
@echo "Feedback submitted to .feedback/inbound/" @echo "Feedback submitted to feedback/inbound/"
.PHONY: feedback-list .PHONY: feedback-list
feedback-list: ## List pending feedback feedback-list: ## List pending feedback
@echo "Pending feedback:" @echo "Pending feedback:"
@ls -1t .feedback/inbound/ 2>/dev/null || echo " (none)" @ls -1t feedback/inbound/ 2>/dev/null || echo " (none)"
``` ```
Usage: Usage:
@@ -224,7 +224,7 @@ Content-Type: application/json
} }
``` ```
Backend writes to `.feedback/inbound/` maintaining consistency with other patterns. Backend writes to `feedback/inbound/` maintaining consistency with other patterns.
## Metadata (Optional) ## Metadata (Optional)
@@ -259,12 +259,12 @@ Actual feedback content here...
**Quick Bug Report:** **Quick Bug Report:**
```bash ```bash
echo "Bug: issue list crashes with --milestone='Sprint 2'" > \ echo "Bug: issue list crashes with --milestone='Sprint 2'" > \
.feedback/inbound/$(date +%Y%m%d)-crash-bug.md feedback/inbound/$(date +%Y%m%d)-crash-bug.md
``` ```
**Detailed Feature Request:** **Detailed Feature Request:**
```markdown ```markdown
<!-- .feedback/inbound/20251217-github-support.md --> <!-- feedback/inbound/20251217-github-support.md -->
## Feature Request: GitHub Backend ## Feature Request: GitHub Backend
@@ -284,7 +284,7 @@ echo "Bug: issue list crashes with --milestone='Sprint 2'" > \
**Performance Feedback:** **Performance Feedback:**
```markdown ```markdown
<!-- .feedback/inbound/20251217-sync-perf.md --> <!-- feedback/inbound/20251217-sync-perf.md -->
Sync performance issue: Sync performance issue:
- 5000 issues in Gitea repo - 5000 issues in Gitea repo
@@ -302,15 +302,15 @@ Thanks for the great tool!
```bash ```bash
# 1. Create feedback directory # 1. Create feedback directory
mkdir -p .feedback/inbound .feedback/reviewed .feedback/archived mkdir -p feedback/inbound feedback/reviewed feedback/archived
# 2. Copy this README # 2. Copy this README
cp /path/to/feedback/template/README.md .feedback/ cp /path/to/feedback/template/README.md .feedback/
# 3. Add to .gitignore (optional - feedback can be committed or ignored) # 3. Add to .gitignore (optional - feedback can be committed or ignored)
echo ".feedback/inbound/*.md" >> .gitignore echo "feedback/inbound/*.md" >> .gitignore
# 4. Document in CAPABILITY.yaml # 4. Document in CAPABILITY-issue-tracking.yaml
# Add to capabilities section: # Add to capabilities section:
# - feedback-collection # - feedback-collection
``` ```
@@ -357,7 +357,7 @@ Yes, **this README itself** is part of the feedback capability pattern! If you h
```bash ```bash
cd capabilities/feedback # or wherever feedback capability lives cd capabilities/feedback # or wherever feedback capability lives
echo "The feedback pattern is great but..." > .feedback/inbound/$(date +%Y%m%d)-meta-feedback.md echo "The feedback pattern is great but..." > feedback/inbound/$(date +%Y%m%d)-meta-feedback.md
``` ```
We eat our own dog food. 🐕 We eat our own dog food. 🐕