cortexhawk 3.3.1 → 3.3.2

package/README.md

@@ -2,16 +2,28 @@
 
 [![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.2.0-green.svg?style=flat-square)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.3.1-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%2033%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%2035%20commands%20%7C%2011%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.2
+### What's New in v3.3
+
+- **Gitflow strategy** — full gitflow support in `/cleanup`: dual-target merge detection (feat→develop, release/hotfix→main), conditional branch protection, auto-resync `develop ← main`
+- **`/cleanup` command** — unified post-merge cleanup with 4 strategies (direct-main, feature-branches, dev-branch, gitflow), `--dry-run` preview, native `post-merge` hook opt-in
+- **`/review-pr` command** — fetch, triage, and fix PR review comments in batch (one commit, one notification)
+- **`lint-guard` hook** — auto-detects formatters/linters on staged files; auto-fix for prettier/black/gofmt/rustfmt, check-only for eslint/flake8/mypy; parallel execution, pre-commit delegation
+- **`install.sh` modularized** — extracted 5 modules into `scripts/` (4114 → 3168 lines, -23%)
+- **MCP configs hardened** — all packages pinned to exact versions, puppeteer package name fixed
+- **Security fixes** — path traversal guards in codex-dispatcher and restore, python3 availability guards
+- **10+ bug fixes** — see [CHANGELOG.md](CHANGELOG.md) for full details
+
+<details>
+<summary>v3.2 changes</summary>
 
 - **`/commit` command** — lightweight conventional commit + push without review or PR (use `/ship` for full workflow)
 - **`--version` flag** — standard CLI version display
@@ -21,6 +33,8 @@ CortexHawk provides a modular collection of optimized agents, skills, commands,
 - **`--init` wizard** — "Auto-detect" target option, improved multi-target support
 - **15+ bug fixes** — see [CHANGELOG.md](CHANGELOG.md) for full details
 
+</details>
+
 <details>
 <summary>v3.1 changes</summary>
 
@@ -116,7 +130,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 (33)
+### Commands (35)
 
 Slash commands for common workflows.
 
@@ -126,8 +140,10 @@ Slash commands for common workflows.
 | `/build` | Implement code from plan or description |
 | `/test` | Generate and run tests |
 | `/review` | Multi-agent code review |
+| `/review-pr` | Fetch, triage, and fix PR review comments in batch |
 | `/ship` | Commit + PR pipeline |
 | `/commit` | Lightweight commit + push (no review, no PR) |
+| `/cleanup` | Post-merge branch cleanup (auto-detects strategy) |
 | `/debug` | Debug and fix issues |
 | `/scan` | Full security audit |
 | `/check` | Pre-commit quality gate (lint + test + scan + review → GO/NO-GO) |
@@ -270,7 +286,7 @@ Create custom agents that inherit from base agents with rule/style overrides:
 
 Personas use `extends:` frontmatter and are auto-copied to `.claude/agents/` on install/update.
 
-### Hooks (9)
+### Hooks (11)
 
 Automatic lifecycle hooks that run during Claude Code sessions.
 
@@ -279,12 +295,14 @@ Automatic lifecycle hooks that run during Claude Code sessions.
 | `file-guard` | PreToolUse | Blocks access to .env, secrets, credentials |
 | `branch-guard` | PreToolUse | Prevents direct push to protected branches |
 | `commit-guard` | PreToolUse | Validates conventional commits, checks staged secrets |
+| `lint-guard` | PreToolUse | Auto-detects formatters/linters on staged files; auto-fix or check-only |
 | `self-review` | PostToolUse | Checks for TODO/FIXME, secrets, debug artifacts |
 | `dependency-check` | PostToolUse | Alerts when dependency files are modified |
 | `test-reminder` | PostToolUse | Reminds to update tests for modified source files |
 | `agent-analytics` | PostToolUse | Tracks agent invocations, tokens, timestamps to `docs/.metrics/` |
 | `session-telemetry` | SessionEnd | Generates session summary (agents, tokens, duration, files) |
 | `session-start` | SessionStart | Project context injection, daily stats display |
+| `post-merge` | git post-merge | Auto-runs cleanup after `git merge` (opt-in native git hook) |
 
 Hook pipelines are configured in `hooks/compose.yml`. Manage individual hooks:
 
@@ -327,9 +345,9 @@ 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 (33) | `.claude/commands/*.md` → `/plan` | Skills (`/skill:cmd-*`) | Skills (`$cmd-*`) |
+| Commands (35) | `.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) |
+| Hooks (11) | `settings.json` (automatic) | Skills (`/skill:hook-*`, manual) | Dispatcher (partial) |
 | Modes (7) | `.claude/modes/` (native) | Skills (`/skill:modes/*`) | Skills (`$mode-*`) |
 | MCP | `settings.json` | Optional (`MCP-SETUP.md`) | `config.toml` |
 

package/install.sh

@@ -740,9 +740,11 @@ setup_templates() {
     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"
+        if [ -f "$SCRIPT_DIR/templates/github/PULL_REQUEST_TEMPLATE.md" ]; then
+            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
     fi
 
     # Commit template
@@ -757,8 +759,10 @@ setup_templates() {
     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"
+        if [ -f "$SCRIPT_DIR/templates/github/gitmessage" ]; then
+            cp "$SCRIPT_DIR/templates/github/gitmessage" "$project_root/.gitmessage"
+            green "  Commit template created: .gitmessage"
+        fi
     fi
 }
 

package/package.json

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

package/templates/AGENT.md

@@ -0,0 +1,19 @@
+---
+name: [agent-name]
+description: [One sentence — what this agent does and when to activate it]
+---
+
+# [Agent Name] Agent
+
+You are a [role description].
+
+## Process
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Output Format
+[What the agent should produce]
+
+## Rules
+[Constraints and guidelines — 5-7 items max]

package/templates/CLAUDE.md.template

@@ -0,0 +1,41 @@
+# [Project Name]
+
+[One-line description of what the project does]
+
+## Tech Stack
+- **Language**: [e.g., TypeScript, Python]
+- **Framework**: [e.g., Next.js, FastAPI]
+- **Database**: [e.g., PostgreSQL, MongoDB]
+- **Testing**: [e.g., vitest, pytest]
+
+## Structure
+```
+src/
+├── [main directories]
+tests/
+```
+
+## Conventions
+- **Naming**: [files: kebab-case, functions: camelCase, classes: PascalCase]
+- **Commits**: `type(scope): description` (feat, fix, docs, refactor, test, chore)
+- **Branches**: `feature/description`, `fix/description`, `hotfix/description`
+
+## Commands
+- `[dev command]` — Start dev server
+- `[test command]` — Run tests
+- `[build command]` — Build for production
+- `[lint command]` — Run linter
+
+## Architecture Decisions
+- [Key decision 1 and why]
+- [Key decision 2 and why]
+
+## Security
+- No hardcoded secrets — use environment variables
+- Input validation on all endpoints
+- Auth required on all protected routes
+
+## Testing
+- Unit tests for business logic
+- Integration tests for API endpoints
+- Coverage target: [80%]

package/templates/COMMAND.md

@@ -0,0 +1,14 @@
+# /[command-name]
+
+## Purpose
+[One sentence — what this command does]
+
+---
+
+Activate the **[agent-name]** agent. Target: `$ARGUMENTS`
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+[Any additional constraints or output format requirements]

package/templates/ORCHESTRATION.md

@@ -0,0 +1,79 @@
+# Agent Orchestration Patterns
+
+## Sequential Pipeline
+
+Run agents one after another, each receiving the previous output.
+
+```
+/plan → planner → plan.md
+/build → implementer → code changes (follows plan.md)
+/test → tester → test results
+/review → reviewer → review report
+/ship → git-manager + reviewer → commit + PR
+```
+
+**Use when**: Feature development from scratch.
+
+## Parallel Execution
+
+Run independent agents simultaneously to save time.
+
+```
+┌─ tester (unit tests)
+plan → implementer ─┤
+                    └─ tester (integration tests)
+```
+
+**Use when**: Test generation can happen in parallel for different scopes.
+
+## Gate Pattern
+
+Agent B only runs if Agent A passes.
+
+```
+reviewer → [pass?] → git-manager → [commit]
+                  → [fail?] → STOP, report issues
+```
+
+**Use when**: `/ship` — don't commit if review finds critical issues.
+
+## Loop Pattern
+
+Repeat until quality gate passes.
+
+```
+implementer → tester → [tests pass?] → done
+                     → [tests fail?] → implementer (fix) → tester → ...
+```
+
+**Use when**: `/tdd` — red-green-refactor cycle.
+
+## Escalation Pattern
+
+Start simple, bring in specialists when needed.
+
+```
+debugger → [found root cause?] → fix
+        → [needs architecture change?] → architect → planner → implementer
+```
+
+**Use when**: `/debug` — simple bugs stay with debugger, complex ones escalate.
+
+## Multi-Agent Review
+
+Multiple agents review the same code from different angles.
+
+```
+       ┌─ reviewer (correctness)
+code ──┼─ security-auditor (security)
+       └─ code-simplifier (complexity)
+```
+
+**Use when**: Pre-release quality gate or critical code paths.
+
+## Rules
+- Each agent receives clear input and produces structured output
+- Gate pattern prevents broken code from progressing
+- Parallel agents must not modify the same files
+- Always define a failure path — what happens when an agent flags issues
+- Keep pipelines ≤5 steps — longer pipelines are harder to debug

package/templates/PERSONA.md

@@ -0,0 +1,17 @@
+---
+name: [persona-name]
+extends: [base-agent-name]
+description: [One sentence — how this persona differs from the base agent]
+---
+
+# [Persona Name]
+
+Custom agent persona extending **[base-agent-name]**.
+
+## Overrides
+
+[Rules, style, or behavior that override or extend the base agent]
+
+## Rules
+
+[Additional rules specific to this persona — these are ADDED to the base agent's rules]

package/templates/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: [skill-name]
+description: [One sentence — when should Claude use this skill?]
+detect: [base | <file> | <file>:<pattern> | dir:<path> — omit if not auto-detectable]
+requires: [category/skill-name — space-separated list of required skills, omit if none]
+---
+
+# [Skill Name]
+
+## [Core Instructions]
+[What Claude should do when this skill is active]
+
+## Examples
+[Concrete code/usage examples]
+
+## Rules
+[Do's and don'ts — keep it to 5-7 items max]

package/templates/github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## Summary
+<!-- What does this PR do and why? -->
+
+## Type
+<!-- Check one -->
+- [ ] Feature
+- [ ] Bug fix
+- [ ] Refactor
+- [ ] Docs
+- [ ] Chore
+
+## Changes
+-
+
+## Test Plan
+- [ ]
+
+## Checklist
+- [ ] Tests pass
+- [ ] No secrets or .env committed
+- [ ] Docs updated (if applicable)
+- [ ] No breaking changes (or documented below)
+
+## Related
+<!-- Link issues, backlog items, or conversations -->
+<!-- Examples: Closes #123 | Backlog #119 | N/A -->

package/templates/github/gitmessage

@@ -0,0 +1,10 @@
+
+# type(scope): subject
+#
+# Types: feat, fix, docs, style, refactor, test, chore, perf, security
+# Scope: optional module/component name
+# Subject: imperative mood, lowercase, no period, max 72 chars
+#
+# Body: explain WHY, not WHAT (the diff shows the what)
+#
+# Footer: BREAKING CHANGE: description | Closes #123 | Backlog #N