@hustle-together/api-dev-tools 3.12.3 → 3.12.16

package/hooks/orchestrator-handoff.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""
+Orchestrator handoff hook.
+
+When a Skill is invoked, this hook checks if we're in an orchestrated build
+and injects shared_decisions into the sub-workflow's state.
+
+Hook Type: PreToolUse (matcher: Skill)
+"""
+
+import json
+import os
+from pathlib import Path
+from datetime import datetime
+
+
+def load_build_state():
+    """Load hustle-build orchestration state"""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    state_file = Path(project_dir) / ".claude" / "hustle-build-state.json"
+
+    if state_file.exists():
+        try:
+            return json.loads(state_file.read_text())
+        except Exception:
+            pass
+    return None
+
+
+def load_api_state():
+    """Load api-dev state"""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    state_file = Path(project_dir) / ".claude" / "api-dev-state.json"
+
+    if state_file.exists():
+        try:
+            return json.loads(state_file.read_text())
+        except Exception:
+            pass
+    return {}
+
+
+def save_api_state(state):
+    """Save api-dev state with shared decisions"""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    state_file = Path(project_dir) / ".claude" / "api-dev-state.json"
+
+    try:
+        state_file.write_text(json.dumps(state, indent=2))
+        return True
+    except Exception:
+        return False
+
+
+def get_skill_name(tool_input):
+    """Extract skill name from tool input"""
+    try:
+        data = json.loads(tool_input)
+        return data.get("skill", "")
+    except Exception:
+        return ""
+
+
+def main():
+    tool_input = os.environ.get("CLAUDE_TOOL_INPUT", "{}")
+
+    # Get skill being invoked
+    skill_name = get_skill_name(tool_input)
+
+    # Check if this is a workflow skill
+    workflow_skills = [
+        "api-create", "hustle-ui-create", "hustle-ui-create-page",
+        "hustle-combine", "red", "green", "refactor", "cycle"
+    ]
+
+    if skill_name not in workflow_skills:
+        print(json.dumps({"continue": True}))
+        return
+
+    # Check if we're in an orchestrated build
+    build_state = load_build_state()
+
+    if not build_state or build_state.get("status") != "in_progress":
+        print(json.dumps({"continue": True}))
+        return
+
+    # Get shared decisions
+    shared_decisions = build_state.get("shared_decisions", {})
+    mode = build_state.get("mode", "interactive")
+
+    if not shared_decisions and mode != "auto":
+        print(json.dumps({"continue": True}))
+        return
+
+    # Load current api-dev state
+    api_state = load_api_state()
+
+    # Inject shared decisions
+    api_state["orchestrated"] = True
+    api_state["build_id"] = build_state.get("build_id")
+    api_state["mode"] = mode
+
+    # Pre-fill interview decisions from shared decisions
+    if "phases" not in api_state:
+        api_state["phases"] = {}
+
+    if "interview" not in api_state["phases"]:
+        api_state["phases"]["interview"] = {"status": "not_started", "decisions": {}}
+
+    # Map shared decisions to interview decisions
+    decision_mappings = {
+        "auth_required": "authentication",
+        "error_handling": "error_strategy",
+        "brand_guide": "use_brand_guide",
+        "testing_level": "testing_thoroughness",
+        "caching_strategy": "caching"
+    }
+
+    for shared_key, interview_key in decision_mappings.items():
+        if shared_key in shared_decisions:
+            api_state["phases"]["interview"]["decisions"][interview_key] = shared_decisions[shared_key]
+
+    # Mark which decisions are from orchestrator (so sub-workflow knows not to re-ask)
+    api_state["shared_decisions_applied"] = list(shared_decisions.keys())
+
+    # Save updated state
+    save_api_state(api_state)
+
+    # Update build state with current active workflow
+    decomposition = build_state.get("decomposition", {})
+
+    # Find the workflow being started
+    for wf_type in ["apis", "components", "combined_apis", "pages"]:
+        workflows = decomposition.get(wf_type, [])
+        for wf in workflows:
+            if wf.get("status") == "pending":
+                # This might be the one being started
+                # We'll rely on the skill to update status
+                break
+
+    # Log the handoff
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    logs_dir = Path(project_dir) / ".claude" / "workflow-logs"
+    logs_dir.mkdir(parents=True, exist_ok=True)
+
+    log_file = logs_dir / f"{build_state.get('build_id', 'unknown')}.json"
+
+    try:
+        if log_file.exists():
+            log = json.loads(log_file.read_text())
+        else:
+            log = {"handoffs": []}
+
+        log["handoffs"].append({
+            "timestamp": datetime.now().isoformat(),
+            "skill": skill_name,
+            "shared_decisions_applied": list(shared_decisions.keys()),
+            "mode": mode
+        })
+
+        log_file.write_text(json.dumps(log, indent=2))
+    except Exception:
+        pass
+
+    # Inject context about orchestration
+    context = f"""
+## Orchestrated Workflow
+
+This workflow is part of a larger build: **{build_state.get('build_id')}**
+
+### Pre-Filled Decisions (from orchestrator):
+{json.dumps(shared_decisions, indent=2)}
+
+These decisions are already applied. **Do not re-ask** questions about:
+{', '.join(shared_decisions.keys())}
+
+Only ask workflow-specific questions not covered above.
+"""
+
+    result = {
+        "continue": True,
+        "additionalContext": context
+    }
+
+    print(json.dumps(result))
+
+
+if __name__ == "__main__":
+    main()

package/hooks/orchestrator-session-startup.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+Orchestrator session startup hook.
+
+Injects hustle-build orchestration state into context at session start.
+This ensures Claude has awareness of multi-workflow builds in progress.
+
+Hook Type: SessionStart
+"""
+
+import json
+import os
+from pathlib import Path
+from datetime import datetime
+
+
+def load_build_state():
+    """Load hustle-build orchestration state if exists"""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    state_file = Path(project_dir) / ".claude" / "hustle-build-state.json"
+
+    if state_file.exists():
+        try:
+            return json.loads(state_file.read_text())
+        except Exception:
+            pass
+    return None
+
+
+def format_workflow_status(workflows):
+    """Format workflow list for context injection"""
+    if not workflows:
+        return "No sub-workflows defined yet."
+
+    lines = []
+    for wf in workflows:
+        status_emoji = {
+            "complete": "✅",
+            "in_progress": "🔄",
+            "pending": "⏳",
+            "failed": "❌"
+        }.get(wf.get("status", "pending"), "⏳")
+
+        wf_type = wf.get("type", "unknown")
+        name = wf.get("name", "unnamed")
+        deps = wf.get("depends_on", [])
+
+        line = f"  {status_emoji} [{wf_type}] {name}"
+        if deps:
+            line += f" (depends on: {', '.join(deps)})"
+        lines.append(line)
+
+    return "\n".join(lines)
+
+
+def format_shared_decisions(decisions):
+    """Format shared decisions for context injection"""
+    if not decisions:
+        return "No shared decisions configured."
+
+    lines = []
+    for key, value in decisions.items():
+        lines.append(f"  - {key}: {value}")
+
+    return "\n".join(lines)
+
+
+def main():
+    state = load_build_state()
+
+    if not state:
+        # No active build, continue normally
+        print(json.dumps({"continue": True}))
+        return
+
+    # Check if build is in progress
+    status = state.get("status", "unknown")
+
+    if status not in ["in_progress", "paused"]:
+        print(json.dumps({"continue": True}))
+        return
+
+    # Build context for injection
+    build_id = state.get("build_id", "unknown")
+    mode = state.get("mode", "interactive")
+    request = state.get("request", {}).get("original", "Unknown request")
+
+    # Get workflow statuses
+    decomposition = state.get("decomposition", {})
+    all_workflows = []
+
+    for wf_type in ["apis", "components", "combined_apis", "pages"]:
+        workflows = decomposition.get(wf_type, [])
+        for wf in workflows:
+            wf["type"] = wf_type.rstrip("s")
+            all_workflows.append(wf)
+
+    # Count progress
+    completed = len([w for w in all_workflows if w.get("status") == "complete"])
+    total = len(all_workflows)
+    in_progress = [w for w in all_workflows if w.get("status") == "in_progress"]
+
+    # Get active sub-workflow
+    active = state.get("active_sub_workflow", {})
+    active_name = active.get("name", "None")
+    active_type = active.get("type", "unknown")
+
+    # Format shared decisions
+    shared_decisions = state.get("shared_decisions", {})
+
+    context = f"""
+## Hustle Build In Progress
+
+**Build ID:** {build_id}
+**Mode:** {mode}
+**Original Request:** "{request}"
+
+### Progress: {completed}/{total} workflows complete
+
+**Currently Active:** [{active_type}] {active_name}
+
+### Sub-Workflows:
+{format_workflow_status(all_workflows)}
+
+### Shared Decisions (applied to all):
+{format_shared_decisions(shared_decisions)}
+
+---
+
+**Commands:**
+- Continue current workflow
+- `/hustle-build-review {build_id}` - View build log
+- Set `mode: "paused"` in state to pause
+
+"""
+
+    result = {
+        "continue": True,
+        "additionalContext": context
+    }
+
+    print(json.dumps(result))
+
+
+if __name__ == "__main__":
+    main()

package/hooks/periodic-reground.py

@@ -3,14 +3,22 @@
 Hook: PostToolUse (for periodic re-grounding)
 Purpose: Inject context reminders every N turns to prevent context dilution
 
-This hook tracks turn count and periodically injects a summary of:
+This hook tracks turn count and periodically injects a comprehensive summary of:
   - Current endpoint and phase
   - Key decisions from interview
+  - Existing registry elements (APIs, components, pages)
+  - Deferred features (don't re-suggest)
+  - Last test status
+  - Brand guide status
   - Research cache status
-  - Important file locations
+  - Orchestrator context (if in /hustle-build)
 
 The goal is to keep Claude grounded during long sessions where
-the original CLAUDE.md context may get diluted.
+the original CLAUDE.md context may get diluted ("lost in the middle").
+
+Based on best practices from:
+  - Manus: "Manipulate Attention Through Recitation"
+  - Sankalp: "Context as limited attention budget"
 
 Configuration:
   - REGROUND_INTERVAL: Number of turns between re-grounding (default: 7)
@@ -27,8 +35,221 @@ from pathlib import Path
 # Configuration
 REGROUND_INTERVAL = 7  # Re-ground every N turns
 
-# State file is in .claude/ directory (sibling to hooks/)
-STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+# State files (in .claude/ directory)
+PROJECT_DIR = Path(os.environ.get("CLAUDE_PROJECT_DIR", "."))
+STATE_FILE = PROJECT_DIR / ".claude" / "api-dev-state.json"
+REGISTRY_FILE = PROJECT_DIR / ".claude" / "registry.json"
+BUILD_STATE_FILE = PROJECT_DIR / ".claude" / "hustle-build-state.json"
+BRAND_GUIDE_FILE = PROJECT_DIR / ".claude" / "BRAND_GUIDE.md"
+
+
+def load_json_file(filepath):
+    """Safely load a JSON file"""
+    if filepath.exists():
+        try:
+            return json.loads(filepath.read_text())
+        except (json.JSONDecodeError, Exception):
+            pass
+    return None
+
+
+def format_list(items, max_items=5, max_chars=80):
+    """Format a list of items with truncation"""
+    if not items:
+        return "None"
+    truncated = list(items)[:max_items]
+    result = ", ".join(str(item)[:20] for item in truncated)
+    if len(items) > max_items:
+        result += f" (+{len(items) - max_items} more)"
+    return result[:max_chars]
+
+
+def get_registry_summary(registry):
+    """Get summary of existing registry elements"""
+    if not registry:
+        return None
+
+    summary = {}
+    for category in ["apis", "components", "pages", "combined"]:
+        items = registry.get(category, {})
+        if items:
+            summary[category] = list(items.keys())
+    return summary if summary else None
+
+
+def get_test_status(state):
+    """Get last test run status"""
+    test_run = state.get("last_test_run", {})
+    if not test_run:
+        return None
+
+    passed = test_run.get("passed", 0)
+    failed = test_run.get("failed", 0)
+    timestamp = test_run.get("timestamp", "")
+
+    if passed or failed:
+        return {
+            "passed": passed,
+            "failed": failed,
+            "total": passed + failed,
+            "status": "GREEN" if failed == 0 else "RED",
+            "timestamp": timestamp
+        }
+    return None
+
+
+def get_brand_guide_status():
+    """Check if brand guide exists and get key info"""
+    if not BRAND_GUIDE_FILE.exists():
+        return None
+
+    try:
+        content = BRAND_GUIDE_FILE.read_text()
+        # Extract key colors if present
+        colors = []
+        for line in content.split("\n"):
+            if "primary" in line.lower() and "#" in line:
+                colors.append("primary found")
+                break
+        return {"exists": True, "has_colors": len(colors) > 0}
+    except Exception:
+        return {"exists": True}
+
+
+def get_orchestrator_status(build_state):
+    """Get orchestrator build status if active"""
+    if not build_state:
+        return None
+
+    status = build_state.get("status")
+    if status not in ["in_progress", "paused"]:
+        return None
+
+    build_id = build_state.get("build_id", "unknown")
+    decomposition = build_state.get("decomposition", {})
+
+    total = 0
+    completed = 0
+    for wf_type in ["apis", "components", "combined_apis", "pages"]:
+        workflows = decomposition.get(wf_type, [])
+        total += len(workflows)
+        completed += len([w for w in workflows if w.get("status") == "complete"])
+
+    active = build_state.get("active_sub_workflow", {})
+
+    return {
+        "build_id": build_id,
+        "progress": f"{completed}/{total}",
+        "active_type": active.get("type", "none"),
+        "active_name": active.get("name", "none")
+    }
+
+
+def build_reground_context(state, turn_count):
+    """Build comprehensive re-grounding context"""
+    parts = []
+    parts.append(f"## Re-Grounding Reminder (Turn {turn_count})")
+    parts.append("")
+
+    # === Current Workflow ===
+    endpoint = state.get("endpoint", "unknown")
+    parts.append(f"**Active Endpoint:** `{endpoint}`")
+
+    # Get current phase
+    phases = state.get("phases", {})
+    phase_order = [
+        "disambiguation", "scope", "research_initial", "interview",
+        "research_deep", "schema_creation", "environment_check",
+        "tdd_red", "tdd_green", "verify", "code_review", "tdd_refactor",
+        "documentation", "completion"
+    ]
+
+    current_phase = None
+    completed_phases = []
+    for phase_name in phase_order:
+        phase = phases.get(phase_name, {})
+        status = phase.get("status", "not_started")
+        if status == "complete":
+            completed_phases.append(phase_name)
+        elif status == "in_progress" and not current_phase:
+            current_phase = phase_name
+
+    if not current_phase:
+        for phase_name in phase_order:
+            phase = phases.get(phase_name, {})
+            if phase.get("status", "not_started") == "not_started":
+                current_phase = phase_name
+                break
+
+    parts.append(f"**Current Phase:** {current_phase or 'completion'}")
+    parts.append(f"**Completed:** {len(completed_phases)}/{len(phase_order)} phases")
+
+    # === Key Decisions ===
+    interview = phases.get("interview", {})
+    decisions = interview.get("decisions", {})
+    if decisions:
+        parts.append("")
+        parts.append("**Key Decisions:**")
+        for key, value in list(decisions.items())[:5]:
+            response = value.get("value", value.get("response", "N/A"))
+            if response:
+                parts.append(f"  - {key}: {str(response)[:40]}")
+
+    # === Registry Summary ===
+    registry = load_json_file(REGISTRY_FILE)
+    registry_summary = get_registry_summary(registry)
+    if registry_summary:
+        parts.append("")
+        parts.append("**Existing Elements (don't recreate):**")
+        if registry_summary.get("apis"):
+            parts.append(f"  - APIs: {format_list(registry_summary['apis'])}")
+        if registry_summary.get("components"):
+            parts.append(f"  - Components: {format_list(registry_summary['components'])}")
+        if registry_summary.get("pages"):
+            parts.append(f"  - Pages: {format_list(registry_summary['pages'])}")
+
+    # === Deferred Features ===
+    deferred = state.get("deferred_features", [])
+    if deferred:
+        parts.append("")
+        parts.append(f"**Deferred (don't re-suggest):** {format_list(deferred, max_items=3)}")
+
+    # === Test Status ===
+    test_status = get_test_status(state)
+    if test_status:
+        parts.append("")
+        status_emoji = "GREEN" if test_status["status"] == "GREEN" else "RED"
+        parts.append(f"**Last Tests:** {status_emoji} ({test_status['passed']} passed, {test_status['failed']} failed)")
+
+    # === Brand Guide ===
+    brand_status = get_brand_guide_status()
+    if brand_status and brand_status.get("exists"):
+        parts.append("")
+        parts.append("**Brand Guide:** Active - use `.claude/BRAND_GUIDE.md` for styling")
+
+    # === Research Freshness ===
+    research_index = state.get("research_index", {})
+    if endpoint in research_index:
+        entry = research_index[endpoint]
+        days_old = entry.get("days_old", 0)
+        if days_old > 7:
+            parts.append("")
+            parts.append(f"**WARNING:** Research is {days_old} days old. Consider `/api-research`.")
+
+    # === Orchestrator Context ===
+    build_state = load_json_file(BUILD_STATE_FILE)
+    orchestrator = get_orchestrator_status(build_state)
+    if orchestrator:
+        parts.append("")
+        parts.append(f"**Orchestrated Build:** {orchestrator['build_id']}")
+        parts.append(f"  - Progress: {orchestrator['progress']} workflows")
+        parts.append(f"  - Active: [{orchestrator['active_type']}] {orchestrator['active_name']}")
+
+    # === Quick Reminders ===
+    parts.append("")
+    parts.append("**Remember:** Research-first | Questions FROM findings | Verify after green")
+
+    return "\n".join(parts)
 
 
 def main():
@@ -59,73 +280,15 @@ def main():
     should_reground = turn_count % REGROUND_INTERVAL == 0
 
     if should_reground and state.get("endpoint"):
-        # Build re-grounding context
-        context_parts = []
-        context_parts.append(f"## Re-Grounding Reminder (Turn {turn_count})")
-        context_parts.append("")
-
-        endpoint = state.get("endpoint", "unknown")
-        context_parts.append(f"**Active Endpoint:** {endpoint}")
-
-        # Get current phase
-        phases = state.get("phases", {})
-        phase_order = [
-            "disambiguation", "scope", "research_initial", "interview",
-            "research_deep", "schema_creation", "environment_check",
-            "tdd_red", "tdd_green", "verify", "tdd_refactor", "documentation"
-        ]
-
-        current_phase = None
-        completed_phases = []
-        for phase_name in phase_order:
-            phase = phases.get(phase_name, {})
-            status = phase.get("status", "not_started")
-            if status == "complete":
-                completed_phases.append(phase_name)
-            elif status == "in_progress" and not current_phase:
-                current_phase = phase_name
-
-        if not current_phase:
-            # Find first not_started phase
-            for phase_name in phase_order:
-                phase = phases.get(phase_name, {})
-                if phase.get("status", "not_started") == "not_started":
-                    current_phase = phase_name
-                    break
-
-        context_parts.append(f"**Current Phase:** {current_phase or 'documentation'}")
-        context_parts.append(f"**Completed:** {', '.join(completed_phases) if completed_phases else 'None'}")
-
-        # Key decisions summary
-        interview = phases.get("interview", {})
-        decisions = interview.get("decisions", {})
-        if decisions:
-            context_parts.append("")
-            context_parts.append("**Key Decisions:**")
-            for key, value in list(decisions.items())[:5]:  # Limit to 5 key decisions
-                response = value.get("value", value.get("response", "N/A"))
-                if response:
-                    context_parts.append(f"  - {key}: {str(response)[:50]}")
-
-        # Research freshness warning
-        research_index = state.get("research_index", {})
-        if endpoint in research_index:
-            entry = research_index[endpoint]
-            days_old = entry.get("days_old", 0)
-            if days_old > 7:
-                context_parts.append("")
-                context_parts.append(f"**WARNING:** Research is {days_old} days old. Consider re-researching.")
-
-        # File reminders
-        context_parts.append("")
-        context_parts.append("**Key Files:** .claude/api-dev-state.json, .claude/research/")
+        # Build comprehensive re-grounding context
+        context = build_reground_context(state, turn_count)
 
         # Add to reground history
         reground_history = state.setdefault("reground_history", [])
         reground_history.append({
             "turn": turn_count,
             "timestamp": datetime.now().isoformat(),
-            "phase": current_phase
+            "phase": state.get("phases", {}).get("current_phase", "unknown")
         })
         # Keep only last 10 reground events
         state["reground_history"] = reground_history[-10:]
@@ -138,7 +301,7 @@ def main():
             "continue": True,
             "hookSpecificOutput": {
                 "hookEventName": "PostToolUse",
-                "additionalContext": "\n".join(context_parts)
+                "additionalContext": context
             }
         }
         print(json.dumps(output))