claude-all-hands 1.0.0

package/.claude/hooks/scripts/enforce_planning.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""UserPromptSubmit hook - enforces planning workflow based on plan status."""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+def get_envoy_path() -> Path:
+    """Get path to envoy CLI."""
+    cwd = Path.cwd()
+    return cwd / ".claude" / "envoy" / "envoy"
+
+
+def get_current_branch() -> str:
+    """Get current git branch name."""
+    result = subprocess.run(
+        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        return result.stdout.strip()
+    return ""
+
+
+def is_direct_mode_branch() -> bool:
+    """Check if current branch is a direct-mode branch (no planning)."""
+    branch = get_current_branch()
+    direct_branches = {"main", "master", "develop", "staging", "production"}
+    if branch in direct_branches:
+        return True
+    if branch.startswith("quick/"):
+        return True
+    return False
+
+
+def get_plan_status() -> dict:
+    """Get current plan status via envoy."""
+    envoy = get_envoy_path()
+    if not envoy.exists():
+        return {"error": "envoy not found"}
+
+    result = subprocess.run(
+        [str(envoy), "plans", "frontmatter"],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        return {"error": result.stderr}
+
+    try:
+        data = json.loads(result.stdout)
+        return data.get("data", {})
+    except json.JSONDecodeError:
+        return {"error": "invalid json"}
+
+
+def is_worker_subprocess() -> bool:
+    """Check if running inside a parallel worker subprocess."""
+    import os
+    depth = os.environ.get("PARALLEL_WORKER_DEPTH", "0")
+    try:
+        return int(depth) > 0
+    except ValueError:
+        return False
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        return
+
+    # Worker subprocess - return hint about injected plan file
+    if is_worker_subprocess():
+        print("Worker subprocess: /plan disabled. Use injected plan at .claude/plans/<branch>/plan.md")
+        return
+
+    # Early return for direct mode branches (skip envoy call)
+    if is_direct_mode_branch():
+        return
+
+    # Get plan status
+    plan_data = get_plan_status()
+
+    # Direct mode from envoy (fallback check)
+    if plan_data.get("mode") == "direct":
+        return
+
+    # No plan exists yet
+    if not plan_data.get("exists"):
+        print("No plan file. Run /plan to create one.")
+        return
+
+    frontmatter = plan_data.get("frontmatter", {})
+    status = frontmatter.get("status", "draft")
+    plan_path = plan_data.get("path", "")
+
+    if status == "draft":
+        print("PLANNING REQUIRED: Plan status is draft.")
+        print(f"Plan file: {plan_path}")
+        print("Run /plan to begin planning workflow.")
+        print("To skip planning this session, decline when prompted.")
+
+    elif status == "active":
+        print(f"Plan status: active | Plan file: {plan_path}")
+        print("IMPORTANT: If this prompt is NOT related to the current plan, you MUST run /plan to challenge the user to follow workflow best practices.")
+
+    elif status == "deactivated":
+        # User opted out - no enforcement, silent pass
+        return
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks/scripts/enforce_research_fetch.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: intercept WebFetch → redirect to researcher agent."""
+import json
+import sys
+
+data = json.load(sys.stdin)
+url = data.get("tool_input", {}).get("url", "")
+
+if not url:
+    sys.exit(0)
+
+# JSON output with additionalContext for Claude self-correction
+print(json.dumps({
+    "continue": False,
+    "additionalContext": "WebFetch blocked.\n\nMain agent: delegate to researcher agent.\nSubagent: use `.claude/envoy/envoy tavily extract \"<url>\"` instead."
+}))
+sys.exit(0)

package/.claude/hooks/scripts/enforce_research_search.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block WebSearch for non-research agents."""
+import json
+import sys
+
+# JSON output with additionalContext for Claude self-correction
+print(json.dumps({
+    "continue": False,
+    "additionalContext": "WebSearch blocked.\n\nMain agent: delegate to researcher agent.\nSubagent: respond to main agent requesting researcher delegation."
+}))
+sys.exit(0)

package/.claude/hooks/scripts/enforce_rg.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block grep/find and suggest rg (only if rg available)."""
+import json
+import re
+import shutil
+import sys
+
+RULES = [
+    (r"\bgrep\b(?!.*\|)", "Ensure you use Bash with 'rg <pattern>' (ripgrep) instead of grep."),
+    (r"\bfind\s+\S+\s+-name\b", "Ensure you use Bash with 'rg --files -g \"<pattern>\" <path>' instead of find -name."),
+]
+
+data = json.load(sys.stdin)
+command = data.get("tool_input", {}).get("command", "")
+
+if not command:
+    sys.exit(0)
+
+# Check for grep/find patterns
+for pattern, message in RULES:
+    if re.search(pattern, command):
+        # Only enforce if rg is available
+        if shutil.which("rg"):
+            print(json.dumps({
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": message
+                }
+            }))
+            sys.exit(0)
+        break
+
+sys.exit(0)

package/.claude/hooks/scripts/github_url_to_gh.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block GitHub URLs in fetch commands - suggest gh CLI instead."""
+import json
+import sys
+
+GITHUB_DOMAINS = ("github.com", "raw.githubusercontent.com", "gist.github.com")
+
+def deny(reason):
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason
+        }
+    }))
+    sys.exit(0)
+
+data = json.load(sys.stdin)
+tool_name = data.get("tool_name", "")
+tool_input = data.get("tool_input", {})
+
+# Check WebFetch URLs
+if tool_name == "WebFetch":
+    url = tool_input.get("url", "")
+    for domain in GITHUB_DOMAINS:
+        if domain in url:
+            deny("GitHub URL detected. Use 'gh' CLI: gh api repos/OWNER/REPO/contents/PATH")
+    sys.exit(0)
+
+# Check Bash commands for curl, wget, envoy tavily extract
+if tool_name == "Bash":
+    command = tool_input.get("command", "")
+
+    # Check for fetch-like commands
+    is_fetch_cmd = any(cmd in command for cmd in ["curl", "wget", "tavily extract"])
+    if not is_fetch_cmd:
+        sys.exit(0)
+
+    # Check for GitHub URLs
+    for domain in GITHUB_DOMAINS:
+        if domain in command:
+            deny("GitHub URL detected. Use 'gh' CLI: gh api repos/OWNER/REPO/contents/PATH")
+
+sys.exit(0)

package/.claude/hooks/scripts/scan_skills.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""SessionStart hook: scan skills directories for missing/invalid SKILL.md files."""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+
+def parse_frontmatter(content):
+    """Parse YAML frontmatter from content."""
+    if not content.startswith("---"):
+        return None
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        return None
+    result = {}
+    for line in parts[1].strip().split("\n"):
+        if ":" in line:
+            key, _, value = line.partition(":")
+            result[key.strip()] = value.strip().strip('"').strip("'")
+    return result
+
+
+def validate_skill(skill_path):
+    """Validate a skill directory. Returns list of errors."""
+    errors = []
+    skill_md = skill_path / "SKILL.md"
+    name = skill_path.name
+
+    if not skill_md.exists():
+        errors.append(f"{name}: missing SKILL.md")
+        return errors
+
+    try:
+        content = skill_md.read_text()
+    except Exception as e:
+        errors.append(f"{name}: error reading SKILL.md - {e}")
+        return errors
+
+    fm = parse_frontmatter(content)
+    if fm is None:
+        errors.append(f"{name}: missing or invalid frontmatter")
+        return errors
+
+    # Validate name
+    if "name" not in fm:
+        errors.append(f"{name}: missing 'name' field")
+    else:
+        n = fm["name"]
+        if len(n) > 64:
+            errors.append(f"{name}: 'name' exceeds 64 chars ({len(n)})")
+        if not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", n):
+            errors.append(f"{name}: 'name' must be kebab-case")
+
+    # Validate description
+    if "description" not in fm:
+        errors.append(f"{name}: missing 'description' field")
+    elif len(fm["description"]) > 300:
+        errors.append(f"{name}: 'description' exceeds 300 chars")
+
+    return errors
+
+
+def main():
+    # Use CLAUDE_PROJECT_DIR env var to find .claude directory
+    import os
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", "")
+    if not project_dir:
+        return
+    skills_dir = Path(project_dir) / ".claude" / "skills"
+
+    if not skills_dir.exists():
+        return
+
+    all_errors = []
+    for skill_path in skills_dir.iterdir():
+        if skill_path.is_dir() and not skill_path.name.startswith("_"):
+            errors = validate_skill(skill_path)
+            all_errors.extend(errors)
+
+    if all_errors:
+        print("⚠️ Skill validation warnings:", file=sys.stderr)
+        for error in all_errors:
+            print(f"  • {error}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks/scripts/validate_skill.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""PostToolUse hook: validate SKILL.md files on edit."""
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def parse_frontmatter(content):
+    """Parse YAML frontmatter from content."""
+    if not content.startswith("---"):
+        return None
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        return None
+    result = {}
+    for line in parts[1].strip().split("\n"):
+        if ":" in line:
+            key, _, value = line.partition(":")
+            result[key.strip()] = value.strip().strip('"').strip("'")
+    return result
+
+
+def validate_skill_file(file_path):
+    """Validate a SKILL.md file. Returns list of errors."""
+    errors = []
+
+    if not file_path.exists():
+        return errors
+
+    try:
+        content = file_path.read_text()
+    except Exception as e:
+        errors.append(f"Error reading file: {e}")
+        return errors
+
+    fm = parse_frontmatter(content)
+    if fm is None:
+        errors.append("Missing or invalid YAML frontmatter")
+        return errors
+
+    # Validate name
+    if "name" not in fm:
+        errors.append("Missing 'name' field in frontmatter")
+    else:
+        n = fm["name"]
+        if len(n) > 64:
+            errors.append(f"'name' exceeds 64 chars ({len(n)})")
+        if not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", n):
+            errors.append(f"'name' must be kebab-case: '{n}'")
+
+    # Validate description
+    if "description" not in fm:
+        errors.append("Missing 'description' field in frontmatter")
+    elif len(fm["description"]) > 1024:
+        errors.append(f"'description' exceeds 1024 chars ({len(fm['description'])})")
+
+    return errors
+
+
+data = json.load(sys.stdin)
+file_path = data.get("tool_input", {}).get("file_path", "")
+
+if not file_path:
+    sys.exit(0)
+
+# Only validate skill files
+if "/skills/" not in file_path and not file_path.endswith("SKILL.md"):
+    sys.exit(0)
+
+# Only validate SKILL.md files specifically
+if not file_path.endswith("SKILL.md"):
+    sys.exit(0)
+
+errors = validate_skill_file(Path(file_path))
+
+if errors:
+    print("❌ SKILL.md Validation Failed:", file=sys.stderr)
+    for error in errors:
+        print(f"  • {error}", file=sys.stderr)
+    sys.exit(2)

package/.claude/hooks/startup.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+
+# Initialize claude-envoy (creates venv if needed)
+"$CLAUDE_PROJECT_DIR/.claude/envoy/envoy" info > /dev/null 2>&1
+
+# Check if running in worker subprocess
+if [ -n "$PARALLEL_WORKER_DEPTH" ] && [ "$PARALLEL_WORKER_DEPTH" -gt 0 ]; then
+    branch=$(git branch --show-current 2>/dev/null)
+    plan_id=$(echo "$branch" | sed 's/[^a-zA-Z0-9_-]/-/g')
+    plan_file=".claude/plans/$plan_id/plan.md"
+    echo "Worker subprocess mode"
+    echo "Plan file: $plan_file"
+    echo "/plan command disabled - use injected plan"
+    exit 0
+fi
+
+# Sync claude-code-docs (clone if missing, pull if behind)
+DOCS_DIR="$HOME/.claude-code-docs"
+if [ ! -d "$DOCS_DIR" ]; then
+    git clone --quiet https://github.com/ericbuess/claude-code-docs.git "$DOCS_DIR" 2>/dev/null &
+else
+    # Background sync - fetch and pull if behind
+    (cd "$DOCS_DIR" && git fetch --quiet origin main 2>/dev/null && \
+     [ "$(git rev-list HEAD..origin/main --count 2>/dev/null)" -gt 0 ] && \
+     git pull --quiet origin main 2>/dev/null) &
+fi
+
+# Check for active plan on current branch
+branch=$(git branch --show-current 2>/dev/null)
+if [ -n "$branch" ]; then
+    if [ "$branch" = "main" ] || [ "$branch" = "master" ] || [ "$branch" = "develop" ] || [ "$branch" = "staging" ] || [ "$branch" = "production" ] || [[ "$branch" == quick/* ]]; then
+        echo "Mode: Direct (no planning) - on $branch branch"
+    else
+        # Feature branch - ensure plan exists and get status
+        result=$("$CLAUDE_PROJECT_DIR/.claude/envoy/envoy" plans create 2>/dev/null)
+        status=$(echo "$result" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('data',{}).get('status',''))" 2>/dev/null)
+
+        plan_id=$(echo "$branch" | sed 's/[^a-zA-Z0-9_-]/-/g')
+        plan_file=".claude/plans/$plan_id/plan.md"
+
+        # Reset deactivated status on new session
+        if [ "$status" = "deactivated" ]; then
+            "$CLAUDE_PROJECT_DIR/.claude/envoy/envoy" plans set-status draft > /dev/null 2>&1
+            status="draft"
+        fi
+
+        if [ "$status" = "draft" ]; then
+            echo "Plan status: draft (planning required)"
+            echo "Plan file: $plan_file"
+        elif [ "$status" = "active" ]; then
+            echo "Plan status: active (implementing)"
+            echo "Plan file: $plan_file"
+        fi
+    fi
+fi
+
+echo "You are the Main Agent - Main Agent Rules apply to you"

package/.claude/plans/feat-npm-package-cli/plan.md

@@ -0,0 +1,85 @@
+---
+status: active
+branch: feat/npm-package-cli
+---
+
+# Plan: NPM Package Registry & Local Dev Mode
+
+## Specifications
+
+### What
+- Publish `claude-all-hands` to npm registry (callable via `npx claude-all-hands`)
+- GitHub Action auto-publishes on main branch push
+- Local dev via `tsx` when `ALLHANDS_PATH` set (skip rebuild requirement)
+
+### Acceptance Criteria
+1. `npx claude-all-hands <command>` works from any repo
+2. GitHub Action publishes to npm on main push (build + publish)
+3. When `ALLHANDS_PATH` set, uses `tsx src/cli.ts` instead of built `bin/cli.js`
+4. Hooks in repo use local tsx path when developing
+
+### Constraints
+- Node >= 18
+- Package already configured: `claude-all-hands` (unscoped)
+- npm auth via `NPM_TOKEN` secret
+
+## Current State (Completed)
+
+### TypeScript CLI ✅
+- [x] TypeScript config, esbuild bundling
+- [x] CLI entry point with yargs (`src/cli.ts`)
+- [x] All commands migrated (init, update, sync-back, check-ignored)
+- [x] Package.json configured with bin, files, scripts
+
+### AllHands Sync Action ✅
+- [x] `.github/workflows/allhands-sync.yml` handles sync-back
+- [x] Owner check, PR creation logic
+
+## Implementation Steps
+
+### Phase 1: NPM Publish Action ✅
+- [x] Create `.github/workflows/npm-publish.yml`
+  - Trigger: push to main
+  - Steps: checkout → setup node → npm ci → npm run build → npm publish
+  - Auth via `NPM_TOKEN` secret
+- [x] Add `publishConfig` to package.json (public access)
+- [x] Version bump strategy: manual before PR merge
+
+### Phase 2: Local Dev Mode (tsx) ✅
+- [x] Add `tsx` dev dependency
+- [x] Create wrapper script `scripts/dev-cli.sh`
+- [x] tsx mode works via `npx tsx src/cli.ts`
+- [ ] Document in README (optional)
+
+### Phase 3: Hook Integration ✅
+- [x] Update `.husky/post-merge` to use tsx when `ALLHANDS_PATH` set
+- [x] Test hook invocation with tsx path
+
+### Phase 4: CI/CD Verification ✅
+- [x] Verify build output in `bin/cli.js` built in CI
+- [x] `prepublishOnly` script runs build before publish
+
+## Files to Create
+
+- `.github/workflows/npm-publish.yml` - npm publish action
+- `scripts/dev-cli.sh` - local dev wrapper (optional)
+
+## Files to Modify
+
+- `package.json` - add tsx devDep, publishConfig
+- `src/lib/paths.ts` - tsx mode detection (if needed)
+- `.husky/post-merge` - use tsx path for local dev
+- `README.md` - document local dev workflow
+
+## Resolved Decisions
+
+1. **npm publish trigger**: Push to main only (not tags, simpler)
+2. **Version management**: Manual bump before PR merge
+3. **tsx integration**: Wrapper script pattern for clean separation
+4. **Build in CI**: Yes, `prepublishOnly` handles pre-publish build
+
+## Unresolved Questions
+
+- Auto-bump version via commit message convention? (e.g., `feat:` → minor)
+- npm publish to public registry or private?
+- Add `--dry-run` publish step to PR workflow for safety?