cortexhawk 3.1.1 → 3.2.0

package/CHANGELOG.md

@@ -3,12 +3,32 @@
 All notable changes to CortexHawk are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/)
 
-## [3.1.1] - 2026-02-15
+## [3.2.0] - 2026-02-15
+
+### Added
+- `/commit` command: lightweight conventional commit + push without review or PR — use `/ship` for full workflow, `/commit` for quick iterations
+- Install auto-detects existing PR/commit templates; generates CortexHawk defaults (`.github/PULL_REQUEST_TEMPLATE.md`, `.gitmessage`) if missing — agents (`git-manager`, `/ship`, `/commit`) read templates at runtime
+- `--version` / `-v` flag: displays CortexHawk version
+- `scripts/refresh-context.sh`: regenerates `docs/.context/_shared.md` mid-session — `/task` and `/backlog` auto-refresh after modifying backlog
 
 ### Fixed
 - `branch-guard` / `commit-guard` hooks: JSON parsing via `jq` with regex fallback — fixes false "hook error" on commands containing quotes or HEREDOC
 - `commit-guard`: multi-format commit message extraction (HEREDOC, single/double quotes)
 - `file-guard`: match on basename only — `*secret*`/`*credentials*` no longer false-positive on legitimate files (e.g., `oauth_service.py`); `.env.example`/`.env.sample`/`.env.template` whitelisted; `docker-compose*.yml` unblocked
+- **Security**: eliminate shell injection in all Python HEREDOC/inline scripts — `$hooks_json`, file paths, and user input no longer interpolated into Python source; uses `sys.argv`/`sys.stdin` instead. Hook names validated against path traversal, hook paths shell-escaped via `shlex.quote()`
+- Portable `sed -i` via `sed_inplace()` helper — fixes `sed` failures on macOS (BSD) across snapshot, hook toggle, and init wizard
+- Argument validation for `--target`, `--profile`, and `--restore` flags — prevents cryptic shell errors when value is missing
+- `update_gitignore()` now ensures essential entries (`.env`, `node_modules/`, `dist/`, etc.) are present — previously only added `.claude/` to an existing `.gitignore`
+- Warning when python3 is not found — `generate_hooks_config()` previously failed silently, now alerts user that static fallback is used
+- `.env` parser now strips single quotes, inline comments, and trailing whitespace — previously only stripped double quotes
+- `--init` wizard now supports "All" and "Auto-detect" targets — removed false `--target all/auto` + `--init` guards, scope step auto-selects local for multi-target
+- Snapshot no longer reads stale `/tmp/cortexhawk-custom-*.json` from previous runs — uses `$PROFILE_FILE` from current session only
+- `copy_skills()` now warns when a skill from the profile doesn't exist in source — previously silently skipped
+- Removed `local` keyword used outside function in `--target auto` dispatcher — fixes portability issues
+- `.gitignore` no longer duplicates `# CortexHawk` header with `--target all` — groups all target dirs under single header
+- `SKILL_COUNT` no longer shows 1 when no skills detected — fixed `wc -l` on empty string in `autodetect-profile.sh`
+- `_shared.md` now includes generation timestamp for staleness awareness
+- `settings.json` now merges on reinstall instead of skipping — new hooks regenerated from compose.yml, new permissions added via union (user customizations preserved). `--update` also merges new permissions
 
 ## [3.1.0] - 2026-02-14
 

package/CLAUDE.md

@@ -6,7 +6,7 @@ Open-source development toolkit for Claude Code — optimized agents, skills, co
 
 ```
 agents/       — 20 specialized AI agents
-commands/     — 32 slash commands
+commands/     — 33 slash commands
 scripts/      — Validation and post-install audit scripts
 skills/       — 36 domain-specific knowledge modules
 hooks/        — 9 lifecycle hooks
@@ -49,7 +49,7 @@ Custom agents in `.cortexhawk-agents/` at project root. Each `.md` file uses `ex
 
 ## Commands
 
-`/plan` `/build` `/test` `/review` `/ship` `/debug` `/scan` `/check` `/refactor` `/research` `/doc` `/bootstrap` `/tdd` `/optimize` `/migrate` `/monitor` `/api-gen` `/changelog` `/journal` `/brainstorm` `/simplify` `/deploy` `/export` `/backlog` `/pulse` `/map` `/learn` `/chain` `/task` `/ci` `/context` `/upgrade`
+`/plan` `/build` `/test` `/review` `/ship` `/commit` `/debug` `/scan` `/check` `/refactor` `/research` `/doc` `/bootstrap` `/tdd` `/optimize` `/migrate` `/monitor` `/api-gen` `/changelog` `/journal` `/brainstorm` `/simplify` `/deploy` `/export` `/backlog` `/pulse` `/map` `/learn` `/chain` `/task` `/ci` `/context` `/upgrade`
 
 ## Skills
 

package/README.md

@@ -2,22 +2,35 @@
 
 [![GitHub stars](https://img.shields.io/github/stars/Spechawk94/CortexHawk?style=flat-square)](https://github.com/Spechawk94/CortexHawk/stargazers)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.1.0-green.svg?style=flat-square)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.2.0-green.svg?style=flat-square)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/cortexhawk?style=flat-square&color=red)](https://www.npmjs.com/package/cortexhawk)
 [![Skills](https://img.shields.io/badge/skills-36%20built--in%20%7C%2087k%2B%20via%20SkillsMP-orange.svg?style=flat-square)](https://skillsmp.com)
-[![Components](https://img.shields.io/badge/20%20agents%20%7C%2032%20commands%20%7C%209%20hooks%20%7C%207%20modes-purple.svg?style=flat-square)](#whats-inside)
+[![Components](https://img.shields.io/badge/20%20agents%20%7C%2033%20commands%20%7C%209%20hooks%20%7C%207%20modes-purple.svg?style=flat-square)](#whats-inside)
 
 An open-source, community-driven development toolkit for Claude Code.
 
 CortexHawk provides a modular collection of optimized agents, skills, commands, hooks, and behavioral modes that transform Claude Code into a full-stack development team. Every prompt has been written for maximum efficiency — less token bloat, sharper instructions, better agent coordination.
 
-### What's New in v3.1
+### What's New in v3.2
+
+- **`/commit` command** — lightweight conventional commit + push without review or PR (use `/ship` for full workflow)
+- **`--version` flag** — standard CLI version display
+- **PR/commit templates** — auto-detected at install, generated if missing; agents read templates at runtime
+- **Settings.json merge** — reinstall and `--update` now merge new hooks + permissions instead of skipping
+- **Security hardening** — eliminated shell injection in all Python HEREDOC scripts, portable `sed -i`, input validation
+- **`--init` wizard** — "Auto-detect" target option, improved multi-target support
+- **15+ bug fixes** — see [CHANGELOG.md](CHANGELOG.md) for full details
+
+<details>
+<summary>v3.1 changes</summary>
 
 - **`npm install -g cortexhawk`** — available on npm, auto-resolves source from symlinked binary
 - **`cortexhawk` CLI wrapper** — clean subcommands (init, install, update, doctor, validate, search, snapshot, etc.) instead of `bash install.sh --flags`
 - **`--target auto`** — auto-detects installed CLIs (claude, kimi, codex) and installs for all found
 - **`cortexhawk validate`** — post-install diagnostic verifying skills/agents discovery per target
 
+</details>
+
 <details>
 <summary>v3.0 changes</summary>
 
@@ -103,7 +116,7 @@ Specialized AI agents that coordinate together instead of working in silos.
 | `fullstack-developer` | Full-stack orchestration front+back |
 | `teacher` | Teaches concepts with 3 pedagogical levels (guided, mentor, professor) |
 
-### Commands (32)
+### Commands (33)
 
 Slash commands for common workflows.
 
@@ -114,6 +127,7 @@ Slash commands for common workflows.
 | `/test` | Generate and run tests |
 | `/review` | Multi-agent code review |
 | `/ship` | Commit + PR pipeline |
+| `/commit` | Lightweight commit + push (no review, no PR) |
 | `/debug` | Debug and fix issues |
 | `/scan` | Full security audit |
 | `/check` | Pre-commit quality gate (lint + test + scan + review → GO/NO-GO) |
@@ -313,7 +327,7 @@ Each target adapts components to the CLI's native format:
 | Component | Claude Code | Kimi CLI | Codex CLI |
 |---|---|---|---|
 | Agents (20) | `.claude/agents/*.md` | Skills (`/skill:agent-*`) + `AGENTS.md` | `AGENTS.md` |
-| Commands (32) | `.claude/commands/*.md` → `/plan` | Skills (`/skill:cmd-*`) | Skills (`$cmd-*`) |
+| Commands (33) | `.claude/commands/*.md` → `/plan` | Skills (`/skill:cmd-*`) | Skills (`$cmd-*`) |
 | Skills (36) | `.claude/skills/` | `.kimi/skills/` (auto-discovered) | `.agents/skills/` |
 | Hooks (9) | `settings.json` (automatic) | Skills (`/skill:hook-*`, manual) | Dispatcher (partial) |
 | Modes (7) | `.claude/modes/` (native) | Skills (`/skill:modes/*`) | Skills (`$mode-*`) |
@@ -335,6 +349,7 @@ Each target adapts components to the CLI's native format:
 ./install.sh --update --dry-run        # preview update delta
 
 # Diagnostics
+./install.sh --version                 # show CortexHawk version
 ./install.sh --doctor                  # check installation health
 ./install.sh --test-hooks              # dry-run all hooks with synthetic inputs
 ./install.sh --stats                   # installation overview (version, counts)

package/agents/git-manager.md

@@ -49,6 +49,10 @@ Description: imperative mood, lowercase, no period, max 72 chars
 - Checklist: tests pass, no warnings, docs updated
 ```
 
+## Templates
+- Before creating a PR, check for `.github/PULL_REQUEST_TEMPLATE.md` — if found, follow that format
+- Before committing, check for `.gitmessage` — if found, follow that format for the commit message
+
 ## Rules
 - Atomic commits — one logical change per commit
 - Never force-push to shared branches

package/commands/backlog.md

@@ -12,6 +12,7 @@ Activate the **project-manager** agent in backlog mode.
 3. Score: impact (H/M/L), effort (H/M/L), feasibility (H/M/L)
 4. Update `docs/backlog.md` — add new items, re-prioritize existing ones
 5. Mark items already implemented as done
+6. Run `bash scripts/refresh-context.sh` to update shared context
 
 Backlog format in `docs/backlog.md`:
 

package/commands/commit.md

@@ -0,0 +1,24 @@
+---
+name: commit
+description: Conventional commit and push — lightweight alternative to /ship (no review, no PR).
+---
+
+# /commit
+
+Activate the **git-manager** agent. Commit: `$ARGUMENTS`
+
+1. Read `## Git Workflow` from CLAUDE.md if present — respect branching strategy, commit convention, and auto-push settings
+2. If `.gitmessage` exists, read it for commit message format guidance
+3. Review staged and unstaged changes, stage relevant files (never `git add -A`)
+4. Generate conventional commit message from changes — format: `type(scope): description`
+5. Commit with the generated message
+6. If auto-push is enabled, push to remote
+7. Show commit summary (hash, message, files changed)
+
+## Rules
+
+- No review pass — use `/ship` for reviewed commits, `/commit` for quick iterations
+- No PR creation — use `/ship` when a PR is needed
+- Respect `.gitignore` — never stage `.env`, secrets, or debug artifacts
+- If no changes to commit, report and stop
+- If `$ARGUMENTS` is provided, use it as commit message context (not the literal message)

package/commands/ship.md

@@ -11,7 +11,7 @@ Activate the **git-manager** agent, then the **reviewer** agent. Ship: `$ARGUMEN
 1. Stage changes and generate conventional commit message
 2. Run quick review pass — reviewer runs Pass 1 (Correctness) and Pass 2 (Security) only, reporting Critical findings exclusively
 3. If review passes, commit and push
-4. Create PR with description, testing notes, and checklist
+4. Create PR — if `.github/PULL_REQUEST_TEMPLATE.md` exists, follow that format; otherwise use: Summary, Changes, Test Plan, Checklist
 5. If review finds critical issues, report them and stop — don't ship broken code
 
 Format: `feat(scope): description` or `fix(scope): description`

package/commands/task.md

@@ -16,6 +16,7 @@ Activate the **project-manager** agent as orchestrator. Execute backlog item `$A
 6. Update `CHANGELOG.md` with a one-line entry under the current version's `### Added` section
 7. If chain completes without critical blockers, execute `/ship`
 8. Mark item as `done` in backlog
+9. Run `bash scripts/refresh-context.sh` to update shared context
 
 ## Save Rules
 

package/hooks/session-start.sh

@@ -44,14 +44,17 @@ if [ -d "docs/.context" ] && [ ! -L "docs/.context" ]; then
 
     echo "# Shared Context" > "$SHARED"
     echo "" >> "$SHARED"
-    echo "_Auto-generated by session-start. Do not edit manually._" >> "$SHARED"
+    echo "_Auto-generated at $(date '+%Y-%m-%d %H:%M'). Snapshot from session start — may be stale._" >> "$SHARED"
     echo "" >> "$SHARED"
 
     # Backlog summary
     if [ -f "docs/backlog.md" ]; then
-        ACTIVE=$(grep -c '| todo |' docs/backlog.md 2>/dev/null || echo 0)
-        DEFERRED=$(grep -c '| deferred |' docs/backlog.md 2>/dev/null || echo 0)
-        DONE=$(grep -c '| done |' docs/backlog.md 2>/dev/null || echo 0)
+        ACTIVE=$(grep -c '| todo |' docs/backlog.md 2>/dev/null || true)
+        : "${ACTIVE:=0}"
+        DEFERRED=$(grep -c '| deferred |' docs/backlog.md 2>/dev/null || true)
+        : "${DEFERRED:=0}"
+        DONE=$(grep -c '| done |' docs/backlog.md 2>/dev/null || true)
+        : "${DONE:=0}"
         echo "## Backlog" >> "$SHARED"
         echo "- Active: $ACTIVE | Deferred: $DEFERRED | Done: $DONE" >> "$SHARED"
         # List active items

package/install.sh

@@ -7,7 +7,14 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 if [ -f ".env" ]; then
     while IFS='=' read -r key value; do
         [[ -z "$key" || "$key" == \#* ]] && continue
+        # Strip double quotes
         value="${value%\"}" && value="${value#\"}"
+        # Strip single quotes
+        value="${value%'}" && value="${value#'}"
+        # Strip inline comments (space + # marks start of comment)
+        value="$(printf '%s\n' "$value" | sed 's/[[:space:]]#.*$//')"
+        # Strip trailing whitespace
+        value="${value%"${value##*[! ]}"}"
         export "$key=$value" 2>/dev/null || true
     done < .env
 fi
@@ -20,6 +27,15 @@ get_version() {
     grep -m1 '## \[' "$SCRIPT_DIR/CHANGELOG.md" | sed 's/.*\[\([^]]*\)\].*/\1/'
 }
 
+# Portable sed -i (GNU vs BSD)
+sed_inplace() {
+    if sed --version 2>/dev/null | grep -q GNU; then
+        sed -i "$@"
+    else
+        sed -i '' "$@"
+    fi
+}
+
 compute_checksum() {
     local file="$1"
     if command -v sha256sum >/dev/null 2>&1; then
@@ -106,6 +122,7 @@ print_usage() {
     echo "  --dry-run         Simulate install/update without writing files"
     echo "  --test-hooks      Dry-run all hooks with synthetic inputs"
     echo "  --no-scan         Skip post-install security audit"
+    echo "  --version, -v     Show CortexHawk version"
     echo "  --help, -h        Show this help"
 }
 
@@ -149,10 +166,18 @@ MAX_SNAPSHOTS=10
 while [ $# -gt 0 ]; do
     case "$1" in
         --target)
+            if [ -z "${2:-}" ]; then
+                echo "Error: --target requires a value (claude|kimi|codex|auto|all)"
+                exit 1
+            fi
             TARGET_CLI="$2"
             shift 2
             ;;
         --profile)
+            if [ -z "${2:-}" ]; then
+                echo "Error: --profile requires a value (fullstack|api|data)"
+                exit 1
+            fi
             PROFILE="$2"
             shift 2
             ;;
@@ -218,6 +243,10 @@ while [ $# -gt 0 ]; do
             ;;
         --restore)
             RESTORE_MODE=true
+            if [ -z "${2:-}" ]; then
+                echo "Error: --restore requires a snapshot path or --latest"
+                exit 1
+            fi
             SNAPSHOT_FILE="$2"
             if [ "$SNAPSHOT_FILE" = "--latest" ]; then
                 if [ "$GLOBAL" = true ]; then
@@ -323,6 +352,10 @@ while [ $# -gt 0 ]; do
             fi
             shift 2
             ;;
+        --version|-v)
+            echo "CortexHawk $(get_version)"
+            exit 0
+            ;;
         --help|-h)
             print_usage
             exit 0
@@ -368,14 +401,6 @@ if [ "$RESTORE_MODE" = true ] && { [ "$INIT_MODE" = true ] || [ "$UPDATE_MODE" =
     echo "Error: --restore cannot be combined with --init or --update"
     exit 1
 fi
-if [ "$TARGET_CLI" = "all" ] && [ "$INIT_MODE" = true ]; then
-    echo "Error: --target all cannot be combined with --init (run --init per target instead)"
-    exit 1
-fi
-if [ "$TARGET_CLI" = "auto" ] && [ "$INIT_MODE" = true ]; then
-    echo "Error: --target auto cannot be combined with --init (run --init per target instead)"
-    exit 1
-fi
 if [ -n "$ADD_SKILL_URL" ] && { [ "$INIT_MODE" = true ] || [ "$UPDATE_MODE" = true ] || [ "$SNAPSHOT_MODE" = true ] || [ "$RESTORE_MODE" = true ]; }; then
     echo "Error: --add-skill cannot be combined with --init, --update, --snapshot, or --restore"
     exit 1
@@ -486,6 +511,10 @@ copy_skills() {
         grep '"[a-z]' "$PROFILE_FILE" | sed 's/.*"\([a-z][^"]*\)".*/\1/' | grep '/' | while read -r skill; do
             local src="$SCRIPT_DIR/skills/$skill"
             local dest="$target_dir/skills/$skill"
+            if [ ! -d "$src" ]; then
+                yellow "  Warning: skill '$skill' not found in source — skipping"
+                continue
+            fi
             mkdir -p "$(dirname "$dest")"
             cp -r "$src" "$dest" 2>/dev/null || true
         done
@@ -594,11 +623,34 @@ update_gitignore() {
         touch "$gitignore"
     fi
 
-    # Auto-add target directory (always)
-    if ! grep -qx "$target_dir/" "$gitignore" 2>/dev/null; then
-        echo "" >> "$gitignore"
-        echo "# CortexHawk" >> "$gitignore"
-        echo "$target_dir/" >> "$gitignore"
+    # Ensure essential entries are present (disable glob to keep *.log literal)
+    local essentials="node_modules/ __pycache__/ .env .env.local *.log dist/ build/ .DS_Store"
+    local added_count=0
+    set -f
+    for entry in $essentials; do
+        if ! grep -qxF "$entry" "$gitignore" 2>/dev/null; then
+            echo "$entry" >> "$gitignore"
+            added_count=$((added_count + 1))
+        fi
+    done
+    set +f
+    if [ "$added_count" -gt 0 ]; then
+        green "  Added $added_count essential entries to .gitignore (.env, node_modules/, etc.)"
+    fi
+
+    # Auto-add target directory (always), group under single header
+    if ! grep -qxF "$target_dir/" "$gitignore" 2>/dev/null; then
+        if grep -q "# CortexHawk" "$gitignore" 2>/dev/null; then
+            # Append under the first existing header only
+            local header_line
+            header_line=$(grep -n "# CortexHawk" "$gitignore" | head -1 | cut -d: -f1)
+            sed_inplace "${header_line}a\\
+$target_dir/" "$gitignore"
+        else
+            echo "" >> "$gitignore"
+            echo "# CortexHawk" >> "$gitignore"
+            echo "$target_dir/" >> "$gitignore"
+        fi
         green "  Added $target_dir/ to .gitignore"
     fi
 
@@ -619,6 +671,52 @@ update_gitignore() {
     fi
 }
 
+# --- setup_templates() ---
+# Detects existing PR/commit templates; generates CortexHawk defaults if missing
+# Args: $1=project_root
+setup_templates() {
+    local project_root="$1"
+
+    [ "$GLOBAL" = true ] && return
+
+    # PR template
+    local pr_template=""
+    for path in ".github/PULL_REQUEST_TEMPLATE.md" ".github/pull_request_template.md" "docs/pull_request_template.md"; do
+        if [ -f "$project_root/$path" ]; then
+            pr_template="$path"
+            break
+        fi
+    done
+    # Also check template directory
+    if [ -z "$pr_template" ] && [ -d "$project_root/.github/PULL_REQUEST_TEMPLATE" ]; then
+        pr_template=".github/PULL_REQUEST_TEMPLATE/"
+    fi
+
+    if [ -n "$pr_template" ]; then
+        green "  PR template found: $pr_template"
+    else
+        mkdir -p "$project_root/.github"
+        cp "$SCRIPT_DIR/templates/github/PULL_REQUEST_TEMPLATE.md" "$project_root/.github/PULL_REQUEST_TEMPLATE.md"
+        green "  PR template created: .github/PULL_REQUEST_TEMPLATE.md"
+    fi
+
+    # Commit template
+    local commit_template=""
+    for path in ".gitmessage" ".github/gitmessage" ".github/commit-template"; do
+        if [ -f "$project_root/$path" ]; then
+            commit_template="$path"
+            break
+        fi
+    done
+
+    if [ -n "$commit_template" ]; then
+        green "  Commit template found: $commit_template"
+    else
+        cp "$SCRIPT_DIR/templates/github/gitmessage" "$project_root/.gitmessage"
+        green "  Commit template created: .gitmessage"
+    fi
+}
+
 # --- run_audit() ---
 run_audit() {
     local project_root="$1"
@@ -641,11 +739,12 @@ generate_hooks_config() {
     fi
 
     if ! command -v python3 >/dev/null 2>&1; then
+        yellow "  Warning: python3 not found — hooks config will use static fallback" >&2
         return 1
     fi
 
-    python3 << PYEOF
-import re, json, sys
+    python3 - "$compose_file" "$hooks_dir" << 'PYEOF'
+import re, json, sys, shlex
 
 def parse_compose(path, hooks_dir):
     """Parse compose.yml and generate Claude Code hooks JSON."""
@@ -679,10 +778,13 @@ def parse_compose(path, hooks_dir):
         # Hook item
         elif line.strip().startswith('- '):
             hook_name = line.strip()[2:].strip()
+            if not re.match(r'^[a-zA-Z0-9_-]+$', hook_name):
+                print(f"Warning: skipping invalid hook name: {hook_name}", file=sys.stderr)
+                continue
             hook_path = f"{hooks_dir}/{hook_name}.sh"
 
             # Build command — hooks read stdin JSON (Claude Code protocol)
-            cmd = f'bash {hook_path}'
+            cmd = f'bash {shlex.quote(hook_path)}'
 
             hook_entry = {"type": "command", "command": cmd}
 
@@ -708,7 +810,7 @@ def parse_compose(path, hooks_dir):
     return result
 
 try:
-    result = parse_compose("$compose_file", "$hooks_dir")
+    result = parse_compose(sys.argv[1], sys.argv[2])
     print(json.dumps(result, indent=2))
 except Exception as e:
     print(f"Error: {e}", file=sys.stderr)
@@ -1176,30 +1278,40 @@ do_update() {
         # Make hooks executable
         chmod +x "$TARGET/hooks/"*.sh 2>/dev/null || true
 
-        # 7b. Regenerate settings.json hooks section from compose.yml
+        # 7b. Regenerate settings.json hooks + merge new permissions from compose.yml
         if [ -f "$SCRIPT_DIR/hooks/compose.yml" ]; then
             local hooks_json
             hooks_json=$(generate_hooks_config "$SCRIPT_DIR/hooks/compose.yml" ".claude/hooks")
-            if [ -n "$hooks_json" ]; then
-                python3 << PYEOF
+            if [ -n "$hooks_json" ] && [ "$hooks_json" != "{}" ]; then
+                echo "$hooks_json" | python3 -c "
 import json, sys
-
-# Read current settings.json to preserve permissions
+hooks = json.load(sys.stdin)
 current = {}
 try:
-    with open('$TARGET/settings.json') as f:
+    with open(sys.argv[1]) as f:
         current = json.load(f)
 except:
     pass
-
-# Merge: keep existing permissions, replace hooks
-hooks = json.loads('''$hooks_json''')
 current['hooks'] = hooks
-
-with open('$TARGET/settings.json', 'w') as f:
+# Merge new permissions from source
+try:
+    with open(sys.argv[2]) as f:
+        src_perms = json.load(f).get('permissions', {})
+    cur_perms = current.get('permissions', {})
+    for key in ('allow', 'deny'):
+        src_list = src_perms.get(key, [])
+        cur_list = cur_perms.get(key, [])
+        added = [p for p in src_list if p not in cur_list]
+        if added:
+            cur_list.extend(added)
+        cur_perms[key] = cur_list
+    current['permissions'] = cur_perms
+except:
+    pass
+with open(sys.argv[1], 'w') as f:
     json.dump(current, f, indent=2)
     f.write('\n')
-PYEOF
+" "$TARGET/settings.json" "$SCRIPT_DIR/settings.json"
                 echo "  Regenerated settings.json hooks from compose.yml"
             fi
         fi
@@ -1214,6 +1326,7 @@ PYEOF
         local target_dir_name=".${TARGET_CLI:-claude}"
         update_gitignore "$(dirname "$TARGET")" "$target_dir_name"
         [ "$TARGET_CLI" = "codex" ] && update_gitignore "$(dirname "$TARGET")" ".agents"
+        setup_templates "$(dirname "$TARGET")"
 
         if [ ! -f "$TARGET/git-workflow.conf" ]; then
             GIT_BRANCHING="direct-main"
@@ -1313,12 +1426,10 @@ do_snapshot() {
         git_push=$(grep '^AUTO_PUSH=' "$TARGET/git-workflow.conf" | cut -d= -f2)
     fi
 
-    # Read custom profile if applicable
+    # Read custom profile if applicable (use PROFILE_FILE from current run, never glob /tmp/)
     local profile_def="null"
-    local custom_profile
-    custom_profile=$(ls /tmp/cortexhawk-custom-*.json 2>/dev/null | head -1)
-    if [ -n "$custom_profile" ] && [ -f "$custom_profile" ]; then
-        profile_def=$(cat "$custom_profile")
+    if [ -n "$PROFILE_FILE" ] && [ -f "$PROFILE_FILE" ]; then
+        profile_def=$(cat "$PROFILE_FILE")
     fi
 
     # Build files checksums from manifest
@@ -1369,7 +1480,7 @@ do_snapshot() {
     [ -n "$git_workflow_content" ] && printf '    "git-workflow.conf": "%s",\n' "$git_workflow_content" >> "$snap_file"
     [ -n "$claude_md_content" ] && printf '    "CLAUDE.md": "%s",\n' "$claude_md_content" >> "$snap_file"
     # Remove trailing comma from last entry
-    sed -i '$ s/,$//' "$snap_file"
+    sed_inplace '$ s/,$//' "$snap_file"
     printf '  }\n' >> "$snap_file"
     printf '}\n' >> "$snap_file"
 
@@ -1875,15 +1986,15 @@ do_restore() {
     if command -v python3 >/dev/null 2>&1; then
         python3 -c "
 import json, sys
-with open('$snap_file') as f:
+with open(sys.argv[1]) as f:
     snap = json.load(f)
 settings = snap.get('settings')
 if settings is not None:
-    with open('$TARGET/settings.json', 'w') as f:
+    with open(sys.argv[2], 'w') as f:
         json.dump(settings, f, indent=2)
         f.write('\n')
     print('  Restored settings.json')
-"
+" "$snap_file" "$TARGET/settings.json"
     else
         echo "  Warning: python3 not found — settings.json not restored from snapshot"
     fi
@@ -1909,23 +2020,24 @@ if settings is not None:
     if grep -q '"file_contents"' "$snap_file" && command -v python3 >/dev/null 2>&1; then
         python3 -c "
 import json, base64, sys, os
-with open('$snap_file') as f:
+snap_file, target_dir = sys.argv[1], sys.argv[2]
+with open(snap_file) as f:
     snap = json.load(f)
 contents = snap.get('file_contents', {})
 for filename, b64data in contents.items():
     try:
         data = base64.b64decode(b64data).decode('utf-8')
         if filename == 'CLAUDE.md':
-            target_path = os.path.dirname('$TARGET') + '/CLAUDE.md'
+            target_path = os.path.dirname(target_dir) + '/CLAUDE.md'
         else:
-            target_path = '$TARGET/' + filename
+            target_path = target_dir + '/' + filename
         os.makedirs(os.path.dirname(target_path), exist_ok=True)
         with open(target_path, 'w') as f:
             f.write(data)
         print(f'  Restored {filename} (from file_contents)')
     except Exception as e:
         print(f'  Warning: could not restore {filename}: {e}', file=sys.stderr)
-"
+" "$snap_file" "$TARGET"
     fi
 
     # Write new manifest
@@ -2312,14 +2424,14 @@ do_list_hooks() {
     printf "  %-20s %-14s %-8s %s\n" "Name" "Event" "Status" "Description"
     printf "  %-20s %-14s %-8s %s\n" "----" "-----" "------" "-----------"
     # Parse hooks.json with python3 for reliable JSON handling
-    python3 << PYEOF
-import json
-with open("$hooks_json") as f:
+    python3 - "$hooks_json" "$compose_file" << 'PYEOF'
+import json, sys
+with open(sys.argv[1]) as f:
     data = json.load(f)
 # Read compose.yml to detect disabled hooks (commented out)
 disabled = set()
 try:
-    with open("$compose_file") as f:
+    with open(sys.argv[2]) as f:
         for line in f:
             stripped = line.strip()
             if stripped.startswith("# - "):
@@ -2368,14 +2480,14 @@ do_toggle_hook() {
             echo "Hook '$hook_name' is already disabled"
             return 0
         fi
-        sed -i "s/^      - ${hook_name}$/      # - ${hook_name}/" "$compose_file"
+        sed_inplace "s/^      - ${hook_name}$/      # - ${hook_name}/" "$compose_file"
         echo "Disabled hook: $hook_name"
     else
         if grep -q "^      - ${hook_name}$" "$compose_file"; then
             echo "Hook '$hook_name' is already enabled"
             return 0
         fi
-        sed -i "s/^      # - ${hook_name}$/      - ${hook_name}/" "$compose_file"
+        sed_inplace "s/^      # - ${hook_name}$/      - ${hook_name}/" "$compose_file"
         echo "Enabled hook: $hook_name"
     fi
     # Regenerate settings.json if target exists
@@ -2383,17 +2495,18 @@ do_toggle_hook() {
     if [ -d "$target" ] && [ -f "$target/settings.json" ]; then
         local hooks_json
         hooks_json=$(generate_hooks_config "$compose_file" ".claude/hooks")
-        if [ -n "$hooks_json" ]; then
-            python3 << PYEOF
-import json
-with open('$target/settings.json') as f:
+        if [ -n "$hooks_json" ] && [ "$hooks_json" != "{}" ]; then
+            echo "$hooks_json" | python3 -c "
+import json, sys
+hooks = json.load(sys.stdin)
+with open(sys.argv[1]) as f:
     settings = json.load(f)
-settings['hooks'] = json.loads('''$hooks_json''')
-with open('$target/settings.json', 'w') as f:
+settings['hooks'] = hooks
+with open(sys.argv[1], 'w') as f:
     json.dump(settings, f, indent=2)
     f.write('\n')
 print('  Regenerated settings.json')
-PYEOF
+" "$target/settings.json"
         fi
     fi
 }
@@ -2441,17 +2554,18 @@ _search_skillsmp() {
     fi
 
     # Parse JSON response with python3
-    python3 << PYEOF
+    python3 - "$tmp_response" "$keyword" << 'PYEOF'
 import json, sys
 try:
-    with open("$tmp_response") as f:
+    response_file, keyword = sys.argv[1], sys.argv[2]
+    with open(response_file) as f:
         data = json.load(f)
     container = data.get("data", {})
     skills = container.get("skills", [])
     pagination = container.get("pagination", {})
     total = pagination.get("total", len(skills))
     if not skills:
-        print("  No skills found matching '$keyword'")
+        print(f"  No skills found matching '{keyword}'")
         print("")
         print("  Try broader terms or check https://skillsmp.com")
         sys.exit(0)
@@ -2474,7 +2588,7 @@ try:
             if len(parts) >= 2:
                 print(f"  Install: ./install.sh --add-skill {parts[0]}/{parts[1]}")
                 break
-    print(f"  Browse all: https://skillsmp.com/?q=$keyword")
+    print(f"  Browse all: https://skillsmp.com/?q={keyword}")
 except Exception as e:
     print(f"  Error parsing response: {e}")
     print("  Falling back to local registry")
@@ -2841,26 +2955,78 @@ install_claude() {
     cp -r "$SCRIPT_DIR/modes/"* "$TARGET/modes/" 2>/dev/null || true
     cp -r "$SCRIPT_DIR/mcp/"* "$TARGET/mcp/" 2>/dev/null || true
 
+    local hooks_json
+    hooks_json=$(generate_hooks_config "$SCRIPT_DIR/hooks/compose.yml" ".claude/hooks")
     if [ ! -f "$TARGET/settings.json" ]; then
-        # Generate settings.json with hooks from compose.yml
-        local hooks_json
-        hooks_json=$(generate_hooks_config "$SCRIPT_DIR/hooks/compose.yml" ".claude/hooks")
+        # Fresh install: generate settings.json from scratch
         if [ -n "$hooks_json" ] && [ "$hooks_json" != "{}" ]; then
-            # Build settings.json with generated hooks
-            python3 -c "
-import json
-permissions = $(cat "$SCRIPT_DIR/settings.json" | python3 -c "import sys,json; d=json.load(sys.stdin); print(json.dumps(d.get('permissions',{})))")
-hooks = $hooks_json
-with open('$TARGET/settings.json', 'w') as f:
+            echo "$hooks_json" | python3 -c "
+import json, sys
+hooks = json.load(sys.stdin)
+with open(sys.argv[1]) as f:
+    permissions = json.load(f).get('permissions', {})
+with open(sys.argv[2], 'w') as f:
     json.dump({'permissions': permissions, 'hooks': hooks}, f, indent=2)
     f.write('\n')
-"
+" "$SCRIPT_DIR/settings.json" "$TARGET/settings.json"
             echo "  Generated settings.json from hooks/compose.yml"
         else
             cp "$SCRIPT_DIR/settings.json" "$TARGET/settings.json"
         fi
     else
-        echo "settings.json already exists — skipping (check manually for updates)"
+        # Merge: preserve user customizations, add new hooks + permissions
+        python3 -c "
+import json, sys, shutil, os
+
+raw = sys.stdin.read().strip()
+hooks = json.loads(raw) if raw else {}
+
+# Load current settings (tolerate corrupted JSON)
+try:
+    with open(sys.argv[1]) as f:
+        current = json.load(f)
+except Exception:
+    backup = sys.argv[1] + '.bak'
+    if os.path.isfile(sys.argv[1]):
+        shutil.copy2(sys.argv[1], backup)
+        print(f'  Warning: settings.json corrupted — backed up to {os.path.basename(backup)}', file=sys.stderr)
+    current = {}
+
+try:
+    with open(sys.argv[2]) as f:
+        source = json.load(f)
+except Exception:
+    source = {}
+
+changes = []
+
+# Merge hooks (regenerate from compose.yml)
+if hooks and hooks != {}:
+    current['hooks'] = hooks
+    changes.append('hooks regenerated')
+
+# Merge permissions (union: keep user additions + add new from source)
+src_perms = source.get('permissions', {})
+cur_perms = current.get('permissions', {})
+for key in ('allow', 'deny'):
+    src_list = src_perms.get(key, [])
+    cur_list = cur_perms.get(key, [])
+    added = [p for p in src_list if p not in cur_list]
+    if added:
+        cur_list.extend(added)
+        changes.append(f'{len(added)} new {key} permission(s)')
+    cur_perms[key] = cur_list
+current['permissions'] = cur_perms
+
+with open(sys.argv[1], 'w') as f:
+    json.dump(current, f, indent=2)
+    f.write('\n')
+
+if changes:
+    print('  Merged settings.json: ' + ', '.join(changes))
+else:
+    print('  settings.json up to date — no merge needed')
+" "$TARGET/settings.json" "$SCRIPT_DIR/settings.json" <<< "${hooks_json:-}"
     fi
 
     PROJECT_ROOT="$(dirname "$TARGET")"
@@ -2897,11 +3063,12 @@ with open('$TARGET/settings.json', 'w') as f:
 
     run_audit "$(dirname "$TARGET")"
     update_gitignore "$(dirname "$TARGET")" ".claude"
+    setup_templates "$(dirname "$TARGET")"
 
     echo ""
     echo "CortexHawk installed successfully for Claude Code!"
     echo ""
-    echo "  32 commands | 20 agents | 36 skills | 9 hooks | 7 modes"
+    echo "  33 commands | 20 agents | 36 skills | 9 hooks | 7 modes"
     echo ""
     do_quickstart
     echo ""
@@ -3749,7 +3916,6 @@ else
             install_codex
             ;;
         auto)
-            local detected
             detected=$(detect_installed_clis)
             if [ -z "$detected" ]; then
                 echo "Error: no supported CLI found (claude, kimi, codex)"
@@ -3758,7 +3924,7 @@ else
             fi
             echo "Auto-detected CLIs: $detected"
             echo ""
-            local auto_count=0
+            auto_count=0
             for cli in $detected; do
                 [ $auto_count -gt 0 ] && echo "" && echo "---" && echo ""
                 case "$cli" in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortexhawk",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "Open-source development toolkit for Claude Code — optimized agents, skills, commands, hooks, and modes",
   "bin": {
     "cortexhawk": "./cortexhawk"

package/scripts/autodetect-profile.sh

@@ -57,7 +57,11 @@ $SKILL_JSON
   ]
 }
 EOF
-SKILL_COUNT=$(echo "$SKILLS" | tr ',' '\n' | wc -l | tr -d ' ')
+if [ -z "$SKILLS" ]; then
+    SKILL_COUNT=0
+else
+    SKILL_COUNT=$(echo "$SKILLS" | tr ',' '\n' | wc -l | tr -d ' ')
+fi
 
 # --- Stack snapshot ---
 if [ -d "docs/.context" ]; then

package/scripts/interactive-init.sh

@@ -20,11 +20,13 @@ echo "  1) Claude Code (default) — fully supported"
 echo "  2) Kimi CLI (experimental)"
 echo "  3) Codex CLI (experimental)"
 echo "  4) All (install for all CLIs simultaneously)"
-read -r -p "Choice [1-4] (default: 1): " target_choice
+echo "  5) Auto-detect (install for all CLIs found on system)"
+read -r -p "Choice [1-5] (default: 1): " target_choice
 case "$target_choice" in
     2) TARGET_CLI="kimi" ;;
     3) TARGET_CLI="codex" ;;
     4) TARGET_CLI="all" ;;
+    5) TARGET_CLI="auto" ;;
     *) TARGET_CLI="claude" ;;
 esac
 green "  → $TARGET_CLI"
@@ -32,14 +34,19 @@ echo ""
 
 # --- Step 2: Scope ---
 bold "2. Install Scope"
-echo "  1) Local project — install in current directory (default)"
-echo "  2) Global — install in ~/.${TARGET_CLI}/ (shared across all projects)"
-read -r -p "Choice [1-2] (default: 1): " scope_choice
-case "$scope_choice" in
-    2) GLOBAL=true ;;
-    *) GLOBAL=false ;;
-esac
-green "  → $([ "$GLOBAL" = true ] && echo "global" || echo "local")"
+if [ "$TARGET_CLI" = "all" ] || [ "$TARGET_CLI" = "auto" ]; then
+    GLOBAL=false
+    green "  → local (always local for multi-target install)"
+else
+    echo "  1) Local project — install in current directory (default)"
+    echo "  2) Global — install in ~/.${TARGET_CLI}/ (shared across all projects)"
+    read -r -p "Choice [1-2] (default: 1): " scope_choice
+    case "$scope_choice" in
+        2) GLOBAL=true ;;
+        *) GLOBAL=false ;;
+    esac
+    green "  → $([ "$GLOBAL" = true ] && echo "global" || echo "local")"
+fi
 echo ""
 
 # --- Step 3: Skills ---
@@ -122,7 +129,7 @@ echo ""
 read -r -p "  API key (press Enter to skip): " SKILLSMP_KEY
 if [ -n "$SKILLSMP_KEY" ]; then
     if [ -f ".env" ] && grep -q '^SKILLSMP_API_KEY=' .env 2>/dev/null; then
-        sed -i "s/^SKILLSMP_API_KEY=.*/SKILLSMP_API_KEY=$SKILLSMP_KEY/" .env
+        sed_inplace "s/^SKILLSMP_API_KEY=.*/SKILLSMP_API_KEY=$SKILLSMP_KEY/" .env
     else
         echo "SKILLSMP_API_KEY=$SKILLSMP_KEY" >> .env
     fi

package/scripts/refresh-context.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# refresh-context.sh — Regenerate docs/.context/_shared.md mid-session
+# Called by agents after modifying backlog, completing tasks, or committing code
+
+[ -d "docs/.context" ] && [ ! -L "docs/.context" ] || exit 0
+
+SHARED="docs/.context/_shared.md"
+
+echo "# Shared Context" > "$SHARED"
+echo "" >> "$SHARED"
+echo "_Auto-generated at $(date '+%Y-%m-%d %H:%M'). Last refresh: $(date '+%H:%M:%S')._" >> "$SHARED"
+echo "" >> "$SHARED"
+
+# Backlog summary
+if [ -f "docs/backlog.md" ]; then
+    ACTIVE=$(grep -c '| todo |' docs/backlog.md 2>/dev/null || true)
+    : "${ACTIVE:=0}"
+    DEFERRED=$(grep -c '| deferred |' docs/backlog.md 2>/dev/null || true)
+    : "${DEFERRED:=0}"
+    DONE=$(grep -c '| done |' docs/backlog.md 2>/dev/null || true)
+    : "${DONE:=0}"
+    echo "## Backlog" >> "$SHARED"
+    echo "- Active: $ACTIVE | Deferred: $DEFERRED | Done: $DONE" >> "$SHARED"
+    grep '| todo |' docs/backlog.md >> "$SHARED" 2>/dev/null || true
+    echo "" >> "$SHARED"
+fi
+
+# Recent commits
+if git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
+    echo "## Recent Commits" >> "$SHARED"
+    git log --oneline -5 2>/dev/null >> "$SHARED" || true
+    echo "" >> "$SHARED"
+fi
+
+# User context
+if [ -f "docs/.context/_user.md" ]; then
+    cat "docs/.context/_user.md" >> "$SHARED"
+    echo "" >> "$SHARED"
+fi
+
+# Active warnings
+echo "## Warnings" >> "$SHARED"
+WARNINGS=0
+if [ -f ".env.example" ] && [ ! -f ".env" ]; then
+    echo "- .env missing — copy from .env.example" >> "$SHARED"
+    WARNINGS=$((WARNINGS + 1))
+fi
+if [ "$WARNINGS" -eq 0 ]; then
+    echo "- None" >> "$SHARED"
+fi
+echo "" >> "$SHARED"