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

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,261 @@ 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 = {}
+    # Core elements
+    for category in ["apis", "components", "pages", "combined"]:
+        items = registry.get(category, {})
+        if items:
+            summary[category] = list(items.keys())
+
+    # Infrastructure tracking (v1.3.0+)
+    routes = registry.get("routes", {})
+    if routes and not routes.get("_description"):
+        # Has actual routes, not just template
+        actual_routes = [k for k in routes.keys() if not k.startswith("_")]
+        if actual_routes:
+            summary["routes"] = actual_routes
+
+    env_vars = registry.get("env_vars", {})
+    if env_vars:
+        actual_vars = [k for k in env_vars.keys() if not k.startswith("_")]
+        if actual_vars:
+            summary["env_vars"] = actual_vars
+
+    services = registry.get("services", {})
+    if services:
+        actual_services = [k for k in services.keys() if not k.startswith("_")]
+        if actual_services:
+            summary["services"] = actual_services
+
+    webhooks = registry.get("webhooks", {})
+    if webhooks:
+        actual_webhooks = [k for k in webhooks.keys() if not k.startswith("_")]
+        if actual_webhooks:
+            summary["webhooks"] = actual_webhooks
+
+    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'])}")
+        if registry_summary.get("routes"):
+            parts.append(f"  - Routes: {format_list(registry_summary['routes'])}")
+
+    # === Infrastructure Awareness ===
+    if registry_summary:
+        if registry_summary.get("services"):
+            parts.append("")
+            parts.append(f"**External Services:** {format_list(registry_summary['services'])}")
+        if registry_summary.get("webhooks"):
+            parts.append(f"**Webhooks:** {format_list(registry_summary['webhooks'])}")
+        if registry_summary.get("env_vars"):
+            parts.append(f"**Env Vars Tracked:** {len(registry_summary['env_vars'])} variables")
+
+    # === 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 +320,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 +341,7 @@ def main():
             "continue": True,
             "hookSpecificOutput": {
                 "hookEventName": "PostToolUse",
-                "additionalContext": "\n".join(context_parts)
+                "additionalContext": context
             }
         }
         print(json.dumps(output))

package/hooks/project-document-prompt.py

@@ -0,0 +1,302 @@
+#!/usr/bin/env python3
+"""
+Project Document Prompt Hook
+
+Prompts users for a project document (PRD, spec, deep research output) at the
+start of /hustle-build. Stores the document in state for AI-powered decomposition.
+
+Hook Type: PreToolUse (matcher: Skill)
+Trigger: When /hustle-build is invoked
+Version: 4.6.0
+
+Flags:
+  --skip-document      Skip the project document prompt
+  --from-document PATH Use specified file as project document
+  --no-document        Alias for --skip-document
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+from datetime import datetime
+
+try:
+    from hook_utils import load_state, save_state, get_project_dir, log_workflow_event
+    UTILS_AVAILABLE = True
+except ImportError:
+    UTILS_AVAILABLE = False
+
+
+def get_project_dir_fallback():
+    """Get project directory from environment or current directory."""
+    return Path(os.environ.get("CLAUDE_PROJECT_DIR", "."))
+
+
+def load_hustle_build_state():
+    """Load hustle-build orchestration state."""
+    project_dir = get_project_dir_fallback()
+    state_file = 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 save_hustle_build_state(state):
+    """Save hustle-build orchestration state."""
+    project_dir = get_project_dir_fallback()
+    state_file = project_dir / ".claude" / "hustle-build-state.json"
+    state_file.parent.mkdir(parents=True, exist_ok=True)
+    state_file.write_text(json.dumps(state, indent=2))
+
+
+def parse_flags(args):
+    """Parse command-line style flags from arguments string."""
+    flags = {
+        "skip_document": False,
+        "from_document": None,
+    }
+
+    if not args:
+        return flags
+
+    # Check for skip flags
+    if "--skip-document" in args or "--no-document" in args:
+        flags["skip_document"] = True
+
+    # Check for --from-document PATH
+    if "--from-document" in args:
+        # Extract path after --from-document
+        parts = args.split("--from-document")
+        if len(parts) > 1:
+            path_part = parts[1].strip().split()[0] if parts[1].strip() else None
+            if path_part and not path_part.startswith("--"):
+                flags["from_document"] = path_part
+
+    return flags
+
+
+def read_document_file(file_path):
+    """Read a document file and detect its format."""
+    path = Path(file_path)
+
+    if not path.exists():
+        # Try relative to project dir
+        project_dir = get_project_dir_fallback()
+        path = project_dir / file_path
+
+    if not path.exists():
+        return None, None, f"File not found: {file_path}"
+
+    try:
+        content = path.read_text()
+
+        # Detect format
+        suffix = path.suffix.lower()
+        if suffix in [".md", ".markdown"]:
+            fmt = "markdown"
+        elif suffix == ".json":
+            fmt = "json"
+        elif suffix in [".txt", ".text"]:
+            fmt = "text"
+        else:
+            # Guess based on content
+            if content.strip().startswith("{") or content.strip().startswith("["):
+                fmt = "json"
+            elif content.startswith("#") or "##" in content[:500]:
+                fmt = "markdown"
+            else:
+                fmt = "text"
+
+        return content, fmt, None
+    except Exception as e:
+        return None, None, f"Error reading file: {e}"
+
+
+def main():
+    # Read tool input from stdin or environment
+    tool_input_raw = os.environ.get("CLAUDE_TOOL_INPUT", "")
+
+    # Also check stdin for hook input
+    try:
+        if not sys.stdin.isatty():
+            stdin_data = sys.stdin.read()
+            if stdin_data:
+                try:
+                    hook_input = json.loads(stdin_data)
+                    tool_input_raw = json.dumps(hook_input.get("tool_input", {}))
+                except json.JSONDecodeError:
+                    pass
+    except Exception:
+        pass
+
+    try:
+        data = json.loads(tool_input_raw) if tool_input_raw else {}
+        skill_name = data.get("skill", "")
+        args = data.get("args", "")
+    except Exception:
+        # Not a skill invocation or invalid JSON
+        print(json.dumps({"continue": True}))
+        return
+
+    # Only trigger for hustle-build skill
+    if skill_name != "hustle-build":
+        print(json.dumps({"continue": True}))
+        return
+
+    # Parse flags from arguments
+    flags = parse_flags(args)
+
+    # Check for skip flag
+    if flags["skip_document"]:
+        print(json.dumps({"continue": True}))
+        return
+
+    # Check if project_spec already exists with content
+    state = load_hustle_build_state()
+    if state and state.get("project_spec", {}).get("raw_content"):
+        print(json.dumps({"continue": True}))
+        return
+
+    # Handle --from-document flag
+    if flags["from_document"]:
+        content, fmt, error = read_document_file(flags["from_document"])
+
+        if error:
+            # Inject error message
+            result = {
+                "continue": True,
+                "additionalContext": f"""
+## Project Document Error
+
+Could not load document: {error}
+
+Please provide the document path again or use `--skip-document` to proceed without a document.
+"""
+            }
+            print(json.dumps(result))
+            return
+
+        # Initialize or update state with document
+        if not state:
+            state = {
+                "version": "4.6.0",
+                "build_id": f"build-{datetime.now().strftime('%Y%m%d-%H%M%S')}",
+                "status": "initializing"
+            }
+
+        state["project_spec"] = {
+            "source": "file",
+            "file_path": flags["from_document"],
+            "raw_content": content,
+            "format": fmt,
+            "loaded_at": datetime.now().isoformat(),
+            "word_count": len(content.split()),
+            "extracted": None,  # Will be filled by Phase 0.5
+            "user_modifications": {
+                "added": [],
+                "removed": [],
+                "modified": []
+            }
+        }
+
+        save_hustle_build_state(state)
+
+        # Log the event
+        if UTILS_AVAILABLE:
+            log_workflow_event("project_document_loaded", {
+                "source": "file",
+                "file_path": flags["from_document"],
+                "format": fmt,
+                "word_count": len(content.split())
+            })
+
+        # Inject confirmation
+        result = {
+            "continue": True,
+            "additionalContext": f"""
+## Project Document Loaded
+
+Successfully loaded project document:
+- **Source:** `{flags["from_document"]}`
+- **Format:** {fmt}
+- **Size:** {len(content.split())} words
+
+The document will be analyzed in Phase 0.5 to extract:
+- Pages/routes
+- Components
+- APIs
+- Data models
+- External integrations
+
+Proceeding to parse your build request...
+"""
+        }
+        print(json.dumps(result))
+        return
+
+    # No document provided - inject prompt asking for one
+    context = """
+## Project Document Intake
+
+Before decomposing this build request, I need to check if you have a comprehensive project document.
+
+**Do you have a project document (PRD, spec, deep research output)?**
+
+A project document helps me:
+- Identify ALL pages, components, and APIs upfront
+- Build accurate dependency graphs
+- Reference the spec throughout each sub-workflow
+- Ensure nothing is missed
+
+### How to Provide a Document
+
+**Option 1: File Path**
+```
+I have a document at ./docs/my-prd.md
+```
+
+**Option 2: Paste Content**
+Just paste the document content directly in your next message.
+
+**Option 3: URL**
+```
+Fetch the document from https://example.com/my-spec.md
+```
+
+**Option 4: No Document**
+```
+No document, proceed with parsing my description
+```
+
+### Supported Formats
+- Markdown (`.md`) - PRDs, specs, research outputs
+- Plain text (`.txt`) - Notes, outlines
+- JSON (`.json`) - Structured specs, API definitions
+
+---
+
+_To skip this prompt in the future, use:_
+```
+/hustle-build --skip-document [description]
+```
+
+_Or provide a document directly:_
+```
+/hustle-build --from-document ./docs/spec.md [description]
+```
+"""
+
+    result = {
+        "continue": True,
+        "additionalContext": context
+    }
+
+    print(json.dumps(result))
+
+
+if __name__ == "__main__":
+    main()