hatch3r 1.2.0 → 1.4.0

package/agents/modes/migration-path.md

@@ -0,0 +1,55 @@
+---
+id: researcher-mode-migration-path
+type: mode
+description: Design a phased execution plan with safe ordering and rollback points.
+parent: hatch3r-researcher
+---
+### Mode: `migration-path`
+
+Design a phased execution plan with safe ordering. Each phase must leave the codebase in a working state. Identify parallel lanes, rollback points, and map phases to execution skills.
+
+**Output structure:**
+
+```markdown
+## Migration Path
+
+### Phase Overview
+| Phase | Title | Scope | Depends On | Skill | Effort | Rollback Point? |
+|-------|-------|-------|-----------|-------|--------|----------------|
+| 0 | {test scaffolding} | {add missing tests before refactoring} | — | hatch3r-qa-validation | S/M | Yes |
+| 1 | {first transformation} | {what changes} | Phase 0 | hatch3r-refactor | S/M/L | Yes |
+
+### Phase Details
+
+#### Phase {N}: {Title}
+- **Goal:** {what this phase achieves}
+- **Transformations:** {list of specific changes}
+- **Files:** {list with change descriptions}
+- **Behavioral invariants:** {what must still hold after this phase}
+- **Verification:** {how to confirm the phase is successful}
+- **Rollback:** {how to revert this phase without affecting others}
+
+### Parallel Lanes
+| Lane | Phases | Why Independent |
+|------|--------|----------------|
+| A | {phase numbers} | {no shared files or interfaces} |
+| B | {phase numbers} | {no shared files or interfaces} |
+
+### Critical Path
+{phase X} → {phase Y} → {phase Z} (total: {effort estimate})
+
+### Completion Criteria
+- [ ] All phases completed and verified
+- [ ] All behavioral invariants confirmed via tests
+- [ ] No regression in existing test suite
+- [ ] Dead code from old patterns removed
+- [ ] Documentation updated (specs, ADRs)
+
+### Skill Mapping
+| Phase | Execution Skill | Why |
+|-------|----------------|-----|
+| {phase} | hatch3r-refactor | Structural code quality improvement |
+| {phase} | hatch3r-logical-refactor | Behavior or logic flow change |
+| {phase} | hatch3r-visual-refactor | UI/UX component change |
+| {phase} | hatch3r-qa-validation | Test scaffolding before refactoring |
+```

package/agents/modes/prior-art.md

@@ -0,0 +1,31 @@
+---
+id: researcher-mode-prior-art
+type: mode
+description: Research best practices, known issues, and ecosystem trends via web search.
+parent: hatch3r-researcher
+---
+### Mode: `prior-art`
+
+Research best practices, known issues, ecosystem trends, and prior art via web search. Use for novel problems, security advisories, or approaches not covered by local docs or Context7.
+
+**Output structure:**
+
+```markdown
+## Prior Art Research
+
+### Best Practices
+| # | Practice | Source | Applicability |
+|---|---------|--------|--------------|
+| 1 | {practice} | {source — blog, docs, RFC} | {how it applies to the subject} |
+
+### Known Issues / CVEs
+| # | Issue | Severity | Affected Versions | Mitigation |
+|---|-------|----------|-------------------|------------|
+| 1 | {issue or CVE} | {severity} | {versions} | {fix or workaround} |
+
+### Ecosystem Trends
+- {trend}: {relevance to the subject}
+
+### Reference Implementations
+- {project/example}: {what it demonstrates and how it's relevant}
+```

package/agents/modes/refactoring-strategy.md

@@ -0,0 +1,55 @@
+---
+id: researcher-mode-refactoring-strategy
+type: mode
+description: Design the refactoring approach with transformations, invariants, and patterns.
+parent: hatch3r-researcher
+---
+### Mode: `refactoring-strategy`
+
+Design the refactoring approach. Propose specific transformations (extract, inline, rename, restructure, migrate). Define behavioral invariants that must hold throughout. Identify patterns to follow from the existing codebase or from best practices.
+
+**Dimension-specific focus** (when provided):
+- **Structural:** Extract module, split file, reduce coupling, enforce boundaries
+- **Logical:** Behavior migration, data model evolution, API versioning, state machine redesign
+- **Visual:** Component refactoring, design token standardization, accessibility remediation, layout restructuring
+- **Migration:** Framework swap, adapter pattern, compatibility shim, incremental migration
+
+**Output structure:**
+
+```markdown
+## Refactoring Strategy
+
+### Target Architecture
+{Description of the desired end state — how the code should look after refactoring}
+
+### Transformation Plan
+| # | Transformation | Type | From → To | Invariants |
+|---|---------------|------|-----------|-----------|
+| 1 | {what to do} | Extract/Inline/Restructure/Migrate/Replace | {current} → {target} | {what must not change} |
+
+### Behavioral Invariants
+| # | Invariant | How to Verify | Current Test Coverage |
+|---|-----------|--------------|---------------------|
+| 1 | {behavior that must be preserved} | {test or assertion strategy} | Covered/Needs test |
+
+### New Patterns Introduced
+| Pattern | Where | Justification | Precedent in Codebase? |
+|---------|-------|--------------|----------------------|
+| {pattern} | {where it applies} | {why this pattern over alternatives} | Yes — {where} / No — {why new} |
+
+### Patterns Removed
+| Pattern | Where | Replacement | Migration Strategy |
+|---------|-------|-------------|-------------------|
+| {pattern being replaced} | {current locations} | {what replaces it} | {how to migrate} |
+
+### Interface Contracts
+| Interface / API | Current Contract | New Contract | Breaking? | Migration |
+|----------------|-----------------|-------------|-----------|-----------|
+| {interface} | {current shape} | {new shape or "unchanged"} | Yes/No | {strategy} |
+
+### Effort Estimate
+| Phase | Effort | Parallelizable? |
+|-------|--------|----------------|
+| {phase} | S/M/L/XL | Yes/No |
+| **Total** | {aggregate} | {parallel lanes} |
+```

package/agents/modes/regression.md

@@ -0,0 +1,45 @@
+---
+id: researcher-mode-regression
+type: mode
+description: Investigate when an issue was introduced by analyzing git history and changes.
+parent: hatch3r-researcher
+---
+### Mode: `regression`
+
+Investigate when the issue was likely introduced and what changed. Analyze git history, recent dependency updates, configuration changes, and deployment events in the affected area.
+
+**Output structure:**
+
+```markdown
+## Regression Analysis
+
+### Timeline
+| Date / Period | Change | Author | Files | Potential Link |
+|--------------|--------|--------|-------|---------------|
+| {date or range} | {commit message or change description} | {who} | {files changed} | High/Med/Low — {reasoning} |
+
+### Recent Changes in Affected Area
+| File | Last Modified | Change Summary | Suspicious? |
+|------|-------------|----------------|-------------|
+| {file path} | {date} | {what changed} | Yes/No — {why} |
+
+### Dependency Changes
+| Dependency | Previous Version | Current Version | Changelog Relevant? |
+|-----------|-----------------|----------------|---------------------|
+| {package} | {old} | {new} | Yes — {breaking change or bug fix} / No |
+
+### Configuration Changes
+| Config | Change | When | Impact |
+|--------|--------|------|--------|
+| {config file or env var} | {what changed} | {when} | {how it could cause the issue} |
+
+### Most Likely Introduction Window
+- **When:** {date range or commit range}
+- **What changed:** {description}
+- **Confidence:** High/Med/Low
+- **Bisect strategy:** {how to narrow down further if needed}
+
+### Previously Working State
+- **Last known good:** {version, commit, or date when this worked}
+- **Evidence:** {test results, user reports, or deploy logs}
+```

package/agents/modes/requirements-elicitation.md

@@ -0,0 +1,68 @@
+---
+id: researcher-mode-requirements-elicitation
+type: mode
+description: Detect ambiguities and missing requirements, generate structured questions across 10 dimensions.
+parent: hatch3r-researcher
+---
+### Mode: `requirements-elicitation`
+
+Analyze the task description against the codebase to detect ambiguities, unstated assumptions, and missing requirements. Generate structured questions for the user across 10 dimensions to resolve unknowns before implementation. Triggered by the `hatch3r-deep-context` rule based on complexity tier.
+
+**Protocol:**
+
+1. Parse the task description for vague language ("improve", "better", "proper", "handle", "support", "clean up", "fix", "update") and flag each instance.
+2. Identify unstated assumptions by comparing the task against the codebase structure — what does the task imply but not state explicitly?
+3. For each of the 10 dimensions below, determine if the task description addresses it. If not, generate a targeted question.
+4. Scan the codebase for modules that will be affected by the task. For each, check whether the task description accounts for its consumers, contracts, and side effects. Generate dependency-derived questions from gaps.
+5. Check for cross-cutting concerns triggered by the task and list them with status (addressed / unaddressed).
+
+**10 Dimensions:**
+
+1. **Data** — schema shape, data source, expected volume, validation rules, migration needs
+2. **Behavior** — success flow, error/failure flow, edge cases, concurrent access, idempotency
+3. **UI/UX** — loading states, empty states, error states, responsive behavior, accessibility, animations
+4. **Security** — auth/authz model, data sensitivity classification, input validation, rate limiting, CSRF/XSS
+5. **Performance** — expected data volume, caching strategy, pagination, lazy loading, bundle impact
+6. **Integration** — existing features this interacts with, shared state, event chains, API consumers
+7. **Migration** — existing data or behavior that changes, backward compatibility, rollback strategy
+8. **Observability** — logging requirements, metrics, error tracking, audit trail for the new behavior
+9. **Testing** — what constitutes "working", acceptance test scenarios, edge case coverage expectations
+10. **Rollout** — feature flags, phased rollout, A/B testing, rollback trigger conditions
+
+**Output structure:**
+
+```markdown
+## Requirements Elicitation
+
+### Ambiguity Detection
+| # | Term / Phrase | Context | Why It's Ambiguous | Suggested Clarification |
+|---|--------------|---------|-------------------|------------------------|
+| 1 | {vague term} | {where it appears} | {what's unclear} | {specific question} |
+
+### Dimension Probe Questions
+| # | Dimension | Question | Why This Matters | Default If Unanswered |
+|---|-----------|----------|-----------------|----------------------|
+| 1 | {dimension} | {specific question} | {what could go wrong without an answer} | {safe default the implementer would assume} |
+
+### Dependency-Derived Questions
+| # | Module / Interface | Consumers | Question |
+|---|-------------------|-----------|----------|
+| 1 | {module being changed} | {list of consumers} | {question about contract impact} |
+
+### Cross-Cutting Concern Checklist
+| Concern | Triggered? | Addressed in Task? | Action Needed |
+|---------|-----------|-------------------|--------------|
+| Authentication / Authorization | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+| Internationalization (i18n) | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+| Accessibility (a11y) | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+| Error Handling | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+| Data Validation | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+| Observability / Logging | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+| Backward Compatibility | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+| Feature Flags / Rollout | Yes/No | Yes/No/Partial | {what to clarify or confirm} |
+
+### Requirements Summary
+- **Resolved:** {N} dimensions fully addressed
+- **Needs clarification:** {N} questions requiring user input before implementation
+- **Safe defaults available:** {N} questions where a reasonable default exists if the user defers
+```

package/agents/modes/risk-assessment.md

@@ -0,0 +1,41 @@
+---
+id: researcher-mode-risk-assessment
+type: mode
+description: Identify risks, security implications, performance concerns, and breaking changes.
+parent: hatch3r-researcher
+---
+### Mode: `risk-assessment`
+
+Identify risks, security implications, performance concerns, breaking changes, migration needs, and common mistakes.
+
+**Output structure:**
+
+```markdown
+## Risk Assessment
+
+### Technical Risks
+| # | Risk | Likelihood | Impact | Mitigation |
+|---|------|-----------|--------|------------|
+| 1 | {risk} | High/Med/Low | High/Med/Low | {strategy} |
+
+### Security Implications
+| # | Concern | Severity | Mitigation |
+|---|---------|----------|------------|
+| 1 | {concern} | Critical/High/Med/Low | {strategy} |
+
+### Performance Concerns
+| # | Concern | When It Matters | Mitigation |
+|---|---------|----------------|------------|
+| 1 | {concern} | {threshold or condition} | {strategy} |
+
+### Breaking Changes
+| # | What Breaks | Who Is Affected | Migration Path |
+|---|------------|----------------|----------------|
+| 1 | {change} | {consumers/users} | {migration strategy} |
+
+### Common Mistakes
+- **{mistake}**: {why it's tempting} → {what to do instead}
+
+### Recommended Safeguards
+- {safeguard}: {rationale}
+```

package/agents/modes/risk-prioritization.md

@@ -0,0 +1,43 @@
+---
+id: researcher-mode-risk-prioritization
+type: mode
+description: Risk-ranked prioritization of testing effort by business impact and coverage.
+parent: hatch3r-researcher
+---
+### Mode: `risk-prioritization`
+
+Produce a risk-ranked prioritization of testing effort considering business impact, security exposure, change frequency, and current coverage. Used by `hatch3r-test-plan` to order test implementation for maximum risk reduction.
+
+**Output structure:**
+
+```markdown
+## Risk-Based Test Prioritization
+
+### Risk Matrix
+| # | Module / Area | Business Impact | Security Exposure | Change Frequency | Current Coverage | Risk Score | Test Priority |
+|---|-------------|----------------|------------------|-----------------|-----------------|-----------|--------------|
+| 1 | {module} | Critical/High/Med/Low | Critical/High/Med/Low | High/Med/Low | High/Med/Low/None | {weighted score} | P0/P1/P2/P3 |
+
+### Recommended Test Investment Order
+| Priority | Module / Area | Recommended Tests | Effort | Risk Reduction |
+|----------|-------------|------------------|--------|---------------|
+| P0 | {module} | {test types and count} | S/M/L | {what risk this eliminates} |
+| P1 | {module} | {test types and count} | S/M/L | {what risk this reduces} |
+| P2 | {module} | {test types and count} | S/M/L | {what risk this reduces} |
+| P3 | {module} | {test types and count} | S/M/L | {incremental improvement} |
+
+### Quick Wins
+| # | Test to Add | Module | Effort | Risk Reduction | Why It's a Quick Win |
+|---|-----------|--------|--------|---------------|---------------------|
+| 1 | {specific test description} | {module} | XS/S | {impact} | {already has test infra / simple boundary / high-value assertion} |
+
+### Technical Debt Tests
+| # | Debt Item | Module | Current Risk | Recommended Test | Blocks |
+|---|----------|--------|-------------|-----------------|--------|
+| 1 | {tech debt — e.g., untested legacy module, missing error handling tests} | {module} | {what could go wrong} | {test type and scope} | {what this blocks — e.g., safe refactoring, migration} |
+```
+
+**Depth scaling:**
+- **quick**: Risk matrix (top 5 modules) + quick wins only.
+- **standard**: Full risk matrix, investment order (P0-P2), quick wins, and top 3 technical debt items.
+- **deep**: All sections exhaustively. Full risk matrix with weighted scoring, complete investment order (P0-P3), all quick wins, and comprehensive technical debt test inventory.

package/agents/modes/root-cause.md

@@ -0,0 +1,39 @@
+---
+id: researcher-mode-root-cause
+type: mode
+description: Analyze the codebase for candidate root causes using static analysis patterns.
+parent: hatch3r-researcher
+---
+### Mode: `root-cause`
+
+Analyze the codebase for candidate root causes. Use static analysis patterns: off-by-one errors, race conditions, missing null checks, incorrect assumptions, stale caches, wrong operator usage, missing error handling, and anti-patterns. Rank hypotheses by likelihood.
+
+**Output structure:**
+
+```markdown
+## Root Cause Analysis
+
+### Hypotheses (Ranked by Likelihood)
+| Rank | Hypothesis | Likelihood | Evidence | Files Involved | Verification Strategy |
+|------|-----------|-----------|----------|----------------|----------------------|
+| 1 | {what might be wrong} | High/Med/Low | {code evidence supporting this} | {file paths} | {how to confirm or rule out} |
+| 2 | {alternative cause} | High/Med/Low | {evidence} | {files} | {verification} |
+
+### Code Smells in Affected Area
+| # | Smell | Location | Relevance to Bug |
+|---|-------|----------|-----------------|
+| 1 | {pattern — e.g., missing error handling, implicit type coercion} | {file:line} | {how it could cause or mask the bug} |
+
+### Dependency Analysis
+| Dependency | Version | Known Issues | Relevance |
+|-----------|---------|-------------|-----------|
+| {library/module} | {version} | {any known bugs or CVEs} | {how it relates to the symptoms} |
+
+### Recommended Investigation Order
+1. {hypothesis to test first — highest likelihood + easiest to verify}
+2. {next hypothesis}
+3. {etc.}
+
+### Ruling-Out Notes
+- {hypotheses already considered unlikely and why}
+```

package/agents/modes/similar-implementation.md

@@ -0,0 +1,70 @@
+---
+id: researcher-mode-similar-implementation
+type: mode
+description: Search the codebase for analogous features and extract implementation conventions.
+parent: hatch3r-researcher
+---
+### Mode: `similar-implementation`
+
+Search the codebase for analogous features, components, or modules and extract their implementation conventions as a reference for the implementer. The goal is to ensure new code follows established patterns rather than inventing new approaches.
+
+**Protocol:**
+
+1. Parse the task to extract the core *type* of work — CRUD resource, dashboard widget, API endpoint, auth flow, data pipeline, form, modal, notification, list/table view, search feature, file upload, webhook handler, background job, etc.
+2. Search the codebase for modules and components that perform the same *type* of work. Use file name patterns, directory structure, import analysis, and semantic code search.
+3. Rank matches by structural similarity: file organization, patterns used, complexity level, recency.
+4. For the top 2-3 matches, extract:
+   - File structure and naming conventions (file names, directory placement, barrel exports)
+   - State management pattern (local state, context, store, server state, URL state)
+   - Error handling approach (try/catch style, error boundaries, toast notifications, inline errors)
+   - Data fetching / API pattern (hooks, services, direct fetch, query library)
+   - Test structure and coverage approach (co-located vs separate, naming, mock strategy)
+   - Component composition pattern (container/presenter, compound components, render props — if UI)
+5. Identify where the proposed feature MUST differ from references and why (different data shape, different auth model, different performance requirements).
+6. Present reference implementations with a recommendation for which to follow.
+
+**Output structure:**
+
+```markdown
+## Similar Implementation Analysis
+
+### Work Type Classification
+- **Detected type:** {type of work — e.g., "CRUD resource with list view and detail page"}
+- **Search strategy:** {how references were found — file patterns, directory scan, semantic search}
+
+### Reference Implementations
+| # | Module / Feature | Location | Similarity | Why It's a Good Reference |
+|---|-----------------|----------|-----------|--------------------------|
+| 1 | {name} | {directory/file path} | High/Med | {what makes it analogous} |
+| 2 | {name} | {directory/file path} | High/Med | {what makes it analogous} |
+
+### Convention Extraction
+
+#### Reference 1: {name}
+| Aspect | Convention | Files |
+|--------|-----------|-------|
+| File structure | {pattern — e.g., "feature directory with index barrel, component, hook, types, test files"} | {example files} |
+| State management | {pattern — e.g., "React Query for server state + local useState for UI state"} | {example files} |
+| Error handling | {pattern — e.g., "ErrorBoundary wrapper + toast for mutations + inline for forms"} | {example files} |
+| Data fetching | {pattern — e.g., "custom hook wrapping useQuery, service layer for API calls"} | {example files} |
+| Test structure | {pattern — e.g., "co-located .test.tsx, RTL for components, msw for API mocks"} | {example files} |
+| Component composition | {pattern — e.g., "container fetches data, presenter renders, shared via compound"} | {example files} |
+
+### Recommendation
+- **Primary reference:** {name} — follow this for {rationale}
+- **Secondary reference:** {name} — consult for {specific aspect}
+
+### Divergence Warnings
+| # | Aspect | Reference Pattern | Required Divergence | Reason |
+|---|--------|------------------|-------------------|--------|
+| 1 | {aspect} | {what the reference does} | {what the new feature must do differently} | {why} |
+
+### Pattern-Match Checklist for Implementer
+- [ ] File structure follows {reference} convention
+- [ ] State management uses {pattern} as established in {reference}
+- [ ] Error handling follows {pattern} from {reference}
+- [ ] Data fetching uses {pattern} from {reference}
+- [ ] Test structure matches {pattern} from {reference}
+- [ ] Component composition follows {pattern} from {reference}
+- [ ] Documented divergences with justification for each
+```

package/agents/modes/symptom-trace.md

@@ -0,0 +1,39 @@
+---
+id: researcher-mode-symptom-trace
+type: mode
+description: Trace reported symptoms through the codebase to find divergence points.
+parent: hatch3r-researcher
+---
+### Mode: `symptom-trace`
+
+Trace reported symptoms through the codebase. Map the execution path from user action to observed failure. Identify where expected behavior diverges from actual behavior.
+
+**Output structure:**
+
+```markdown
+## Symptom Trace
+
+### Execution Path
+| # | Step | File / Function | Expected Behavior | Observed / Likely Behavior |
+|---|------|----------------|-------------------|---------------------------|
+| 1 | {user action or trigger} | {entry point} | {what should happen} | {what likely happens} |
+| 2 | {next step in flow} | {file:function} | {expected} | {observed or inferred} |
+
+### Divergence Point
+- **Where:** {file:function or module where behavior diverges}
+- **What:** {description of the divergence}
+- **Evidence:** {code patterns, conditions, or state that suggest this is the divergence point}
+
+### Error Propagation
+| From | To | How | Observable? |
+|------|----|-----|-------------|
+| {origin} | {downstream} | {mechanism — exception, bad state, silent failure} | Yes/No |
+
+### Affected Code Paths
+| Path | Entry Point | Risk of Symptom | Notes |
+|------|-------------|----------------|-------|
+| {flow name} | {file:function} | High/Med/Low | {why this path is affected} |
+
+### Data Flow Concerns
+- {any data integrity, state management, or concurrency concerns identified during tracing}
+```

package/agents/modes/test-pattern.md

@@ -0,0 +1,61 @@
+---
+id: researcher-mode-test-pattern
+type: mode
+description: Extract existing test conventions, framework usage, mock patterns, and helper libraries.
+parent: hatch3r-researcher
+---
+### Mode: `test-pattern`
+
+Extract existing test conventions, framework usage, mock patterns, and helper libraries to ensure new tests follow established patterns. Used by `hatch3r-test-plan` to align the test strategy with the project's existing test infrastructure.
+
+**Output structure:**
+
+```markdown
+## Test Pattern Analysis
+
+### Framework & Tooling Inventory
+| Tool | Version | Config File | Purpose |
+|------|---------|------------|---------|
+| {vitest/jest/playwright/stryker/etc.} | {version} | {config path} | {unit/integration/E2E/mutation} |
+
+### Directory Conventions
+| Test Type | Directory | Naming Pattern | Co-located? |
+|-----------|-----------|---------------|-------------|
+| Unit | {path} | {pattern — e.g., *.test.ts} | Yes/No |
+| Integration | {path} | {pattern} | Yes/No |
+| E2E | {path} | {pattern} | Yes/No |
+| Fixtures | {path} | {pattern} | — |
+| Quarantine | {path or "none"} | {pattern} | — |
+
+### Mock & Fixture Patterns
+| Pattern | Where Used | Convention | Compliance with hatch3r-testing |
+|---------|-----------|-----------|-------------------------------|
+| {fakes / stubs / mocks / MSW / nock / etc.} | {example files} | {how the project uses this pattern} | {aligned — fakes > stubs > mocks / divergent — explain} |
+
+### Test Helper Library
+| Helper | Location | Purpose | Used By |
+|--------|----------|---------|---------|
+| {factory function / builder / custom matcher / setup utility} | {file path} | {what it does} | {which test files use it} |
+
+### Property-Based Testing Usage
+| Status | Library | Where Used | Coverage |
+|--------|---------|-----------|---------|
+| {Active / Not used / Minimal} | {fast-check / etc. or "none"} | {file paths or "N/A"} | {which function types are covered} |
+
+### Convention Compliance
+| Convention (hatch3r-testing rule) | Current State | Compliance |
+|----------------------------------|--------------|-----------|
+| Deterministic (no wall clock) | {compliant / violations found} | {details} |
+| Isolated (own setup/teardown) | {compliant / violations found} | {details} |
+| Fast (unit < 50ms, integration < 2s) | {compliant / unknown / violations} | {details} |
+| Named clearly (behavior descriptions) | {compliant / mixed / non-compliant} | {details} |
+| No network in unit tests | {compliant / violations found} | {details} |
+| No type escape hatches | {compliant / violations found} | {details} |
+| Fakes > stubs > mocks hierarchy | {followed / partially / not followed} | {details} |
+| Factory over fixtures | {followed / partially / not followed} | {details} |
+```
+
+**Depth scaling:**
+- **quick**: Framework inventory + directory conventions only.
+- **standard**: Full inventory, directory conventions, mock patterns, and convention compliance summary.
+- **deep**: All sections exhaustively. Include test helper library analysis, property-based testing status, and detailed convention compliance with file-level violations.

package/agents/shared/external-knowledge.md

@@ -0,0 +1,32 @@
+---
+id: shared-external-knowledge
+type: reference
+description: Shared external knowledge reference for all agents — tooling hierarchy, platform CLI, Context7 MCP, and web research guidance.
+---
+## 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
+- **Fallback** to platform MCP only for operations not covered by the CLI (e.g., sub-issue management, project field mutations).
+
+## Context7 MCP Protocol
+
+Use `resolve-library-id` to find the library, then `query-docs` to retrieve current documentation. Apply this for any framework, library, or tool whose API surface may have changed since training data.
+
+- Prefer Context7 over guessing API signatures, configuration options, or behavioral details from potentially outdated training data.
+- Always verify: method names, parameter signatures, return types, and configuration keys before using them in code.
+- If Context7 returns no results, fall back to web research (below).
+
+## Web Research Protocol
+
+Use web search when Context7 does not cover the topic, or for information that changes frequently:
+
+- **Security:** Current CVE details (NVD), security advisories, supply chain attack patterns.
+- **Standards:** Current best practice guidance, specification updates, compliance requirements.
+- **Ecosystem:** Package maintenance status, alternative evaluations, community adoption signals.
+- **Platform-specific advisories** by platform:
+  - **GitHub:** GitHub Security Advisories, Dependabot alerts
+  - **Azure DevOps:** Microsoft Defender for DevOps, WhiteSource/Mend
+  - **GitLab:** GitLab Dependency Scanning, Advisory Database