cortexhawk 3.1.0

package/README.md

@@ -0,0 +1,418 @@
+# CortexHawk
+
+[![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.0.0-green.svg?style=flat-square)](CHANGELOG.md)
+[![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)
+
+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.0
+
+- **`--init` wizard overhaul** — reordered flow with git workflow config, auto `git init` + `.gitignore` creation, branching strategies (direct-main, dev-branch, git-flow)
+- **`/bootstrap --smart`** — researcher agent scans roadmap, compares stacks, recommends, then scaffolds
+- **Post-install gitignore** — auto-adds `.claude/`, `.kimi/`, `.codex/` to `.gitignore`, asks about `docs/`
+- **`--update` checksum detection** — compares file checksums instead of just version numbers to detect changes
+- **Kimi CLI overhaul** — agents, commands, hooks all converted to skills; AGENTS.md at project root; MCP optional; auto `.envrc` for local install
+- **Codex CLI fixes** — config.toml format fixes (flat model key, save-all persistence)
+- **`--demo` flag** — sandbox project in `/tmp/` with intentional bugs for testing
+- **`/upgrade` command** — check for updates, show changelog diff, propose `--update`
+- **`--publish-skill`** — publish local skills to GitHub with auto-generated README
+- **Cursor CLI removed** — too unstable for maintained support
+
+## Quick Start
+
+```bash
+# Install (pick one)
+npm install -g cortexhawk                          # via npm
+git clone https://github.com/Spechawk94/CortexHawk.git ~/.cortexhawk && cd ~/.cortexhawk && ./setup.sh  # via git
+
+# Set up your project
+cd /path/to/your/project
+cortexhawk init                       # interactive wizard (recommended)
+cortexhawk install                    # direct install (all skills)
+cortexhawk install --profile api      # install only API skills
+cortexhawk install --target auto      # auto-detect installed CLIs
+cortexhawk install --target kimi      # Kimi CLI (experimental)
+
+# Useful commands
+cortexhawk update                     # update installation
+cortexhawk validate                   # verify skills/agents discovery
+cortexhawk doctor                     # check installation health
+cortexhawk search react               # search 87k+ community skills
+cortexhawk self-update                # update CortexHawk source
+```
+
+<details>
+<summary>Alternative: use install.sh directly (no CLI wrapper)</summary>
+
+```bash
+git clone https://github.com/Spechawk94/CortexHawk.git /tmp/cortexhawk
+cd /path/to/your/project
+bash /tmp/cortexhawk/install.sh --init
+
+# Skill packs (curated bundles)
+bash /tmp/cortexhawk/install.sh --pack react-app
+bash /tmp/cortexhawk/install.sh --pack security-suite
+
+# Profiles: fullstack, api, data, autodetect
+bash /tmp/cortexhawk/install.sh --profile autodetect
+```
+
+</details>
+
+## What's Inside
+
+### Agents (20)
+
+Specialized AI agents that coordinate together instead of working in silos.
+
+| Agent | Role |
+|---|---|
+| `planner` | Breaks features into executable tasks |
+| `implementer` | Writes production code from plans |
+| `tester` | Generates tests and validates coverage |
+| `reviewer` | Multi-pass code review (logic, security, perf) |
+| `debugger` | Root cause analysis and fix |
+| `security-auditor` | OWASP Top 10, CVE scanning, audit reports |
+| `architect` | System design, API design, infra decisions |
+| `devops` | CI/CD, Docker, deployment, monitoring |
+| `researcher` | Tech research, benchmarks, comparisons |
+| `designer` | UI/UX patterns, accessibility, responsive |
+| `git-manager` | Branching strategy, commits, PR management |
+| `docs-manager` | Documentation generation and maintenance |
+| `project-manager` | Progress tracking, roadmaps, milestones |
+| `copywriter` | Release notes, changelogs, technical comms |
+| `journal-writer` | Dev journals, decision logs, retrospectives |
+| `brainstormer` | Ideation, mind mapping, solution exploration |
+| `code-simplifier` | Complexity reduction, code clarification |
+| `codebase-mapper` | Generates architectural map of the codebase |
+| `fullstack-developer` | Full-stack orchestration front+back |
+| `teacher` | Teaches concepts with 3 pedagogical levels (guided, mentor, professor) |
+
+### Commands (32)
+
+Slash commands for common workflows.
+
+| Command | Description |
+|---|---|
+| `/plan` | Create implementation plan for a feature |
+| `/build` | Implement code from plan or description |
+| `/test` | Generate and run tests |
+| `/review` | Multi-agent code review |
+| `/ship` | Commit + PR pipeline |
+| `/debug` | Debug and fix issues |
+| `/scan` | Full security audit |
+| `/check` | Pre-commit quality gate (lint + test + scan + review → GO/NO-GO) |
+| `/refactor` | Guided refactoring |
+| `/research` | Technology research and comparison |
+| `/doc` | Generate documentation |
+| `/bootstrap` | Initialize a new project with full setup |
+| `/tdd` | Test-driven development cycle |
+| `/optimize` | Performance analysis and improvement |
+| `/migrate` | Database migration generation |
+| `/monitor` | Monitoring, health checks, alerting |
+| `/api-gen` | Generate API endpoints from spec |
+| `/changelog` | Generate changelog from git history |
+| `/journal` | Write a dev journal entry |
+| `/brainstorm` | Structured brainstorming session |
+| `/simplify` | Simplify complex code |
+| `/deploy` | Deploy to production |
+| `/export` | Save session as structured markdown |
+| `/backlog` | Process brainstorms into prioritized backlog |
+| `/pulse` | Project health dashboard with agent analytics |
+| `/map` | Generate architectural map of the codebase |
+| `/learn` | Activate learn mode with level and topic |
+| `/chain` | Sequential agent execution with context passing |
+| `/task` | Execute a backlog item end-to-end via chain orchestration |
+| `/ci` | Generate CI/CD pipeline tailored to project stack |
+| `/context` | Manage persistent project context shared across all agents |
+| `/upgrade` | Check for updates, show changelog diff, propose update |
+
+### Agent Chaining
+
+Chain multiple agents into automated pipelines. Each agent receives the output of the previous one.
+
+**Built-in presets:**
+
+| Preset | Sequence |
+|---|---|
+| `default` | plan → build → test → review |
+| `security` | scan → review |
+| `ship` | test → review → ship |
+
+**Usage:**
+
+```bash
+/chain default auth-system           # run default preset
+/chain security payment-module       # security audit pipeline
+/chain plan,build,test api-endpoint  # explicit comma-separated list
+/chain --gate default auth-system    # pause between each step for confirmation
+/chain --replay auth-system          # re-execute previous chain with fresh context
+```
+
+**Custom presets:** Create `.cortexhawk-chains.yml` at project root to define your own:
+
+```yaml
+# .cortexhawk-chains.yml
+presets:
+  api:
+    steps: plan,build,test,scan
+    description: "API feature pipeline with security scan"
+  hotfix:
+    steps: debug,build,test,ship
+    description: "Quick fix pipeline"
+  qa:
+    steps: scan,test,review
+    description: "Quality assurance pipeline"
+    gate: true
+```
+
+Then use: `/chain qa auth-module` instead of `/chain scan,test,review auth-module`
+
+Custom presets override built-in presets with the same name. See `templates/cortexhawk-chains.yml` for a full template.
+
+**Agent 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
+
+**Agent delegation:** Agents can invoke sub-agents mid-chain via `@delegate(agent, context, return)` — detected by `/chain` and executed as dynamic sub-steps.
+
+**`/task` command:** Execute a backlog item end-to-end — reads `docs/backlog.md`, chains plan→build→test→review, then ships. Effort-based save rules: L=inline, M/H=save to `docs/chains/`.
+
+### Skills (36)
+
+Domain-specific knowledge modules loaded on demand.
+
+- **Security**: auth-analyzer, compliance-checker, container-security, dependency-auditor, encryption, incident-response, secrets, security-headers, security-logging, vulnerability-scanner
+- **DevOps**: ci-cd, deployment, docker
+- **Databases**: schema-designer, sql-optimizer
+- **Testing**: e2e-testing, tdd, test-generator
+- **Quality**: complexity-analyzer, error-handling, log-analyzer, pattern-detector
+- **Meta**: mcp-builder, skill-creator
+- **Frameworks**: api-design, sveltekit, fastapi, nextjs, tailwindcss, react, typescript, python
+- **Optimization**: performance
+- **Workflow**: commit, confidence-check, pr-review-comments
+
+Skills support dependency declarations via `requires:` frontmatter, validated at install time and reported in `/pulse`.
+
+### SkillsMP — Community Skills (87k+)
+
+Search and discover community skills from [SkillsMP](https://skillsmp.com):
+
+```bash
+./install.sh --search react          # search 87k+ skills (requires API key)
+./install.sh --add-skill user/repo   # install a skill from GitHub
+./install.sh --publish-skill skills/my-skill  # publish to GitHub (requires gh CLI)
+```
+
+Set your SkillsMP API key in `.env` or via `--init` wizard:
+
+```bash
+# .env
+SKILLSMP_API_KEY=sk_live_...
+```
+
+Without an API key, `--search` falls back to the local `REGISTRY.md`.
+
+### Skill Packs
+
+Curated skill bundles for common stacks — install multiple skills in one command:
+
+| Pack | Skills |
+|---|---|
+| `react-app` | frameworks/react, frameworks/nextjs, frameworks/tailwindcss, testing/e2e-testing, quality/error-handling |
+| `python-api` | frameworks/fastapi, frameworks/python, databases/sql-optimizer, security/auth-analyzer, testing/test-generator |
+| `svelte-app` | frameworks/sveltekit, frameworks/tailwindcss, frameworks/typescript, testing/e2e-testing |
+| `devops-full` | devops/ci-cd, devops/deployment, devops/docker, optimization/performance, quality/log-analyzer |
+| `security-suite` | All 10 security skills |
+| `testing-full` | testing/tdd, testing/test-generator, testing/e2e-testing, quality/complexity-analyzer, workflow/confidence-check |
+
+```bash
+./install.sh --pack react-app
+./install.sh --pack security-suite --target kimi
+```
+
+### Agent Personas
+
+Create custom agents that inherit from base agents with rule/style overrides:
+
+```
+.cortexhawk-agents/
+  strict-reviewer.md    # extends: reviewer — stricter rules
+  fast-planner.md       # extends: planner — output format tweaks
+```
+
+Personas use `extends:` frontmatter and are auto-copied to `.claude/agents/` on install/update.
+
+### Hooks (9)
+
+Automatic lifecycle hooks that run during Claude Code sessions.
+
+| Hook | Event | Description |
+|---|---|---|
+| `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 |
+| `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 |
+
+Hook pipelines are configured in `hooks/compose.yml`. Manage individual hooks:
+
+```bash
+./install.sh --list-hooks             # show all hooks with status (active/disabled)
+./install.sh --enable-hook file-guard # enable a specific hook
+./install.sh --disable-hook test-reminder  # disable a specific hook
+./install.sh --test-hooks             # dry-run all hooks with synthetic inputs
+```
+
+### Modes (7)
+
+Behavioral presets that adapt Claude's responses.
+
+| Mode | Behavior |
+|---|---|
+| `default` | Balanced, clear, actionable |
+| `fast` | Minimal tokens, direct answers |
+| `research` | Deep analysis, brainstorming |
+| `review` | Critical, thorough examination |
+| `orchestration` | Multi-agent coordination |
+| `learn` | Teaching mode with 3 levels (guided, mentor, professor) |
+| `pair` | Alternates implementer/reviewer on each change, max 2 cycles |
+
+## Multi-CLI Support
+
+CortexHawk installs on 3 CLI tools:
+
+| Target | Status | Directory | How |
+|---|---|---|---|
+| Claude Code (default) | **Fully supported** | `.claude/` | `./install.sh` |
+| Kimi CLI | Experimental | `.kimi/` + `AGENTS.md` | `./install.sh --target kimi` |
+| Codex CLI | Experimental | `.codex/` + `.agents/` | `./install.sh --target codex` |
+| All at once | — | all of the above | `./install.sh --target all` |
+
+> **Note**: Only Claude Code is fully supported. Kimi and Codex targets are experimental — some features are adapted to each CLI's architecture.
+
+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-*`) |
+| 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-*`) |
+| MCP | `settings.json` | Optional (`MCP-SETUP.md`) | `config.toml` |
+
+## Installation Management
+
+```bash
+# Update to latest version (checksum-based detection, preserves customizations)
+./install.sh --update
+./install.sh --update --force          # force even if up to date
+
+# Getting started
+./install.sh --quickstart              # post-install guide (5 things to try)
+./install.sh --demo                    # sandbox project with intentional bugs
+
+# Simulate without writing files
+./install.sh --dry-run                 # preview install
+./install.sh --update --dry-run        # preview update delta
+
+# Diagnostics
+./install.sh --doctor                  # check installation health
+./install.sh --test-hooks              # dry-run all hooks with synthetic inputs
+./install.sh --stats                   # installation overview (version, counts)
+
+# Snapshots
+./install.sh --snapshot                # save installation state
+./install.sh --snapshot --portable     # self-contained .tar.gz archive
+./install.sh --snapshots               # list all snapshots
+./install.sh --restore <file>          # restore from snapshot
+./install.sh --restore --latest        # restore most recent
+./install.sh --diff <file>             # compare current vs snapshot
+./install.sh --diff <a> <b>            # semantic diff between two snapshots
+
+# Uninstall
+./install.sh --uninstall               # clean removal (creates snapshot first)
+./install.sh --uninstall --force       # skip confirmation
+
+# Community skills
+./install.sh --add-skill user/repo     # install from GitHub
+```
+
+## Team Sharing
+
+```bash
+# Export current config as team preset
+./install.sh --export-team             # generates .cortexhawk-team.yml
+./install.sh --export-config           # alias for --export-team
+
+# Install from team config
+./install.sh --team                    # reads .cortexhawk-team.yml
+./install.sh --import-config           # alias for --team
+```
+
+Team members can override with `.cortexhawk-local.yml`.
+
+## Docs Workspace
+
+`install.sh` creates a `docs/` directory for persisting agent outputs across sessions.
+
+| Directory | Agent | Command |
+|---|---|---|
+| `docs/brainstorms/` | brainstormer | `/brainstorm` |
+| `docs/plans/` | planner | `/plan` |
+| `docs/decisions/` | journal-writer | `/journal` |
+| `docs/research/` | researcher | `/research` |
+| `docs/audits/` | security-auditor | `/scan` |
+| `docs/conversations/` | — | `/export` |
+| `docs/chains/` | chain agents | `/chain`, `/task` |
+| `docs/.context/` | all agents | `/context`, (auto — agent memory) |
+| `docs/.metrics/` | analytics hooks | (auto — JSONL telemetry) |
+
+Files are saved as `YYYY-MM-DD-[topic].md`. Agent memory files in `.context/` are free-form markdown, created automatically.
+
+## Post-Install Security Audit
+
+After installation, CortexHawk runs a lightweight security audit on your project:
+
+1. `.gitignore` covers `.env`
+2. No `.env` files committed to git
+3. No hardcoded secrets in source files
+4. Dependency vulnerabilities (`npm audit` / `pip-audit` if available)
+5. No sensitive files tracked (`.pem`, `.key`, `id_rsa`, etc.)
+
+Warnings only — never blocks installation. Skip with `--no-scan`. Run `/scan` for a full AI-powered audit.
+
+## Benchmark Framework
+
+`tests/` contains synthetic repos and agent expectations for validating agent output quality.
+
+| Directory | Purpose |
+|---|---|
+| `tests/fixtures/` | 3 synthetic repos with intentional bugs and security flaws |
+| `tests/expectations/` | JSON checklists per agent (required sections, keywords, forbidden patterns) |
+
+Run `bash scripts/benchmark.sh` to validate fixture integrity and expectation schemas.
+
+## Philosophy
+
+- **Open-source and free forever**
+- **Optimized prompts** — no verbosity eating your context
+- **Modular** — install only what you need
+- **Framework agnostic** — works with any stack
+- **Community-driven** — PRs welcome
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, [templates/](templates/) for creating new components, and [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for common issues.
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

package/REGISTRY.md

@@ -0,0 +1,23 @@
+# CortexHawk Skill Registry
+
+Community skills for CortexHawk. Install with `./install.sh --add-skill <url>`.
+Search with `./install.sh --search <keyword>`.
+
+Submit your skill: open a PR adding a row to this table.
+
+| Name | Category | Description | Author | URL |
+|---|---|---|---|---|
+| vue | frameworks | Vue.js patterns, Composition API, Pinia state management | community | cortexhawk/skill-vue |
+| django | frameworks | Django ORM, middleware, REST framework, admin | community | cortexhawk/skill-django |
+| graphql | frameworks | GraphQL schema design, resolvers, subscriptions | community | cortexhawk/skill-graphql |
+| rails | frameworks | Ruby on Rails conventions, ActiveRecord, migrations | community | cortexhawk/skill-rails |
+| angular | frameworks | Angular components, services, RxJS patterns | community | cortexhawk/skill-angular |
+| flutter | frameworks | Flutter widgets, state management, platform channels | community | cortexhawk/skill-flutter |
+| rust | frameworks | Rust ownership, lifetimes, async, error handling | community | cortexhawk/skill-rust |
+| go | frameworks | Go idioms, concurrency, interfaces, testing | community | cortexhawk/skill-go |
+| kubernetes | devops | K8s deployments, services, ingress, helm charts | community | cortexhawk/skill-kubernetes |
+| terraform | devops | Infrastructure as code, providers, modules, state | community | cortexhawk/skill-terraform |
+| aws | devops | AWS services, IAM, Lambda, S3, CloudFormation | community | cortexhawk/skill-aws |
+| mongodb | databases | MongoDB queries, aggregation, indexing, replication | community | cortexhawk/skill-mongodb |
+| redis | databases | Redis data structures, caching patterns, pub/sub | community | cortexhawk/skill-redis |
+| elasticsearch | databases | Elasticsearch queries, mappings, aggregations | community | cortexhawk/skill-elasticsearch |

package/agents/architect.md

@@ -0,0 +1,46 @@
+---
+name: architect
+description: System design, API design, infrastructure decisions, and architecture documentation.
+---
+
+# Architect Agent
+
+You are a principal engineer making architecture decisions.
+
+## Responsibilities
+- System design and component decomposition
+- API design (REST, GraphQL, gRPC) with consistent contracts
+- Database schema design and migration strategy
+- Infrastructure and deployment architecture
+- Technology selection with trade-off analysis
+
+## Process
+
+0. **Context** — Read `docs/.context/_shared.md` and `docs/.context/architect.md`
+1. **Understand** requirements — functional and non-functional (scale, latency, cost)
+2. **Explore** current architecture — what exists, what constraints
+3. **Design** with trade-offs explicit — no perfect solutions, only trade-offs
+4. **Document** decisions with ADR (Architecture Decision Records)
+
+## Output Format
+```markdown
+# ADR-[number]: [Title]
+## Status: PROPOSED | ACCEPTED | DEPRECATED
+## Context
+[Why this decision is needed]
+## Options Considered
+1. [Option A] — Pros: ... Cons: ...
+2. [Option B] — Pros: ... Cons: ...
+## Decision
+[What we chose and why]
+## Consequences
+[What changes, what risks remain]
+```
+
+## Rules
+- Always present ≥2 options with trade-offs
+- Optimize for simplicity first, scale second
+- No premature abstraction — design for current needs + 1 step ahead
+- API contracts must be versioned from day one
+- Every external dependency is a risk — justify it
+- Update `docs/.context/architect.md` with patterns, decisions, and key files discovered

package/agents/brainstormer.md

@@ -0,0 +1,57 @@
+---
+name: brainstormer
+description: Structured brainstorming, ideation, mind mapping, and solution exploration.
+---
+
+# Brainstormer Agent
+
+You are a creative technologist facilitating structured ideation sessions.
+
+## Process
+
+0. **Context** — Read `docs/.context/_shared.md`, `docs/.context/brainstormer.md`, and last 3 files in `docs/brainstorms/`
+1. **Frame** — Define the problem space, constraints, and success criteria
+2. **Diverge** — Generate 5-10 ideas without filtering — quantity over quality
+3. **Explore** — Expand the 3 most promising ideas with pros, cons, and feasibility
+4. **Converge** — Score ideas against criteria, identify the strongest option
+5. **Prototype** — Outline a minimal proof-of-concept for the winning idea
+
+## Output Format
+
+```markdown
+## Brainstorm: [Topic]
+
+### Problem
+[1-2 sentence problem statement]
+
+### Constraints
+- [technical, time, resource constraints]
+
+### Ideas
+| # | Idea | Feasibility | Impact | Effort |
+|---|---|---|---|---|
+| 1 | [idea] | H/M/L | H/M/L | H/M/L |
+
+### Deep Dive: Top 3
+#### 1. [Idea]
+- Pros: [list]
+- Cons: [list]
+- Technical approach: [brief outline]
+
+### Recommendation
+[winning idea with reasoning]
+
+### Next Steps
+1. [concrete action to validate the idea]
+```
+
+## Rules
+- No idea is bad during diverge phase — capture everything
+- Constraints must be stated upfront — they shape the solution space
+- Always include at least one unconventional/risky option
+- Score ideas objectively — don't anchor on the first idea
+- Feasibility check must consider existing codebase and tech stack
+- End with concrete next steps, not abstract conclusions
+- Keep sessions focused — one problem per brainstorm
+- Save output to `docs/brainstorms/YYYY-MM-DD-[topic-slug].md`
+- Update `docs/.context/brainstormer.md` with patterns, decisions, and key files discovered

package/agents/code-simplifier.md

@@ -0,0 +1,56 @@
+---
+name: code-simplifier
+description: Simplification of complex code — reduce cyclomatic complexity, clarify logic, improve readability.
+---
+
+# Code Simplifier Agent
+
+You are a senior engineer focused on reducing unnecessary complexity.
+
+## Process
+
+0. **Context** — Read `docs/.context/_shared.md` and `docs/.context/code-simplifier.md`
+1. **Measure** — Identify complexity hotspots (deep nesting, long functions, high cyclomatic complexity)
+2. **Analyze** — Understand why the complexity exists — is it essential or accidental?
+3. **Simplify** — Apply targeted transformations to reduce complexity
+4. **Verify** — Ensure behavior is preserved — tests must pass before and after
+5. **Document** — Explain what changed and why the simpler version is equivalent
+
+## Techniques
+- Extract early returns to flatten nesting
+- Replace complex conditionals with guard clauses
+- Split functions >30 lines into focused helpers
+- Replace flag arguments with separate functions
+- Simplify boolean expressions with De Morgan's laws
+- Replace imperative loops with declarative alternatives (map, filter, reduce)
+- Inline single-use abstractions that add indirection without value
+
+## Output Format
+
+```markdown
+## Simplification: [file/function]
+
+### Before
+- Cyclomatic complexity: [score]
+- Lines: [count]
+- Max nesting depth: [depth]
+
+### Changes
+- [file:line] — [transformation applied]
+
+### After
+- Cyclomatic complexity: [new score]
+- Lines: [new count]
+- Max nesting depth: [new depth]
+
+### Behavior preserved: yes/no
+```
+
+## Rules
+- Never change behavior — simplification is not refactoring
+- Run tests before AND after every change
+- Reduce nesting before reducing line count
+- If complexity is essential (business logic), document it instead of forcing simplification
+- Don't abstract prematurely — 3 similar lines > 1 premature abstraction
+- If touching >5 files, pause and confirm approach
+- Update `docs/.context/code-simplifier.md` with patterns, decisions, and key files discovered

package/agents/codebase-mapper.md

@@ -0,0 +1,63 @@
+---
+name: codebase-mapper
+description: Generates an architectural map of the codebase — structure, dependencies, entry points, and key patterns.
+---
+
+# Codebase Mapper Agent
+
+You are a senior engineer creating a navigable architectural map of the codebase.
+
+## Process
+
+0. **Context** — Read `docs/.context/_shared.md` and `docs/.context/codebase-mapper.md`
+1. **Structure** — Walk the directory tree, identify top-level modules and their responsibilities
+2. **Entry points** — Find main files, CLI entrypoints, API routes, exports
+3. **Dependencies** — Map internal module dependencies and external packages
+4. **Patterns** — Detect architecture style (MVC, layered, monorepo, plugin-based), conventions, shared utilities
+5. **Data flow** — Trace key data paths (request lifecycle, event flow, build pipeline)
+6. **Generate** — Produce a structured CODEBASE.md
+
+## Output Format
+
+```markdown
+# Codebase Map — [project-name]
+
+**Generated**: [date] | **Root**: [path]
+
+## Overview
+[1-3 sentence summary of what this project is and its architecture style]
+
+## Directory Structure
+[annotated tree — each directory with a one-line description]
+
+## Entry Points
+| Entry | File | Purpose |
+|---|---|---|
+| [name] | [path] | [what it does] |
+
+## Module Dependencies
+[module] → [module] — [relationship]
+
+## Key Patterns
+- [pattern name]: [where and how it's used]
+
+## Tech Stack
+| Layer | Technology |
+|---|---|
+| [layer] | [tech] |
+
+## Critical Files
+| File | Why It Matters |
+|---|---|
+| [path] | [explanation] |
+```
+
+## Rules
+- Max depth 3 for directory tree — deeper levels only if architecturally significant
+- Annotate every top-level directory — no naked file trees
+- Entry points must be verified (check for main, exports, routes), not guessed
+- Dependencies = internal module relationships, not just package.json
+- Skip generated files, node_modules, build artifacts, .git
+- If scope is provided, map only that subtree but note its relationship to the whole
+- Save output to `CODEBASE.md` at project root
+- Update `docs/.context/codebase-mapper.md` with patterns, decisions, and key files discovered