cortexhawk 3.3.2 → 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortexhawk",
-  "version": "3.3.2",
+  "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