From 35daa514e59788250847cd706c43ea78f24c5c1d Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Wed, 17 Dec 2025 22:22:47 +0100
Subject: [PATCH] refactor: align with ReusableCapabilitiesArchitecture v0.1
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 .capability/README.md                         |   14 +-
 .capability/detach                            |  226 ++++
 .capability/feedback                          |    4 +-
 ...ITY.yaml => CAPABILITY-issue-tracking.yaml |    6 +-
 CLAUDE.md                                     |   24 +-
 ReusableCapabilitiesArchitecture.md           | 1182 +++++++++++++++++
 examples/feedback-example.md                  |   14 +-
 {.feedback => feedback}/README.md             |   60 +-
 8 files changed, 1469 insertions(+), 61 deletions(-)
 create mode 100755 .capability/detach
 rename CAPABILITY.yaml => CAPABILITY-issue-tracking.yaml (95%)
 create mode 100644 ReusableCapabilitiesArchitecture.md
 rename {.feedback => feedback}/README.md (78%)

diff --git a/.capability/README.md b/.capability/README.md
index 264664d..0185665 100644
--- a/.capability/README.md
+++ b/.capability/README.md
@@ -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
diff --git a/.capability/detach b/.capability/detach
new file mode 100755
index 0000000..666a06e
--- /dev/null
+++ b/.capability/detach
@@ -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"
diff --git a/.capability/feedback b/.capability/feedback
index 1a4ce60..f44d3a2 100755
--- a/.capability/feedback
+++ b/.capability/feedback
@@ -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
 }
 
diff --git a/CAPABILITY.yaml b/CAPABILITY-issue-tracking.yaml
similarity index 95%
rename from CAPABILITY.yaml
rename to CAPABILITY-issue-tracking.yaml
index ea4c87f..b1344dc 100644
--- a/CAPABILITY.yaml
+++ b/CAPABILITY-issue-tracking.yaml
@@ -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:
diff --git a/CLAUDE.md b/CLAUDE.md
index c9f0036..e7a842c 100644
--- a/CLAUDE.md
+++ b/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.
diff --git a/ReusableCapabilitiesArchitecture.md b/ReusableCapabilitiesArchitecture.md
new file mode 100644
index 0000000..1b83ae9
--- /dev/null
+++ b/ReusableCapabilitiesArchitecture.md
@@ -0,0 +1,1182 @@
+# Reusable Capabilities Architecture
+
+**A framework for composable, AI-integrated development capabilities**
+
+Version: 0.1.0 (Draft)
+Status: Evolving specification
+Audience: DevHumans and DevAgents
+
+---
+
+## Philosophy
+
+Capabilities are **conceptual units of reusable functionality** that focus on **use-cases and requirements** rather than rigid technical interfaces. Unlike traditional libraries or services, capabilities are designed for:
+
+- **Natural language integration** by coding agents (AI-assisted development)
+- **Requirements-level reuse** not just code-level reuse
+- **Evolutionary maturity** as implementations and patterns emerge
+- **Human-agent collaboration** in understanding and applying capabilities
+
+Capabilities bridge the gap between "what we need" (requirements) and "how we build it" (implementation), enabling both humans and AI agents to discover, understand, and integrate functionality through conceptual understanding rather than just technical contracts.
+
+---
+
+## Core Concepts
+
+### Capability Family
+
+A **Capability Family** is an abstract, conceptual grouping of related functionality defined by common use-cases and problem domains, not rigid type systems.
+
+**Examples:**
+- `issue-tracking` - Managing issues across different platforms
+- `feedback-collection` - Gathering and organizing user feedback
+- `authentication` - User identity and access management
+- `documentation-generation` - Creating docs from code/specs
+
+**Characteristics:**
+- Described in **natural language** (human and agent readable)
+- Focused on **what problems** it solves (use-cases)
+- Allows **multiple implementations** with varying approaches
+- **Evolves organically** as new use-cases emerge
+
+**Why "Family" not "Type"?**
+- "Type" implies rigid, formal contracts (technical focus)
+- "Family" implies related concepts with variation (conceptual focus)
+- Capabilities operate at the **requirements/discussion level**, not just interface level
+- AI agents understand families through natural language, not just type signatures
+
+### Capability Implementation
+
+A **Capability Implementation** is a concrete realization of a Capability Family - the actual code, tools, and patterns that provide the functionality.
+
+**Examples:**
+- `issue-facade` - An implementation of the `issue-tracking` family
+- `feedback-tool` - An implementation of the `feedback-collection` family
+
+**Characteristics:**
+- Provides **concrete functionality** (code, CLI, API)
+- May implement **multiple backend variants** (Gitea, GitHub, local)
+- Has **maturity levels** (experimental, beta, production)
+- Can be **composed with other capabilities**
+
+### Repository as Capability Provider
+
+A **repository** can provide:
+- **Single capability** (common for focused tools)
+- **Multiple capabilities** (common for mature projects)
+- **Capability variants** (different implementations of same family)
+
+---
+
+## File and Directory Conventions
+
+### Capability Declaration Files
+
+Every capability implementation must declare itself via a specification file:
+
+**Format:** `CAPABILITY-<family-name>.yaml`
+
+**Examples:**
+```
+CAPABILITY-issue-tracking.yaml       # Declares issue-tracking capability
+CAPABILITY-feedback-collection.yaml  # Declares feedback-collection capability
+CAPABILITY-authentication.yaml       # Declares authentication capability
+```
+
+**Location:** Repository root
+
+**Why this format?**
+- **Explicit family declaration** even for single-capability repos
+- **Self-documenting** - filename reveals the capability family
+- **Discoverable** - agents can glob `CAPABILITY-*.yaml`
+- **Scalable** - naturally supports multiple capabilities per repo
+
+### Single Capability Repository Structure
+
+```
+issue-facade/                              # Repository name (implementation)
+├── CAPABILITY-issue-tracking.yaml         # Declares: provides "issue-tracking"
+├── README.md                              # Human-readable documentation
+├── feedback/                              # Visible: user interface for feedback
+│   ├── inbound/
+│   ├── reviewed/
+│   └── README.md
+├── .capability/                           # Hidden: implementation infrastructure
+│   ├── feedback                           # Feedback CLI tool
+│   ├── integrate.sh                       # Integration script
+│   └── ...
+├── issue_tracker/                         # Core implementation code
+│   ├── core/
+│   ├── backends/
+│   └── cli/
+├── tests/
+└── examples/
+```
+
+**Key decisions:**
+- `feedback/` is **visible** (user-facing interface)
+- `.capability/` is **hidden** (evolving implementation details)
+- `CAPABILITY-issue-tracking.yaml` is **visible** (stable interface/contract)
+
+### Multiple Capabilities Repository Structure
+
+```
+unified-devtools/                          # Repository providing multiple capabilities
+├── CAPABILITY-issue-tracking.yaml         # First capability
+├── CAPABILITY-feedback-collection.yaml    # Second capability
+├── CAPABILITY-documentation.yaml          # Third capability
+├── README.md
+├── feedback/                              # Namespaced by family
+│   ├── issue-tracking/
+│   │   ├── inbound/
+│   │   └── reviewed/
+│   ├── feedback-collection/               # Meta: feedback about feedback!
+│   │   ├── inbound/
+│   │   └── reviewed/
+│   └── documentation/
+│       ├── inbound/
+│       └── reviewed/
+├── .capability/                           # Shared or namespaced (implementation choice)
+│   ├── issue-tracking/
+│   ├── feedback-collection/
+│   └── common/
+├── src/
+│   ├── issue_tracker/
+│   ├── feedback_tool/
+│   └── doc_generator/
+└── tests/
+```
+
+**Notes:**
+- Each capability gets its own `CAPABILITY-<family>.yaml`
+- Feedback is namespaced by family name
+- `.capability/` organization is implementation detail (can be shared or separated)
+
+---
+
+## Integrating Capabilities into Projects
+
+### The Directory Depth Problem
+
+Traditional approaches create deep directory trees:
+```
+my-project/
+└── capabilities/
+    └── issue-facade/
+        └── issue_tracker/
+            └── backends/
+                └── gitea/
+                    └── backend.py    # 6 levels deep!
+```
+
+### Proposed Solution: Underscore Prefix
+
+Use **underscore-prefixed directories** at the repository root to signal "integrated capability, not core code":
+
+**Option A: Implementation-Based (Recommended)**
+```
+my-project/
+├── _issue-facade/                  # Integrated capability (flat!)
+│   └── issue_tracker/              # Only 2-3 levels deep
+│       └── backends/
+├── _feedback-tool/                 # Another integrated capability
+├── src/                            # Core project code
+│   └── my_app/
+├── tests/
+└── README.md
+```
+
+**Option B: Family-Based**
+```
+my-project/
+├── _issue-tracking/                # Capability family
+│   └── issue-facade/               # Implementation (if multiple needed)
+├── _feedback-collection/
+│   └── feedback-tool/
+└── src/
+```
+
+**Option C: Short Alias**
+```
+my-project/
+├── c/                              # "c" for capabilities
+│   ├── issue-facade/
+│   └── feedback-tool/
+└── src/
+```
+
+**Recommendation: Option A (Implementation-Based)**
+
+**Rationale:**
+- **Flatter hierarchy** - `_issue-facade/issue_tracker/...` (3 levels vs 6)
+- **Clear signal** - underscore means "integrated, not core"
+- **Discoverable** - `ls _*/` shows all integrated capabilities
+- **No ambiguity** - implementation name is explicit
+- **Scales well** - multiple implementations of same family coexist naturally
+
+**Example:**
+```
+my-project/
+├── _issue-facade/              # Issue tracking via issue-facade
+├── _auth-service/              # Authentication via auth-service
+├── _postgres-tools/            # Database tools
+├── src/                        # Core project code
+│   └── my_app/
+│       ├── api/
+│       ├── models/
+│       └── main.py
+├── tests/
+├── README.md
+└── requirements.txt
+```
+
+**Discovery:**
+```bash
+# List all integrated capabilities
+ls -d _*/
+
+# Read capability specs
+cat _issue-facade/CAPABILITY-*.yaml
+cat _auth-service/CAPABILITY-*.yaml
+```
+
+**Important:** The underscore prefix is **local convention** for integrated capabilities, not part of the upstream git repository name. When integrating `github.com/markitect/issue-facade`, it becomes `_issue-facade/` in your project.
+
+---
+
+## CAPABILITY Specification Format
+
+### Minimal Example
+
+```yaml
+# CAPABILITY-issue-tracking.yaml
+metadata:
+  family: issue-tracking
+  implementation: issue-facade
+  version: 1.0.0
+  description: >
+    Unified interface for issue tracking across Gitea, GitHub, GitLab.
+    Enables agent coordination via standardized issue operations.
+
+purpose:
+  use_cases:
+    - "Create and manage issues programmatically"
+    - "Coordinate multi-agent workflows via issue states"
+    - "Offline issue tracking with sync to remote platforms"
+
+  problems_solved:
+    - "Platform-specific API differences"
+    - "Credential management across multiple backends"
+    - "Offline/online workflow complexity"
+
+integration:
+  methods:
+    python_api: true
+    cli: true
+    mcp_server: false  # planned
+
+  installation:
+    command: "pip install -e _issue-facade/"
+    verify: "issue --version"
+
+documentation:
+  readme: "README.md"
+  integration_guide: "AGENT_INTEGRATION.md"
+  examples: "examples/"
+
+feedback:
+  enabled: true
+  directory: "feedback/"
+```
+
+### Comprehensive Example
+
+```yaml
+# CAPABILITY-issue-tracking.yaml
+metadata:
+  family: issue-tracking
+  implementation: issue-facade
+  version: 1.0.0
+  maturity: production  # experimental, beta, production
+
+  description: >
+    Universal CLI for issue tracking that provides a unified interface
+    to multiple issue tracking backends. Designed for agent coordination
+    via standardized issue operations across platforms.
+
+# What problems this capability solves
+purpose:
+  primary: "Agent coordination via issue tracking"
+
+  use_cases:
+    - "Create, update, query issues across platforms"
+    - "Multi-agent task coordination through issue states"
+    - "Offline development with sync to remote backends"
+    - "Unified issue management for polyglot platform environments"
+
+  problems_solved:
+    - "Direct API calls to GitHub/GitLab/Gitea (avoids credential sprawl)"
+    - "Inconsistent issue tracking access patterns"
+    - "Platform-specific code in agents"
+    - "Offline/online workflow synchronization"
+
+# When to use this capability
+usage_rules:
+  MUST_USE_INSTEAD_OF:
+    - "Direct Gitea/GitHub/GitLab API calls"
+    - "Platform-specific CLIs (gh, glab)"
+    - "Python libraries (PyGithub, python-gitlab)"
+
+  USE_WHEN:
+    - "Creating, updating, or querying issues"
+    - "Multi-agent coordination needed"
+    - "Offline work with sync required"
+    - "Cross-platform issue management"
+
+# How to integrate this capability
+integration:
+  methods:
+    python_api:
+      available: true
+      import: "from issue_tracker.backends.gitea import GiteaBackend"
+      docs: "AGENT_INTEGRATION.md"
+
+    cli:
+      available: true
+      command: "issue"
+      subcommands: ["list", "create", "show", "edit", "close", "comment"]
+      json_output: true
+
+    mcp_server:
+      available: false
+      status: planned
+      version: "2.0.0"
+
+  installation:
+    method: pip
+    command: "pip install -e _issue-facade/"
+    verify: "issue --version"
+
+  configuration:
+    required: true
+    method: manual  # auto-detection planned for v1.1
+    steps:
+      - "Export GITEA_API_TOKEN environment variable"
+      - "Run: issue backend add myproject gitea"
+      - "Provide: URL, owner, repo when prompted"
+      - "Run: issue backend set-default myproject"
+
+# API surface for agents
+api:
+  core_operations:
+    - name: list_issues
+      description: "Query issues with filtering"
+      python: "backend.list_issues(IssueFilter(state='open', labels=['bug']))"
+      cli: "issue list --state=open --label=bug --format=json"
+
+    - name: create_issue
+      description: "Create new issue"
+      python: "backend.create_issue(Issue(...))"
+      cli: "issue create 'Title' --label=bug --assignee=agent"
+
+    - name: update_issue
+      description: "Update existing issue"
+      python: "backend.update_issue(issue)"
+      cli: "issue edit 42 --state=in_progress"
+
+# Backend variants provided
+backends:
+  - name: gitea
+    status: production
+    features: [crud, sync, labels, milestones, comments]
+
+  - name: local-sqlite
+    status: production
+    features: [crud, offline, sync]
+
+  - name: github
+    status: planned
+    target_version: "1.1.0"
+
+# Depends on other capabilities
+dependencies:
+  capabilities:
+    - family: feedback-collection
+      optional: true
+      reason: "Integrated feedback system for continuous improvement"
+
+# Performance characteristics
+efficiency:
+  local_caching: true
+  offline_mode: true
+  batch_operations: false  # v1.0 limitation
+  rate_limiting: automatic
+
+# Credentials and security
+credentials:
+  method: environment_variables
+  variables:
+    - GITEA_API_TOKEN
+    - GITEA_URL  # optional with config
+
+  security:
+    - "Tokens never in code or logs"
+    - "Config stored in ~/.config/issue-facade/"
+    - "Per-repo config in .issue-facade/ (gitignored)"
+
+# Documentation references
+documentation:
+  readme: "README.md"
+  integration_guide: "AGENT_INTEGRATION.md"
+  development_guide: "CLAUDE.md"
+  roadmap: "ROADMAP.md"
+  examples: "examples/agents/"
+  api_docs: null  # not yet available
+
+# Feedback system
+feedback:
+  enabled: true
+  directory: "feedback/"
+  cli_tool: ".capability/feedback"
+
+  for_users: |
+    Submit feedback: ./.capability/feedback submit "Your feedback"
+
+  for_maintainers: |
+    Review feedback: ./.capability/feedback list
+
+# Testing and validation
+testing:
+  test_command: "make test"
+  coverage: 61%
+  test_count: 109
+
+  verify_installation: |
+    issue backend list
+    issue list --format=json | jq 'length'
+
+# Current limitations
+limitations:
+  - "Manual backend configuration required (auto-detect in v1.1)"
+  - "No built-in issue locking (workaround via assignee + comment)"
+  - "Basic conflict resolution (advanced in v2.0)"
+
+# Roadmap
+roadmap:
+  v1.1:
+    - "Auto-detection from git remotes"
+    - "GitHub backend support"
+  v1.2:
+    - "Agent identity management"
+    - "Issue claiming/locking API"
+  v2.0:
+    - "Issue dependencies"
+    - "Distributed locking"
+    - "MCP server integration"
+
+# Priority for agent integration
+priority:
+  score: 95  # 0-100, where 100 = critical
+  reasoning: >
+    Critical for agent coordination. Bypassing this capability leads to
+    credential sprawl, inconsistent state, and race conditions.
+```
+
+---
+
+## Discovery and Integration Patterns
+
+### For DevHumans
+
+**Discover capabilities in a repository:**
+```bash
+# List all capability declarations
+ls CAPABILITY-*.yaml
+
+# Read a specific capability
+cat CAPABILITY-issue-tracking.yaml
+
+# View feedback
+ls feedback/
+cat feedback/README.md
+```
+
+**Integrate a capability:**
+```bash
+# Clone/copy into underscore-prefixed directory
+git clone https://github.com/markitect/issue-facade _issue-facade
+
+# Or use git submodule
+git submodule add https://github.com/markitect/issue-facade _issue-facade
+
+# Install
+pip install -e _issue-facade/
+
+# Verify
+issue --version
+```
+
+### For DevAgents
+
+**Discover capabilities programmatically:**
+```python
+import glob
+import yaml
+from pathlib import Path
+
+def discover_capabilities(repo_path):
+    """Discover all capabilities provided by a repository."""
+    capabilities = []
+
+    for spec_file in glob.glob(f"{repo_path}/CAPABILITY-*.yaml"):
+        with open(spec_file) as f:
+            spec = yaml.safe_load(f)
+            capabilities.append(spec)
+
+    return capabilities
+
+def find_capability_family(repo_path, family_name):
+    """Find a specific capability family implementation."""
+    spec_file = f"{repo_path}/CAPABILITY-{family_name}.yaml"
+
+    if Path(spec_file).exists():
+        with open(spec_file) as f:
+            return yaml.safe_load(f)
+
+    return None
+
+# Usage
+capabilities = discover_capabilities("_issue-facade")
+# Returns: [{'metadata': {'family': 'issue-tracking', ...}}]
+
+issue_cap = find_capability_family("_issue-facade", "issue-tracking")
+print(f"Found: {issue_cap['metadata']['implementation']}")
+# Output: Found: issue-facade
+```
+
+**Use capability via natural language understanding:**
+```python
+# Agent reads capability spec
+spec = find_capability_family("_issue-facade", "issue-tracking")
+
+# Agent understands use-cases
+use_cases = spec['purpose']['use_cases']
+# ["Create and manage issues programmatically", ...]
+
+# Agent discovers integration methods
+if spec['integration']['methods']['python_api']['available']:
+    import_statement = spec['integration']['methods']['python_api']['import']
+    # "from issue_tracker.backends.gitea import GiteaBackend"
+
+    # Agent can now integrate programmatically
+    exec(import_statement)
+
+# Or use CLI
+if spec['integration']['methods']['cli']['available']:
+    cli_command = spec['integration']['methods']['cli']['command']
+    # "issue"
+
+    # Agent executes CLI commands
+    os.system(f"{cli_command} list --format=json")
+```
+
+**Provide feedback:**
+```python
+# Agent encounters issue, submits feedback
+feedback_dir = spec['feedback']['directory']
+feedback_file = f"{feedback_dir}/inbound/{timestamp}-{hash}.md"
+
+with open(feedback_file, 'w') as f:
+    f.write(f"""---
+timestamp: {now}
+source: agent
+category: bug
+---
+
+Encountered error when syncing 5000+ issues: TimeoutError
+Suggest implementing batch processing.
+""")
+```
+
+---
+
+## Capability Composition
+
+### Capabilities Using Capabilities
+
+Capabilities can depend on other capabilities:
+
+```yaml
+# CAPABILITY-project-management.yaml
+metadata:
+  family: project-management
+  implementation: pm-tool
+  version: 1.0.0
+
+# This capability integrates other capabilities
+integrates:
+  - family: issue-tracking
+    implementation: issue-facade
+    version: ">=1.0.0"
+    reason: "Uses issue tracking for task management"
+
+  - family: feedback-collection
+    implementation: feedback-tool
+    version: ">=1.0.0"
+    reason: "Collects user feedback about project"
+
+  - family: documentation
+    implementation: doc-gen
+    version: ">=0.5.0"
+    reason: "Generates project documentation"
+```
+
+**Repository structure:**
+```
+pm-tool/
+├── CAPABILITY-project-management.yaml
+├── _issue-facade/                    # Integrated capability
+├── _feedback-tool/                   # Integrated capability
+├── _doc-gen/                         # Integrated capability
+├── src/
+│   └── pm/
+│       ├── tasks.py                  # Uses issue-facade
+│       ├── feedback.py               # Uses feedback-tool
+│       └── docs.py                   # Uses doc-gen
+└── README.md
+```
+
+### Capability Families as Contracts
+
+When one capability depends on a **family** (not a specific implementation), it creates a flexible contract:
+
+```yaml
+# pm-tool requires "issue-tracking" family
+integrates:
+  - family: issue-tracking    # Any implementation works!
+    version: ">=1.0.0"
+```
+
+**Multiple valid integrations:**
+```
+pm-tool/
+├── _issue-facade/            # Option 1: issue-facade implementation
+└── ...
+
+pm-tool/
+├── _github-native/           # Option 2: github-native implementation
+└── ...
+
+pm-tool/
+├── _jira-bridge/             # Option 3: jira-bridge implementation
+└── ...
+```
+
+All three satisfy the `issue-tracking` family contract!
+
+---
+
+## Maturity Levels
+
+Capabilities evolve through maturity stages:
+
+### Experimental
+- **Purpose:** Exploring concepts, validating ideas
+- **Stability:** APIs may change drastically
+- **Testing:** Minimal, proof-of-concept level
+- **Documentation:** Basic README
+- **Use case:** Research, prototyping, learning
+
+```yaml
+metadata:
+  maturity: experimental
+  version: 0.1.0
+```
+
+### Beta
+- **Purpose:** Solidifying patterns, gathering feedback
+- **Stability:** Core APIs stabilizing, minor changes possible
+- **Testing:** Comprehensive tests, some production use
+- **Documentation:** Complete user guide, examples
+- **Use case:** Early adopters, non-critical projects
+
+```yaml
+metadata:
+  maturity: beta
+  version: 0.9.0
+```
+
+### Production
+- **Purpose:** Stable, reliable, widely used
+- **Stability:** Semantic versioning, backward compatibility
+- **Testing:** Extensive tests, battle-tested
+- **Documentation:** Complete docs, tutorials, troubleshooting
+- **Use case:** Production systems, critical workflows
+
+```yaml
+metadata:
+  maturity: production
+  version: 1.0.0
+```
+
+---
+
+## Evolution and Governance
+
+### How Capability Families Emerge
+
+1. **Pattern Recognition** - Similar needs across multiple projects
+2. **Natural Language Discussion** - DevHumans and agents discuss requirements
+3. **Prototype Implementation** - First experimental implementation
+4. **Specification Emergence** - Common use-cases documented
+5. **Multiple Implementations** - Different approaches to same family
+6. **Standardization** - Family contract stabilizes
+
+**Example: The `issue-tracking` family**
+```
+Project A needs GitHub issues
+Project B needs GitLab issues
+Project C needs Gitea issues
+
+→ Pattern: "We need issue tracking"
+→ Family: "issue-tracking"
+→ Implementation 1: issue-facade (multi-backend)
+→ Implementation 2: github-native (GitHub-only, optimized)
+→ Implementation 3: jira-bridge (JIRA connector)
+
+All implement "issue-tracking" family with different trade-offs
+```
+
+### Versioning Strategy
+
+**Capability Family Versions:**
+- Families evolve slowly (conceptual stability)
+- Major version when use-cases fundamentally change
+- Example: `issue-tracking@1.x` vs `issue-tracking@2.x`
+
+**Implementation Versions:**
+- Implementations evolve independently
+- Follow semantic versioning (semver)
+- Example: `issue-facade@1.2.3`, `github-native@0.5.0`
+
+**Compatibility:**
+```yaml
+# Implementation declares family version compatibility
+metadata:
+  family: issue-tracking
+  family_version: "1.x"           # Compatible with v1 family spec
+  implementation: issue-facade
+  version: 1.2.3                  # Implementation version
+```
+
+---
+
+## Best Practices
+
+### For Capability Developers
+
+1. **Start with Use-Cases** - What problems are you solving?
+2. **Write for Agents** - Natural language descriptions, clear contracts
+3. **Provide Feedback Mechanism** - `feedback/` directory from day one
+4. **Document Integration Paths** - Python API, CLI, future MCP
+5. **Test Thoroughly** - Both unit tests and integration scenarios
+6. **Evolve Gradually** - Experimental → Beta → Production
+7. **Semantic Versioning** - Breaking changes = major version bump
+
+### For Capability Users (Integrators)
+
+1. **Prefer Families over Implementations** - Depend on `issue-tracking`, not `issue-facade`
+2. **Pin Versions Loosely** - `>=1.0.0, <2.0.0` allows updates
+3. **Use Underscore Prefix** - `_issue-facade/` signals "integrated"
+4. **Provide Feedback** - Use `feedback/` to guide improvement
+5. **Read the Spec** - `CAPABILITY-*.yaml` is the contract
+6. **Check Maturity** - Match capability maturity to your needs
+
+### For AI Agents
+
+1. **Parse CAPABILITY-*.yaml** - Structured data about capabilities
+2. **Understand Natural Language** - Use-cases, descriptions, reasoning
+3. **Discover Programmatically** - Glob patterns, YAML parsing
+4. **Integrate Flexibly** - Python API, CLI, or direct file access
+5. **Submit Feedback Automatically** - Report issues, suggest improvements
+6. **Respect Maturity Levels** - Experimental = expect changes
+
+---
+
+## Migration Guide
+
+### From Current (hidden feedback) to Architecture v0.1
+
+**Changes:**
+1. Rename `feedback/` → `feedback/` (visible)
+2. Keep `.capability/` (hidden infrastructure)
+3. Rename `CAPABILITY-issue-tracking.yaml` → `CAPABILITY-<family>.yaml`
+
+**Steps:**
+```bash
+# 1. Rename feedback directory
+mv .feedback feedback
+
+# 2. Rename capability spec
+mv CAPABILITY-issue-tracking.yaml CAPABILITY-issue-tracking.yaml
+
+# 3. Update references in code/docs
+grep -r "\.feedback" . | # Find references
+sed -i 's/\.feedback/feedback/g' **/*.md
+
+# 4. Update .gitignore if needed
+# Remove .feedback from ignore, keep .capability
+```
+
+**Commit:**
+```bash
+git add feedback/ CAPABILITY-issue-tracking.yaml
+git rm -r .feedback/
+git commit -m "refactor: align with ReusableCapabilitiesArchitecture v0.1"
+```
+
+---
+
+## FAQ
+
+### Why underscore prefix for integrated capabilities?
+
+**Problem:** Deep directory trees, unclear what's "yours" vs "integrated"
+
+**Solution:** Underscore signals "used by this repo, not core to it"
+
+**Benefits:**
+- Visual distinction: `_issue-facade/` vs `src/`
+- Flatter hierarchy: 2-3 levels vs 5-6 levels
+- Easy discovery: `ls _*/` lists all integrations
+- Works with tab completion: `cd _<tab>` shows capabilities
+
+**Trade-off:** Prefix is local convention, not in upstream repo name
+
+### Why "Family" instead of "Type"?
+
+**Type** implies:
+- Rigid, formal contracts
+- Technical focus (interfaces, signatures)
+- Compile-time checking
+
+**Family** implies:
+- Conceptual grouping
+- Natural language understanding
+- Evolutionary, organic development
+- AI-friendly (agents understand families through discussion)
+
+Capabilities operate at the **requirements level** where natural language and flexible understanding matter more than rigid types.
+
+### Can one repo provide multiple implementations of the same family?
+
+Yes! Example:
+
+```
+multi-backend-tool/
+├── CAPABILITY-issue-tracking-v1.yaml      # Stable, production backend
+├── CAPABILITY-issue-tracking-v2.yaml      # Experimental, next-gen backend
+├── src/
+│   ├── v1/                                # issue-facade-classic
+│   └── v2/                                # issue-facade-next
+└── README.md
+```
+
+Both implement `issue-tracking` family with different approaches.
+
+### How do agents choose between multiple implementations?
+
+Agents consider:
+1. **Maturity** - Production > Beta > Experimental
+2. **Version compatibility** - Match required version range
+3. **Features** - Does it support needed backends?
+4. **Context** - User preferences, existing config
+5. **Natural language** - Description match to requirements
+
+```python
+# Agent logic
+capabilities = discover_capabilities(".")
+issue_trackers = [c for c in capabilities if c['metadata']['family'] == 'issue-tracking']
+
+# Filter by maturity
+production_ready = [c for c in issue_trackers if c['metadata']['maturity'] == 'production']
+
+# Choose highest version
+best = max(production_ready, key=lambda c: c['metadata']['version'])
+```
+
+### What about backward compatibility?
+
+**Capability Family:**
+- Maintain backward compatibility within major version
+- `issue-tracking@1.x` stays stable
+- `issue-tracking@2.x` can break compatibility
+
+**Implementation:**
+- Semantic versioning (semver)
+- `1.2.3` → `1.3.0` = backward compatible
+- `1.3.0` → `2.0.0` = breaking changes
+
+**Contract:**
+```yaml
+# Implementation declares compatibility
+metadata:
+  family: issue-tracking
+  family_version: "1.x"      # Works with v1 family specs
+  version: 1.2.3             # Implementation version
+```
+
+### How do I create a new capability family?
+
+1. **Identify the pattern** - Multiple projects need similar functionality
+2. **Write use-cases** - What problems does it solve?
+3. **Create first implementation** - Experimental, version 0.1.0
+4. **Write CAPABILITY-<family>.yaml** - Document contract
+5. **Gather feedback** - Use `feedback/` from early users
+6. **Iterate** - Refine based on real-world usage
+7. **Stabilize** - Reach beta/production maturity
+
+**No central registry required!** Families emerge organically through use.
+
+---
+
+## Examples
+
+### Example 1: Simple Single Capability
+
+```
+password-generator/
+├── CAPABILITY-password-generation.yaml
+├── README.md
+├── feedback/
+│   ├── inbound/
+│   └── README.md
+├── .capability/
+│   └── feedback
+├── src/
+│   └── pwgen/
+│       ├── generator.py
+│       ├── strength.py
+│       └── cli.py
+└── tests/
+```
+
+### Example 2: Multiple Capabilities
+
+```
+devtools-suite/
+├── CAPABILITY-issue-tracking.yaml
+├── CAPABILITY-code-review.yaml
+├── CAPABILITY-deployment.yaml
+├── README.md
+├── feedback/
+│   ├── issue-tracking/
+│   ├── code-review/
+│   └── deployment/
+├── .capability/
+│   ├── common/
+│   └── feedback
+└── src/
+    ├── issues/
+    ├── review/
+    └── deploy/
+```
+
+### Example 3: Project Integrating Capabilities
+
+```
+my-saas-app/
+├── _issue-facade/              # Issue tracking capability
+├── _auth-service/              # Authentication capability
+├── _feedback-tool/             # Feedback collection capability
+├── src/
+│   └── myapp/
+│       ├── api/
+│       │   ├── issues.py       # Uses _issue-facade
+│       │   └── auth.py         # Uses _auth-service
+│       ├── models/
+│       └── main.py
+├── tests/
+├── README.md
+└── requirements.txt
+```
+
+**Installation:**
+```bash
+# Clone integrated capabilities
+git submodule add https://github.com/markitect/issue-facade _issue-facade
+git submodule add https://github.com/markitect/auth-service _auth-service
+git submodule add https://github.com/markitect/feedback-tool _feedback-tool
+
+# Install
+pip install -e _issue-facade/ -e _auth-service/ -e _feedback-tool/
+
+# Use in code
+from issue_tracker.backends.gitea import GiteaBackend
+from auth_service import AuthManager
+```
+
+---
+
+## Appendix: Complete CAPABILITY-*.yaml Template
+
+```yaml
+# CAPABILITY-<family-name>.yaml
+# Complete template with all optional fields
+
+metadata:
+  family: <family-name>
+  implementation: <implementation-name>
+  version: 1.0.0
+  maturity: production  # experimental, beta, production
+  description: >
+    One-paragraph description of this capability implementation.
+    Focus on what it does and why it's useful.
+
+purpose:
+  primary: "Main use-case in one sentence"
+
+  use_cases:
+    - "Specific use-case 1"
+    - "Specific use-case 2"
+    - "Specific use-case 3"
+
+  problems_solved:
+    - "Problem 1 this capability addresses"
+    - "Problem 2 this capability addresses"
+
+usage_rules:
+  MUST_USE_INSTEAD_OF:
+    - "Anti-pattern 1 this replaces"
+    - "Anti-pattern 2 this replaces"
+
+  PREFER_OVER:
+    - "Alternative 1"
+
+  USE_WHEN:
+    - "Situation 1"
+    - "Situation 2"
+
+integration:
+  methods:
+    python_api:
+      available: true
+      import: "from module import Class"
+      docs: "path/to/docs.md"
+
+    cli:
+      available: true
+      command: "command-name"
+      subcommands: ["sub1", "sub2"]
+      json_output: true
+
+    mcp_server:
+      available: false
+      status: planned
+
+  installation:
+    method: pip
+    command: "pip install -e _implementation/"
+    verify: "command --version"
+
+  configuration:
+    required: true
+    method: manual
+    steps:
+      - "Step 1"
+      - "Step 2"
+
+api:
+  core_operations:
+    - name: operation_name
+      description: "What this operation does"
+      python: "code.example()"
+      cli: "command example"
+
+backends:
+  - name: backend1
+    status: production
+    features: [feature1, feature2]
+
+dependencies:
+  capabilities:
+    - family: other-family
+      version: ">=1.0.0"
+      optional: false
+      reason: "Why this dependency exists"
+
+efficiency:
+  local_caching: true
+  offline_mode: false
+  batch_operations: true
+  rate_limiting: automatic
+
+credentials:
+  method: environment_variables
+  variables:
+    - ENV_VAR_1
+    - ENV_VAR_2
+  security:
+    - "Security practice 1"
+
+documentation:
+  readme: "README.md"
+  integration_guide: "INTEGRATION.md"
+  examples: "examples/"
+
+feedback:
+  enabled: true
+  directory: "feedback/"
+  cli_tool: ".capability/feedback"
+
+testing:
+  test_command: "make test"
+  coverage: 85%
+  test_count: 150
+
+limitations:
+  - "Limitation 1"
+  - "Limitation 2"
+
+roadmap:
+  v1.1:
+    - "Feature 1"
+  v2.0:
+    - "Breaking change 1"
+
+priority:
+  score: 80
+  reasoning: >
+    Why this capability is important for agents to use.
+```
+
+---
+
+## Changelog
+
+- **v0.1.0** (2025-12-17) - Initial draft
+  - Core concepts defined
+  - File conventions established
+  - Integration patterns documented
+  - Examples provided
+
+---
+
+## License
+
+This architecture document is part of the MarkiTect project and is licensed under MIT License.
+
+## Contributing
+
+This architecture is **evolving**. Feedback is essential:
+
+```bash
+cd /path/to/capability-repo
+./.capability/feedback submit "Architecture feedback: ..."
+```
+
+Or open an issue/PR in the MarkiTect project repository.
+
+---
+
+**Thank you for building reusable capabilities!**
diff --git a/examples/feedback-example.md b/examples/feedback-example.md
index fa2bf24..ed9efb2 100644
--- a/examples/feedback-example.md
+++ b/examples/feedback-example.md
@@ -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?
 
diff --git a/.feedback/README.md b/feedback/README.md
similarity index 78%
rename from .feedback/README.md
rename to feedback/README.md
index a9cecbe..c1dbdc5 100644
--- a/.feedback/README.md
+++ b/feedback/README.md
@@ -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. 🐕