claude-flow-novice 2.10.5 → 2.10.6

package/claude-assets/commands/cfn/context-query.md

@@ -0,0 +1,215 @@
+---
+description: Query adaptive context bullets by category, tags, confidence
+tags: [context, ace, query, search, retrieval]
+---
+
+# Context Query Command
+
+Search the `adaptive_context` table to retrieve relevant bullets.
+
+**Usage:**
+```bash
+/context-query [--category=<type>] [--tags=<tag>] [--min-confidence=<0.0-1.0>]
+```
+
+**Quick SQL Queries:**
+
+```bash
+# Get top strategy bullets
+sqlite3 ./.artifacts/database/swarm-memory.db "
+SELECT bullet_id, content, confidence_score, helpful_count
+FROM adaptive_context
+WHERE is_active = 1 AND category = 'strategy' AND confidence_score >= 0.8
+ORDER BY confidence_score DESC, helpful_count DESC
+LIMIT 10;
+"
+
+# Find CFN Loop coordination patterns
+sqlite3 ./.artifacts/database/swarm-memory.db "
+SELECT bullet_id, category, content, tags
+FROM adaptive_context
+WHERE is_active = 1
+  AND (tags LIKE '%cfn-loop%' OR tags LIKE '%coordination%')
+  AND helpful_count >= 3
+ORDER BY helpful_count DESC;
+"
+
+# Get high-priority optimization tips
+sqlite3 ./.artifacts/database/swarm-memory.db "
+SELECT bullet_id, content, confidence_score, priority
+FROM adaptive_context
+WHERE is_active = 1
+  AND category = 'optimization'
+  AND priority >= 7
+ORDER BY confidence_score DESC;
+"
+
+# Get all active bullets
+sqlite3 ./.artifacts/database/swarm-memory.db "
+SELECT bullet_id, category, content, confidence_score, helpful_count, harmful_count
+FROM adaptive_context
+WHERE is_active = 1
+ORDER BY helpful_count DESC, confidence_score DESC
+LIMIT 20;
+"
+```
+
+**Arguments:**
+- `--category=<type>`: strategy|pattern|edge_case|domain_insight|anti_pattern|optimization
+- `--tags=<tag>`: Filter by tag (single tag)
+- `--min-confidence=<0.0-1.0>`: Minimum confidence (default: 0.6)
+- `--min-helpful=<N>`: Minimum helpful_count (default: 0)
+- `--limit=<N>`: Max results (default: 20)
+
+**Output Formats:**
+
+**1. Markdown (Default):**
+```markdown
+## Query Results: 10 bullets (category=strategy, min-confidence=0.8)
+
+### [STRAT-001] Use Phone Contacts as Identity Key ⭐
+When identifying relationships (roommates, contacts), prefer phone contact matching instead of description parsing.
+
+**Metadata:**
+- Confidence: 0.92 | Helpful: 12 | Harmful: 0 | Priority: 9
+- Tags: identity, matching, contacts
+- Last used: 2025-10-12 | Source: task-roomsync-v2
+- Category: strategy
+
+---
+
+### [STRAT-042] CFN Loop Coordination Strategy ⭐
+Use Redis pub/sub for ephemeral coordination state (heartbeats, signals) and SQLite for persistent audit trails and cross-loop data.
+
+**Metadata:**
+- Confidence: 0.85 | Helpful: 8 | Harmful: 0 | Priority: 8
+- Tags: cfn-loop, coordination, redis, sqlite, persistence
+- Last used: 2025-10-13 | Source: phase-0-foundation
+- Category: strategy
+
+...
+```
+
+**2. CLAUDE.md Format:**
+```markdown
+## 📘 Adaptive Context Bullets (Auto-Injected)
+
+### Strategies
+
+**[STRAT-001]** Use phone contacts as identity key when identifying relationships
+(Confidence: 0.92 | Helpful: 12 | Source: task-roomsync-v2)
+
+**[STRAT-042]** Use Redis pub/sub for ephemeral state + SQLite for persistent audit trails in CFN Loop
+(Confidence: 0.85 | Helpful: 8 | Source: phase-0-foundation)
+
+### Patterns
+
+**[PATTERN-017]** API pagination via `while true` until empty page
+(Confidence: 0.88 | Helpful: 9 | Source: task-api-pagination)
+
+...
+```
+
+**3. JSON:**
+```json
+{
+  "query": {
+    "category": "strategy",
+    "min_confidence": 0.8,
+    "limit": 10
+  },
+  "results": [
+    {
+      "bullet_id": "STRAT-001",
+      "category": "strategy",
+      "content": "Use phone contacts as identity key when identifying relationships",
+      "confidence_score": 0.92,
+      "helpful_count": 12,
+      "harmful_count": 0,
+      "priority": 9,
+      "tags": ["identity", "matching", "contacts"],
+      "source_context": "task-roomsync-v2",
+      "last_used_at": "2025-10-12T10:30:00Z",
+      "usage_count": 15
+    }
+  ],
+  "total_results": 10,
+  "avg_confidence": 0.86
+}
+```
+
+**Semantic Search (Optional):**
+If embeddings available:
+```sql
+SELECT
+    bullet_id,
+    content,
+    confidence_score,
+    helpful_count,
+    COSINE_SIMILARITY(embedding_vector, query_embedding) AS similarity
+FROM adaptive_context
+WHERE is_active = 1
+    AND similarity > 0.75
+ORDER BY similarity DESC, confidence_score DESC
+LIMIT 10;
+```
+
+**Usage Patterns:**
+
+**1. Pre-Agent Spawn Context Injection:**
+```bash
+# Get relevant bullets for agent spawn
+/context-query --tags=cfn-loop,coordination --min-confidence=0.7 --output=claude-md --inject
+
+# This injects bullets into agent's CLAUDE.md context:
+Task("coder", "Implement CFN Loop coordinator with context: [STRAT-042, PATTERN-017, ...]")
+```
+
+**2. Task-Specific Context:**
+```bash
+# Get security patterns before security audit
+/context-query --category=pattern --tags=security,acl --min-helpful=5
+
+# Get optimization tips before performance work
+/context-query --category=optimization --priority-min=7 --sort-by=helpful_count
+```
+
+**3. Debugging & Investigation:**
+```bash
+# Find related edge cases
+/context-query --category=edge_case --tags=sqlite,acl
+
+# Check anti-patterns to avoid
+/context-query --category=anti_pattern --min-harmful=3
+```
+
+**4. Learning & Documentation:**
+```bash
+# Get domain insights for documentation
+/context-query --category=domain_insight --project-id=proj-auth --output=markdown
+```
+
+**Usage Tracking:**
+When bullets are retrieved and used in task execution:
+```sql
+INSERT INTO context_usage_log (bullet_id, task_id, agent_id, usage_outcome, outcome_reason)
+VALUES ('STRAT-001', 'task-xyz', 'agent-abc', 'helpful', 'Identity matching strategy worked perfectly');
+```
+This automatically increments `helpful_count` via trigger.
+
+**Performance:**
+- Indexed queries: <5ms for tag/category filters
+- Semantic search: <50ms with embeddings (SQLite-vec extension)
+- Results cached in Redis for 5 minutes
+
+**ACL Enforcement:**
+- Respects bullet ACL levels
+- Filters results based on agent/swarm/project permissions
+- Private bullets (ACL 1) only visible to owning agent
+- Project bullets (ACL 4) visible to all project agents
+
+**See Also:**
+- `/context-reflect` - Extract lessons from execution
+- `/context-curate` - Merge reflections into context
+- `/context-inject` - Add bullets to CLAUDE.md
+- `/context-stats` - View bullet statistics

package/claude-assets/commands/cfn/context-reflect.md

@@ -0,0 +1,165 @@
+---
+description: Run ACE reflector to extract lessons from recent task execution and store in SQLite
+tags: [context, ace, reflection, learning]
+---
+
+# Context Reflection Command
+
+Spawn a `context-reflector` agent to analyze recent task execution traces and extract structured lessons (bullets) for the adaptive context system.
+
+**Usage:**
+```bash
+/context-reflect [--task-id=<id>] [--agent-id=<id>] [--auto-curate]
+```
+
+**What This Does:**
+1. Spawns `context-reflector` agent (specialized for ACE reflection)
+2. Fetches execution traces from recent tasks (or specific task if --task-id provided)
+3. Analyzes:
+   - Successful patterns and strategies
+   - Failed approaches and blockers
+   - Edge cases discovered
+   - Performance optimizations
+   - Security lessons
+4. Generates structured reflection with proposed bullets:
+   ```json
+   {
+     "reflection_type": "success|failure|optimization|edge_case|pattern",
+     "extracted_lessons": [
+       {
+         "bullet_id": "STRAT-042",
+         "category": "strategy",
+         "content": "When implementing CFN Loop coordination, use Redis pub/sub for ephemeral state and SQLite for persistent audit trails",
+         "confidence": 0.85,
+         "tags": ["cfn-loop", "coordination", "persistence"]
+       }
+     ]
+   }
+   ```
+5. Stores reflection in `context_reflections` table (ACL Level 3)
+6. If `--auto-curate`: Automatically triggers `/context-curate` to merge bullets
+
+**Arguments:**
+- `--task-id=<id>`: Reflect on specific task (default: last completed task)
+- `--agent-id=<id>`: Reflect on specific agent's work
+- `--swarm-id=<id>`: Reflect on entire swarm execution
+- `--phase=<name>`: Reflect on specific CFN Loop phase
+- `--auto-curate`: Automatically merge extracted lessons into adaptive_context table
+- `--feedback-file=<path>`: Provide additional feedback signals (test results, metrics, errors)
+- `--reflection-type=<type>`: Filter reflection focus (success/failure/optimization/edge_case/pattern)
+- `--output=<path>`: Save reflection JSON to file
+
+**Examples:**
+
+```bash
+# Reflect on last completed task
+/context-reflect
+
+# Reflect on specific task with auto-curation
+/context-reflect --task-id=task-auth-123 --auto-curate
+
+# Reflect on entire CFN Loop phase
+/context-reflect --phase=phase-0-foundation --swarm-id=swarm-xyz
+
+# Reflect with external feedback (test results)
+/context-reflect --task-id=task-api-456 --feedback-file=./test-results.json --auto-curate
+
+# Reflect on optimization opportunities
+/context-reflect --reflection-type=optimization --swarm-id=swarm-perf
+```
+
+**Implementation:**
+
+Spawn the `context-reflector` agent with task context:
+
+```javascript
+Task("context-reflector", `
+You are a Context Reflector for the ACE system.
+
+**Your Mission:**
+Analyze recent task execution and extract 3-7 high-quality lessons. For each lesson:
+
+1. **Identify the pattern/insight**: What worked? What failed? What was unexpected?
+2. **Classify the lesson**:
+   - **Strategy**: High-level approach or methodology
+   - **Pattern**: Reusable code/architecture pattern
+   - **Edge Case**: Unexpected condition or corner case
+   - **Domain Insight**: Domain-specific knowledge or constraint
+   - **Anti-Pattern**: Approach to avoid
+   - **Optimization**: Performance/efficiency improvement
+
+3. **Write the bullet**:
+   - Start with action verb (Use/Avoid/Ensure/Consider/Implement)
+   - Be specific and actionable
+   - Include context/conditions ("When X, do Y")
+   - 1-3 sentences max
+
+4. Assess confidence (0.0-1.0)
+5. Add 2-5 relevant tags
+
+**Steps:**
+1. Read recent task execution logs/context
+2. Identify patterns, successes, failures, edge cases
+3. For each lesson, use store-reflection.sh:
+
+   \`\`\`bash
+   # Create lessons file
+   cat > /tmp/lessons.json << 'EOF'
+   [
+     {
+       "bullet_id": "STRAT-XXX",
+       "category": "strategy",
+       "content": "Lesson content here",
+       "confidence": 0.85,
+       "tags": ["tag1", "tag2"]
+     }
+   ]
+   EOF
+
+   # Store reflection
+   ./.claude/skills/cfn-ace-system/store-reflection.sh \\
+     --reflection-type success \\
+     --task-id \${TASK_ID} \\
+     --agent-id \${AGENT_ID} \\
+     --lessons-file /tmp/lessons.json
+   \`\`\`
+
+4. Report reflection ID and summary
+`, "context-reflector");
+```
+
+**Post-Reflection:**
+1. If `--auto-curate` enabled: Trigger `/context-curate --reflection-id=<id>`
+2. Otherwise: Reflection queued for manual curation
+3. Print summary:
+   ```
+   ✅ Reflection Complete: reflection-abc123
+   📊 Extracted 5 lessons:
+      - STRAT-042: CFN Loop coordination strategy (confidence: 0.85)
+      - PATTERN-043: Redis pub/sub + SQLite pattern (confidence: 0.90)
+      - EDGE-044: ACL permission boundary case (confidence: 0.75)
+      ...
+
+   💡 Helpful bullets: STRAT-001, PATTERN-017
+   ⚠️  Harmful bullets: (none)
+
+   Next: Run /context-curate --reflection-id=reflection-abc123 to merge
+   ```
+
+**Integration with CFN Loop:**
+- **Loop 3 completion**: Auto-reflect on each agent's work
+- **Loop 2 validation**: Reflect on validation insights
+- **Loop 4 decision**: Reflect on PO decision reasoning
+- **Phase completion**: Comprehensive phase reflection
+
+**ACL & Security:**
+- Reflections inherit ACL from source task
+- Minimum ACL Level 3 (Swarm) - prevents private leakage
+- Sensitive data (API keys, credentials) automatically redacted
+- Audit trail in `audit_log` table
+
+**See Also:**
+- `/context-curate` - Merge reflections into adaptive context
+- `/context-query` - Search relevant bullets
+- `/context-stats` - View bullet statistics
+- `/context-inject` - Add bullets to CLAUDE.md

package/claude-assets/commands/cfn/context-stats.md

@@ -0,0 +1,294 @@
+---
+description: View adaptive context statistics, health metrics, and bullet analytics
+tags: [context, ace, stats, analytics, health]
+---
+
+# Context Statistics Command
+
+View statistics about adaptive context bullets in the database.
+
+**Usage:**
+```bash
+/context-stats [--query=<type>] [--limit=<N>]
+```
+
+**What This Does:**
+Queries the `adaptive_context` and related tables for statistics.
+
+**Arguments:**
+- `--query=<type>`: Query type (reflections|insights|summary) (default: summary)
+- `--limit=<N>`: Maximum results (default: 100)
+- `--category=<type>`: Filter by bullet category
+- `--min-confidence=<0.0-1.0>`: Filter by minimum confidence
+
+**Implementation:**
+Execute the ACE stats script directly:
+
+```bash
+# Query summary
+./.claude/skills/cfn-ace-system/invoke-context-stats.sh --query summary
+
+# Query all bullets
+sqlite3 ./.artifacts/database/swarm-memory.db "
+SELECT
+  category,
+  COUNT(*) as count,
+  AVG(confidence_score) as avg_confidence,
+  SUM(helpful_count) as total_helpful,
+  SUM(harmful_count) as total_harmful
+FROM adaptive_context
+WHERE is_active = 1
+GROUP BY category
+ORDER BY count DESC;
+"
+
+# Get top bullets
+sqlite3 ./.artifacts/database/swarm-memory.db "
+SELECT bullet_id, category, confidence_score, helpful_count, harmful_count, content
+FROM adaptive_context
+WHERE is_active = 1
+ORDER BY helpful_count DESC, confidence_score DESC
+LIMIT 10;
+"
+```
+
+**Output Example:**
+
+```
+═══════════════════════════════════════════════════════════════
+📊 ADAPTIVE CONTEXT HEALTH REPORT
+═══════════════════════════════════════════════════════════════
+
+Period: Last 30 days (2025-09-13 to 2025-10-13)
+Project: claude-flow-novice | Swarm: swarm-phase-0
+
+───────────────────────────────────────────────────────────────
+📈 BULLET STATISTICS
+───────────────────────────────────────────────────────────────
+
+Total Bullets:           127
+  └─ Active:             118 (92.9%)
+  └─ Archived:            9 (7.1%)
+
+By Category:
+  • Strategy:             42 (35.6%)  ⭐ Most common
+  • Pattern:              38 (32.2%)
+  • Edge Case:            21 (17.8%)
+  • Domain Insight:       12 (10.2%)
+  • Optimization:          5 (4.2%)
+  • Anti-Pattern:          0 (0.0%)   ✅ None identified
+
+By Confidence:
+  • High (≥0.8):          67 (56.8%)  ⭐ Strong validation
+  • Medium (0.6-0.8):     43 (36.4%)
+  • Low (<0.6):            8 (6.8%)   ⚠️  Needs validation
+
+By Priority:
+  • Critical (9-10):      15 (12.7%)
+  • High (7-8):           48 (40.7%)
+  • Medium (5-6):         42 (35.6%)
+  • Low (1-4):            13 (11.0%)
+
+───────────────────────────────────────────────────────────────
+💡 USAGE PATTERNS
+───────────────────────────────────────────────────────────────
+
+Total Usage Events:      1,847 (past 30 days)
+  └─ Helpful:           1,623 (87.9%)  ⭐ Excellent
+  └─ Harmful:              42 (2.3%)
+  └─ Neutral:             182 (9.8%)
+
+Most Used Bullets:
+  1. [STRAT-042] CFN Loop coordination      (89 uses, 0.92 confidence)
+  2. [STRAT-001] Phone contacts identity    (67 uses, 0.95 confidence)
+  3. [PATTERN-017] API pagination           (54 uses, 0.88 confidence)
+  4. [EDGE-044] SQLite ACL boundaries       (48 uses, 0.75 confidence)
+  5. [STRAT-033] Redis pub/sub patterns     (41 uses, 0.85 confidence)
+
+Least Used Bullets (>90 days):
+  ⚠️  [PATTERN-008] Legacy module pattern   (0 uses, 0.60 confidence)
+  ⚠️  [EDGE-012] Edge case description      (1 use, 0.55 confidence)
+  💡 Recommendation: Review for archival
+
+Most Improved Bullets:
+  1. [STRAT-042] +15 helpful, confidence 0.70→0.92  ⭐
+  2. [PATTERN-017] +9 helpful, confidence 0.75→0.88
+  3. [EDGE-044] +5 helpful, confidence 0.65→0.75
+
+Declining Bullets:
+  ⚠️  [PATTERN-012] +4 harmful, confidence 0.80→0.65
+  💡 Recommendation: Investigate or archive
+
+───────────────────────────────────────────────────────────────
+🔄 CURATION ACTIVITY
+───────────────────────────────────────────────────────────────
+
+Total Reflections:       34 (past 30 days)
+  └─ Processed:          31 (91.2%)
+  └─ Pending:             3 (8.8%)
+
+Total Merge Actions:     127
+  • New bullets added:    18 (14.2%)
+  • Helpful increments:   82 (64.6%)
+  • Harmful increments:   12 (9.4%)
+  • Merges/consolidations: 8 (6.3%)
+  • Archives:              7 (5.5%)
+
+Avg Time to Curation:    2.3 hours
+Avg Bullets per Reflection: 3.7
+
+Recent Curation Highlights:
+  • 2025-10-13: Merged STRAT-001 + STRAT-042 (similarity 0.91)
+  • 2025-10-12: Archived ANTI-013 (harmful_count >= 5)
+  • 2025-10-11: Added 5 new security patterns from phase-2 reflection
+
+───────────────────────────────────────────────────────────────
+🎯 QUALITY METRICS
+───────────────────────────────────────────────────────────────
+
+Average Confidence:      0.78  ⭐ Good
+  └─ Trend (30d):        ↗️  +0.05 (improving)
+
+Helpful/Harmful Ratio:   38.6:1  ⭐ Excellent
+  └─ Benchmark:          >20:1 recommended
+
+Validation Coverage:     85.6%
+  └─ Bullets validated:  101 / 118
+  └─ Pending validation: 17   ⚠️  Review queue
+
+Tag Coverage:            96.6%
+  └─ Well-tagged (≥3):   114 / 118
+  └─ Under-tagged (<3):   4    ⚠️  Needs tagging
+
+───────────────────────────────────────────────────────────────
+🔍 INSIGHTS & RECOMMENDATIONS
+───────────────────────────────────────────────────────────────
+
+✅ STRENGTHS:
+  • High helpful/harmful ratio (38.6:1)
+  • Strong confidence trend (+0.05 over 30d)
+  • Good usage distribution across categories
+  • Fast curation cycle (2.3h average)
+
+⚠️  AREAS FOR IMPROVEMENT:
+  • 8 bullets with low confidence (<0.6) need validation
+  • 2 bullets unused for >90 days should be reviewed
+  • 17 bullets pending validation (backlog building)
+  • 4 bullets under-tagged (reduces discoverability)
+
+💡 RECOMMENDATIONS:
+
+1. **Immediate Actions:**
+   - Run `/context-curate --maintenance` to deduplicate
+   - Review low-confidence bullets: EDGE-012, PATTERN-008
+   - Archive unused bullets: PATTERN-008 (90+ days, 0 uses)
+   - Validate pending bullets: Run `/context-validate --pending`
+
+2. **Phase-Specific Focus:**
+   - Phase 2 (Security): Add more security patterns (only 5 currently)
+   - Phase 3 (Deployment): Add deployment/monitoring bullets (0 currently)
+
+3. **Optimization Opportunities:**
+   - Enable semantic similarity (embeddings) for better deduplication
+   - Set up auto-validation for bullets with helpful_count ≥ 10
+   - Configure periodic maintenance curation (weekly)
+
+4. **Top Bullets to Inject:**
+   For current phase (phase-0-foundation):
+   - [STRAT-042] CFN Loop coordination (0.92 confidence, 89 uses)
+   - [STRAT-001] Phone contacts identity (0.95 confidence, 67 uses)
+   - [PATTERN-017] API pagination (0.88 confidence, 54 uses)
+
+───────────────────────────────────────────────────────────────
+📌 QUICK ACTIONS
+───────────────────────────────────────────────────────────────
+
+# Run maintenance curation
+/context-curate --maintenance --auto-merge
+
+# Inject top bullets into CLAUDE.md
+/context-inject --min-confidence=0.8 --min-helpful=10 --limit=15
+
+# Query underused bullets
+/context-query --max-usage=1 --min-confidence=0.5
+
+# Validate pending bullets
+/context-validate --pending --auto-approve-threshold=0.85
+
+───────────────────────────────────────────────────────────────
+```
+
+**JSON Output:**
+```json
+{
+  "period": {
+    "start": "2025-09-13",
+    "end": "2025-10-13",
+    "days": 30
+  },
+  "bullets": {
+    "total": 127,
+    "active": 118,
+    "archived": 9,
+    "by_category": {
+      "strategy": 42,
+      "pattern": 38,
+      "edge_case": 21,
+      "domain_insight": 12,
+      "optimization": 5,
+      "anti_pattern": 0
+    },
+    "by_confidence": {
+      "high": 67,
+      "medium": 43,
+      "low": 8
+    }
+  },
+  "usage": {
+    "total_events": 1847,
+    "helpful": 1623,
+    "harmful": 42,
+    "neutral": 182,
+    "helpful_harmful_ratio": 38.6
+  },
+  "quality_metrics": {
+    "avg_confidence": 0.78,
+    "confidence_trend": 0.05,
+    "validation_coverage": 0.856,
+    "tag_coverage": 0.966
+  },
+  "recommendations": [
+    {
+      "priority": "high",
+      "action": "Run maintenance curation",
+      "command": "/context-curate --maintenance"
+    }
+  ]
+}
+```
+
+**Trend Analysis:**
+Track confidence evolution over time:
+```sql
+SELECT
+    DATE(updated_at) as date,
+    AVG(confidence_score) as avg_confidence,
+    COUNT(*) as bullet_count
+FROM adaptive_context
+WHERE is_active = 1
+GROUP BY DATE(updated_at)
+ORDER BY date DESC
+LIMIT 30;
+```
+
+**Health Checks:**
+Automated health validation:
+- ✅ **Healthy**: helpful/harmful ratio > 20:1, avg confidence > 0.75
+- ⚠️  **Warning**: ratio 10-20:1, avg confidence 0.6-0.75
+- ❌ **Critical**: ratio < 10:1, avg confidence < 0.6
+
+**See Also:**
+- `/context-query` - Search bullets
+- `/context-curate` - Run maintenance curation
+- `/context-inject` - Inject top bullets into CLAUDE.md
+- `/context-validate` - Validate pending bullets