aiox-core 5.0.2 → 5.0.4

package/pro/squads/squad-creator-pro/tasks/refresh-registry.md

@@ -0,0 +1,403 @@
+# Task: Refresh Squad Registry
+
+**Task ID:** refresh-registry
+**Version:** 2.0.0
+**Purpose:** Scan all squads in the ecosystem and update squad-registry.yaml
+**Orchestrator:** @squad-chief
+**Mode:** Hybrid (Script + LLM)
+**Execution Type:** `Hybrid` (Worker script + Agent enrichment)
+**Worker Script:** `scripts/refresh-registry.py`
+
+**Architecture:**
+```
+DETERMINISTIC (Python Script)          LLM (Semantic Understanding)
+├── Count agents, tasks, etc.          ├── Infer domain category
+├── Read config.yaml metadata          ├── Extract keywords from README
+├── List directory contents            ├── Generate highlights
+├── Validate YAML syntax               ├── Generate example_use
+└── Output structured JSON             └── Analyze gaps
+```
+
+**Script:** `scripts/refresh-registry.py`
+
+---
+
+## Overview
+
+This task uses a hybrid approach:
+1. **Python script** handles all deterministic operations (counts, file reads)
+2. **LLM** handles semantic understanding (keywords, domain inference)
+
+```
+TRIGGER (hook or command)
+    ↓
+[STEP 1: RUN SCRIPT] (Deterministic)
+    → python3 scripts/refresh-registry.py --output json
+    → Gets: counts, config metadata, agent names
+    → Output: structured JSON with factual data
+    ↓
+[STEP 2: LLM ENRICHMENT] (Semantic)
+    → For each squad:
+      - Infer domain from description
+      - Extract keywords from README
+      - Generate highlights
+      - Generate example_use
+    ↓
+[STEP 3: MERGE]
+    → Combine script output + LLM enrichment
+    → Preserve manual annotations (quality_reference)
+    → Update domain_index
+    ↓
+[STEP 4: WRITE]
+    → Write updated squad-registry.yaml
+    → Validate YAML syntax
+    ↓
+OUTPUT: Updated squad-registry.yaml
+```
+
+---
+
+## Triggers (Hooks)
+
+### 1. Manual Command
+```bash
+*refresh-registry
+```
+
+### 2. On Squad-Creator Activation (Optional)
+```yaml
+# In squad-chief.md activation-instructions
+auto_refresh:
+  enabled: false  # Set to true for auto-refresh
+  condition: "registry older than 24 hours"
+```
+
+### 3. After Creating New Squad
+```yaml
+# Automatic trigger after *create-squad completes
+post_create_hook:
+  action: "refresh-registry"
+  when: "squad creation successful"
+```
+
+### 4. Pre-Commit Hook (Recommended)
+```bash
+# .claude/hooks/refresh-registry.sh
+# Trigger: Changes to squads/*/config.yaml
+
+#!/bin/bash
+if git diff --cached --name-only | grep -q "squads/.*/config.yaml"; then
+  echo "Squad config changed, refreshing registry..."
+  # Claude Code will handle this via hook
+fi
+```
+
+---
+
+## Inputs
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `squads_path` | string | No | `squads/` | Base path to scan |
+| `preserve_manual` | boolean | No | `true` | Keep manual highlights, quality_reference |
+| `update_gaps` | boolean | No | `false` | Re-analyze gaps (slower) |
+
+---
+
+## Execution Steps
+
+### Step 1: Run Python Script (DETERMINISTIC)
+
+```bash
+# Run the refresh script
+python3 squads/squad-creator-pro/scripts/refresh-registry.py --output json --registry-format
+```
+
+**Script Output:**
+```json
+{
+  "metadata": {
+    "scan_date": "2026-02-01T13:04:19",
+    "total_squads": 22
+  },
+  "squads": {
+    "{squad-name}": {  // Example: "copy", "legal", "data"
+      "path": "squads/{squad-name}/",
+      "version": "1.0.0",
+      "description": "Squad description...",
+      "counts": {
+        "agents": N,
+        "tasks": N,
+        "workflows": N,
+        "templates": N,
+        "checklists": N,
+        "data_files": N
+      },
+      "agent_names": ["{agent-1}", "{agent-2}", ...],  // Your agent names
+      "domain": "_TO_BE_INFERRED_",  // LLM will fill
+      "keywords": [],                 // LLM will fill
+      "highlights": [],               // LLM will fill
+      "example_use": ""               // LLM will fill
+    }
+  },
+  "summary": {
+    "total_agents": 124,
+    "total_tasks": 291,
+    "total_workflows": 49
+  }
+}
+```
+
+**What Script Does (Deterministic):**
+- Scans `squads/` directory
+- Reads each `config.yaml`
+- Counts files in each subdirectory
+- Lists agent names
+- Checks for README.md, CHANGELOG.md
+- Validates YAML syntax
+
+**What Script Does NOT Do:**
+- Infer domain category
+- Extract keywords
+- Generate highlights
+- Generate example_use
+
+### Step 2: LLM Enrichment (SEMANTIC)
+
+For each squad in script output, LLM analyzes:
+
+```yaml
+llm_enrichment:
+  for_each_squad:
+    # Read README.md for context
+    read: "squads/{name}/README.md"
+
+    infer_domain:
+      from: "description + README overview"
+      categories:
+        - content_marketing
+        - technical
+        - business_ops
+        - people_psychology
+        - meta_frameworks
+      output: "Single category that best fits"
+
+    extract_keywords:
+      from: "README.md + agent_names + description"
+      method: |
+        1. Extract nouns and key phrases
+        2. Include agent names as keywords
+        3. Add domain-specific terms
+        4. Deduplicate and lowercase
+      output: "List of 5-15 keywords"
+
+    generate_highlights:
+      from: "README.md + counts + agent_names"
+      method: |
+        1. What makes this squad unique?
+        2. Key features or capabilities
+        3. Notable agents or frameworks
+      output: "List of 2-4 bullet points"
+
+    generate_example_use:
+      from: "purpose + keywords"
+      method: "Create realistic usage example"
+      output: "Single sentence starting with verb"
+```
+
+### Step 3: Build Registry Entry
+
+```yaml
+build_entry:
+  template: |
+    {squad_name}:
+      path: "squads/{squad_name}/"
+      domain: "{inferred_domain}"
+      purpose: "{description_from_config}"
+      keywords: {extracted_keywords}
+      agents: {agent_count}
+      tasks: {task_count}
+      workflows: {workflow_count}
+      highlights:
+        - "{auto_generated_highlight_1}"
+        - "{auto_generated_highlight_2}"
+      example_use: "{generated_example}"
+
+  preserve_if_exists:
+    - highlights  # Keep manual annotations
+    - quality_reference
+    - example_use  # Keep if manually set
+```
+
+### Step 4: Update Domain Index
+
+```yaml
+update_domain_index:
+  for_each_squad:
+    - Add squad.domain → squad_name mapping
+    - Add each keyword → squad_name mapping
+
+  handle_conflicts:
+    # If keyword maps to multiple squads
+    action: "keep both, note in comments"
+    example: |
+      analytics: ["data", "monitor"]  # Multiple squads cover this
+```
+
+### Step 5: Update Gaps Analysis
+
+```yaml
+update_gaps:
+  # Only if update_gaps=true (slower operation)
+  known_domains:
+    - finance
+    - health
+    - sales
+    - customer_success
+    - product_management
+    - research
+    - real_estate
+
+  for_each_gap:
+    check: "Is there now a squad covering this?"
+    if_covered: "Remove from gaps"
+    if_not_covered: "Keep in gaps"
+```
+
+### Step 6: Write Updated Registry
+
+```yaml
+write_registry:
+  file: "squads/squad-creator-pro/data/squad-registry.yaml"
+
+  structure:
+    metadata:
+      version: "1.0.0"
+      last_updated: "{current_date}"
+      total_squads: "{count}"
+      maintainer: "squad-creator"
+
+    squads: "{all_squad_entries}"
+    domain_index: "{all_mappings}"
+    gaps: "{remaining_gaps}"
+    quality_references: "{preserved_from_original}"
+    conventions: "{preserved_from_original}"
+
+  validate:
+    - "YAML syntax valid"
+    - "No duplicate squad names"
+    - "All paths exist"
+```
+
+---
+
+## Output
+
+```yaml
+output:
+  file: "squads/squad-creator-pro/data/squad-registry.yaml"
+  console: |
+    Registry updated successfully!
+
+    Squads: {total} ({new} new, {updated} updated)
+    Domains covered: {domain_count}
+    Gaps remaining: {gap_count}
+
+    New squads detected:
+    - {new_squad_1}
+    - {new_squad_2}
+
+    Updated squads:
+    - {updated_squad_1}: +2 agents, +1 task
+```
+
+---
+
+## Hook Configuration
+
+### Add to .claude/hooks/
+
+Create `.claude/hooks/post-squad-create.py`:
+
+```python
+#!/usr/bin/env python3
+"""
+Hook: Refresh registry after squad creation
+Trigger: After successful *create-squad execution
+"""
+
+import os
+import sys
+
+def should_run(event):
+    """Check if this hook should run"""
+    # Run after create-squad task completes
+    return (
+        event.get('task') == 'create-squad' and
+        event.get('status') == 'success'
+    )
+
+def main():
+    # Signal to Claude Code to run refresh-registry
+    print("HOOK: Squad created, triggering registry refresh")
+    print("ACTION: run-task refresh-registry")
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())
+```
+
+### Add to squad-chief.md
+
+```yaml
+post_command_hooks:
+  "*create-squad":
+    on_success:
+      - task: "refresh-registry"
+        silent: true  # Don't show output unless error
+```
+
+---
+
+## Usage Examples
+
+### Manual Refresh
+```bash
+@squad-chief
+*refresh-registry
+```
+
+### Refresh with Gap Analysis
+```bash
+*refresh-registry --update-gaps
+```
+
+### Check Registry Status
+```bash
+*show-registry
+# Shows current registry contents
+
+*registry-status
+# Shows: last updated, total squads, any issues
+```
+
+---
+
+## Validation
+
+After refresh, verify:
+
+```yaml
+validation:
+  - All squads in squads/ are in registry
+  - All registry entries have valid paths
+  - domain_index has no orphan entries
+  - YAML is valid and parseable
+  - No duplicate keywords pointing to wrong squads
+```
+
+---
+
+_Task Version: 1.0.0_
+_Created: 2026-02-01_
+_Trigger: Manual, post-create-squad, or pre-commit hook_

package/pro/squads/squad-creator-pro/tasks/smoke-test-model-routing.md

@@ -0,0 +1,167 @@
+# Task: smoke-test-model-routing
+
+**Command:** `*smoke-test-model-routing`
+**Version:** 2.0.0
+**Execution Type:** Hybrid (Worker scripts + Agent validation)
+**Worker Scripts:** `scripts/model-tier-validator.cjs`, `scripts/model-usage-logger.cjs`
+**Model:** `Haiku` (QUALIFIED — validation task, scripts do heavy lifting)
+**Haiku Eligible:** YES — scripts handle validation, LLM only reports
+
+## Purpose
+
+Validate that the model routing system is functional by:
+1. Running 3 haiku-tier tasks with explicit model parameter
+2. Comparing behavior with/without model parameter
+3. Logging results to metrics
+
+## Veto Conditions
+
+- [ ] VETO if model-routing.yaml doesn't exist
+- [ ] VETO if outputs/metrics/ directory not writable
+- [ ] VETO if Task tool doesn't support model parameter
+- [ ] **VETO if preflight script not executed first (GAP ZERO)**
+
+---
+
+## ⛔ MANDATORY PREFLIGHT: Run Validator Script FIRST
+
+```
+EXECUTE FIRST — before ANY manual validation:
+
+  node squads/squad-creator-pro/scripts/model-tier-validator.cjs report > /tmp/preflight-model-routing.txt
+
+IF the command fails → FIX the script error. Do NOT proceed manually.
+IF the command succeeds → READ /tmp/preflight-model-routing.txt. Use ONLY these results.
+
+VETO: If /tmp/preflight-model-routing.txt does not exist → BLOCK.
+      Do NOT manually check model routing. Do NOT grep config files yourself.
+      The script validates tier assignments faster and 100% consistently.
+```
+
+---
+
+## Workflow
+
+### Phase 1: Pre-flight Check (via script)
+
+```bash
+# Run comprehensive preflight via validator script
+node squads/squad-creator-pro/scripts/model-tier-validator.cjs list
+
+# Verify metrics dir exists
+ls -la outputs/metrics/
+
+# Verify logger script exists
+ls -la squads/squad-creator-pro/scripts/model-usage-logger.cjs
+```
+
+**Gate:** All files exist → Continue. Any missing → STOP and create.
+
+### Phase 2: Validate Task Lookup (3 samples)
+
+For each test task, verify expected tier:
+
+```bash
+node squads/squad-creator-pro/scripts/model-usage-logger.cjs validate qa-after-creation.md
+node squads/squad-creator-pro/scripts/model-usage-logger.cjs validate validate-squad.md
+node squads/squad-creator-pro/scripts/model-usage-logger.cjs validate extract-voice-dna.md
+```
+
+**Expected results:**
+| Task | Expected Tier |
+|------|---------------|
+| qa-after-creation.md | haiku |
+| validate-squad.md | haiku |
+| extract-voice-dna.md | opus |
+
+**Gate:** All lookups return correct tier → Continue.
+
+### Phase 3: Execution Test (Haiku Task)
+
+Spawn a simple haiku-tier task with explicit model parameter:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  model: "haiku",
+  description: "Test haiku routing",
+  prompt: "Read squads/squad-creator-pro/config/model-routing.yaml and count how many tasks are marked as haiku tier. Return ONLY the number."
+)
+```
+
+**Expected:** Task completes successfully using Haiku model.
+
+**Log result:**
+```bash
+node squads/squad-creator-pro/scripts/model-usage-logger.cjs log smoke-test-haiku.md haiku 500 100 2000
+```
+
+### Phase 4: Comparison Test (Without model param)
+
+Spawn same task WITHOUT model parameter:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Test default routing",
+  prompt: "Read squads/squad-creator-pro/config/model-routing.yaml and count how many tasks are marked as sonnet tier. Return ONLY the number."
+)
+```
+
+**Observe:** What model does it use? (Should default to parent/opus)
+
+### Phase 5: Generate Report
+
+```bash
+node squads/squad-creator-pro/scripts/model-usage-logger.cjs report
+```
+
+## Completion Criteria
+
+- [ ] Phase 1: All pre-flight checks pass
+- [ ] Phase 2: All 3 task lookups return correct tier
+- [ ] Phase 3: Haiku task completes successfully
+- [ ] Phase 4: Comparison shows difference (or confirms behavior)
+- [ ] Phase 5: Report generated with at least 1 logged entry
+
+## Output Example
+
+```
+============================================================
+SMOKE TEST RESULTS - Model Routing
+============================================================
+
+Pre-flight: ✅ PASS (all files exist)
+
+Task Lookup Validation:
+  qa-after-creation.md → haiku ✅
+  validate-squad.md → haiku ✅
+  extract-voice-dna.md → opus ✅
+
+Execution Test:
+  Haiku task (with model param): ✅ Completed in 2.3s
+  Default task (no model param): ⚠️ Used opus (expected behavior)
+
+Conclusion:
+  - Model parameter IS respected by Task tool
+  - Without explicit model param, defaults to opus
+  - ENFORCEMENT GAP: Nothing prevents forgetting model param
+
+Recommendation:
+  Model routing WORKS when used correctly.
+  Need hook to ENFORCE usage (prevent forgetting).
+
+============================================================
+```
+
+## Next Steps After Smoke Test
+
+If smoke test PASSES:
+1. Model routing capability is validated
+2. Priority: Create enforcement hook
+3. Start logging real task executions
+
+If smoke test FAILS:
+1. Identify failure point
+2. Fix before proceeding
+3. Re-run smoke test