cortexhawk 3.1.0

package/commands/plan.md

@@ -0,0 +1,17 @@
+---
+name: plan
+description: Create an implementation plan for a feature or task.
+---
+
+# /plan
+
+Activate the **planner** agent. Analyze the codebase context and the user's request: `$ARGUMENTS`
+
+1. Scan relevant files to understand current architecture
+2. Break the work into 2-5 minute tasks
+3. Output a structured plan with tasks, files, acceptance criteria, test strategy, and rollback steps
+4. If scope is ambiguous, ask ONE question before proceeding
+
+Keep the plan actionable — every task should be something `/build` can execute directly.
+
+Save output to `docs/plans/YYYY-MM-DD-[feature].md`

package/commands/pulse.md

@@ -0,0 +1,46 @@
+---
+name: pulse
+description: Project health dashboard — code quality metrics at a glance.
+---
+
+# /pulse
+
+Activate the **project-manager** agent in health-check mode. Scope: `$ARGUMENTS`
+
+**Flags**: `--history Nd` = show metrics trends over N days (e.g., `--history 7d`, `--history 30d`)
+
+## Standard mode (no flag)
+
+1. **Git health** — branch, uncommitted changes, last commit age, unmerged branches
+2. **Code quality** — count `TODO`, `FIXME`, `HACK` markers across source files
+3. **Dependencies** — run `npm audit` / `pip-audit` / `cargo audit` if lock file exists; check `requires:` in installed skills and report unsatisfied dependencies
+4. **Backlog** — read `docs/backlog.md` and summarize active/deferred/done counts
+5. **Tests** — run test suite if configured, report pass/fail and coverage if available
+6. **Agent analytics** — read `docs/.metrics/YYYY-MM-DD.jsonl` for today:
+   - Count agent invocations (lines without `"type":"session"`)
+   - List unique agents with invocation count per agent
+   - Sum `estimated_tokens` across all invocations
+   - If a `"type":"session"` entry exists, show duration and files modified
+7. Output single dashboard table
+
+## History mode (`--history Nd`)
+
+Read all `docs/.metrics/*.jsonl` files within the requested period. For each day:
+- Count agent invocations and sum `estimated_tokens` from non-session entries
+- Extract `duration_seconds`, `files_modified` from `"type":"session"` entries
+
+Output:
+
+```
+# Metrics Trends — [N] days
+
+| Day        | Invocations | Tokens  | Sessions | Avg Duration |
+|------------|-------------|---------|----------|--------------|
+| YYYY-MM-DD | [count]     | [total] | [count]  | [minutes]    |
+
+Top agents: [agent1] ×N, [agent2] ×N, ...
+Total: [invocations] invocations, [tokens] tokens, [sessions] sessions
+Avg: [tokens/day] tokens/day, [duration] min/session
+```
+
+If scope is specified, limit checks to those files/directories.

package/commands/refactor.md

@@ -0,0 +1,16 @@
+---
+name: refactor
+description: Improve code structure without changing behavior.
+---
+
+# /refactor
+
+Activate the **reviewer** agent for analysis, then the **implementer** agent for changes. Refactor: `$ARGUMENTS`
+
+1. Analyze current code for: duplication, complexity, coupling, naming, dead code
+2. Propose specific refactoring steps (extract function, rename, simplify conditional, etc.)
+3. Confirm approach with user before applying
+4. Apply changes incrementally — verify tests pass after each step
+5. Never change behavior — only structure
+
+If no tests exist for the target code, generate them FIRST as a safety net.

package/commands/research.md

@@ -0,0 +1,18 @@
+---
+name: research
+description: Research technologies, libraries, or approaches with evidence-based comparison.
+---
+
+# /research
+
+Activate the **researcher** agent. Research: `$ARGUMENTS`
+
+1. Define evaluation criteria relevant to the project
+2. Identify 3-5 candidates (include at least one underdog)
+3. Compare with evidence — benchmarks, docs, GitHub stats, real-world adoption
+4. Present comparison matrix
+5. Make a recommendation with reasoning, or state there's no clear winner
+
+Output a structured research report with sources.
+
+Save output to `docs/research/YYYY-MM-DD-[topic].md`

package/commands/review.md

@@ -0,0 +1,16 @@
+---
+name: review
+description: Multi-pass code review covering correctness, security, performance, and maintainability.
+---
+
+# /review
+
+Activate the **reviewer** agent. Review target: `$ARGUMENTS`
+
+1. If target is specified, review those files
+2. If no target, review files modified in current branch vs main
+3. Run all 4 review passes (correctness, security, performance, maintainability)
+4. Score each finding by confidence (0-100), only report ≥70
+5. Output structured report with severity, location, issue, and fix
+
+Max 10 findings per pass. Include positive observations too.

package/commands/scan.md

@@ -0,0 +1,19 @@
+---
+name: scan
+description: Full security audit of the project.
+---
+
+# /scan
+
+Activate the **security-auditor** agent. Scope: `$ARGUMENTS`
+
+1. If scope specified, audit those files/components
+2. If no scope, audit the entire project
+3. Check all OWASP Top 10 categories systematically
+4. Run dependency audit (npm audit / pip-audit / safety)
+5. Review security headers, auth, input validation, secrets management
+6. Generate full audit report with severity, impact, proof, and fix for each finding
+
+Output a structured security audit report in markdown.
+
+Save output to `docs/audits/YYYY-MM-DD-[scope].md`

package/commands/ship.md

@@ -0,0 +1,17 @@
+---
+name: ship
+description: Commit, create PR, and prepare for deployment.
+---
+
+# /ship
+
+Activate the **git-manager** agent, then the **reviewer** agent. Ship: `$ARGUMENTS`
+
+0. Read `## Git Workflow` from CLAUDE.md if present — respect PR preference and auto-push settings
+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
+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/simplify.md

@@ -0,0 +1,16 @@
+---
+name: simplify
+description: Simplify complex code without changing behavior.
+---
+
+# /simplify
+
+Activate the **code-simplifier** agent. Target: `$ARGUMENTS`
+
+1. Measure current complexity (nesting depth, cyclomatic complexity, line count)
+2. Identify accidental vs essential complexity
+3. Apply simplification transforms (early returns, guard clauses, extract helpers)
+4. Verify tests pass after each change
+5. Report before/after complexity metrics
+
+Behavior must be preserved — simplification is not refactoring.

package/commands/task.md

@@ -0,0 +1,32 @@
+---
+name: task
+description: Execute a backlog item end-to-end via chain orchestration.
+---
+
+# /task
+
+Activate the **project-manager** agent as orchestrator. Execute backlog item `$ARGUMENTS` through the full development chain.
+
+0. Read `docs/backlog.md` and extract the row matching the given `#N`
+1. If item not found or already done, report and stop
+2. Mark item as `active` in backlog
+3. Display item summary (feature, impact, effort, source)
+4. Determine save mode from effort level (see Save Rules below)
+5. Execute chain (plan, build, test, review) with the feature description as topic
+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
+
+## Save Rules
+
+- **Effort L** — execute chain inline, no `docs/chains/` output (commit is the trace)
+- **Effort M/H** — save each step to `docs/chains/YYYY-MM-DD-{slug}/` + `SUMMARY.md`, link to `docs/plans/` (symlink by default)
+- **`--save` flag** — forces save to `docs/chains/` regardless of effort level
+- **`--copy` flag** — use physical copy with provenance header instead of symlink
+- **Effort H** — also use `--gate` mode (pause between chain steps for confirmation)
+
+## Rules
+
+- Argument must be a backlog number (e.g., `/task #36` or `/task 36`)
+- If the item has a linked brainstorm, read it for additional context before planning
+- Do not auto-ship if review found critical issues — report and stop

package/commands/tdd.md

@@ -0,0 +1,17 @@
+---
+name: tdd
+description: Test-driven development workflow — red-green-refactor cycle.
+---
+
+# /tdd
+
+Activate the **tester** agent, then the **implementer** agent. TDD target: `$ARGUMENTS`
+
+1. **Red** — Write a failing test for the desired behavior
+2. Run the test — confirm it fails for the right reason
+3. **Green** — Write the minimum code to make the test pass
+4. Run the test — confirm it passes
+5. **Refactor** — Clean up code while keeping tests green
+6. Repeat for the next behavior
+
+Never write production code without a failing test first.

package/commands/test.md

@@ -0,0 +1,16 @@
+---
+name: test
+description: Generate and run tests for a component or recent changes.
+---
+
+# /test
+
+Activate the **tester** agent. Test target: `$ARGUMENTS`
+
+1. Detect the test framework in use
+2. If target is specified, generate tests for it
+3. If no target, generate tests for recently modified files
+4. Run the tests and report results
+5. Identify coverage gaps and suggest additional tests
+
+Prioritize: happy path → error paths → edge cases → integration.

package/commands/upgrade.md

@@ -0,0 +1,27 @@
+---
+name: upgrade
+description: Check for CortexHawk updates and show what changed
+agent: project-manager
+---
+
+# /upgrade
+
+Check if a newer version of CortexHawk is available and propose updating.
+
+## Process
+
+1. Run `./install.sh --check-update` to detect version delta
+2. If update available, show the changelog diff
+3. Ask the user if they want to update
+4. If yes, run `./install.sh --update`
+5. After update, run `./install.sh --stats` to confirm
+
+## Output
+
+Version comparison + changelog delta + update command.
+
+## Rules
+
+- Never auto-update without user confirmation
+- Show `--dry-run` option for preview
+- If already up to date, report and stop