hatch3r 1.0.0 → 1.2.0

package/rules/hatch3r-agent-orchestration.mdc

@@ -0,0 +1,225 @@
+---
+description: Mandatory agent delegation, skill loading, and subagent usage directives for ALL tasks in ALL contexts
+alwaysApply: true
+---
+# Agent Orchestration
+
+This rule governs when and how to delegate work to hatch3r agents, load skills, and spawn subagents. These directives are mandatory — not suggestions.
+
+## Universal Applicability
+
+This rule applies to EVERY context without exception:
+
+- **Board-pickup** (epic, sub-issue, standalone, batch)
+- **Workflow command** (full mode and quick mode)
+- **Plain chat** (single task or multiple tasks)
+- **Issue references** (e.g., "implement #5")
+- **Natural language requests** (e.g., "add a dark mode toggle")
+
+Whether the user invokes a command or simply asks for a task in conversation, the full sub-agent pipeline defined below is mandatory. There is no context where implementing code inline (without sub-agents) is acceptable.
+
+## Universal Sub-Agent Pipeline
+
+Every task MUST follow this four-phase pipeline:
+
+**Phase 1 — Research:** Spawn `hatch3r-researcher` for context gathering. Skip only for trivial single-line edits (typos, comment fixes, single-value config changes). All other tasks require researcher context. **Before spawning researchers, score the task's complexity per the `hatch3r-deep-context` rule** and add the tier-appropriate researcher modes alongside the standard task-type modes (see Deep Context Integration below).
+
+**Phase 2 — Implement:** Spawn `hatch3r-implementer` for ALL code changes. One dedicated implementer per task. Never implement inline — always delegate via the Task tool. **Include reference conventions, resolved requirements, and blast radius data** from Phase 1 in the implementer prompt when available (see Deep Context Integration below).
+
+**Phase 3 — Review Loop:**
+
+- 3a. Spawn `hatch3r-reviewer` to review the implementation.
+- 3b. If Critical or Warning findings exist: spawn `hatch3r-fixer` with the reviewer output. When fixes touch shared or public interfaces, also include blast radius data and reference conventions from Phase 1 (if available).
+- 3c. Re-review: spawn `hatch3r-reviewer` on the fixed code.
+- 3d. Repeat 3b–3c until the reviewer reports 0 Critical + 0 Warning, or max 3 iterations reached.
+- 3e. If max iterations reached with remaining findings: surface to user for manual resolution.
+
+**Phase 4 — Final Quality** (runs ONLY after the review loop is clean):
+
+Spawn all applicable specialists in parallel:
+
+| Specialist | When | Mandatory? |
+|-----------|------|------------|
+| `hatch3r-test-writer` | After every code change | YES — always for code changes |
+| `hatch3r-security-auditor` | After every code change | YES — always for code changes |
+| `hatch3r-docs-writer` | After every implementation | EVALUATE — spawn when changes affect APIs, architecture, user-facing behavior, or when specs/ADRs need updating |
+| `hatch3r-lint-fixer` | When lint errors present | Conditional |
+| `hatch3r-a11y-auditor` | When UI/accessibility changes | Conditional |
+| `hatch3r-perf-profiler` | When performance-sensitive changes | Conditional |
+| `hatch3r-dependency-auditor` | When dependencies change | Conditional |
+| `hatch3r-ci-watcher` | When CI fails | Conditional |
+| `hatch3r-architect` | When architectural decisions are needed or system design review is requested | Conditional |
+| `hatch3r-devops` | When CI/CD, deployment, or infrastructure tasks are involved | Conditional |
+
+## Agent Roster
+
+| Agent | Purpose | Invoke When |
+|-------|---------|-------------|
+| `hatch3r-researcher` | Context gathering across 15 research modes | ALWAYS before implementation. Skip only for trivial single-line edits. Select modes by task type + tier-appropriate deep context modes. |
+| `hatch3r-implementer` | Focused single-task implementation | ALWAYS. One dedicated implementer per task — standalone issues, epic sub-issues, batched issues, and plain chat tasks all get dedicated implementers. |
+| `hatch3r-reviewer` | Code review for quality, security, performance | ALWAYS in review loop (Phase 3). Reviews implementation, then re-reviews after fixes. |
+| `hatch3r-fixer` | Targeted fixes for reviewer findings | When `hatch3r-reviewer` reports Critical or Warning findings during the review loop (Phase 3). |
+| `hatch3r-test-writer` | Regression and coverage tests | ALWAYS for code changes in final quality (Phase 4). Not just bugs — every code change gets tests. |
+| `hatch3r-security-auditor` | Security rules, data flows, access control | ALWAYS for code changes in final quality (Phase 4). Not just `area:security` — every code change gets a security review. |
+| `hatch3r-docs-writer` | Specs, ADRs, documentation maintenance | ALWAYS evaluate in final quality (Phase 4). Spawn when changes affect APIs, architecture, or user-facing behavior. |
+| `hatch3r-lint-fixer` | Style, formatting, type error cleanup | After implementation when lint errors are present. |
+| `hatch3r-a11y-auditor` | WCAG AA compliance checks | When UI/accessibility changes are made. |
+| `hatch3r-perf-profiler` | Performance profiling and optimization | When performance-sensitive changes are made. |
+| `hatch3r-dependency-auditor` | Supply chain security, CVE scanning | When dependencies change or new packages are added. |
+| `hatch3r-ci-watcher` | CI/CD failure diagnosis and fix suggestions | When CI fails during or after implementation. |
+| `hatch3r-architect` | Architecture design, system design review, technical decision documentation | When architectural decisions are needed or system design review is requested. |
+| `hatch3r-devops` | CI/CD pipeline operations, deployment configuration, infrastructure setup | When CI/CD, deployment, or infrastructure tasks are involved. |
+
+## Deep Context Integration
+
+Before spawning researchers in Phase 1, score the task's complexity using the `hatch3r-deep-context` rule criteria. The resulting tier determines which additional researcher modes to include alongside the standard task-type modes.
+
+### Tier-Adjusted Research Modes
+
+**Tier 1 (Light — score 0–2):** Use only the standard task-type modes below. No additional modes.
+
+**Tier 2 (Standard — score 3–5):** Add these modes at `quick` depth alongside the task-type modes:
+- `requirements-elicitation` — scan for top ambiguities, ask 3–5 clarifying questions
+- `similar-implementation` — find 1 reference implementation, extract top-level patterns
+
+Present the elicitation questions to the user inline. Await answers before proceeding to Phase 2.
+
+**Tier 3 (Deep — score 6+):** Add these modes at `deep` depth alongside the task-type modes:
+- `requirements-elicitation` — full 10-dimension ambiguity scan, dependency questions, cross-cutting concern checklist
+- `similar-implementation` — find 2–3 references, full convention extraction, divergence analysis
+- `codebase-impact` at `deep` depth (with transitive tracing, API consumer map, blast radius)
+
+**Mandatory Tier 3 checkpoint:** Present a consolidated Pre-Implementation Summary to the user and ASK for confirmation. Do NOT proceed to Phase 2 until all unresolved questions are answered.
+
+### Implementer Prompt Enrichment
+
+When spawning `hatch3r-implementer` in Phase 2, include the following from Phase 1 results when available:
+- **Reference Conventions**: `similar-implementation` output — the implementer uses this in its Convention Lock step (Step 1b)
+- **Resolved Requirements**: User's answers to `requirements-elicitation` questions — explicit decisions the implementer should follow instead of guessing
+- **Blast Radius**: Enhanced `codebase-impact` output with transitive traces and API consumer maps — informs which consumers and contracts must be preserved
+
+## Mandatory Delegation Directives
+
+### Context Gathering (Before Implementation)
+
+You MUST spawn a `hatch3r-researcher` subagent before implementing any task. Skip only for trivial single-line edits (typos, comment fixes, single-value config changes). Select research modes by task type, then add tier-appropriate modes per the Deep Context Integration section above:
+
+- **`type:bug`**: modes `symptom-trace`, `root-cause`, `codebase-impact` + tier modes
+- **`type:feature`**: modes `codebase-impact`, `feature-design`, `architecture` + tier modes
+- **`type:refactor`**: modes `current-state`, `refactoring-strategy`, `migration-path` + tier modes
+- **`type:qa`**: modes `codebase-impact` + tier modes
+
+Use depth `quick` for low-risk tasks, `standard` for medium-risk, `deep` for high-risk. The `hatch3r-deep-context` tier may override depth upward (e.g., a Tier 3 task always uses `deep` depth for the additional modes, even if the task-type modes use `standard`).
+
+### Implementation Delegation
+
+You MUST spawn a `hatch3r-implementer` subagent via the Task tool for ALL code changes. Never implement inline.
+
+- **Single standalone issue**: Spawn one `hatch3r-implementer`. The orchestrator coordinates git, PR, and board operations.
+- **Plain chat single task**: Spawn one `hatch3r-implementer`. Create synthetic issue context first (title, acceptance criteria, type).
+- **Epics with sub-issues**: Spawn one `hatch3r-implementer` per sub-issue. Execute level-by-level respecting dependency order.
+- **Multiple standalone issues (batch)**: Treat as a batch. Group by dependency level, spawn one `hatch3r-implementer` per issue, execute level-by-level. Shared branch, combined PR.
+
+**Implementer prompt enrichment:** For Tier 2 and Tier 3 tasks, include the deep context outputs in the implementer prompt:
+- `similar-implementation` findings as "Reference Conventions" (triggers the implementer's Convention Lock step)
+- Resolved `requirements-elicitation` answers as "Resolved Requirements"
+- Enhanced `codebase-impact` blast radius data (Tier 3 only)
+
+### Post-Implementation Quality Pipeline
+
+You MUST run the review loop and final quality phases after implementation completes.
+
+**Phase 3 — Review Loop:**
+
+1. Spawn `hatch3r-reviewer` — code review. Include the diff and acceptance criteria in the prompt.
+2. If the reviewer reports Critical or Warning findings: spawn `hatch3r-fixer` with the full reviewer output (findings, file paths, line references, suggested fixes).
+3. After fixes: spawn `hatch3r-reviewer` again to re-review the fixed code.
+4. Repeat steps 2–3 until the reviewer reports 0 Critical + 0 Warning, or max 3 iterations reached.
+5. If max iterations reached with remaining findings: surface to user for manual resolution. Do not proceed to Phase 4 until the user acknowledges.
+
+**Phase 4 — Final Quality** (runs ONLY after the review loop is clean):
+
+Launch as many independent subagents in parallel as the platform supports — no artificial concurrency limit.
+
+**Always spawn (mandatory for every code change):**
+
+1. `hatch3r-test-writer` — tests for all code changes. Unit tests for new logic, regression tests for bug fixes, integration tests for cross-module changes.
+2. `hatch3r-security-auditor` — security review of all code changes. Audit data flows, access control, input validation, and secret management.
+
+**Always evaluate (spawn when applicable):**
+
+3. `hatch3r-docs-writer` — spawn when changes affect public APIs, architectural patterns, user-facing behavior, or when specs/ADRs need updating. If no documentation impact exists, skip silently.
+
+**Conditional specialists (spawn when triggered):**
+
+4. `hatch3r-lint-fixer` — when lint or type errors are present after implementation.
+5. `hatch3r-a11y-auditor` — when UI or accessibility changes are made.
+6. `hatch3r-perf-profiler` — when performance-sensitive changes are made.
+7. `hatch3r-dependency-auditor` — when dependencies change or new packages are added.
+8. `hatch3r-architect` — when architectural decisions are needed or system design review is requested.
+9. `hatch3r-devops` — when CI/CD, deployment, or infrastructure tasks are involved.
+
+## Skill Loading Directives
+
+Before implementing any task, you MUST read and follow the matching hatch3r skill:
+
+| Task Type | Skill |
+|-----------|-------|
+| `type:bug` | `hatch3r-bug-fix` |
+| `type:feature` | `hatch3r-feature` (aka `hatch3r-feature-implementation`) |
+| `type:refactor` + `area:ui` | `hatch3r-visual-refactor` |
+| `type:refactor` + behavior change | `hatch3r-logical-refactor` |
+| `type:refactor` (other) | `hatch3r-refactor` (aka `hatch3r-code-refactor`) |
+| `type:qa` | `hatch3r-qa-validation` |
+
+When a skill references agents under "Required Agent Delegation", those delegations are mandatory — you MUST spawn the listed agents via the Task tool.
+
+## Subagent Spawning Protocol
+
+When spawning any subagent via the Task tool:
+
+1. **Use `subagent_type: "generalPurpose"`** for all hatch3r agent delegations.
+2. **Include in every subagent prompt**:
+   - The agent protocol to follow (e.g., "Follow the hatch3r-implementer agent protocol").
+   - All `scope: always` rules from `.agents/rules/` that apply.
+   - The project's tooling hierarchy (Context7 MCP for library docs, web research for current context).
+   - Relevant learnings from `.agents/learnings/` if the directory exists.
+3. **Launch as many independent subagents in parallel as the platform supports.** Do not impose an artificial concurrency limit. Use maximum parallelism for independent work.
+4. **Await and review results** before proceeding. If a subagent reports BLOCKED or PARTIAL, surface to the user.
+
+## Single-Task Plain Chat Protocol
+
+When the user provides a single task in plain chat (no command invoked, no issue reference), the full sub-agent pipeline still applies:
+
+1. **Classify** the task by type (bug/feature/refactor/QA/other) based on context.
+2. **Create synthetic issue context** — title, acceptance criteria, and type — from the user's instruction.
+3. **Run the Universal Sub-Agent Pipeline**: Phase 1 (Research) → Phase 2 (Implement) → Phase 3 (Review Loop) → Phase 4 (Final Quality).
+4. For issue references in chat (e.g., "fix #5"), fetch issue details using the platform CLI (check `platform` in `.agents/hatch.json`) and use them as the task context instead of creating synthetic context:
+   - **GitHub:** `gh issue view`
+   - **Azure DevOps:** `az boards work-item show --id`
+   - **GitLab:** `glab issue view`
+
+This ensures consistent quality regardless of how the task was initiated.
+
+## Multi-Task Detection (Plain Chat)
+
+When the user provides multiple tasks in a single message — numbered lists, comma-separated instructions, multiple issue references (e.g., "implement #1, #3, #7"), or multiple distinct requests — you MUST parallelize them:
+
+1. **Parse** the message into individual discrete tasks. Each distinct implementation request is one task.
+2. **Classify** each task by type (bug/feature/refactor/QA/other) based on context or explicit labels.
+3. **Build a dependency graph** among the tasks. Independent tasks share the same level and run in parallel.
+4. **Spawn one `hatch3r-researcher` subagent per task** (skip for trivial single-line edits only). Launch in parallel.
+5. **Spawn one `hatch3r-implementer` subagent per task** per dependency level.
+6. **For issue references**: fetch issue details using the platform CLI (check `platform` in `.agents/hatch.json`):
+   - **GitHub:** `gh issue view`
+   - **Azure DevOps:** `az boards work-item show --id`
+   - **GitLab:** `glab issue view`
+7. **For natural language tasks**: create synthetic issue context (title, acceptance criteria, type) from the instruction. Pass this context to the implementer subagent.
+8. **Run the review loop** (Phase 3) after all implementations complete: spawn reviewer, then fixer for Critical/Warning findings, re-review, repeat until clean (max 3 iterations).
+9. **Spawn final quality subagents** (Phase 4, after review loop is clean): test-writer + security-auditor (always), plus docs-writer, auditors as applicable.
+
+This directive applies regardless of whether board-pickup was invoked. Any context where implementation tasks are identified MUST use one subagent per task with maximum parallelism.
+
+## Rule Application
+
+All hatch3r rules with `scope: always` apply to every implementation task, including work delegated to subagents. When constructing subagent prompts, include the rule directives — subagents do not automatically inherit the parent's rule context.

package/rules/hatch3r-api-design.md

@@ -1,6 +1,9 @@
 ---
+id: hatch3r-api-design
+type: rule
 description: API endpoint and contract design patterns for the project
-alwaysApply: true
+scope: always
+tags: [planning]
 ---
 # API Design
 

package/rules/hatch3r-browser-verification.md

@@ -1,6 +1,9 @@
 ---
+id: hatch3r-browser-verification
+type: rule
 description: Browser-based verification for UI and user-facing changes
-alwaysApply: false
+scope: conditional
+tags: [review]
 ---
 # Browser Verification
 
@@ -26,6 +29,35 @@ Skip browser verification for:
 - CI/CD pipeline changes
 - Code refactors that do not alter rendered output
 
+## Session Prompt Pattern
+
+Browser verification is opt-in per command session. The orchestrator follows a standardized prompt flow so the user is asked exactly once.
+
+### Prompt Rules
+
+1. **At the START of any command that supports browser verification**, the orchestrator MUST ask the user once: *"Would you like to enable browser verification for this session? This uses Playwright to test changes in the running application."*
+2. **The user's answer applies to ALL stages of that command** — implementation, review, and verification. Do not re-ask at any subsequent stage.
+3. **If yes:** all implementation, review, and verification stages include browser testing steps as defined in the Verification Protocol below. The orchestrator ensures a dev server is running and executes browser checks at each verification point.
+4. **If no:** all browser verification steps are skipped silently. Do not emit warnings, reminders, or suggestions to reconsider. The command proceeds as if the Verification Protocol section does not exist.
+
+### Command Support Matrix
+
+| Supports Browser Verification | Does NOT Support |
+| ------------------------------ | ---------------- |
+| `hatch3r-workflow` | `hatch3r-board-fill` |
+| `hatch3r-board-pickup` | `hatch3r-board-groom` |
+| `hatch3r-quick-change` | `hatch3r-board-refresh` |
+| `hatch3r-revision` | `hatch3r-roadmap` |
+| `hatch3r-debug` | `hatch3r-release` |
+| | `hatch3r-refactor-plan` |
+| | `hatch3r-security-audit` |
+| | `hatch3r-rule-customize` |
+| | `hatch3r-skill-customize` |
+
+Commands in the "Does NOT Support" column are documentation-only, planning-only, or non-implementation commands. They MUST NOT prompt for browser verification.
+
+---
+
 ## Verification Protocol
 
 ### 1. Ensure Dev Server is Running

package/rules/hatch3r-browser-verification.mdc

@@ -26,6 +26,35 @@ Skip browser verification for:
 - CI/CD pipeline changes
 - Code refactors that do not alter rendered output
 
+## Session Prompt Pattern
+
+Browser verification is opt-in per command session. The orchestrator follows a standardized prompt flow so the user is asked exactly once.
+
+### Prompt Rules
+
+1. **At the START of any command that supports browser verification**, the orchestrator MUST ask the user once: *"Would you like to enable browser verification for this session? This uses Playwright to test changes in the running application."*
+2. **The user's answer applies to ALL stages of that command** — implementation, review, and verification. Do not re-ask at any subsequent stage.
+3. **If yes:** all implementation, review, and verification stages include browser testing steps as defined in the Verification Protocol below. The orchestrator ensures a dev server is running and executes browser checks at each verification point.
+4. **If no:** all browser verification steps are skipped silently. Do not emit warnings, reminders, or suggestions to reconsider. The command proceeds as if the Verification Protocol section does not exist.
+
+### Command Support Matrix
+
+| Supports Browser Verification | Does NOT Support |
+| ------------------------------ | ---------------- |
+| `hatch3r-workflow` | `hatch3r-board-fill` |
+| `hatch3r-board-pickup` | `hatch3r-board-groom` |
+| `hatch3r-quick-change` | `hatch3r-board-refresh` |
+| `hatch3r-revision` | `hatch3r-roadmap` |
+| `hatch3r-debug` | `hatch3r-release` |
+| | `hatch3r-refactor-plan` |
+| | `hatch3r-security-audit` |
+| | `hatch3r-rule-customize` |
+| | `hatch3r-skill-customize` |
+
+Commands in the "Does NOT Support" column are documentation-only, planning-only, or non-implementation commands. They MUST NOT prompt for browser verification.
+
+---
+
 ## Verification Protocol
 
 ### 1. Ensure Dev Server is Running

package/rules/hatch3r-ci-cd.md

@@ -3,6 +3,7 @@ id: hatch3r-ci-cd
 type: rule
 description: CI/CD pipeline standards covering stage gates, deployment strategies, and rollback procedures
 scope: always
+tags: [devops]
 ---
 # CI/CD Standards
 
@@ -64,7 +65,10 @@ scope: always
 ## Secrets Management in CI
 
 - Never store secrets in pipeline configuration files.
-- Use the CI platform's secret storage (GitHub Secrets, GitLab CI Variables, etc.).
+- Use the CI platform's secret storage:
+  - **GitHub:** GitHub Secrets (repository or organization level)
+  - **Azure DevOps:** Pipeline variables (marked secret) or Azure Key Vault linked variable groups
+  - **GitLab:** CI/CD Variables (project or group level, marked Protected and Masked)
 - Rotate CI secrets on a regular schedule (at least quarterly).
 - Audit secret access logs for unauthorized usage.
 - Use OIDC-based authentication for cloud provider access instead of long-lived credentials.

package/rules/hatch3r-ci-cd.mdc

@@ -62,7 +62,10 @@ alwaysApply: true
 ## Secrets Management in CI
 
 - Never store secrets in pipeline configuration files.
-- Use the CI platform's secret storage (GitHub Secrets, GitLab CI Variables, etc.).
+- Use the CI platform's secret storage:
+  - **GitHub:** GitHub Secrets (repository or organization level)
+  - **Azure DevOps:** Pipeline variables (marked secret) or Azure Key Vault linked variable groups
+  - **GitLab:** CI/CD Variables (project or group level, marked Protected and Masked)
 - Rotate CI secrets on a regular schedule (at least quarterly).
 - Audit secret access logs for unauthorized usage.
 - Use OIDC-based authentication for cloud provider access instead of long-lived credentials.

package/rules/hatch3r-code-standards.md

@@ -3,6 +3,7 @@ id: hatch3r-code-standards
 type: rule
 description: Code quality and file naming conventions for the project
 scope: always
+tags: [core]
 ---
 # Code Standards
 
@@ -81,6 +82,15 @@ scope: always
 - Log the full error (including stack trace) at the boundary. Return a safe, sanitized error response to the caller — no internal details.
 - Let errors propagate naturally within a module. Catching errors mid-flow and re-throwing obscures the stack trace. Handle at the boundary.
 
+### General Error Discipline
+
+- Never swallow errors silently. Always re-throw or log with context.
+- User-facing errors are separate from internal errors. Never expose internal details to clients.
+- API endpoints return structured error responses `{ code, message, details? }`. Never return stack traces.
+- Retry with exponential backoff for transient failures (network, rate limits). Honor `Retry-After` on 429.
+- Include `correlationId` in all error logs for tracing across client and server.
+- No secrets, tokens, or PII in error messages or logs.
+
 ## Import Ordering
 
 Enforce consistent import ordering via linter rules (e.g., `eslint-plugin-import`). The canonical order:
@@ -93,6 +103,14 @@ Enforce consistent import ordering via linter rules (e.g., `eslint-plugin-import
 
 Separate each group with a blank line. Sort alphabetically within each group.
 
+## Monorepo Conventions
+
+When working in a monorepo (multiple packages or apps in a single repository):
+
+- **Scope changes to a single package at a time.** A PR should touch one package unless the change requires a coordinated cross-package update (e.g., a shared type change and its consumers). Coordinated changes must be documented in the PR description.
+- **Run tests only for affected packages.** Use the monorepo tool's filtering (e.g., `--filter`, `--scope`, `--since`) to run tests, lint, and builds only for packages affected by the current change.
+- **Respect package boundaries — do not import across packages without explicit dependency.** If package A needs something from package B, B must be declared as a dependency in A's `package.json` (or equivalent manifest). Direct file-path imports across package boundaries are forbidden.
+
 ## Dead Code Prevention
 
 - Remove unused imports, variables, functions, and type definitions immediately. Do not comment them out "for later."

package/rules/hatch3r-code-standards.mdc

@@ -1,5 +1,5 @@
 ---
-description: TypeScript and file naming conventions for the project
+description: Code quality and file naming conventions for the project
 alwaysApply: true
 ---
 # Code Standards
@@ -79,6 +79,15 @@ alwaysApply: true
 - Log the full error (including stack trace) at the boundary. Return a safe, sanitized error response to the caller — no internal details.
 - Let errors propagate naturally within a module. Catching errors mid-flow and re-throwing obscures the stack trace. Handle at the boundary.
 
+### General Error Discipline
+
+- Never swallow errors silently. Always re-throw or log with context.
+- User-facing errors are separate from internal errors. Never expose internal details to clients.
+- API endpoints return structured error responses `{ code, message, details? }`. Never return stack traces.
+- Retry with exponential backoff for transient failures (network, rate limits). Honor `Retry-After` on 429.
+- Include `correlationId` in all error logs for tracing across client and server.
+- No secrets, tokens, or PII in error messages or logs.
+
 ## Import Ordering
 
 Enforce consistent import ordering via linter rules (e.g., `eslint-plugin-import`). The canonical order:

package/rules/hatch3r-component-conventions.md

@@ -1,7 +1,10 @@
 ---
+id: hatch3r-component-conventions
+type: rule
 description: Rules for component development in web applications
+scope: conditional
 globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx
-alwaysApply: false
+tags: [implementation]
 ---
 # Component Conventions
 

package/rules/hatch3r-data-classification.md

@@ -3,6 +3,7 @@ id: hatch3r-data-classification
 type: rule
 description: Data classification standards covering PII handling, encryption, retention policies, and regulatory compliance
 scope: always
+tags: [security]
 ---
 # Data Classification Standards
 

package/rules/hatch3r-deep-context.md

@@ -0,0 +1,94 @@
+---
+id: hatch3r-deep-context
+type: rule
+description: Adaptive pre-implementation analysis — complexity scoring, requirements elicitation, similar implementation discovery, and transitive dependency tracing before coding
+scope: always
+tags: [core]
+---
+# Deep Context Analysis
+
+Before implementing any non-trivial task, assess its complexity and run proportional pre-implementation analysis. This rule ensures the agent asks the right questions, discovers existing patterns to follow, and maps the full blast radius before writing code.
+
+## Complexity Scoring
+
+Score every task against these signals before implementation. Each signal adds weight:
+
+| Signal | Weight | Detection |
+|--------|--------|-----------|
+| Multiple modules/layers touched (data + API + UI, etc.) | +3 | Count distinct architectural layers in the task description and affected files |
+| Vague or underspecified terms ("improve", "better", "proper", "handle", "support", "clean up") | +2 | Scan task description for ambiguous language |
+| Cross-cutting concerns triggered (auth, i18n, a11y, payments, migrations, observability) | +2 | Match task against known cross-cutting domains |
+| Epic or multi-issue scope | +3 | Task references multiple issues, contains numbered sub-tasks, or spans multiple features |
+| New dependency or integration introduction | +2 | Task mentions new libraries, services, or external APIs |
+| Estimated file count > 5 | +2 | Infer from task scope and codebase exploration |
+| Security-sensitive area (auth, payments, data access, secrets) | +2 | Match task against security-sensitive directories or keywords |
+| Behavioral contract change (API signature, event schema, type interface) | +2 | Task implies changes to shared interfaces or public APIs |
+
+### Tier Assignment
+
+| Total Weight | Tier | Label |
+|-------------|------|-------|
+| 0–2 | 1 | Light |
+| 3–5 | 2 | Standard |
+| 6+ | 3 | Deep |
+
+## Tier Actions
+
+### Tier 1 — Light
+
+Single-file changes, config tweaks, typo fixes, comment edits, constant value changes. No additional analysis required beyond existing researcher modes.
+
+Skip deep context analysis entirely. Proceed with the standard pipeline.
+
+### Tier 2 — Standard
+
+Multi-file changes with clear scope. Run these researcher modes at `quick` depth before implementation:
+
+1. **`requirements-elicitation`** at `quick` — scan for top ambiguities and ask 3–5 clarifying questions.
+2. **`similar-implementation`** at `quick` — find 1 reference implementation and extract top-level patterns.
+
+Present findings to the user inline. Proceed after answers are received — no separate confirmation checkpoint required.
+
+### Tier 3 — Deep
+
+Cross-module features, architectural changes, multi-layer implementations, or tasks with high ambiguity. Run these researcher modes at `deep` depth:
+
+1. **`requirements-elicitation`** at `deep` — full 10-dimension ambiguity scan, dependency-derived questions, cross-cutting concern checklist.
+2. **`similar-implementation`** at `deep` — find 2–3 reference implementations, full convention extraction, divergence analysis.
+3. **`codebase-impact`** at `deep` — full transitive dependency tracing, API consumer map, blast radius summary.
+
+**Mandatory checkpoint:** Present a consolidated "Pre-Implementation Summary" to the user and ASK for confirmation before proceeding to implementation:
+
+```
+Pre-Implementation Summary:
+  Complexity: Tier 3 (Deep) — score {N}
+  Resolved requirements: {N}/{M} dimensions addressed
+  Unresolved questions: {list — these MUST be answered before proceeding}
+  Reference implementation: {name} — conventions locked
+  Blast radius: {N} files directly affected, {M} transitively at risk
+  Cross-cutting concerns: {list with status}
+```
+
+Do NOT proceed to implementation until all unresolved questions are answered by the user.
+
+## Passing Context to Implementer
+
+When the `similar-implementation` mode produces reference implementations, include them in the implementer sub-agent prompt as **"Reference Conventions"**. The implementer's Convention Lock step (Step 1b) uses these to align its architectural decisions with established codebase patterns.
+
+When the `requirements-elicitation` mode produces resolved requirements, include the user's answers in the implementer sub-agent prompt as **"Resolved Requirements"** so the implementer has explicit answers to all ambiguities rather than guessing.
+
+When the enhanced `codebase-impact` mode produces a blast radius summary, include it in the implementer sub-agent prompt so the implementer knows which consumers and contracts must be preserved.
+
+## Integration with Existing Pipeline
+
+This rule augments — not replaces — the existing Universal Sub-Agent Pipeline from `hatch3r-agent-orchestration`. The complexity scoring happens at the start of Phase 1 (Research), and the additional researcher modes run alongside the existing task-type modes:
+
+- **`type:feature`**: existing modes `codebase-impact`, `feature-design`, `architecture` + new modes per tier
+- **`type:bug`**: existing modes `symptom-trace`, `root-cause`, `codebase-impact` + `requirements-elicitation` per tier (bugs often have underspecified reproduction steps)
+- **`type:refactor`**: existing modes `current-state`, `refactoring-strategy`, `migration-path` + `similar-implementation` per tier (refactors benefit most from convention alignment)
+
+## Exceptions
+
+- **`hatch3r-quick-change` command**: Tier 1 items proceed without research. Tier 2 items get lightweight `similar-implementation` at `quick` depth. Tier 3 items must be routed to `hatch3r-workflow` (hard block).
+- **Trivial single-line edits**: Always Tier 1 regardless of scoring signals. This is the only valid basis for skipping research — label-based shortcuts (e.g., `risk:low AND priority:p3`) are not sufficient alone.
+- **`hatch3r-revision` command**: Operates on already-implemented code. Deep context analysis applies to the original implementation, not the revision pass.

package/rules/hatch3r-deep-context.mdc

@@ -0,0 +1,69 @@
+---
+description: Adaptive pre-implementation analysis — complexity scoring, requirements elicitation, similar implementation discovery, and transitive dependency tracing before coding
+alwaysApply: true
+---
+# Deep Context Analysis
+
+Before implementing any non-trivial task, assess its complexity and run proportional pre-implementation analysis. This rule ensures the agent asks the right questions, discovers existing patterns to follow, and maps the full blast radius before writing code.
+
+## Complexity Scoring
+
+Score every task against these signals before implementation. Each signal adds weight:
+
+| Signal | Weight | Detection |
+|--------|--------|-----------|
+| Multiple modules/layers touched (data + API + UI, etc.) | +3 | Count distinct architectural layers in the task description and affected files |
+| Vague or underspecified terms ("improve", "better", "proper", "handle", "support", "clean up") | +2 | Scan task description for ambiguous language |
+| Cross-cutting concerns triggered (auth, i18n, a11y, payments, migrations, observability) | +2 | Match task against known cross-cutting domains |
+| Epic or multi-issue scope | +3 | Task references multiple issues, contains numbered sub-tasks, or spans multiple features |
+| New dependency or integration introduction | +2 | Task mentions new libraries, services, or external APIs |
+| Estimated file count > 5 | +2 | Infer from task scope and codebase exploration |
+| Security-sensitive area (auth, payments, data access, secrets) | +2 | Match task against security-sensitive directories or keywords |
+| Behavioral contract change (API signature, event schema, type interface) | +2 | Task implies changes to shared interfaces or public APIs |
+
+### Tier Assignment
+
+| Total Weight | Tier | Label |
+|-------------|------|-------|
+| 0–2 | 1 | Light |
+| 3–5 | 2 | Standard |
+| 6+ | 3 | Deep |
+
+## Tier Actions
+
+### Tier 1 — Light
+
+Single-file changes, config tweaks, typo fixes, comment edits, constant value changes. No additional analysis required beyond existing researcher modes. Skip deep context analysis entirely.
+
+### Tier 2 — Standard
+
+Multi-file changes with clear scope. Run these researcher modes at `quick` depth before implementation:
+
+1. **`requirements-elicitation`** at `quick` — scan for top ambiguities and ask 3–5 clarifying questions.
+2. **`similar-implementation`** at `quick` — find 1 reference implementation and extract top-level patterns.
+
+Present findings to the user inline. Proceed after answers are received.
+
+### Tier 3 — Deep
+
+Cross-module features, architectural changes, multi-layer implementations, or tasks with high ambiguity. Run these researcher modes at `deep` depth:
+
+1. **`requirements-elicitation`** at `deep` — full 10-dimension ambiguity scan, dependency-derived questions, cross-cutting concern checklist.
+2. **`similar-implementation`** at `deep` — find 2–3 reference implementations, full convention extraction, divergence analysis.
+3. **`codebase-impact`** at `deep` — full transitive dependency tracing, API consumer map, blast radius summary.
+
+**Mandatory checkpoint:** Present a consolidated "Pre-Implementation Summary" to the user and ASK for confirmation before proceeding. Do NOT proceed until all unresolved questions are answered.
+
+## Passing Context to Implementer
+
+When the `similar-implementation` mode produces reference implementations, include them in the implementer sub-agent prompt as **"Reference Conventions"**. When the `requirements-elicitation` mode produces resolved requirements, include the user's answers as **"Resolved Requirements"**. When `codebase-impact` produces a blast radius summary, include it so the implementer knows which consumers and contracts must be preserved.
+
+## Integration with Existing Pipeline
+
+This rule augments the existing Universal Sub-Agent Pipeline from `hatch3r-agent-orchestration`. The complexity scoring happens at the start of Phase 1 (Research), and the additional researcher modes run alongside the existing task-type modes.
+
+## Exceptions
+
+- **`hatch3r-quick-change`**: Tier 1 items proceed without research. Tier 2 items get lightweight `similar-implementation` at `quick` depth. Tier 3 items must be routed to `hatch3r-workflow` (hard block).
+- **Trivial single-line edits**: Always Tier 1 regardless of scoring. This is the only valid basis for skipping research — label-based shortcuts (e.g., `risk:low AND priority:p3`) are not sufficient alone.
+- **`hatch3r-revision`**: Operates on already-implemented code; deep context analysis applies to the original implementation.

package/rules/hatch3r-dependency-management.md

@@ -3,6 +3,7 @@ id: hatch3r-dependency-management
 type: rule
 description: Rules for managing project dependencies
 scope: always
+tags: [maintenance]
 ---
 # Dependency Management
 
@@ -15,3 +16,15 @@ scope: always
 - Remove unused dependencies on every cleanup pass.
 - Security patches (CVEs) are P0/P1 priority. Patch within 48h for critical.
 - Check bundle size impact against budget. Reject deps that exceed.
+
+## Transitive Dependency Hygiene
+
+- Audit transitive dependencies, not just direct ones. A direct dependency with a compromised transitive dep is still a vulnerability. Use `npm ls`, `pip show`, or `cargo tree` to inspect the full dependency graph.
+- When a transitive dependency has a known CVE, determine whether the vulnerable code path is reachable from your project. If reachable, override or patch the transitive dep. If unreachable, document the finding with justification for deferral.
+- Avoid dependencies that pull in excessively large transitive trees for minimal functionality. If a package adds 50+ transitive deps for a single utility function, write the utility inline or find a lighter alternative.
+
+## Version Upgrade Strategy
+
+- Review changelogs and migration guides before upgrading major versions. Never blindly bump major versions and assume backward compatibility.
+- Run the full test suite after any dependency upgrade, including integration tests. A passing unit test suite does not guarantee compatibility with upgraded peer dependencies.
+- When upgrading a shared dependency used across multiple modules, upgrade all consumers in the same PR to avoid version skew within the monorepo or project.

package/rules/hatch3r-feature-flags.md

@@ -1,6 +1,9 @@
 ---
+id: hatch3r-feature-flags
+type: rule
 description: Feature flag patterns and lifecycle for the project
-alwaysApply: false
+scope: conditional
+tags: [implementation]
 ---
 # Feature Flags
 

package/rules/hatch3r-git-conventions.md

@@ -3,6 +3,7 @@ id: hatch3r-git-conventions
 type: rule
 description: Git commit message and branching conventions
 scope: always
+tags: [core]
 ---
 # Git Conventions