generated from coulomb/repo-seed
Compare commits
2 Commits
324453bd8d
...
35daa514e5
| Author | SHA1 | Date | |
|---|---|---|---|
| 35daa514e5 | |||
| 1627fd9673 |
@@ -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"
|
||||
391
.capability/feedback
Executable file
391
.capability/feedback
Executable file
@@ -0,0 +1,391 @@
|
||||
#!/usr/bin/env bash
|
||||
# feedback - Universal feedback submission tool for capabilities
|
||||
#
|
||||
# Usage:
|
||||
# feedback submit "Your feedback text"
|
||||
# feedback submit path/to/feedback.md
|
||||
# feedback submit "Text" --category=bug --contact=me@email.com
|
||||
# feedback list [--reviewed] [--archived]
|
||||
# feedback show <filename>
|
||||
#
|
||||
# This tool can be copied to any capability that wants to use the feedback pattern.
|
||||
|
||||
set -e
|
||||
|
||||
FEEDBACK_DIR="feedback"
|
||||
INBOUND_DIR="${FEEDBACK_DIR}/inbound"
|
||||
REVIEWED_DIR="${FEEDBACK_DIR}/reviewed"
|
||||
ARCHIVED_DIR="${FEEDBACK_DIR}/archived"
|
||||
|
||||
# Colors for output
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
# Helper functions
|
||||
error() {
|
||||
echo -e "${RED}Error: $1${NC}" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
success() {
|
||||
echo -e "${GREEN}$1${NC}"
|
||||
}
|
||||
|
||||
info() {
|
||||
echo -e "${BLUE}$1${NC}"
|
||||
}
|
||||
|
||||
warn() {
|
||||
echo -e "${YELLOW}$1${NC}"
|
||||
}
|
||||
|
||||
# Check if we're in a capability directory
|
||||
check_capability_dir() {
|
||||
if [ ! -d "$FEEDBACK_DIR" ]; then
|
||||
error "Not in a capability directory with feedback support.\n Looking for: $FEEDBACK_DIR/\n Run from capability root or initialize with: mkdir -p $INBOUND_DIR"
|
||||
fi
|
||||
}
|
||||
|
||||
# Initialize feedback directories
|
||||
init_dirs() {
|
||||
mkdir -p "$INBOUND_DIR" "$REVIEWED_DIR" "$ARCHIVED_DIR"
|
||||
}
|
||||
|
||||
# Generate metadata
|
||||
generate_metadata() {
|
||||
local category="${1:-}"
|
||||
local contact="${2:-}"
|
||||
|
||||
local timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
|
||||
local git_repo=$(git rev-parse --show-toplevel 2>/dev/null || echo "unknown")
|
||||
local git_branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
|
||||
local python_version=$(python3 --version 2>/dev/null | cut -d' ' -f2 || echo "unknown")
|
||||
|
||||
# Try to find capability version
|
||||
local cap_version="unknown"
|
||||
if [ -f "CAPABILITY.yaml" ]; then
|
||||
cap_version=$(grep "^version:" CAPABILITY.yaml | awk '{print $2}' | tr -d '"' || echo "unknown")
|
||||
fi
|
||||
|
||||
cat <<EOF
|
||||
---
|
||||
timestamp: $timestamp
|
||||
source: cli
|
||||
EOF
|
||||
|
||||
[ -n "$category" ] && echo "category: $category"
|
||||
[ -n "$contact" ] && echo "contact: $contact"
|
||||
|
||||
cat <<EOF
|
||||
context:
|
||||
git_repo: $git_repo
|
||||
git_branch: $git_branch
|
||||
capability_version: $cap_version
|
||||
python_version: $python_version
|
||||
---
|
||||
|
||||
EOF
|
||||
}
|
||||
|
||||
# Submit feedback
|
||||
submit_feedback() {
|
||||
local content="$1"
|
||||
local category="${2:-}"
|
||||
local contact="${3:-}"
|
||||
|
||||
init_dirs
|
||||
|
||||
local timestamp=$(date +%Y%m%d-%H%M%S)
|
||||
local hash=$(echo "$content" | md5sum 2>/dev/null | cut -c1-8 || echo "$(date +%N)")
|
||||
local filename="${INBOUND_DIR}/${timestamp}-${hash}.md"
|
||||
|
||||
# Check if content is a file
|
||||
if [ -f "$content" ]; then
|
||||
info "Submitting feedback from file: $content"
|
||||
{
|
||||
generate_metadata "$category" "$contact"
|
||||
cat "$content"
|
||||
} > "$filename"
|
||||
else
|
||||
info "Submitting text feedback"
|
||||
{
|
||||
generate_metadata "$category" "$contact"
|
||||
echo "$content"
|
||||
} > "$filename"
|
||||
fi
|
||||
|
||||
success "✓ Feedback submitted: $filename"
|
||||
echo ""
|
||||
info "Your feedback has been recorded and will be reviewed by the capability maintainers."
|
||||
echo ""
|
||||
echo "To view: feedback show $(basename "$filename")"
|
||||
}
|
||||
|
||||
# List feedback
|
||||
list_feedback() {
|
||||
local dir="$INBOUND_DIR"
|
||||
local label="Inbound"
|
||||
|
||||
case "${1:-}" in
|
||||
--reviewed)
|
||||
dir="$REVIEWED_DIR"
|
||||
label="Reviewed"
|
||||
;;
|
||||
--archived)
|
||||
dir="$ARCHIVED_DIR"
|
||||
label="Archived"
|
||||
;;
|
||||
esac
|
||||
|
||||
check_capability_dir
|
||||
|
||||
if [ ! -d "$dir" ]; then
|
||||
warn "No feedback directory: $dir"
|
||||
return
|
||||
fi
|
||||
|
||||
local count=$(ls -1 "$dir" 2>/dev/null | wc -l)
|
||||
|
||||
echo -e "${BLUE}=== $label Feedback ($count) ===${NC}"
|
||||
echo ""
|
||||
|
||||
if [ "$count" -eq 0 ]; then
|
||||
echo " (none)"
|
||||
return
|
||||
fi
|
||||
|
||||
ls -lt "$dir" | tail -n +2 | while read -r line; do
|
||||
local file=$(echo "$line" | awk '{print $NF}')
|
||||
local date=$(echo "$line" | awk '{print $6, $7, $8}')
|
||||
|
||||
# Try to extract category from metadata
|
||||
local category=""
|
||||
if [ -f "$dir/$file" ]; then
|
||||
category=$(grep "^category:" "$dir/$file" | awk '{print $2}' || echo "")
|
||||
fi
|
||||
|
||||
# Colorize based on category
|
||||
local color=$NC
|
||||
case "$category" in
|
||||
bug) color=$RED ;;
|
||||
feature) color=$GREEN ;;
|
||||
improvement) color=$YELLOW ;;
|
||||
esac
|
||||
|
||||
echo -e " ${color}${file}${NC}"
|
||||
[ -n "$category" ] && echo " Category: $category"
|
||||
echo " Date: $date"
|
||||
echo ""
|
||||
done
|
||||
}
|
||||
|
||||
# Show specific feedback
|
||||
show_feedback() {
|
||||
local filename="$1"
|
||||
|
||||
check_capability_dir
|
||||
|
||||
# Search in all directories
|
||||
local filepath=""
|
||||
for dir in "$INBOUND_DIR" "$REVIEWED_DIR" "$ARCHIVED_DIR"; do
|
||||
if [ -f "$dir/$filename" ]; then
|
||||
filepath="$dir/$filename"
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
if [ -z "$filepath" ]; then
|
||||
error "Feedback not found: $filename"
|
||||
fi
|
||||
|
||||
echo -e "${BLUE}=== Feedback: $filename ===${NC}"
|
||||
echo ""
|
||||
cat "$filepath"
|
||||
}
|
||||
|
||||
# Review feedback (move to reviewed)
|
||||
review_feedback() {
|
||||
local filename="$1"
|
||||
local create_issue="${2:-}"
|
||||
|
||||
check_capability_dir
|
||||
init_dirs
|
||||
|
||||
if [ ! -f "$INBOUND_DIR/$filename" ]; then
|
||||
error "Feedback not found in inbound: $filename"
|
||||
fi
|
||||
|
||||
if [ "$create_issue" = "--create-issue" ]; then
|
||||
info "Creating issue from feedback..."
|
||||
|
||||
# Extract title and body
|
||||
local title=$(head -20 "$INBOUND_DIR/$filename" | grep -v "^---" | grep -v "^$" | head -1 | sed 's/^# *//')
|
||||
local body=$(cat "$INBOUND_DIR/$filename")
|
||||
|
||||
if command -v issue &> /dev/null; then
|
||||
issue create "$title" --description "$body" --label=feedback
|
||||
success "✓ Issue created"
|
||||
else
|
||||
warn "Issue command not found. Please create issue manually."
|
||||
fi
|
||||
fi
|
||||
|
||||
mv "$INBOUND_DIR/$filename" "$REVIEWED_DIR/$filename"
|
||||
success "✓ Feedback moved to reviewed: $filename"
|
||||
}
|
||||
|
||||
# Archive feedback
|
||||
archive_feedback() {
|
||||
local filename="$1"
|
||||
|
||||
check_capability_dir
|
||||
init_dirs
|
||||
|
||||
# Try both inbound and reviewed
|
||||
if [ -f "$INBOUND_DIR/$filename" ]; then
|
||||
mv "$INBOUND_DIR/$filename" "$ARCHIVED_DIR/$filename"
|
||||
elif [ -f "$REVIEWED_DIR/$filename" ]; then
|
||||
mv "$REVIEWED_DIR/$filename" "$ARCHIVED_DIR/$filename"
|
||||
else
|
||||
error "Feedback not found: $filename"
|
||||
fi
|
||||
|
||||
success "✓ Feedback archived: $filename"
|
||||
}
|
||||
|
||||
# Show usage
|
||||
usage() {
|
||||
cat <<EOF
|
||||
feedback - Universal feedback submission tool
|
||||
|
||||
Usage:
|
||||
feedback submit <content> [options] Submit feedback
|
||||
feedback list [--reviewed|--archived] List feedback
|
||||
feedback show <filename> Show specific feedback
|
||||
feedback review <filename> [options] Mark feedback as reviewed (maintainers)
|
||||
feedback archive <filename> Archive feedback (maintainers)
|
||||
feedback stats Show feedback statistics
|
||||
feedback help Show this help
|
||||
|
||||
Submit Options:
|
||||
--category=<type> Category: bug, feature, improvement, question, other
|
||||
--contact=<email> Optional contact for follow-up
|
||||
|
||||
Review Options:
|
||||
--create-issue Create an issue from the feedback
|
||||
|
||||
Examples:
|
||||
# Quick text feedback
|
||||
feedback submit "The sync command is slow with 1000+ issues"
|
||||
|
||||
# Feedback from file
|
||||
feedback submit my-feedback.md
|
||||
|
||||
# With metadata
|
||||
feedback submit "Bug: crashes on startup" --category=bug --contact=me@email.com
|
||||
|
||||
# List feedback
|
||||
feedback list
|
||||
feedback list --reviewed
|
||||
|
||||
# Show specific feedback
|
||||
feedback show 20251217-103045-abc12345.md
|
||||
|
||||
# Review and create issue (maintainers)
|
||||
feedback review 20251217-103045-abc12345.md --create-issue
|
||||
|
||||
# Archive (maintainers)
|
||||
feedback archive 20251217-103045-abc12345.md
|
||||
|
||||
For more information, see feedback/README.md
|
||||
EOF
|
||||
}
|
||||
|
||||
# Show statistics
|
||||
show_stats() {
|
||||
check_capability_dir
|
||||
|
||||
local inbound=$(ls -1 "$INBOUND_DIR" 2>/dev/null | wc -l)
|
||||
local reviewed=$(ls -1 "$REVIEWED_DIR" 2>/dev/null | wc -l)
|
||||
local archived=$(ls -1 "$ARCHIVED_DIR" 2>/dev/null | wc -l)
|
||||
local total=$((inbound + reviewed + archived))
|
||||
|
||||
echo -e "${BLUE}=== Feedback Statistics ===${NC}"
|
||||
echo ""
|
||||
echo " Pending: $inbound"
|
||||
echo " Reviewed: $reviewed"
|
||||
echo " Archived: $archived"
|
||||
echo " ─────────────"
|
||||
echo " Total: $total"
|
||||
echo ""
|
||||
|
||||
if [ "$inbound" -gt 0 ]; then
|
||||
warn "⚠ $inbound feedback items awaiting review"
|
||||
else
|
||||
success "✓ No pending feedback"
|
||||
fi
|
||||
}
|
||||
|
||||
# Main command dispatcher
|
||||
main() {
|
||||
local command="${1:-help}"
|
||||
shift || true
|
||||
|
||||
case "$command" in
|
||||
submit)
|
||||
local content="${1:-}"
|
||||
[ -z "$content" ] && error "Usage: feedback submit <content|file> [--category=TYPE] [--contact=EMAIL]"
|
||||
|
||||
local category=""
|
||||
local contact=""
|
||||
|
||||
# Parse options
|
||||
shift || true
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--category=*)
|
||||
category="${1#--category=}"
|
||||
;;
|
||||
--contact=*)
|
||||
contact="${1#--contact=}"
|
||||
;;
|
||||
*)
|
||||
warn "Unknown option: $1"
|
||||
;;
|
||||
esac
|
||||
shift
|
||||
done
|
||||
|
||||
submit_feedback "$content" "$category" "$contact"
|
||||
;;
|
||||
list)
|
||||
list_feedback "$@"
|
||||
;;
|
||||
show)
|
||||
[ -z "${1:-}" ] && error "Usage: feedback show <filename>"
|
||||
show_feedback "$1"
|
||||
;;
|
||||
review)
|
||||
[ -z "${1:-}" ] && error "Usage: feedback review <filename> [--create-issue]"
|
||||
review_feedback "$1" "${2:-}"
|
||||
;;
|
||||
archive)
|
||||
[ -z "${1:-}" ] && error "Usage: feedback archive <filename>"
|
||||
archive_feedback "$1"
|
||||
;;
|
||||
stats)
|
||||
show_stats
|
||||
;;
|
||||
help|--help|-h)
|
||||
usage
|
||||
;;
|
||||
*)
|
||||
error "Unknown command: $command\n\n$(usage)"
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
main "$@"
|
||||
@@ -158,12 +158,52 @@ agent_guidance:
|
||||
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-facade:
|
||||
./.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:
|
||||
155
CLAUDE.md
155
CLAUDE.md
@@ -243,3 +243,158 @@ This is a capability within the larger markitect project (`/capabilities/issue-f
|
||||
- Can be installed independently via `pip install -e .`
|
||||
- Integrates with parent project via Makefile targets
|
||||
- Follows markitect capability conventions for structure and naming
|
||||
|
||||
## Feedback and Continuous Improvement
|
||||
|
||||
This capability implements the **feedback pattern** - a lightweight, unstructured feedback loop for continuous improvement based on real-world usage from master projects integrating this capability.
|
||||
|
||||
### Overview
|
||||
|
||||
The feedback system consists of:
|
||||
- **`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
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
.feedback/
|
||||
├── inbound/ # New feedback from users (unreviewed)
|
||||
├── reviewed/ # Feedback reviewed by maintainers
|
||||
├── archived/ # Resolved or outdated feedback
|
||||
└── README.md # Complete documentation
|
||||
```
|
||||
|
||||
### For Users: Submitting Feedback
|
||||
|
||||
Users of issue-facade (master projects integrating it) can submit feedback in multiple ways:
|
||||
|
||||
**Option 1: Using feedback CLI**
|
||||
```bash
|
||||
# Quick text feedback
|
||||
./.capability/feedback submit "The sync command is slow with 1000+ issues"
|
||||
|
||||
# From a file
|
||||
./.capability/feedback submit detailed-feedback.md
|
||||
|
||||
# With metadata
|
||||
./.capability/feedback submit "Bug report" --category=bug --contact=me@email.com
|
||||
```
|
||||
|
||||
**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'
|
||||
The sync is taking 10+ minutes with our 5000-issue repo.
|
||||
Would love to see progress indicators or batch processing.
|
||||
EOF
|
||||
```
|
||||
|
||||
**Option 3: From master project**
|
||||
```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
|
||||
```
|
||||
|
||||
### For Maintainers: Processing Feedback
|
||||
|
||||
**List and review feedback:**
|
||||
```bash
|
||||
# List pending feedback
|
||||
./.capability/feedback list
|
||||
|
||||
# Show specific feedback
|
||||
./.capability/feedback show 20251217-103045-abc12345.md
|
||||
|
||||
# Show statistics
|
||||
./.capability/feedback stats
|
||||
```
|
||||
|
||||
**Process feedback:**
|
||||
```bash
|
||||
# Mark as reviewed
|
||||
./.capability/feedback review 20251217-103045-abc12345.md
|
||||
|
||||
# Create issue from feedback
|
||||
./.capability/feedback review 20251217-103045-abc12345.md --create-issue
|
||||
|
||||
# Archive when resolved
|
||||
./.capability/feedback archive 20251217-103045-abc12345.md
|
||||
```
|
||||
|
||||
**Manual workflow (without CLI):**
|
||||
```bash
|
||||
# 1. List new feedback
|
||||
ls -lt feedback/inbound/
|
||||
|
||||
# 2. Read feedback
|
||||
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)" \
|
||||
--label=feedback --label=feature
|
||||
|
||||
# 4. Move to reviewed
|
||||
mv feedback/inbound/20251217-103045-sync-issue.md feedback/reviewed/
|
||||
```
|
||||
|
||||
### Integration with Development Workflow
|
||||
|
||||
Feedback informs:
|
||||
- **Roadmap prioritization**: Most requested features get priority
|
||||
- **Bug triage**: Real-world issues from production usage
|
||||
- **Documentation improvements**: Where users struggle
|
||||
- **UX enhancements**: Friction points in actual usage
|
||||
|
||||
**Review rhythm:**
|
||||
- Daily: Quick scan of new feedback
|
||||
- Weekly: Deep review, create issues, respond to users
|
||||
- Monthly: Archive old feedback, analyze trends
|
||||
|
||||
### Feedback Pattern (Reusable Across Capabilities)
|
||||
|
||||
The feedback system is **capability-agnostic** and can be copied to any markitect capability:
|
||||
|
||||
1. **Copy the pattern:**
|
||||
```bash
|
||||
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-issue-tracking.yaml:**
|
||||
```yaml
|
||||
feedback:
|
||||
enabled: true
|
||||
method: feedback-capability
|
||||
submission:
|
||||
cli: ".capability/feedback submit 'Your feedback'"
|
||||
directory: "feedback/inbound/"
|
||||
```
|
||||
|
||||
3. **Add to Makefile (optional):**
|
||||
```makefile
|
||||
feedback:
|
||||
@./.capability/feedback submit "$(MSG)"
|
||||
```
|
||||
|
||||
**Future Evolution:**
|
||||
- When capability becomes a service, add API endpoint: `POST /api/feedback`
|
||||
- API writes to same `feedback/inbound/` directory
|
||||
- Maintains consistency across CLI, file drop, and API submission
|
||||
|
||||
### Why This Pattern?
|
||||
|
||||
- **Decentralized**: Each capability owns its feedback
|
||||
- **Flexible**: No forms, no required structure
|
||||
- **Durable**: Plain files survive system changes
|
||||
- **Auditable**: Git tracks all feedback
|
||||
- **Actionable**: Feedback lives where maintainers work
|
||||
- **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.
|
||||
|
||||
32
Makefile
32
Makefile
@@ -38,6 +38,13 @@ help: ## Show issue facade capability help
|
||||
@echo " test-cov Run tests with coverage report"
|
||||
@echo " test-verbose Run tests with verbose output"
|
||||
@echo ""
|
||||
@echo "Feedback & Continuous Improvement:"
|
||||
@echo " feedback MSG=\"...\" Submit feedback about issue-facade"
|
||||
@echo " feedback-list List pending feedback"
|
||||
@echo " feedback-stats Show feedback statistics"
|
||||
@echo " feedback-show FILE=\"...\" Show specific feedback"
|
||||
@echo " feedback-review FILE=\"...\" Review feedback (maintainers)"
|
||||
@echo ""
|
||||
@echo "Development & Setup (from parent):"
|
||||
@echo " issue-facade-install Install issue facade capability"
|
||||
@echo " issue-facade-install-dev Install with development dependencies"
|
||||
@@ -202,6 +209,31 @@ test-cov: ## Run tests with coverage report (local development)
|
||||
test-verbose: ## Run tests with verbose output (local development)
|
||||
pytest tests/ -v
|
||||
|
||||
# Feedback and Continuous Improvement
|
||||
.PHONY: feedback
|
||||
feedback: ## Submit feedback (Usage: make feedback MSG="your feedback")
|
||||
@./.capability/feedback submit "$(MSG)"
|
||||
|
||||
.PHONY: feedback-list
|
||||
feedback-list: ## List pending feedback
|
||||
@./.capability/feedback list
|
||||
|
||||
.PHONY: feedback-stats
|
||||
feedback-stats: ## Show feedback statistics
|
||||
@./.capability/feedback stats
|
||||
|
||||
.PHONY: feedback-show
|
||||
feedback-show: ## Show specific feedback (Usage: make feedback-show FILE=20251217-xxx.md)
|
||||
@./.capability/feedback show "$(FILE)"
|
||||
|
||||
.PHONY: feedback-review
|
||||
feedback-review: ## Review feedback (Usage: make feedback-review FILE=20251217-xxx.md)
|
||||
@./.capability/feedback review "$(FILE)"
|
||||
|
||||
.PHONY: feedback-review-issue
|
||||
feedback-review-issue: ## Review feedback and create issue (Usage: make feedback-review-issue FILE=20251217-xxx.md)
|
||||
@./.capability/feedback review "$(FILE)" --create-issue
|
||||
|
||||
.PHONY: issue-facade-install
|
||||
issue-facade-install: ## Install issue facade capability
|
||||
pip install -e capabilities/issue-facade/
|
||||
|
||||
1182
ReusableCapabilitiesArchitecture.md
Normal file
1182
ReusableCapabilitiesArchitecture.md
Normal file
File diff suppressed because it is too large
Load Diff
289
examples/feedback-example.md
Normal file
289
examples/feedback-example.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# Feedback System Example
|
||||
|
||||
This example demonstrates how to submit feedback about the issue-facade capability.
|
||||
|
||||
## Quick Feedback Submission
|
||||
|
||||
### Method 1: Using the feedback CLI
|
||||
|
||||
```bash
|
||||
# Navigate to the capability directory
|
||||
cd capabilities/issue-facade
|
||||
|
||||
# Submit quick text feedback
|
||||
./.capability/feedback submit "The sync command is very slow when dealing with repositories that have 5000+ issues. Would love to see a progress indicator or batch processing to speed this up."
|
||||
|
||||
# Submit detailed feedback from a file
|
||||
cat > my-feedback.md << 'EOF'
|
||||
## Performance Issue: Sync with Large Repositories
|
||||
|
||||
**Problem**: The `issue sync pull` command takes 10+ minutes when syncing a repository with 5000+ issues.
|
||||
|
||||
**Context**:
|
||||
- Gitea backend
|
||||
- Repository: company/large-project (5243 issues)
|
||||
- Network: 100 Mbps
|
||||
- System: Ubuntu 22.04, Python 3.11
|
||||
|
||||
**Observed Behavior**:
|
||||
- CPU usage is low (~5%)
|
||||
- Appears to be making sequential API calls
|
||||
- No progress indicator, feels frozen
|
||||
|
||||
**Expected Behavior**:
|
||||
- Sync completes in 1-2 minutes
|
||||
- Progress bar showing "Syncing: 1234/5243"
|
||||
- Possibly batch API requests
|
||||
|
||||
**Suggested Solutions**:
|
||||
1. Parallel API requests (respect rate limits)
|
||||
2. Batch endpoints (if Gitea supports them)
|
||||
3. Progress indicator for UX
|
||||
4. Incremental sync (only changed issues)
|
||||
|
||||
**Willingness to Help**: Happy to test beta versions and provide performance metrics.
|
||||
|
||||
**Contact**: devteam@company.com
|
||||
EOF
|
||||
|
||||
./.capability/feedback submit my-feedback.md
|
||||
```
|
||||
|
||||
### 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'
|
||||
## Quick Note
|
||||
|
||||
The JSON output format for `issue list` is fantastic for scripting!
|
||||
|
||||
One small thing: the timestamps are in ISO format which is great, but
|
||||
could we also have a `--format=json-pretty` that adds nice indentation?
|
||||
Makes debugging so much easier.
|
||||
|
||||
Thanks!
|
||||
EOF
|
||||
```
|
||||
|
||||
### Method 3: From Master Project
|
||||
|
||||
If you're working in a master project that integrates issue-facade:
|
||||
|
||||
```bash
|
||||
# From your master project root
|
||||
cd ~/my-master-project
|
||||
|
||||
# Write feedback
|
||||
cat > feedback-for-issue-facade.md << 'EOF'
|
||||
## Feature Request: GitHub Backend
|
||||
|
||||
We're using issue-facade for our Gitea repos, but our company also has
|
||||
50+ repositories on GitHub. Would love to have a GitHub backend so we
|
||||
can use the same CLI for all our issue tracking.
|
||||
|
||||
This would enable:
|
||||
- Consistent workflow across platforms
|
||||
- Offline sync for GitHub issues
|
||||
- Multi-repo issue searches
|
||||
|
||||
We'd be happy to contribute or test!
|
||||
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
|
||||
```
|
||||
|
||||
## Feedback Categories
|
||||
|
||||
You can optionally categorize your feedback:
|
||||
|
||||
```bash
|
||||
# Bug report
|
||||
./.capability/feedback submit "Bug: crashes when..." --category=bug
|
||||
|
||||
# Feature request
|
||||
./.capability/feedback submit "Please add..." --category=feature
|
||||
|
||||
# Performance issue
|
||||
./.capability/feedback submit "Slow performance..." --category=improvement
|
||||
|
||||
# Question
|
||||
./.capability/feedback submit "How do I..." --category=question
|
||||
|
||||
# General feedback (no category)
|
||||
./.capability/feedback submit "Great tool!"
|
||||
```
|
||||
|
||||
## Including Contact Information
|
||||
|
||||
If you'd like to be contacted about your feedback:
|
||||
|
||||
```bash
|
||||
./.capability/feedback submit "Feature request..." \
|
||||
--category=feature \
|
||||
--contact=myemail@example.com
|
||||
```
|
||||
|
||||
**Note**: Contact information is optional and only used for follow-up. It's never shared externally.
|
||||
|
||||
## Viewing Your Feedback
|
||||
|
||||
```bash
|
||||
# List all pending feedback
|
||||
./.capability/feedback list
|
||||
|
||||
# Show statistics
|
||||
./.capability/feedback stats
|
||||
|
||||
# View specific feedback
|
||||
./.capability/feedback show 20251217-103045-abc12345.md
|
||||
```
|
||||
|
||||
## Types of Feedback We Value
|
||||
|
||||
### Bug Reports
|
||||
- Describe the issue
|
||||
- Steps to reproduce
|
||||
- Expected vs actual behavior
|
||||
- Error messages (if any)
|
||||
- System/environment details
|
||||
|
||||
Example:
|
||||
```
|
||||
Bug: issue list crashes with certain milestone names
|
||||
|
||||
Steps to reproduce:
|
||||
1. issue backend add test gitea
|
||||
2. issue list --milestone="Sprint 2"
|
||||
3. Crashes with "AttributeError: 'NoneType' object..."
|
||||
|
||||
System: macOS 14.1, Python 3.11.5, Gitea 1.21.0
|
||||
```
|
||||
|
||||
### Feature Requests
|
||||
- What you need
|
||||
- Why it's valuable (your use case)
|
||||
- How you imagine it working
|
||||
- Any alternatives you've tried
|
||||
|
||||
Example:
|
||||
```
|
||||
Feature Request: Bulk label operations
|
||||
|
||||
Use Case: We need to relabel 200+ issues from "priority-high" to
|
||||
"priority:high" (changing naming convention).
|
||||
|
||||
Current Approach: Manually editing each issue (very tedious)
|
||||
|
||||
Proposed: issue bulk-edit --filter="label=priority-high" \
|
||||
--remove-label=priority-high \
|
||||
--add-label=priority:high
|
||||
|
||||
This would save hours of manual work.
|
||||
```
|
||||
|
||||
### Performance Issues
|
||||
- What's slow
|
||||
- Your scale/context
|
||||
- Measurements if available
|
||||
- Impact on your workflow
|
||||
|
||||
Example:
|
||||
```
|
||||
Performance: Slow issue list with many labels
|
||||
|
||||
Context: Repository with 150+ labels, 3000 issues
|
||||
|
||||
Observation: `issue list` takes 8 seconds to respond
|
||||
|
||||
Impact: Slows down our agent automation that polls every 30s
|
||||
|
||||
Note: Local SQLite backend is instant, only Gitea backend is slow
|
||||
```
|
||||
|
||||
### UX Feedback
|
||||
- What's confusing or difficult
|
||||
- What worked well
|
||||
- Suggestions for improvement
|
||||
|
||||
Example:
|
||||
```
|
||||
UX: Backend configuration is confusing
|
||||
|
||||
Issue: Setting up a Gitea backend required reading docs multiple times.
|
||||
The prompts don't explain what URL format is expected.
|
||||
|
||||
Suggestion: Show examples in the prompts:
|
||||
"Gitea URL (e.g., https://gitea.example.com):"
|
||||
|
||||
Also: Maybe detect from git remote and offer to auto-configure?
|
||||
```
|
||||
|
||||
### Positive Feedback
|
||||
We love hearing what's working well!
|
||||
|
||||
Example:
|
||||
```
|
||||
The offline sync feature is AMAZING! Being able to work on issues
|
||||
during flights and sync later has changed my workflow completely.
|
||||
|
||||
The local SQLite backend is incredibly fast and the JSON output
|
||||
makes scripting so easy.
|
||||
|
||||
Thank you!
|
||||
```
|
||||
|
||||
## What Happens to Your Feedback
|
||||
|
||||
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
|
||||
- Fix immediately if it's quick
|
||||
- Document for roadmap planning
|
||||
- Respond to you if you provided contact
|
||||
4. **Archive**: Moved to `reviewed/` or `archived/` after handling
|
||||
|
||||
## Privacy & Data
|
||||
|
||||
- Feedback is **anonymous by default**
|
||||
- Git paths are captured for context, not shared externally
|
||||
- Contact info is only used for follow-up, never shared
|
||||
- Feedback files may be committed to git (part of the project)
|
||||
|
||||
## Checking Feedback Status
|
||||
|
||||
If you're curious whether your feedback was addressed:
|
||||
|
||||
```bash
|
||||
# Check if it's still in inbound (pending review)
|
||||
ls feedback/inbound/ | grep <keyword>
|
||||
|
||||
# Check if it's been reviewed
|
||||
ls feedback/reviewed/ | grep <keyword>
|
||||
|
||||
# Check if an issue was created
|
||||
issue list --label=feedback --search="<your topic>"
|
||||
```
|
||||
|
||||
## For Capability Maintainers
|
||||
|
||||
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`
|
||||
|
||||
## Questions?
|
||||
|
||||
If you have questions about the feedback system itself, that's also feedback!
|
||||
|
||||
```bash
|
||||
./.capability/feedback submit "Question about feedback: How often is it reviewed?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Thank you for helping make issue-facade better through your feedback!**
|
||||
367
feedback/README.md
Normal file
367
feedback/README.md
Normal file
@@ -0,0 +1,367 @@
|
||||
# Feedback System
|
||||
|
||||
**A lightweight, unstructured feedback loop for continuous capability improvement.**
|
||||
|
||||
This capability uses the **feedback pattern** - a simple, reusable approach for collecting user feedback without imposing structure or process overhead.
|
||||
|
||||
## Philosophy
|
||||
|
||||
**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.
|
||||
|
||||
**Easy Submission**: One command, or just drop a file. No forms, no required fields, no process.
|
||||
|
||||
**Maintainer Discretion**: Review and act on feedback at your own pace. Create issues, fix directly, or archive for later.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
.feedback/
|
||||
├── inbound/ # New feedback awaiting review
|
||||
├── reviewed/ # Feedback that's been reviewed (optional)
|
||||
├── archived/ # Old/resolved feedback (optional)
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
**Only `inbound/` is required.** The other directories are optional organizational tools.
|
||||
|
||||
## For Users: Submitting Feedback
|
||||
|
||||
### Option 1: Direct File Drop (Simplest)
|
||||
|
||||
Just create a markdown file in `feedback/inbound/`:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
Would be great to have progress indicators and maybe batch processing.
|
||||
|
||||
Thanks!
|
||||
EOF
|
||||
```
|
||||
|
||||
### Option 2: Use Feedback CLI (If Available)
|
||||
|
||||
Some capabilities provide a `feedback` command:
|
||||
|
||||
```bash
|
||||
# Quick text feedback
|
||||
feedback submit "Feature request: Add bulk operations"
|
||||
|
||||
# From file
|
||||
feedback submit my-detailed-feedback.md
|
||||
|
||||
# With metadata
|
||||
feedback submit "Bug report" --category=bug --contact=me@email.com
|
||||
```
|
||||
|
||||
### Option 3: From Master Project
|
||||
|
||||
If you're integrating this capability into a master project:
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
### What to Include
|
||||
|
||||
Whatever helps communicate your feedback:
|
||||
- Bug descriptions (steps to reproduce, error messages)
|
||||
- Feature requests (what you need, why it's valuable)
|
||||
- Performance issues (what's slow, your scale/context)
|
||||
- UX friction (what's confusing or difficult)
|
||||
- Positive notes (what's working well!)
|
||||
|
||||
**No required format.** Just be clear.
|
||||
|
||||
## For Maintainers: Processing Feedback
|
||||
|
||||
### Review Workflow
|
||||
|
||||
```bash
|
||||
# 1. List new feedback
|
||||
ls -lt feedback/inbound/
|
||||
|
||||
# 2. Read feedback
|
||||
cat feedback/inbound/20251217-103045-sync-issue.md
|
||||
|
||||
# 3. Decide action:
|
||||
# - Create issue if it needs tracking
|
||||
# - Fix immediately if it's quick
|
||||
# - Document insight if it's informative
|
||||
# - Archive if not applicable
|
||||
|
||||
# 4. Move to reviewed/ or archived/
|
||||
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
|
||||
```
|
||||
|
||||
### 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)"
|
||||
|
||||
# Recent feedback
|
||||
ls -lt feedback/inbound/ | head -5
|
||||
```
|
||||
|
||||
### Creating Issues from Feedback
|
||||
|
||||
```bash
|
||||
# Read feedback
|
||||
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)" \
|
||||
--label=feedback --label=feature
|
||||
|
||||
# Move to reviewed
|
||||
mv feedback/inbound/20251217-feature-request.md feedback/reviewed/
|
||||
```
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
**Pros**: Simple, no dependencies, capability-owned
|
||||
**Cons**: Manual file creation
|
||||
|
||||
### Pattern 2: Shared Feedback CLI
|
||||
|
||||
Create a reusable `feedback` command that works in any capability directory:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# feedback - Universal feedback submission tool
|
||||
|
||||
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"
|
||||
|
||||
# Create feedback directory if needed
|
||||
mkdir -p "$FEEDBACK_DIR"
|
||||
|
||||
# Submit feedback
|
||||
if [ -f "$1" ]; then
|
||||
cp "$1" "$FILENAME"
|
||||
else
|
||||
echo "$1" > "$FILENAME"
|
||||
fi
|
||||
|
||||
echo "Feedback submitted: $FILENAME"
|
||||
```
|
||||
|
||||
Install once, use everywhere:
|
||||
```bash
|
||||
cp tools/feedback /usr/local/bin/feedback
|
||||
cd any-capability
|
||||
feedback "My feedback here"
|
||||
```
|
||||
|
||||
**Pros**: Consistent UX, easy submission
|
||||
**Cons**: Requires installation
|
||||
|
||||
### Pattern 3: Makefile Integration
|
||||
|
||||
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/"
|
||||
|
||||
.PHONY: feedback-list
|
||||
feedback-list: ## List pending feedback
|
||||
@echo "Pending feedback:"
|
||||
@ls -1t feedback/inbound/ 2>/dev/null || echo " (none)"
|
||||
```
|
||||
|
||||
Usage:
|
||||
```bash
|
||||
make feedback MSG="Sync is slow with 5k issues"
|
||||
make feedback-list
|
||||
```
|
||||
|
||||
**Pros**: No extra tools, uses existing Makefile
|
||||
**Cons**: Less flexible than CLI
|
||||
|
||||
### Pattern 4: API Endpoint (Future)
|
||||
|
||||
When capabilities evolve to services:
|
||||
|
||||
```http
|
||||
POST /api/feedback
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"content": "Feedback text...",
|
||||
"category": "bug",
|
||||
"contact": "user@email.com"
|
||||
}
|
||||
```
|
||||
|
||||
Backend writes to `feedback/inbound/` maintaining consistency with other patterns.
|
||||
|
||||
## Metadata (Optional)
|
||||
|
||||
While feedback content is unstructured, you *can* add metadata using front matter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
timestamp: 2025-12-17T10:30:00Z
|
||||
category: bug
|
||||
priority: high
|
||||
contact: user@example.com
|
||||
context:
|
||||
git_repo: /path/to/master-project
|
||||
git_branch: feature/new-sync
|
||||
capability_version: 1.0.0
|
||||
---
|
||||
|
||||
Actual feedback content here...
|
||||
```
|
||||
|
||||
**Metadata is entirely optional.** Plain text/markdown works fine.
|
||||
|
||||
## Privacy
|
||||
|
||||
- Feedback is **anonymous by default** unless you include contact info
|
||||
- Git paths/context are for debugging, not shared externally
|
||||
- Capability maintainers see submitted feedback
|
||||
- No external tracking or telemetry
|
||||
|
||||
## Examples
|
||||
|
||||
**Quick Bug Report:**
|
||||
```bash
|
||||
echo "Bug: issue list crashes with --milestone='Sprint 2'" > \
|
||||
feedback/inbound/$(date +%Y%m%d)-crash-bug.md
|
||||
```
|
||||
|
||||
**Detailed Feature Request:**
|
||||
```markdown
|
||||
<!-- feedback/inbound/20251217-github-support.md -->
|
||||
|
||||
## Feature Request: GitHub Backend
|
||||
|
||||
**Problem**: Currently using Gitea, but our organization uses GitHub.
|
||||
|
||||
**Proposed Solution**: Add GitHub backend similar to existing Gitea backend.
|
||||
|
||||
**Use Case**:
|
||||
- 50+ repositories on GitHub
|
||||
- Need consistent CLI across all repos
|
||||
- Want offline sync capability
|
||||
|
||||
**Willingness to Help**: Can test beta versions, provide GitHub API expertise.
|
||||
|
||||
**Contact**: devteam@company.com
|
||||
```
|
||||
|
||||
**Performance Feedback:**
|
||||
```markdown
|
||||
<!-- feedback/inbound/20251217-sync-perf.md -->
|
||||
|
||||
Sync performance issue:
|
||||
- 5000 issues in Gitea repo
|
||||
- `issue sync pull` takes 12 minutes
|
||||
- CPU usage is low, seems like sequential API calls
|
||||
|
||||
Suggestion: Batch API requests or parallelize?
|
||||
|
||||
Thanks for the great tool!
|
||||
```
|
||||
|
||||
## For Capability Developers
|
||||
|
||||
### Setup (5 minutes)
|
||||
|
||||
```bash
|
||||
# 1. Create feedback directory
|
||||
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
|
||||
|
||||
# 4. Document in CAPABILITY-issue-tracking.yaml
|
||||
# Add to capabilities section:
|
||||
# - feedback-collection
|
||||
```
|
||||
|
||||
### Maintenance Rhythm
|
||||
|
||||
Review feedback regularly:
|
||||
- **Daily**: Quick scan of inbound
|
||||
- **Weekly**: Deep review, create issues, respond
|
||||
- **Monthly**: Archive old feedback, analyze trends
|
||||
|
||||
### Continuous Improvement Loop
|
||||
|
||||
```
|
||||
User Experience → Feedback Submission → Maintainer Review →
|
||||
→ Action (Fix/Issue/Document) → Improved Capability → Better User Experience
|
||||
```
|
||||
|
||||
The feedback loop directly informs:
|
||||
- Roadmap prioritization
|
||||
- Bug triage
|
||||
- Documentation improvements
|
||||
- UX enhancements
|
||||
|
||||
## Rationale: Why This Pattern?
|
||||
|
||||
**Decentralized**: Each capability owns its feedback. No central feedback system to maintain.
|
||||
|
||||
**Flexible**: Text files are universal. No database, no service dependencies.
|
||||
|
||||
**Durable**: Plain markdown files survive system changes, migrations, refactors.
|
||||
|
||||
**Auditable**: Git tracks all feedback. Easy to see what was submitted when.
|
||||
|
||||
**Actionable**: Close to the code. Maintainers see feedback where they work.
|
||||
|
||||
**Scalable**: Works for 1 user or 1000 users. No infrastructure needed.
|
||||
|
||||
**Future-proof**: Can evolve to CLI tools, APIs, web UIs while maintaining the same underlying structure.
|
||||
|
||||
## This Capability's Feedback
|
||||
|
||||
Yes, **this README itself** is part of the feedback capability pattern! If you have feedback about the feedback system:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
We eat our own dog food. 🐕
|
||||
|
||||
---
|
||||
|
||||
**Thank you for using the feedback pattern. Your input shapes better capabilities.**
|
||||
Reference in New Issue
Block a user