hatch3r 1.2.0 → 1.4.0

package/agents/hatch3r-perf-profiler.md

@@ -47,22 +47,15 @@ Adapt to project-defined budgets. Common targets:
 
 ## External Knowledge
 
-Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Use the project's configured platform CLI (check `platform` in `.agents/hatch.json`):
-- **GitHub:** `gh` CLI
-- **Azure DevOps:** `az devops` / `az boards` / `az repos` CLI
-- **GitLab:** `glab` CLI
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- Bundler optimization options (Vite, webpack, esbuild, Rollup) for tree-shaking, code splitting, and chunk configuration
+- Profiling tool APIs (Lighthouse CI, web-vitals, clinic.js, 0x) and framework-specific performance APIs (React Profiler, Vue DevTools, Angular CDK)
 
-- Use `resolve-library-id` then `query-docs` to look up bundler optimization options (Vite, webpack, esbuild, Rollup) for tree-shaking, code splitting, and chunk configuration.
-- Look up profiling tool APIs and configuration (Lighthouse CI, web-vitals, clinic.js, 0x) to verify correct measurement methodology.
-- Check framework-specific performance APIs (React Profiler, Vue DevTools performance tab, Angular CDK virtual scrolling) for optimization guidance.
-
-## Web Research Usage
-
-- Use web search for current Core Web Vitals thresholds and measurement methodology when auditing user-facing performance.
-- Use web search for optimization techniques specific to detected bottlenecks (e.g., image format benchmarks, font loading strategies, SSR vs SSG trade-offs).
-- Use web search for performance benchmarks and comparison data when recommending alternative libraries or approaches to replace heavy dependencies.
+**Web research focus for this agent:**
+- Current Core Web Vitals thresholds and measurement methodology for user-facing performance audits
+- Optimization techniques for detected bottlenecks and performance benchmarks when recommending alternative libraries
 
 ## Sub-Agent Delegation
 

package/agents/hatch3r-researcher.md

@@ -989,17 +989,15 @@ Use the project's configured platform CLI (check `platform` in `.agents/hatch.js
   - **GitLab:** `glab issue view`, `glab issue list --search`, `glab search`
 - **Fallback** to platform MCP only for operations not covered by the CLI (e.g., sub-issue management, project field mutations).
 
-## Context7 MCP Usage
+## External Knowledge
 
-- Use `resolve-library-id` then `query-docs` to look up current API patterns for frameworks and external dependencies.
-- Prefer Context7 over guessing API signatures or relying on potentially outdated training data.
-- The `library-docs` mode wraps this into a structured workflow, but any mode may use Context7 when external APIs are relevant.
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Web Research Usage
+**Context7 focus for this agent:**
+- The `library-docs` mode wraps Context7 into a structured workflow, but any mode may use Context7 when external APIs are relevant
 
-- Use web search for latest CVEs, security advisories, breaking changes, or novel error messages.
-- Use web search for current best practices when Context7 and local docs are insufficient.
-- The `prior-art` mode wraps this into a structured workflow, but any mode may use web search when current information is needed.
+**Web research focus for this agent:**
+- The `prior-art` mode wraps web search into a structured workflow, but any mode may use web search when current information is needed
 
 ## Structured Reasoning
 
@@ -1026,12 +1024,7 @@ Apply this format whenever research findings involve trade-off analysis, risk as
 
 This agent file is large (~1,000+ lines) because it serves as a composable mode library. The current design is intentional: all modes share a single research protocol, tooling hierarchy, and structured output contract. Splitting individual modes into separate agents would break the composability that allows a single researcher invocation to execute multiple modes.
 
-**When to split:** If this file exceeds ~1,500 lines (e.g., due to new mode additions), consider extracting mode groups into companion agents:
-- `hatch3r-codebase-mapper` -- modes `codebase-impact`, `current-state`, `boundary-analysis` (codebase structure analysis)
-- `hatch3r-test-planner` -- modes `coverage-analysis`, `complexity-risk`, `test-pattern`, `risk-prioritization` (test planning research)
-- `hatch3r-researcher` retains the core protocol, general modes (`feature-design`, `architecture`, `risk-assessment`, `library-docs`, `prior-art`, `requirements-elicitation`, `similar-implementation`), and delegates to companion agents when codebase-mapping or test-planning modes are requested.
-
-Each companion agent would share the same research protocol preamble and tooling hierarchy sections.
+**When to split:** If this file exceeds ~1,500 lines (e.g., due to new mode additions), consider extracting mode groups into companion agents (e.g., a codebase-mapping agent for `codebase-impact`, `current-state`, `boundary-analysis` modes, and a test-planning agent for `coverage-analysis`, `complexity-risk`, `test-pattern`, `risk-prioritization` modes). The researcher would retain the core protocol and general modes, delegating to companions when specialized modes are requested. Each companion agent would share the same research protocol preamble and tooling hierarchy sections.
 
 ## Boundaries
 

package/agents/hatch3r-reviewer.md

@@ -38,6 +38,7 @@ Verify compliance with `.agents/rules/hatch3r-security-patterns.md`, `.agents/ru
 6. **Performance:** No hot-path regressions. Bundle size impact. No per-keystroke cloud writes.
 7. **Accessibility:** Reduced motion respected. WCAG AA contrast. Keyboard accessible. ARIA attributes.
 8. **Dead code:** No unused imports, obsolete comments, or abandoned logic.
+9. **Root-cause verification:** Do the changes address the underlying cause of the issue, not just the symptom? Identify what the original issue was (from the issue body, acceptance criteria, or diff context), then verify the change fixes the root cause. Flag superficial fixes — e.g., adding a try-catch that swallows errors, adding a comment saying "fixed", disabling a test, or suppressing a warning without resolving the underlying condition. If the change treats only the symptom, classify as Critical and specify what root-cause fix is needed.
 
 ## Output Format
 
@@ -58,21 +59,14 @@ Include specific file paths and line references. Propose fixes where possible.
 
 ## External Knowledge
 
-Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Use the project's configured platform CLI (check `platform` in `.agents/hatch.json`):
-- **GitHub:** `gh` CLI
-- **Azure DevOps:** `az devops` / `az boards` / `az repos` CLI
-- **GitLab:** `glab` CLI
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- Verify that reviewed code uses library APIs correctly (correct method signatures, proper error handling, non-deprecated usage)
 
-- Use `resolve-library-id` then `query-docs` to verify that reviewed code uses library APIs correctly (correct method signatures, proper error handling, non-deprecated usage).
-- When reviewing code that integrates with external libraries or frameworks, check Context7 for the current recommended patterns rather than relying on potentially outdated training data.
-
-## Web Research Usage
-
-- Use web search for known vulnerability patterns when reviewing security-sensitive code (auth flows, input handling, cryptographic operations).
-- Use web search for security advisories affecting dependencies used in the reviewed code.
-- Use web search for current best practices when the reviewed code uses patterns you are uncertain about (e.g., new framework features, evolving security standards).
+**Web research focus for this agent:**
+- Known vulnerability patterns and security advisories when reviewing security-sensitive code (auth flows, cryptographic operations)
+- Current best practices when reviewed code uses uncertain patterns (new framework features, evolving security standards)
 
 ## External Verification Signals
 

package/agents/hatch3r-security-auditor.md

@@ -46,23 +46,15 @@ Follow the security patterns defined in `.agents/rules/hatch3r-security-patterns
 
 ## External Knowledge
 
-Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Use the project's configured platform CLI (check `platform` in `.agents/hatch.json`):
-- **GitHub:** `gh` CLI
-- **Azure DevOps:** `az devops` / `az boards` / `az repos` CLI
-- **GitLab:** `glab` CLI
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- Security library APIs (JWT verification, bcrypt, helmet, CSRF middleware, OAuth libraries) and correct auth/crypto usage
+- Framework-specific security middleware docs (Express helmet options, Next.js CSP config, Django security middleware)
 
-- Use `resolve-library-id` then `query-docs` to look up current API patterns for security libraries (JWT verification, bcrypt, helmet, CSRF middleware, OAuth libraries).
-- Verify correct usage of auth/crypto APIs in audited code — training data may reflect deprecated or insecure defaults.
-- Look up framework-specific security middleware docs (e.g., Express helmet options, Next.js CSP config, Django security middleware).
-
-## Web Research Usage
-
-- Use web search for latest CVEs and security advisories affecting dependencies found in the project (NVD, GitHub Security Advisories, platform-specific databases).
-- Use web search for current OWASP Top 10, CWE references, and NIST guidelines when classifying findings.
-- Use web search for known exploit techniques and attack patterns relevant to the application's technology stack.
-- Use web search for security hardening best practices when the codebase uses patterns not covered by local docs or Context7.
+**Web research focus for this agent:**
+- Latest CVEs, security advisories, OWASP Top 10, CWE references, and NIST guidelines for classifying findings
+- Known exploit techniques, attack patterns, and security hardening best practices for the application's technology stack
 
 ## Sub-Agent Delegation
 

package/agents/hatch3r-test-writer.md

@@ -52,22 +52,15 @@ This interactive verification complements automated E2E test suites — use it t
 
 ## External Knowledge
 
-Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Use the project's configured platform CLI (check `platform` in `.agents/hatch.json`):
-- **GitHub:** `gh` CLI
-- **Azure DevOps:** `az devops` / `az boards` / `az repos` CLI
-- **GitLab:** `glab` CLI
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research).
 
-## Context7 MCP Usage
+**Context7 focus for this agent:**
+- Testing framework APIs (Vitest, Jest, Playwright, Cypress, Testing Library), assertion libraries, and mocking utilities
+- Library-recommended testing patterns (React Testing Library queries, Playwright locators, Supertest assertion chains)
 
-- Use `resolve-library-id` then `query-docs` to look up current APIs for testing frameworks (Vitest, Jest, Playwright, Cypress, Testing Library) before writing tests.
-- Look up assertion library APIs, mocking utilities, and test runner configuration to use correct patterns rather than relying on potentially outdated training data.
-- When testing code that uses external libraries, query Context7 for the library's recommended testing patterns (e.g., React Testing Library queries, Playwright locators, Supertest assertion chains).
-
-## Web Research Usage
-
-- Use web search for testing best practices for specific scenarios (e.g., testing race conditions, WebSocket handlers, file uploads, streaming responses).
-- Use web search for known testing pitfalls and flaky test patterns in the project's testing framework.
-- Use web search for security testing techniques (e.g., injection test patterns, auth bypass test cases) when writing security-related tests.
+**Web research focus for this agent:**
+- Testing best practices for specific scenarios (race conditions, WebSocket handlers, file uploads, streaming responses)
+- Security testing techniques (injection test patterns, auth bypass test cases) and known flaky test patterns
 
 ## Output Format
 

package/agents/modes/architecture.md

@@ -0,0 +1,44 @@
+---
+id: researcher-mode-architecture
+type: mode
+description: Design the architectural approach with data model changes, API contracts, and component design.
+parent: hatch3r-researcher
+---
+### Mode: `architecture`
+
+Design the architectural approach. Identify data model changes, API contracts, component design, and whether existing patterns should be followed or new ones introduced. Flag any decisions that warrant ADRs.
+
+**Output structure:**
+
+```markdown
+## Architecture Design
+
+### Data Model Changes
+| Entity / Table | Change Type | Fields / Schema | Migration Needed? |
+|---------------|-------------|-----------------|-------------------|
+| {entity} | Create/Alter/None | {fields or schema changes} | Yes/No |
+
+### API / Interface Contracts
+| Endpoint / Interface | Method | Input | Output | Notes |
+|---------------------|--------|-------|--------|-------|
+| {endpoint or interface} | {method} | {shape} | {shape} | {constraints} |
+
+### Component Design
+| Component | Responsibility | Depends On | New/Existing |
+|-----------|---------------|-----------|--------------|
+| {name} | {what it does} | {dependencies} | New/Existing |
+
+### Pattern Alignment
+- **Follows existing:** {patterns from the codebase this should follow}
+- **New patterns needed:** {any new patterns introduced, with justification}
+
+### Architectural Decisions Requiring ADRs
+| # | Decision | Context | Recommended | Alternatives |
+|---|----------|---------|-------------|--------------|
+| 1 | {title} | {why this decision matters} | {pick} | {alt1}, {alt2} |
+
+### Dependency Analysis
+| Dependency | Type | Status | Notes |
+|-----------|------|--------|-------|
+| {what this depends on} | Hard/Soft | Exists/Needs building | {notes} |
+```

package/agents/modes/boundary-analysis.md

@@ -0,0 +1,45 @@
+---
+id: researcher-mode-boundary-analysis
+type: mode
+description: Map integration boundaries, external dependencies, and data flow seams for test targeting.
+parent: hatch3r-researcher
+---
+### Mode: `boundary-analysis`
+
+Map integration boundaries, external dependencies, data flow boundaries, and event chains to identify where integration and contract tests are most needed. Used by `hatch3r-test-plan` to ensure test coverage at system seams.
+
+**Output structure:**
+
+```markdown
+## Boundary Analysis
+
+### Module Boundaries
+| Boundary | Module A | Module B | Interface Type | Current Test Coverage | Test Need |
+|----------|----------|----------|---------------|---------------------|----------|
+| {boundary name} | {module} | {module} | {API / import / event / shared state} | Covered/Partial/None | Integration/Contract/E2E |
+
+### External Dependencies
+| Dependency | Type | Mock Strategy | Current Mock Coverage | Risk if Unmocked |
+|-----------|------|-------------|---------------------|-----------------|
+| {database / API / service / SDK} | {runtime / build-time / optional} | {fake / stub / MSW / emulator / none} | Covered/Partial/None | {what breaks without proper mocking} |
+
+### Data Flow Boundaries
+| Flow | Source | Transform(s) | Sink | Validation Points | Test Coverage |
+|------|--------|-------------|------|------------------|-------------|
+| {flow name} | {where data enters} | {processing steps} | {where data is consumed} | {where validation happens} | Covered/Partial/None |
+
+### Event / Callback Chains
+| Event | Emitter | Listener(s) | Side Effects | Test Coverage |
+|-------|---------|------------|-------------|-------------|
+| {event name} | {where emitted} | {where consumed} | {what changes} | Covered/Partial/None |
+
+### API Surface Coverage
+| Endpoint / Interface | Methods | Parameters | Response Shapes | Test Coverage | Priority |
+|---------------------|---------|-----------|----------------|-------------|----------|
+| {endpoint or public interface} | {methods} | {param count / complexity} | {shape count} | Covered/Partial/None | P0/P1/P2/P3 |
+```
+
+**Depth scaling:**
+- **quick**: Module boundaries + external dependencies only (top 5 each).
+- **standard**: Full module boundaries, external dependencies, data flow boundaries, and API surface coverage.
+- **deep**: All sections exhaustively. Include event/callback chains, full data flow tracing, and priority-ranked API surface analysis.

package/agents/modes/codebase-impact.md

@@ -0,0 +1,81 @@
+---
+id: researcher-mode-codebase-impact
+type: mode
+description: Analyze current codebase to understand what exists in the areas the subject touches.
+parent: hatch3r-researcher
+---
+### Mode: `codebase-impact`
+
+Analyze the current codebase to understand what exists today in the areas the subject touches. Map files, modules, components, integration points, and coupling.
+
+**Output structure:**
+
+```markdown
+## Codebase Impact Analysis
+
+### Affected Modules
+| Module / Area | Current State | Changes Needed | Coupling Risk |
+|---------------|--------------|----------------|---------------|
+| {module} | {what exists today} | {what needs to change} | Low/Med/High |
+
+### Affected Files
+| File Path | Change Type | Description |
+|-----------|-------------|-------------|
+| {path} | Create/Modify/Extend | {what changes and why} |
+
+### Integration Points
+| Integration | Current Behavior | Required Change | Breaking? |
+|-------------|-----------------|-----------------|-----------|
+| {component/API/event} | {current} | {new} | Yes/No |
+
+### Patterns in Use
+- **{pattern}**: {where used} — {implications for this subject}
+
+### Transitive Dependency Trace
+For each file expected to change, trace importers up to 3 levels deep. This reveals the full blast radius beyond directly modified files.
+
+| Modified File | Direct Importers (L1) | Transitive Importers (L2) | Deep Importers (L3) |
+|--------------|----------------------|--------------------------|-------------------|
+| {file path} | {files that import this} | {files that import L1} | {files that import L2} |
+
+### API Consumer Map
+For each function, class, or interface expected to change, list all call sites across the codebase.
+
+| Symbol | Type | Call Sites | Contract Change Risk |
+|--------|------|-----------|---------------------|
+| {function/class/interface name} | Function/Class/Interface/Type | {file:line — list of all usages} | High/Med/Low — {why} |
+
+### Type Contract Surface
+For each modified type or interface, list all consumers and flag potential contract violations.
+
+| Type / Interface | Consumers | Fields Affected | Breaking Potential |
+|-----------------|-----------|----------------|-------------------|
+| {type name} | {list of files/modules using this type} | {which fields change} | Yes/No — {what could break} |
+
+### Event / Callback Chain
+Trace event emitters, listeners, callback registrations, and pub/sub patterns that depend on modified behavior.
+
+| Event / Callback | Emitter | Listeners / Subscribers | Behavior Change? |
+|-----------------|---------|------------------------|-----------------|
+| {event name or callback} | {where it's emitted/called} | {where it's consumed} | Yes/No — {what changes} |
+
+### Blast Radius Summary
+| Category | Count | Risk Level |
+|----------|-------|-----------|
+| Directly modified files | {N} | — |
+| Direct importers (L1) | {N} | High |
+| Transitive importers (L2) | {N} | Medium |
+| Deep importers (L3) | {N} | Low |
+| API consumers with contract risk | {N} | High |
+| Type consumers with breaking potential | {N} | High |
+| Event/callback chain participants | {N} | Medium |
+| **Total files at risk** | **{N}** | — |
+
+### Current State Summary
+{2-3 paragraphs describing the relevant codebase area, existing conventions, and how the subject fits into the current architecture}
+```
+
+**Depth scaling for transitive tracing:**
+- **quick**: Skip transitive tracing sections entirely. Only produce the standard tables (Affected Modules, Affected Files, Integration Points, Patterns in Use).
+- **standard**: Produce Transitive Dependency Trace (L1 only) and Blast Radius Summary. Skip API Consumer Map, Type Contract Surface, and Event/Callback Chain.
+- **deep**: Produce all sections — full 3-level trace, API Consumer Map, Type Contract Surface, Event/Callback Chain, and Blast Radius Summary.

package/agents/modes/complexity-risk.md

@@ -0,0 +1,40 @@
+---
+id: researcher-mode-complexity-risk
+type: mode
+description: Identify code complexity hotspots and mutation-prone areas for test prioritization.
+parent: hatch3r-researcher
+---
+### Mode: `complexity-risk`
+
+Identify code complexity hotspots, mutation-prone areas, and error handling coverage to prioritize where tests will have the highest impact. Used by `hatch3r-test-plan` to focus testing effort on the riskiest code.
+
+**Output structure:**
+
+```markdown
+## Complexity & Risk Analysis
+
+### Complexity Hotspots
+| # | File / Function | Complexity Signal | Severity | Current Test Coverage | Testing Priority |
+|---|----------------|------------------|----------|---------------------|-----------------|
+| 1 | {file:function} | {high cyclomatic complexity / deep nesting / large function / many branches} | High/Med/Low | Covered/Partial/None | P0/P1/P2/P3 |
+
+### Mutation-Prone Areas
+| # | Module / File | Why Mutation-Prone | Mutation Score (est.) | Recommended Action |
+|---|-------------|-------------------|---------------------|-------------------|
+| 1 | {path} | {many conditionals / complex state transitions / arithmetic logic} | {estimated or measured}% | {add assertions / property tests / mutation testing} |
+
+### Error Handling Coverage
+| # | Error Path | File(s) | Currently Tested? | Failure Impact | Priority |
+|---|-----------|---------|------------------|---------------|----------|
+| 1 | {error scenario} | {file paths} | Yes/No/Partial | {what happens if this error path is wrong} | P0/P1/P2/P3 |
+
+### Recommended Testing Depth
+| Module / Area | Recommended Depth | Rationale |
+|---------------|------------------|-----------|
+| {module} | Thorough (unit + integration + property) / Standard (unit + integration) / Light (unit only) | {complexity, risk, and coverage factors} |
+```
+
+**Depth scaling:**
+- **quick**: Top 5 complexity hotspots + recommended testing depth table only.
+- **standard**: Full hotspots (top 10), mutation-prone areas, error handling coverage (top 5), and recommended depth.
+- **deep**: All sections exhaustively. Cross-reference mutation targets from `hatch3r-testing` rule (70% critical, 60% general). Include estimated mutation scores and specific assertion gaps.

package/agents/modes/coverage-analysis.md

@@ -0,0 +1,44 @@
+---
+id: researcher-mode-coverage-analysis
+type: mode
+description: Map existing test coverage, identify gaps, and surface critical untested paths.
+parent: hatch3r-researcher
+---
+### Mode: `coverage-analysis`
+
+Map existing test coverage, identify gaps, and surface critical untested paths. Used by `hatch3r-test-plan` to understand the current testing baseline before planning new tests.
+
+**Output structure:**
+
+```markdown
+## Coverage Analysis
+
+### Existing Test Inventory
+| Test File | Type | Module / Area Covered | Test Count | Framework |
+|-----------|------|----------------------|-----------|-----------|
+| {path} | Unit/Integration/E2E | {what it tests} | {approx count} | {vitest/jest/playwright/etc.} |
+
+### Coverage Gaps
+| Module / Area | Statement % | Branch % | Function % | Gap Severity | Notes |
+|---------------|------------|----------|-----------|-------------|-------|
+| {module} | {current or "unknown"} | {current or "unknown"} | {current or "unknown"} | Critical/High/Med/Low | {why this gap matters} |
+
+### Critical Untested Paths
+| # | Code Path | File(s) | Risk if Untested | Recommended Test Type |
+|---|-----------|---------|-----------------|---------------------|
+| 1 | {description of untested path} | {file paths} | {what could go wrong} | Unit/Integration/E2E/Property |
+
+### Coverage Metrics Summary
+| Metric | Current | Target (hatch3r-testing rule) | Gap |
+|--------|---------|-------------------------------|-----|
+| Statement coverage | {N}% or unknown | 80% (90% critical) | {delta} |
+| Branch coverage | {N}% or unknown | 70% (85% critical) | {delta} |
+| Function coverage | {N}% or unknown | 80% | {delta} |
+| Mutation score | {N}% or unknown | 70% critical / 60% general | {delta} |
+| Flaky test rate | {N}% or unknown | < 0.5% | {delta} |
+```
+
+**Depth scaling:**
+- **quick**: Test file inventory + coverage metrics summary only. Skip gap analysis and untested paths.
+- **standard**: Full inventory, coverage gaps, critical untested paths (top 5), and metrics summary.
+- **deep**: All sections with exhaustive gap analysis, all untested paths enumerated, cross-reference against `hatch3r-testing` rule thresholds, and flaky test inventory from quarantine directory.

package/agents/modes/current-state.md

@@ -0,0 +1,52 @@
+---
+id: researcher-mode-current-state
+type: mode
+description: Map the current state of code being analyzed — complexity, coupling, cohesion, coverage.
+parent: hatch3r-researcher
+---
+### Mode: `current-state`
+
+Map the current state of the code being analyzed. Measure complexity, coupling, cohesion, test coverage, and code quality. Identify the specific problems that motivate the change.
+
+**Dimension-specific focus** (when provided):
+- **Structural:** Emphasize coupling, cohesion, module boundaries, dead code
+- **Logical:** Emphasize behavior contracts, data flows, state management, business rules
+- **Visual:** Emphasize component hierarchy, design token usage, accessibility compliance, responsive patterns
+- **Migration:** Emphasize framework/library API surface, adapter boundaries, compatibility layers
+
+**Output structure:**
+
+```markdown
+## Current State Analysis
+
+### Module Map
+| Module / Component | Files | Lines of Code | Responsibility | Coupling |
+|-------------------|-------|---------------|---------------|----------|
+| {module} | {count} | {approx} | {what it does} | {what it depends on and what depends on it} |
+
+### Complexity Metrics
+| File / Function | Complexity Signal | Severity | Notes |
+|----------------|------------------|----------|-------|
+| {file:function} | {high cyclomatic complexity / deep nesting / large function / etc.} | High/Med/Low | {context} |
+
+### Code Smells
+| # | Smell | Location | Description | Impact on Maintainability |
+|---|-------|----------|-------------|--------------------------|
+| 1 | {smell type} | {file:line range} | {description} | {how it hurts} |
+
+### Dependency Graph
+| Component | Depends On | Depended On By | Coupling Type |
+|-----------|-----------|---------------|---------------|
+| {component} | {dependencies} | {dependents} | Hard/Soft/Circular |
+
+### Test Coverage
+| Area | Unit Tests | Integration Tests | Coverage Level | Safety for Refactoring |
+|------|-----------|------------------|---------------|----------------------|
+| {area} | {count / exists / missing} | {count / exists / missing} | High/Med/Low | Safe/Needs tests first |
+
+### Pattern Inventory
+- **{pattern}**: {where used} — {whether to keep, replace, or extend}
+
+### Current State Summary
+{2-3 paragraphs describing the state of the code, why it needs changing, and what the key structural problems are}
+```

package/agents/modes/feature-design.md

@@ -0,0 +1,39 @@
+---
+id: researcher-mode-feature-design
+type: mode
+description: Break the subject down into implementable sub-tasks with user stories and acceptance criteria.
+parent: hatch3r-researcher
+---
+### Mode: `feature-design`
+
+Break the subject down into implementable sub-tasks with user stories, acceptance criteria, edge cases, and effort estimates.
+
+**Output structure:**
+
+```markdown
+## Feature Breakdown
+
+### Sub-Tasks
+| # | Sub-Task | User Story | Acceptance Criteria | Effort | Dependencies |
+|---|----------|-----------|---------------------|--------|--------------|
+| 1 | {title} | As a {persona}, I want {goal} so that {benefit} | - [ ] {criterion} | S/M/L/XL | {deps} |
+
+### Edge Cases
+| # | Scenario | Expected Behavior | Priority |
+|---|----------|-------------------|----------|
+| 1 | {edge case} | {how the system should handle it} | Must/Should/Nice |
+
+### UX Considerations
+- **{consideration}**: {recommendation and rationale}
+
+### Effort Summary
+| Metric | Value |
+|--------|-------|
+| Total sub-tasks | {N} |
+| Estimated total effort | {S/M/L/XL — map to rough days} |
+| Parallelizable tasks | {list task numbers that can run concurrently} |
+| Critical path | task {N} → task {M} → task {P} |
+
+### Suggested Priority
+{P0/P1/P2/P3}: {rationale for this priority level}
+```

package/agents/modes/impact-analysis.md

@@ -0,0 +1,45 @@
+---
+id: researcher-mode-impact-analysis
+type: mode
+description: Map the blast radius of an issue across flows, modules, data, and users.
+parent: hatch3r-researcher
+---
+### Mode: `impact-analysis`
+
+Map the blast radius. Identify all flows, modules, data, and users affected. Find related issues or symptoms that might share the same cause. Assess data integrity risk and downstream consumers.
+
+**Output structure:**
+
+```markdown
+## Impact Assessment
+
+### Affected Flows
+| Flow | Impact | Users Affected | Data at Risk? |
+|------|--------|---------------|---------------|
+| {user flow or system process} | {how it is affected} | {persona or segment} | Yes/No — {details} |
+
+### Affected Modules
+| Module / Area | How Affected | Severity | Coupling |
+|---------------|-------------|----------|----------|
+| {module} | {direct failure / degraded / cascading} | Critical/High/Med/Low | Direct/Indirect |
+
+### Downstream Consumers
+| Consumer | Coupling Type | Impact | Action Needed |
+|----------|-------------|--------|--------------|
+| {module/service/user} | {direct API / import / event / data} | {none / update needed / rewrite needed} | {what to do} |
+
+### Data Integrity Risk
+| Data | Risk | Detection | Recovery |
+|------|------|-----------|----------|
+| {what data is at risk} | {corruption / loss / inconsistency} | {how to detect damage} | {how to recover} |
+
+### Related Symptoms
+| # | Symptom | Reported? | Likely Same Cause? |
+|---|---------|-----------|-------------------|
+| 1 | {other observed issue} | Yes (#{issue}) / No | Yes/Likely/Unlikely |
+
+### User-Facing Impact
+- **Severity:** {Critical/High/Med/Low}
+- **Scope:** {how many users, what percentage of traffic}
+- **Workaround available:** {yes — describe / no}
+```

package/agents/modes/library-docs.md

@@ -0,0 +1,31 @@
+---
+id: researcher-mode-library-docs
+type: mode
+description: Look up current API documentation for specific libraries via Context7 MCP.
+parent: hatch3r-researcher
+---
+### Mode: `library-docs`
+
+Look up current API documentation for specific libraries or frameworks using Context7 MCP.
+
+**Protocol:**
+1. Call `resolve-library-id` with the library name to get the Context7-compatible ID.
+2. Call `query-docs` with the resolved ID and the specific API question.
+3. Summarize findings in structured output.
+
+**Output structure:**
+
+```markdown
+## Library Documentation
+
+### {Library Name} ({version})
+| API / Function | Signature | Notes |
+|---------------|-----------|-------|
+| {API} | {signature or usage pattern} | {relevant constraints, deprecations, or gotchas} |
+
+### Key Patterns
+- {pattern}: {how to use it correctly}
+
+### Breaking Changes / Deprecations
+- {item}: {migration path}
+```