generated from coulomb/repo-seed
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:
@@ -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
|
||||
|
||||
226
.capability/detach
Executable file
226
.capability/detach
Executable 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"
|
||||
@@ -12,7 +12,7 @@
|
||||
|
||||
set -e
|
||||
|
||||
FEEDBACK_DIR=".feedback"
|
||||
FEEDBACK_DIR="feedback"
|
||||
INBOUND_DIR="${FEEDBACK_DIR}/inbound"
|
||||
REVIEWED_DIR="${FEEDBACK_DIR}/reviewed"
|
||||
ARCHIVED_DIR="${FEEDBACK_DIR}/archived"
|
||||
@@ -300,7 +300,7 @@ Examples:
|
||||
# Archive (maintainers)
|
||||
feedback archive 20251217-103045-abc12345.md
|
||||
|
||||
For more information, see .feedback/README.md
|
||||
For more information, see feedback/README.md
|
||||
EOF
|
||||
}
|
||||
|
||||
|
||||
@@ -169,7 +169,7 @@ feedback:
|
||||
submission:
|
||||
cli: ".capability/feedback submit 'Your feedback here'"
|
||||
file: ".capability/feedback submit path/to/feedback.md"
|
||||
directory: ".feedback/inbound/"
|
||||
directory: "feedback/inbound/"
|
||||
|
||||
organization:
|
||||
inbound: "New feedback awaiting review"
|
||||
@@ -182,7 +182,7 @@ feedback:
|
||||
./.capability/feedback submit detailed-feedback.md
|
||||
|
||||
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: |
|
||||
Review feedback:
|
||||
@@ -203,7 +203,7 @@ documentation:
|
||||
development: "CLAUDE.md"
|
||||
roadmap: "ROADMAP.md"
|
||||
examples: "examples/agents/"
|
||||
feedback: ".feedback/README.md"
|
||||
feedback: "feedback/README.md"
|
||||
|
||||
# Dependencies and requirements
|
||||
requirements:
|
||||
24
CLAUDE.md
24
CLAUDE.md
@@ -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.
|
||||
|
||||
1182
ReusableCapabilitiesArchitecture.md
Normal file
1182
ReusableCapabilitiesArchitecture.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -52,8 +52,8 @@ EOF
|
||||
### Method 2: Direct File Drop (No CLI Required)
|
||||
|
||||
```bash
|
||||
# Just create a markdown file directly in .feedback/inbound/
|
||||
cat > .feedback/inbound/$(date +%Y%m%d-%H%M%S)-performance.md << 'EOF'
|
||||
# Just create a markdown file directly in feedback/inbound/
|
||||
cat > feedback/inbound/$(date +%Y%m%d-%H%M%S)-performance.md << 'EOF'
|
||||
## Quick Note
|
||||
|
||||
The JSON output format for `issue list` is fantastic for scripting!
|
||||
@@ -92,7 +92,7 @@ EOF
|
||||
|
||||
# Copy to capability's feedback directory
|
||||
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
|
||||
@@ -237,7 +237,7 @@ Thank you!
|
||||
|
||||
## 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)
|
||||
3. **Action**:
|
||||
- Create issue if it needs tracking
|
||||
@@ -259,10 +259,10 @@ If you're curious whether your feedback was addressed:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
ls .feedback/reviewed/ | grep <keyword>
|
||||
ls feedback/reviewed/ | grep <keyword>
|
||||
|
||||
# Check if an issue was created
|
||||
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`
|
||||
- **Creating issues**: `.capability/feedback review <id> --create-issue`
|
||||
- **Statistics**: `.capability/feedback stats`
|
||||
- **Full docs**: `.feedback/README.md`
|
||||
- **Full docs**: `feedback/README.md`
|
||||
|
||||
## Questions?
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ This capability uses the **feedback pattern** - a simple, reusable approach for
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -30,10 +30,10 @@ This capability uses the **feedback pattern** - a simple, reusable approach for
|
||||
|
||||
### Option 1: Direct File Drop (Simplest)
|
||||
|
||||
Just create a markdown file in `.feedback/inbound/`:
|
||||
Just create a markdown file in `feedback/inbound/`:
|
||||
|
||||
```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
|
||||
|
||||
The sync command takes 10+ minutes with 5000 issues.
|
||||
@@ -68,7 +68,7 @@ cd my-master-project
|
||||
echo "Feedback about issue-facade..." > feedback.md
|
||||
|
||||
# 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
|
||||
@@ -88,10 +88,10 @@ Whatever helps communicate your feedback:
|
||||
|
||||
```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. Decide action:
|
||||
# - Create issue if it needs tracking
|
||||
@@ -100,48 +100,48 @@ cat .feedback/inbound/20251217-103045-sync-issue.md
|
||||
# - Archive if not applicable
|
||||
|
||||
# 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
|
||||
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
|
||||
|
||||
```bash
|
||||
# Count feedback by status
|
||||
echo "Pending: $(ls .feedback/inbound/ 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 "Pending: $(ls feedback/inbound/ 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)"
|
||||
|
||||
# Recent feedback
|
||||
ls -lt .feedback/inbound/ | head -5
|
||||
ls -lt feedback/inbound/ | head -5
|
||||
```
|
||||
|
||||
### Creating Issues from Feedback
|
||||
|
||||
```bash
|
||||
# Read feedback
|
||||
cat .feedback/inbound/20251217-feature-request.md
|
||||
cat feedback/inbound/20251217-feature-request.md
|
||||
|
||||
# Create issue with feedback content
|
||||
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
|
||||
|
||||
# Move to reviewed
|
||||
mv .feedback/inbound/20251217-feature-request.md .feedback/reviewed/
|
||||
mv feedback/inbound/20251217-feature-request.md feedback/reviewed/
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
```bash
|
||||
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
|
||||
@@ -155,7 +155,7 @@ Create a reusable `feedback` command that works in any capability directory:
|
||||
#!/bin/bash
|
||||
# feedback - Universal feedback submission tool
|
||||
|
||||
FEEDBACK_DIR=".feedback/inbound"
|
||||
FEEDBACK_DIR="feedback/inbound"
|
||||
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
|
||||
HASH=$(echo "$1" | md5sum | cut -c1-8)
|
||||
FILENAME="${FEEDBACK_DIR}/${TIMESTAMP}-${HASH}.md"
|
||||
@@ -190,14 +190,14 @@ Add feedback commands to capability Makefile:
|
||||
```makefile
|
||||
.PHONY: feedback
|
||||
feedback: ## Submit feedback (Usage: make feedback MSG="your feedback")
|
||||
@mkdir -p .feedback/inbound
|
||||
@echo "$(MSG)" > .feedback/inbound/$$(date +%Y%m%d-%H%M%S)-feedback.md
|
||||
@echo "Feedback submitted to .feedback/inbound/"
|
||||
@mkdir -p feedback/inbound
|
||||
@echo "$(MSG)" > feedback/inbound/$$(date +%Y%m%d-%H%M%S)-feedback.md
|
||||
@echo "Feedback submitted to feedback/inbound/"
|
||||
|
||||
.PHONY: feedback-list
|
||||
feedback-list: ## List pending feedback
|
||||
@echo "Pending feedback:"
|
||||
@ls -1t .feedback/inbound/ 2>/dev/null || echo " (none)"
|
||||
@ls -1t feedback/inbound/ 2>/dev/null || echo " (none)"
|
||||
```
|
||||
|
||||
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)
|
||||
|
||||
@@ -259,12 +259,12 @@ Actual feedback content here...
|
||||
**Quick Bug Report:**
|
||||
```bash
|
||||
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:**
|
||||
```markdown
|
||||
<!-- .feedback/inbound/20251217-github-support.md -->
|
||||
<!-- feedback/inbound/20251217-github-support.md -->
|
||||
|
||||
## Feature Request: GitHub Backend
|
||||
|
||||
@@ -284,7 +284,7 @@ echo "Bug: issue list crashes with --milestone='Sprint 2'" > \
|
||||
|
||||
**Performance Feedback:**
|
||||
```markdown
|
||||
<!-- .feedback/inbound/20251217-sync-perf.md -->
|
||||
<!-- feedback/inbound/20251217-sync-perf.md -->
|
||||
|
||||
Sync performance issue:
|
||||
- 5000 issues in Gitea repo
|
||||
@@ -302,15 +302,15 @@ Thanks for the great tool!
|
||||
|
||||
```bash
|
||||
# 1. Create feedback directory
|
||||
mkdir -p .feedback/inbound .feedback/reviewed .feedback/archived
|
||||
mkdir -p feedback/inbound feedback/reviewed feedback/archived
|
||||
|
||||
# 2. Copy this README
|
||||
cp /path/to/feedback/template/README.md .feedback/
|
||||
|
||||
# 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:
|
||||
# - feedback-collection
|
||||
```
|
||||
@@ -357,7 +357,7 @@ Yes, **this README itself** is part of the feedback capability pattern! If you h
|
||||
|
||||
```bash
|
||||
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. 🐕
|
||||
Reference in New Issue
Block a user