cortexhawk 3.3.1 → 3.4.0

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to CortexHawk are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/)
 
+## [3.4.0] - 2026-02-21
+
+### Added
+- `/gitignore` command: analyses `git status`, detects project stack, proposes missing `.gitignore` patterns grouped by category (#155)
+- Enhanced session-start: commands grouped into 6 categories (Develop, Quality, DevOps, Research, Project, Setup) + contextual tip for new/first-time users (#156)
+- `/quickstart` command: detects project state (empty, first-time, returning) and guides user to their first productive action with stack-aware recommendations (#157)
+- `getting-started` skill: golden paths per stack (Node, Python, Rust, Go, empty) + 4-tier command progression for agents to consult on new projects (#158)
+- `onboarding` chain preset: `map,plan,build,test,review` (auto-swaps `map` for `bootstrap` on empty projects) (#159)
+
 ## [3.3.1] - 2026-02-20
 
 ### Added

package/CLAUDE.md

@@ -6,9 +6,9 @@ Open-source development toolkit for Claude Code — optimized agents, skills, co
 
 ```
 agents/       — 20 specialized AI agents
-commands/     — 35 slash commands
+commands/     — 37 slash commands
 scripts/      — Validation and post-install audit scripts
-skills/       — 36 domain-specific knowledge modules
+skills/       — 37 domain-specific knowledge modules
 hooks/        — 11 lifecycle hooks
 modes/        — 7 behavioral presets
 profiles/     — 3 install profiles (fullstack, api, data)
@@ -49,7 +49,7 @@ Custom agents in `.cortexhawk-agents/` at project root. Each `.md` file uses `ex
 
 ## Commands
 
-`/plan` `/build` `/test` `/review` `/review-pr` `/ship` `/commit` `/cleanup` `/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`
+`/quickstart` `/plan` `/build` `/test` `/review` `/review-pr` `/ship` `/commit` `/cleanup` `/gitignore` `/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
 
@@ -61,7 +61,7 @@ Custom agents in `.cortexhawk-agents/` at project root. Each `.md` file uses `ex
 - **Meta**: mcp-builder, skill-creator
 - **Frameworks**: api-design, fastapi, nextjs, react, sveltekit, tailwindcss, typescript, python
 - **Optimization**: performance
-- **Workflow**: commit, confidence-check, pr-review-comments
+- **Workflow**: commit, confidence-check, getting-started, pr-review-comments
 
 ## Modes
 

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/commands/chain.md

@@ -7,13 +7,13 @@ description: Sequential agent execution with context passing via docs/chains/.
 
 Execute a declared sequence of agents with automatic context passing. Topic: `$ARGUMENTS`
 
-**Built-in presets**: `default` = plan,build,test,review | `security` = scan,review | `ship` = test,review,ship
+**Built-in presets**: `default` = plan,build,test,review | `security` = scan,review | `ship` = test,review,ship | `onboarding` = map,plan,build,test,review (if project empty: bootstrap replaces map)
 
 **Custom presets**: Define in `.cortexhawk-chains.yml` at project root — custom presets override built-in presets with the same name
 
 **Flags**: `--gate` = pause between steps | `--copy` = physical copy to plans/ | `--replay <slug>` = re-run a previous chain | `--browse` = list all available presets + recent chains
 
-**Mapping**: plan=planner, build=implementer, test=tester, review=reviewer, scan=security-auditor, debug=debugger, doc=docs-manager, ship=git-manager, refactor=code-simplifier, research=researcher
+**Mapping**: plan=planner, build=implementer, test=tester, review=reviewer, scan=security-auditor, debug=debugger, doc=docs-manager, ship=git-manager, refactor=code-simplifier, research=researcher, map=codebase-mapper, bootstrap=architect
 
 0. Read `_shared.md` for project context
 1. If `--replay <slug>`: find most recent `docs/chains/*-<slug>/SUMMARY.md`, extract sequence from "## Sequence" line (e.g., `plan → build → test → review`), use as agent list with fresh context. Error if slug not found.
@@ -41,7 +41,7 @@ When detected in a step's output:
 ## Browse mode (`--browse`)
 
 List all available chains from 3 sources:
-1. **Built-in presets** — default, security, ship (table: name, sequence, description)
+1. **Built-in presets** — default, security, ship, onboarding (table: name, sequence, description)
 2. **Custom presets** — read `.cortexhawk-chains.yml` if present (table: name, sequence, description, gate)
 3. **Recent chains** — scan `docs/chains/*/SUMMARY.md`, extract date/slug/sequence/result (table: date, slug, sequence, status — last 10)
 

package/commands/gitignore.md

@@ -0,0 +1,28 @@
+---
+name: gitignore
+description: Analyze git status and update .gitignore with missing patterns.
+---
+
+# /gitignore
+
+Activate the **git-manager** agent. Scope: `$ARGUMENTS`
+
+1. Run `git status --porcelain` to list untracked files
+2. Detect project stack from manifest files (package.json, requirements.txt, Cargo.toml, go.mod, *.csproj, etc.)
+3. Compare untracked files against known patterns for the detected stack:
+   - **Node**: node_modules/, dist/, build/, .next/, coverage/, *.tsbuildinfo
+   - **Python**: __pycache__/, *.pyc, .venv/, .egg-info/, .mypy_cache/
+   - **Rust**: target/
+   - **Go**: vendor/ (if not committed)
+   - **General**: .DS_Store, *.log, .env, .env.local, *.swp, thumbs.db
+4. Read existing `.gitignore` — skip patterns already present
+5. Present proposed additions grouped by category, ask for confirmation
+6. Append confirmed patterns to `.gitignore` (preserve existing structure)
+
+## Rules
+
+- Never auto-commit — user decides when to commit
+- If `.gitignore` doesn't exist, create it with detected patterns
+- If no untracked files need ignoring, report "`.gitignore` is up to date" and stop
+- Respect existing sections/comments in `.gitignore` — append, don't rewrite
+- If `$ARGUMENTS` is a path, scope analysis to that directory only

package/commands/quickstart.md

@@ -0,0 +1,44 @@
+---
+name: quickstart
+description: Detect project state and guide the user to their first productive action.
+---
+
+# /quickstart
+
+Analyze the current project and guide the user to their first productive CortexHawk action.
+
+## Detection
+
+1. Count non-hidden files in current directory
+2. Detect project markers: package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, *.csproj
+3. Detect stack: language, framework, test runner, CI config
+4. Check for CortexHawk artifacts: docs/plans/, docs/chains/, docs/brainstorms/
+
+## Scenarios
+
+**Empty project** (< 3 non-hidden files, no project markers):
+- "This looks like a new project."
+- Recommend: `/bootstrap` to create project structure, or `/bootstrap --smart` to auto-detect goals
+- Show golden path: `/bootstrap` → `/plan` → `/build` → `/test` → `/review`
+
+**Existing project, first CortexHawk session** (project markers exist, no CortexHawk artifacts):
+- Display detected stack (language, framework, test runner)
+- List the 5 most relevant commands for this stack with 1-line descriptions
+- Recommend: `/plan <next feature>` to start, or `/map` to understand the codebase first
+- Mention: `/scan` for a security audit, `/pulse` for project health
+
+**Returning user** (CortexHawk artifacts exist):
+- Show last plan or chain if available, backlog summary (active/done counts)
+- Recommend: `/pulse` for health dashboard, `/backlog` to pick next task, `/task #N` to execute
+
+**Specific question** ($ARGUMENTS is a question about CortexHawk):
+- Map the question to the relevant command, agent, or skill
+- Show usage example and what it does
+
+## Rules
+
+- Never generate code — only recommend commands
+- Max 20 lines of output — conciseness over completeness
+- Always show the golden path for new projects: bootstrap → plan → build → test → review
+- If in doubt, recommend `/plan` — it is the safest starting point
+- If $ARGUMENTS is empty, detect scenario automatically

package/hooks/session-start.sh

@@ -132,4 +132,23 @@ if [ -d "$SKILL_DIR" ]; then
 fi
 
 echo ""
-echo "Commands: /plan /build /test /review /ship /commit /cleanup /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"
+echo "Commands:"
+echo "  Develop    /quickstart /plan /build /test /review /ship /commit /debug"
+echo "  Quality    /scan /check /tdd /refactor /simplify /optimize"
+echo "  DevOps     /deploy /ci /monitor /cleanup /migrate /gitignore"
+echo "  Research   /research /brainstorm /learn /map"
+echo "  Project    /backlog /pulse /task /chain /journal /changelog"
+echo "  Setup      /bootstrap /context /export /upgrade /doc /api-gen /review-pr"
+
+# Contextual tip for new/first-time users
+FILE_COUNT=$(find . -maxdepth 1 -not -name '.*' -not -name 'node_modules' -type f 2>/dev/null | wc -l | tr -d ' ')
+HAS_ARTIFACTS=false
+{ [ -d "docs/plans" ] || [ -d "docs/chains" ]; } && HAS_ARTIFACTS=true
+
+if [ "$FILE_COUNT" -lt 3 ]; then
+    echo ""
+    echo "Tip: New project? Run /quickstart or /bootstrap"
+elif [ "$HAS_ARTIFACTS" = false ]; then
+    echo ""
+    echo "Tip: First time? Run /quickstart for a guided start"
+fi

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.4.0",
   "description": "Open-source development toolkit for Claude Code — optimized agents, skills, commands, hooks, and modes",
   "bin": {
     "cortexhawk": "./cortexhawk"

package/scripts/install-claude.sh

@@ -171,7 +171,7 @@ else:
     echo ""
     echo "CortexHawk installed successfully for Claude Code!"
     echo ""
-    echo "  35 commands | 20 agents | 36 skills | 11 hooks | 7 modes"
+    echo "  37 commands | 20 agents | 37 skills | 11 hooks | 7 modes"
     echo ""
     do_quickstart
     echo ""

package/skills/workflow/getting-started/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: getting-started
+description: Golden paths and command progression for new CortexHawk users.
+detect: base
+---
+
+# Getting Started
+
+## Golden Paths
+
+### Empty project
+1. `/bootstrap` → create structure, configs, CI
+2. `/plan <first feature>` → task breakdown
+3. `/build` → implement the plan
+4. `/test` → generate test suite
+5. `/review` → quality check before commit
+
+### Node.js / TypeScript
+1. `/map` → understand codebase structure
+2. `/scan` → security audit (npm audit + OWASP)
+3. `/plan <feature>` → plan next feature
+4. `/build` → implement
+5. `/test` → add/update tests with Jest/Vitest
+
+### Python
+1. `/map` → understand codebase
+2. `/check` → code quality (flake8, mypy)
+3. `/plan <feature>` → plan next feature
+4. `/build` → implement
+5. `/tdd` → test-driven with pytest
+
+### Rust / Go
+1. `/map` → understand codebase
+2. `/scan` → dependency audit (cargo audit / govulncheck)
+3. `/plan <feature>` → plan next feature
+4. `/build` → implement
+5. `/test` → add tests
+
+## Command Tiers
+
+| Tier | Commands | When |
+|---|---|---|
+| Essential | `/plan` `/build` `/test` `/review` `/commit` | Every session |
+| Quality | `/scan` `/check` `/refactor` `/tdd` `/debug` `/simplify` | Before shipping |
+| Workflow | `/chain` `/task` `/backlog` `/pulse` `/ship` `/cleanup` | Team/project mgmt |
+| Advanced | `/brainstorm` `/research` `/optimize` `/migrate` `/deploy` `/ci` | Specialized needs |
+
+## Stack Detection
+
+| Marker | Stack |
+|---|---|
+| `package.json` | Node.js |
+| `tsconfig.json` | TypeScript |
+| `next.config.*` | Next.js |
+| `svelte.config.*` | SvelteKit |
+| `tailwind.config.*` | Tailwind CSS |
+| `requirements.txt` / `pyproject.toml` | Python |
+| `Cargo.toml` | Rust |
+| `go.mod` | Go |
+| `Gemfile` | Ruby |
+| `*.csproj` | .NET |
+
+## Rules
+- When project has no `docs/plans/` or `docs/chains/`, agent should mention `/quickstart`
+- Recommend `/plan` as default safe starting point for any stack
+- Never skip the test step — always include `/test` or `/tdd` in recommendations

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