cortexhawk 3.1.0

package/mcp/README.md

@@ -0,0 +1,37 @@
+# MCP Server Configs
+
+Pre-configured MCP servers for Claude Code. Copy the ones you need into your project's `.mcp.json`.
+
+## Usage
+
+```bash
+# Copy a single config
+cp mcp/context7.json .mcp.json
+
+# Or merge into existing .mcp.json manually
+```
+
+## Available Servers
+
+| Server | Purpose | Requires |
+|---|---|---|
+| `context7.json` | Library docs lookup via Context7 | npx |
+| `sequential-thinking.json` | Step-by-step reasoning for complex problems | npx |
+| `puppeteer.json` | Browser automation and testing | npx |
+
+## Adding to your project
+
+Create or edit `.mcp.json` at your project root:
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "npx",
+      "args": ["-y", "package-name"]
+    }
+  }
+}
+```
+
+Then restart Claude Code to activate.

package/mcp/context7.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    }
+  }
+}

package/mcp/puppeteer.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "puppeteer": {
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/mcp-server-puppeteer"]
+    }
+  }
+}

package/mcp/sequential-thinking.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+    }
+  }
+}

package/modes/default.md

@@ -0,0 +1,5 @@
+---
+name: default
+description: Balanced mode — thorough but efficient.
+---
+Respond with clear, actionable output. Balance between detail and brevity. Ask for clarification only when truly ambiguous. Show your work when it adds value.

package/modes/fast.md

@@ -0,0 +1,5 @@
+---
+name: fast
+description: Minimal tokens, direct answers, no fluff.
+---
+Be extremely concise. Code over explanation. No preamble, no summary, no caveats unless critical. One-line answers when possible. Skip alternatives unless asked.

package/modes/learn.md

@@ -0,0 +1,9 @@
+---
+name: learn
+description: Teaching mode — three levels from hands-off guidance to structured lectures.
+---
+
+Never write code for the user. Default to **guided** if no level is specified.
+- **guided**: Step-by-step instructions (what file, what line, what concept) but zero code. The user writes everything.
+- **mentor**: Socratic method — ask questions, give hints, review attempts. Never give direct answers.
+- **professor**: Teach theory first. Architecture, trade-offs, patterns, then a learning roadmap.

package/modes/orchestration.md

@@ -0,0 +1,5 @@
+---
+name: orchestration
+description: Multi-agent coordination mode for complex tasks.
+---
+Break the task into subtasks. Assign each to the appropriate agent. Coordinate outputs between agents. Maintain context across handoffs. Report progress at each stage. Chain: plan → build → test → review → ship.

package/modes/pair.md

@@ -0,0 +1,10 @@
+---
+name: pair
+description: Pair-programming mode — alternate between implementer and reviewer on each change.
+---
+
+After each code change, immediately switch to reviewer and run a review pass (Correctness + Security).
+- If the review finds critical issues, fix them as implementer, then re-review. Max 2 review cycles per change.
+- If the review passes, move to the next change.
+- Always announce the current role: `[implementer]` or `[reviewer]`.
+- Prioritize shipping working code over perfection — stop refining after 2 cycles.

package/modes/research.md

@@ -0,0 +1,5 @@
+---
+name: research
+description: Deep analysis, brainstorming, exploration of alternatives.
+---
+Explore thoroughly. Consider multiple angles. Present trade-offs explicitly. Use comparison tables. Include evidence and references. Think out loud. Don't rush to a conclusion — examine the space first.

package/modes/review.md

@@ -0,0 +1,5 @@
+---
+name: review
+description: Critical, thorough examination with high standards.
+---
+Be rigorous. Check every edge case. Question assumptions. Flag anything that could fail in production. Score confidence for each finding. Include both problems and positive observations.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "cortexhawk",
+  "version": "3.1.0",
+  "description": "Open-source development toolkit for Claude Code — optimized agents, skills, commands, hooks, and modes",
+  "bin": {
+    "cortexhawk": "./cortexhawk"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Spechawk94/CortexHawk.git"
+  },
+  "homepage": "https://github.com/Spechawk94/CortexHawk#readme",
+  "bugs": {
+    "url": "https://github.com/Spechawk94/CortexHawk/issues"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "agents",
+    "cli",
+    "productivity",
+    "developer-tools",
+    "kimi",
+    "codex"
+  ],
+  "author": "Spechawk94",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16"
+  }
+}

package/profiles/api.json

@@ -0,0 +1,27 @@
+{
+  "name": "api",
+  "description": "Backend API development",
+  "skills": [
+    "frameworks/fastapi",
+    "frameworks/python",
+    "frameworks/typescript",
+    "frameworks/api-design",
+    "testing/tdd",
+    "testing/test-generator",
+    "databases/schema-designer",
+    "databases/sql-optimizer",
+    "devops/docker",
+    "devops/ci-cd",
+    "devops/deployment",
+    "optimization/performance",
+    "quality/error-handling",
+    "quality/log-analyzer",
+    "security/auth-analyzer",
+    "security/vulnerability-scanner",
+    "security/dependency-auditor",
+    "security/compliance-checker",
+    "workflow/commit",
+    "workflow/confidence-check",
+    "workflow/pr-review-comments"
+  ]
+}

package/profiles/data.json

@@ -0,0 +1,23 @@
+{
+  "name": "data",
+  "description": "Data engineering and data science",
+  "skills": [
+    "frameworks/python",
+    "testing/tdd",
+    "testing/test-generator",
+    "databases/schema-designer",
+    "databases/sql-optimizer",
+    "devops/docker",
+    "devops/ci-cd",
+    "devops/deployment",
+    "optimization/performance",
+    "quality/error-handling",
+    "quality/log-analyzer",
+    "quality/pattern-detector",
+    "security/dependency-auditor",
+    "security/secrets",
+    "workflow/commit",
+    "workflow/confidence-check",
+    "workflow/pr-review-comments"
+  ]
+}

package/profiles/fullstack.json

@@ -0,0 +1,27 @@
+{
+  "name": "fullstack",
+  "description": "Full-stack web development",
+  "skills": [
+    "frameworks/react",
+    "frameworks/nextjs",
+    "frameworks/tailwindcss",
+    "frameworks/typescript",
+    "frameworks/api-design",
+    "testing/tdd",
+    "testing/e2e-testing",
+    "testing/test-generator",
+    "databases/schema-designer",
+    "databases/sql-optimizer",
+    "devops/docker",
+    "devops/ci-cd",
+    "devops/deployment",
+    "optimization/performance",
+    "quality/error-handling",
+    "quality/complexity-analyzer",
+    "security/auth-analyzer",
+    "security/security-headers",
+    "workflow/commit",
+    "workflow/confidence-check",
+    "workflow/pr-review-comments"
+  ]
+}

package/scripts/autodetect-profile.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# autodetect-profile.sh — Metadata-driven skill detection (Phase 2)
+# Usage: source this script. Sets PROFILE_FILE and SKILL_COUNT.
+
+CORTEXHAWK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/.." && pwd)"
+SKILLS=""
+
+add_skill() {
+    case ",$SKILLS," in *",$1,"*) ;; *) SKILLS="${SKILLS:+$SKILLS,}$1" ;; esac
+}
+
+check_marker() {
+    local marker="$1"
+    case "$marker" in
+        base)       return 0 ;;
+        dir:*)      [ -d "${marker#dir:}" ] && return 0 ;;
+        *:*)        local file="${marker%%:*}" pattern="${marker#*:}"
+                    [ -f "$file" ] && grep -qi "$pattern" "$file" 2>/dev/null && return 0 ;;
+        *)          [ -f "$marker" ] && return 0 ;;
+    esac
+    return 1
+}
+
+for skill_file in "$CORTEXHAWK_DIR"/skills/*/*/SKILL.md; do
+    [ -f "$skill_file" ] || continue
+    detect_line=""
+    in_front=false
+    while IFS= read -r line; do
+        if [ "$line" = "---" ]; then
+            if [ "$in_front" = true ]; then break; fi
+            in_front=true; continue
+        fi
+        case "$line" in detect:*) detect_line="${line#detect: }" ;; esac
+    done < "$skill_file"
+    [ -z "$detect_line" ] && continue
+
+    skill_path="${skill_file#$CORTEXHAWK_DIR/skills/}"
+    skill_path="${skill_path%/SKILL.md}"
+
+    for marker in $detect_line; do
+        if check_marker "$marker"; then
+            add_skill "$skill_path"
+            break
+        fi
+    done
+done
+
+# --- Generate JSON ---
+PROFILE_FILE="/tmp/cortexhawk-autodetect-$$.json"
+SKILL_JSON=$(echo "$SKILLS" | tr ',' '\n' | sed 's/.*/    "&"/' | paste -sd ',' - | sed 's/,/,\n/g')
+cat > "$PROFILE_FILE" << EOF
+{
+  "name": "autodetect",
+  "description": "Auto-detected from project stack",
+  "skills": [
+$SKILL_JSON
+  ]
+}
+EOF
+SKILL_COUNT=$(echo "$SKILLS" | tr ',' '\n' | wc -l | tr -d ' ')
+
+# --- Stack snapshot ---
+if [ -d "docs/.context" ]; then
+    { echo "# Stack Detection"; echo "_Auto-generated. Do not edit._"
+      echo ""; echo "Last scan: $(date +%Y-%m-%d)"; echo "Skills detected: $SKILL_COUNT"; echo ""
+      echo "$SKILLS" | tr ',' '\n' | while read -r s; do echo "- $s"; done
+    } > "docs/.context/_stack.md"
+fi

package/scripts/benchmark.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+# benchmark.sh — Validate benchmark fixtures and expectations for CortexHawk agents
+# Run: bash scripts/benchmark.sh
+
+set -euo pipefail
+
+REPO_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+FIXTURES_DIR="$REPO_DIR/tests/fixtures"
+EXPECTATIONS_DIR="$REPO_DIR/tests/expectations"
+PASS=0
+FAIL=0
+
+red() { echo -e "\033[31m$1\033[0m"; }
+green() { echo -e "\033[32m$1\033[0m"; }
+
+pass() { green "  PASS: $1"; PASS=$((PASS + 1)); }
+fail() { red "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+echo "================================"
+echo "CortexHawk Benchmark Validator"
+echo "================================"
+echo ""
+
+# --- Validate fixtures ---
+FIXTURES="node-express-app python-fastapi-app react-nextjs-app"
+
+echo "Checking fixtures..."
+for fixture in $FIXTURES; do
+    fixture_path="$FIXTURES_DIR/$fixture"
+
+    # Check directory exists
+    if [ ! -d "$fixture_path" ]; then
+        fail "$fixture — directory missing"
+        continue
+    fi
+
+    # Count files
+    file_count=$(find "$fixture_path" -type f | wc -l | tr -d ' ')
+    if [ "$file_count" -lt 3 ]; then
+        fail "$fixture — only $file_count files (minimum 3)"
+    else
+        pass "$fixture — $file_count files found"
+    fi
+
+    # Check README exists
+    if [ -f "$fixture_path/README.md" ]; then
+        pass "$fixture — README.md present"
+    else
+        fail "$fixture — README.md missing"
+    fi
+
+    # Count BUG/VULN tags
+    bug_count=$(grep -r "BUG:" "$fixture_path" --include='*.js' --include='*.py' --include='*.txt' 2>/dev/null | wc -l | tr -d ' ')
+    vuln_count=$(grep -r "VULN:" "$fixture_path" --include='*.js' --include='*.py' --include='*.txt' 2>/dev/null | wc -l | tr -d ' ')
+    total_tags=$((bug_count + vuln_count))
+
+    if [ "$total_tags" -ge 4 ]; then
+        pass "$fixture — $bug_count BUG + $vuln_count VULN tags ($total_tags total)"
+    else
+        fail "$fixture — only $total_tags BUG/VULN tags (minimum 4)"
+    fi
+done
+echo ""
+
+# --- Validate expectations ---
+AGENTS="planner implementer reviewer debugger security-auditor architect brainstormer codebase-mapper code-simplifier copywriter designer devops docs-manager fullstack-developer git-manager journal-writer project-manager researcher teacher tester"
+
+echo "Checking expectations..."
+for agent in $AGENTS; do
+    exp_file="$EXPECTATIONS_DIR/$agent.json"
+
+    # Check file exists
+    if [ ! -f "$exp_file" ]; then
+        fail "$agent.json — file missing"
+        continue
+    fi
+
+    # Validate JSON syntax
+    if python3 -m json.tool "$exp_file" > /dev/null 2>&1; then
+        pass "$agent.json — valid JSON"
+    else
+        fail "$agent.json — invalid JSON syntax"
+        continue
+    fi
+
+    # Check required fields via JSON parsing
+    for field in required_sections required_keywords forbidden_patterns; do
+        if python3 -c "import json,sys; data=json.load(open(sys.argv[1])); sys.exit(0 if sys.argv[2] in data else 1)" "$exp_file" "$field" 2>/dev/null; then
+            pass "$agent.json — has '$field'"
+        else
+            fail "$agent.json — missing '$field'"
+        fi
+    done
+done
+echo ""
+
+# --- Summary ---
+TOTAL=$((PASS + FAIL))
+echo "================================"
+if [ "$FAIL" -gt 0 ]; then
+    red "RESULT: $PASS/$TOTAL passed, $FAIL failed"
+    exit 1
+else
+    green "RESULT: $PASS/$TOTAL passed — all checks clean"
+    exit 0
+fi

package/scripts/chain-post-save.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# Post-save hook for chain outputs: creates plan symlink + regenerates INDEX.md
+set -e
+
+CHAIN_DIR="${1:?Usage: chain-post-save.sh <chain-dir> [project-root]}"
+PROJECT_ROOT="${2:-.}"
+PLANS_DIR="$PROJECT_ROOT/docs/plans"
+
+# Extract chain name from dir path
+chain_name=$(basename "$CHAIN_DIR")
+
+# Create symlink for planner output
+if [ -f "$CHAIN_DIR/1-planner.md" ]; then
+    mkdir -p "$PLANS_DIR"
+    ln -sf "../chains/$chain_name/1-planner.md" "$PLANS_DIR/${chain_name}-plan.md"
+    echo "Symlink: docs/plans/${chain_name}-plan.md -> ../chains/$chain_name/1-planner.md"
+fi
+
+# Regenerate plans INDEX.md
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+if [ -f "$SCRIPT_DIR/generate-plans-index.sh" ]; then
+    bash "$SCRIPT_DIR/generate-plans-index.sh" "$PROJECT_ROOT"
+fi

package/scripts/generate-plans-index.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# Generate docs/plans/INDEX.md from standalone plans + chain plans
+set -e
+
+PROJECT_ROOT="${1:-.}"
+PLANS_DIR="$PROJECT_ROOT/docs/plans"
+CHAINS_DIR="$PROJECT_ROOT/docs/chains"
+INDEX="$PLANS_DIR/INDEX.md"
+
+mkdir -p "$PLANS_DIR"
+
+# Collect rows into temp var, then sort
+rows=""
+
+# Standalone plans (skip symlinks — those are listed via chains)
+for file in "$PLANS_DIR"/*.md; do
+    [ -f "$file" ] || continue
+    [ -L "$file" ] && continue
+    name=$(basename "$file" .md)
+    [ "$name" = "INDEX" ] && continue
+    date=$(echo "$name" | grep -oE '^[0-9]{4}-[0-9]{2}-[0-9]{2}' || echo "—")
+    title=$(head -1 "$file" | sed 's/^#* *//')
+    rows="$rows| $date | [$title]($name.md) | standalone |
+"
+done
+
+# Chain plans
+for file in "$CHAINS_DIR"/*/1-planner.md; do
+    [ -f "$file" ] || continue
+    chain_dir=$(basename "$(dirname "$file")")
+    date=$(echo "$chain_dir" | grep -oE '^[0-9]{4}-[0-9]{2}-[0-9]{2}' || echo "—")
+    title=$(head -1 "$file" | sed 's/^#* *//')
+    relpath="../chains/$chain_dir/1-planner.md"
+    rows="$rows| $date | [$title]($relpath) | chain |
+"
+done
+
+# Write INDEX.md: header + sorted rows (newest first)
+{
+    echo "# Plans Index"
+    echo ""
+    echo "Auto-generated — do not edit manually."
+    echo ""
+    echo "| Date | Plan | Source |"
+    echo "|---|---|---|"
+    echo -n "$rows" | sort -r
+} > "$INDEX"
+
+count=$(echo -n "$rows" | grep -c '^|' || true)
+echo "INDEX.md generated: $count plan(s)"

package/scripts/git-workflow-init.sh

@@ -0,0 +1,115 @@
+#!/bin/bash
+# git-workflow-init.sh — Git workflow preferences wizard (step 5 of --init)
+# Sourced by install.sh after CLAUDE.md setup. Args: $1=PROJECT_ROOT $2=TARGET
+# If GIT_BRANCHING is already set (from interactive-init.sh), skip questions and just write.
+
+GW_PROJECT_ROOT="$1"
+GW_TARGET="$2"
+
+cyan()  { printf "\033[36m%s\033[0m\n" "$1"; } 2>/dev/null
+green() { printf "\033[32m%s\033[0m\n" "$1"; } 2>/dev/null
+bold()  { printf "\033[1m%s\033[0m\n" "$1"; } 2>/dev/null
+
+# If variables already set by interactive-init.sh, skip questions
+if [ -z "$GIT_BRANCHING" ]; then
+    echo ""
+    bold "5. Git Workflow"
+    echo ""
+
+    # --- Branching strategy ---
+    echo "  Branching strategy:"
+    echo "    1) Direct main   — commit + push direct to main (solo/small team)"
+    echo "    2) Dev branch    — work on a fixed branch, PR to main when ready"
+    echo "    3) Feature branch — one branch per feature, merge via PR"
+    echo "    4) GitFlow       — develop/release/hotfix (formal release cycles)"
+    read -r -p "  Choice [1-4] (default: 1): " branch_choice
+    case "$branch_choice" in
+        2) GIT_BRANCHING="dev-branch" ;;
+        3) GIT_BRANCHING="feature-branches" ;;
+        4) GIT_BRANCHING="gitflow" ;;
+        *) GIT_BRANCHING="direct-main" ;;
+    esac
+
+    GIT_WORK_BRANCH=""
+    if [ "$GIT_BRANCHING" = "dev-branch" ]; then
+        read -r -p "  Working branch name (default: dev): " work_branch
+        GIT_WORK_BRANCH="${work_branch:-dev}"
+        green "  -> $GIT_BRANCHING (branch: $GIT_WORK_BRANCH)"
+    else
+        green "  -> $GIT_BRANCHING"
+    fi
+    echo ""
+
+    # --- Commit convention ---
+    echo "  Commit convention:"
+    echo "    1) Conventional — feat(scope): description (default)"
+    echo "    2) Freeform     — no enforced format"
+    read -r -p "  Choice [1-2] (default: 1): " commit_choice
+    case "$commit_choice" in
+        2) GIT_COMMIT_CONVENTION="freeform" ;;
+        *) GIT_COMMIT_CONVENTION="conventional" ;;
+    esac
+    green "  -> $GIT_COMMIT_CONVENTION"
+    echo ""
+
+    # --- PR preference ---
+    echo "  Pull requests:"
+    echo "    1) Never    — /ship does commit + push, no PR"
+    echo "    2) On demand — /ship asks before creating a PR (default)"
+    echo "    3) Always   — /ship always creates a PR"
+    read -r -p "  Choice [1-3] (default: 2): " pr_choice
+    case "$pr_choice" in
+        1) GIT_PR_PREFERENCE="never" ;;
+        3) GIT_PR_PREFERENCE="always" ;;
+        *) GIT_PR_PREFERENCE="on-demand" ;;
+    esac
+    green "  -> $GIT_PR_PREFERENCE"
+    echo ""
+
+    # --- Auto-push ---
+    echo "  Auto-push after commit:"
+    echo "    1) Never       — commit only, manual push"
+    echo "    2) After commit — push automatically after each commit (default)"
+    echo "    3) Ask          — ask each time"
+    read -r -p "  Choice [1-3] (default: 2): " push_choice
+    case "$push_choice" in
+        1) GIT_AUTO_PUSH="never" ;;
+        3) GIT_AUTO_PUSH="ask" ;;
+        *) GIT_AUTO_PUSH="after-commit" ;;
+    esac
+    green "  -> $GIT_AUTO_PUSH"
+    echo ""
+fi
+
+# Use variables from interactive-init.sh or from questions above
+BRANCHING="${GIT_BRANCHING}"
+COMMIT_CONVENTION="${GIT_COMMIT_CONVENTION}"
+PR_PREFERENCE="${GIT_PR_PREFERENCE}"
+AUTO_PUSH="${GIT_AUTO_PUSH}"
+
+# --- Write git-workflow.conf ---
+{
+    echo "# CortexHawk git workflow preferences"
+    echo "# Generated by install.sh --init"
+    echo "BRANCHING=$BRANCHING"
+    echo "COMMIT_CONVENTION=$COMMIT_CONVENTION"
+    echo "PR_PREFERENCE=$PR_PREFERENCE"
+    echo "AUTO_PUSH=$AUTO_PUSH"
+    [ -n "$GIT_WORK_BRANCH" ] && echo "WORK_BRANCH=$GIT_WORK_BRANCH"
+} > "$GW_TARGET/git-workflow.conf"
+green "  Saved git-workflow.conf"
+
+# --- Append ## Git Workflow to CLAUDE.md ---
+GW_CLAUDE_MD="$GW_PROJECT_ROOT/CLAUDE.md"
+if [ -f "$GW_CLAUDE_MD" ] && ! grep -q "^## Git Workflow" "$GW_CLAUDE_MD"; then
+    {
+        echo ""
+        echo "## Git Workflow"
+        echo ""
+        echo "- **Branching**: $BRANCHING$([ -n "$GIT_WORK_BRANCH" ] && echo " (working branch: $GIT_WORK_BRANCH)")"
+        echo "- **Commits**: $COMMIT_CONVENTION"
+        echo "- **PR preference**: $PR_PREFERENCE"
+        echo "- **Auto-push**: $AUTO_PUSH"
+    } >> "$GW_CLAUDE_MD"
+    green "  Appended Git Workflow section to CLAUDE.md"
+fi