hatch3r 1.8.0 → 1.9.0

package/{commands → dist/content/commands}/hatch3r-refactor-plan.md

@@ -44,7 +44,7 @@ The command produces phased todo.md entries that map to the appropriate executio
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that downstream commands like `hatch3r-board-fill` rely on. Cache any values found.
+**Read the `hatch3r-board-shared` skill at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that downstream commands like `hatch3r-board-fill` rely on. Cache any values found.
 
 ## Token-Saving Directives
 
@@ -114,10 +114,10 @@ Refactoring Brief:
    - `docs/specs/` — project specifications (read TOC/headers first, expand relevant sections only)
    - `docs/adr/` — architectural decision records (scan for decisions relevant to the target area)
    - `README.md` — project overview
-   - `.agents/hatch.json` — board configuration
+   - `.hatch3r/hatch.json` — board configuration
    - Existing `todo.md` — current backlog (check for overlap or related items)
 2. Scan GitHub issues via `search_issues` for existing work related to the refactoring area. Note in-progress work, dependencies, or prior refactoring attempts.
-3. If `.agents/learnings/` exists, scan for learnings relevant to the target area. Match by area and tags against the refactoring brief.
+3. If `.hatch3r/learnings/` exists, scan for learnings relevant to the target area. Match by area and tags against the refactoring brief.
 4. Scan test coverage in the target area — identify which parts have strong test coverage (safe to refactor) vs. weak coverage (need tests first).
 5. Present a context summary:
 
@@ -445,7 +445,7 @@ If yes, instruct the user to invoke the `hatch3r-board-fill` command. Note that
 - **Sub-agent failure:** Retry the failed sub-agent once. If it fails again, present partial results from the remaining sub-agents and ask the user how to proceed (continue without that researcher's input / provide the missing information manually / abort).
 - **Conflicting researcher outputs:** Present both options side by side with trade-offs. Ask the user to decide. Do not silently pick one.
 - **File write failure:** Report the error and provide the full file content so the user can create the file manually.
-- **Missing project context:** If no `hatch3r-board-shared` or `.agents/hatch.json` exists, proceed without board context — this command does not require board configuration.
+- **Missing project context:** If no `hatch3r-board-shared` or `.hatch3r/hatch.json` exists, proceed without board context — this command does not require board configuration.
 - **No existing specs or docs:** Proceed without spec references. Warn that the refactoring spec will be less contextualized without existing project documentation. Recommend running `hatch3r-project-spec` or `hatch3r-codebase-map` first for best results.
 - **Duplicate detection:** If the refactoring overlaps significantly with existing todo.md items or GitHub issues found in Step 2, present the overlap and ASK whether to proceed (augment existing / replace / abort).
 - **Weak test coverage:** If the current state analyzer finds weak test coverage in the target area, the migration path planner MUST include a Phase 0 for test scaffolding. Do not proceed with refactoring phases without adequate coverage.

package/{commands → dist/content/commands}/hatch3r-report.md

@@ -112,7 +112,7 @@ Create `.hatch3r/reports/` if missing. Write the rendered markdown (executive su
 ### File Footprint
 
 - 12 distinct files read; 9 distinct files edited
-- Top 3 most-read: src/cli/commands/validate.ts (4x), commands/hatch3r-context-health.md (2x), CHANGELOG.md (2x)
+- Top 3 most-read: src/cli/commands/validate.ts (4x), skills/hatch3r-context-health/SKILL.md (2x), CHANGELOG.md (2x)
 
 ### Diagnostics
 

package/{commands → dist/content/commands}/hatch3r-revision.md

@@ -4,7 +4,7 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-implementer, hatch3r-lint-fixer, hatch3r-test-writer, hatch3r-reviewer, hatch3r-fixer, hatch3r-security-auditor, hatch3r-docs-writer, hatch3r-a11y-auditor, hatch3r-perf-profiler]
 description: User-guided revision of agent-implemented code in a fresh context window. Reconstructs what was done, interviews the user for feedback, fixes issues, cleans up leftovers, and drives toward merge readiness. Delegation, quality pipeline, modes, and board integration details are in commands/revision/.
-tags: [implementation, team]
+tags: [implementation, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -53,7 +53,7 @@ The user is the reviewer. The agent is the interviewer and fixer.
 
 ## Shared Context
 
-**If board context exists** (current branch has an associated PR linked to issues), **read the `hatch3r-board-shared` command at the start of the run.** It contains Board Configuration, Platform Detection, Platform Context, Board Sync Procedure, and tooling directives. Cache all values for the duration of this run.
+**If board context exists** (current branch has an associated PR linked to issues), **read the `hatch3r-board-shared` skill at the start of the run.** It contains Board Configuration, Platform Detection, Platform Context, Board Sync Procedure, and tooling directives. Cache all values for the duration of this run.
 
 If no board context exists (plain instruction, no PR, no linked issues), skip shared context loading and work from the git diff alone.
 
@@ -105,7 +105,7 @@ Rebuild full context in the fresh window. No prior implementation context is ass
 #### 1a. Detect Scope of Changes
 
 1. Identify the current branch: `git branch --show-current`.
-2. Determine the default branch from `.agents/hatch.json` (`board.defaultBranch`). Fall back to `main` if unavailable.
+2. Determine the default branch from `.hatch3r/hatch.json` (`board.defaultBranch`). Fall back to `main` if unavailable.
 3. Compute the diff: `git diff {defaultBranch}...HEAD --stat` for a summary, then `git diff {defaultBranch}...HEAD` for the full diff.
 4. Parse the diff summary: files changed, lines added/removed, file types affected.
 5. Identify affected areas from the file paths (e.g., `src/routes/` -> API, `src/components/` -> UI, `tests/` -> testing).
@@ -114,7 +114,7 @@ Rebuild full context in the fresh window. No prior implementation context is ass
 
 > Platform-specific CLI commands: see `commands/board/shared-{platform}.md` for PR/issue lookup
 
-1. Detect the platform from `.agents/hatch.json` (`board.platform`). Fall back to GitHub if unavailable.
+1. Detect the platform from `.hatch3r/hatch.json` (`board.platform`). Fall back to GitHub if unavailable.
 2. Search for an open PR on this branch using the platform CLI:
    - **GitHub:** `gh pr list --head {branch} --state open --json number,title,body,url --limit 1`
    - **Azure DevOps:** `az repos pr list --source-branch {branch} --status active --top 1`
@@ -127,11 +127,11 @@ Rebuild full context in the fresh window. No prior implementation context is ass
 
 #### 1c. Load Project Rules
 
-Read all `scope: always` rules from `.agents/rules/`. These must be included in every sub-agent prompt in Step 6.
+Read all `scope: always` rules from `rules/`. These must be included in every sub-agent prompt in Step 6.
 
 #### 1d. Consult Learnings
 
-If `.agents/learnings/` exists, scan for learnings with matching areas or tags that overlap with the affected areas from Step 1a.5. Cache relevant learnings for Step 6.
+If `.hatch3r/learnings/` exists, scan for learnings with matching areas or tags that overlap with the affected areas from Step 1a.5. Cache relevant learnings for Step 6.
 
 ---
 
@@ -460,7 +460,7 @@ Capture revision-specific learnings. Focus on patterns that inform future implem
    - Were there any integration issues between sub-agent outputs?
 
 2. If significant learnings are identified:
-   - Create learning files in `.agents/learnings/` following the `hatch3r-learn` command format.
+   - Create learning files in `.hatch3r/learnings/` following the `hatch3r-learn` command format.
    - Use category `pitfall` for issues agents commonly miss.
    - Use category `pattern` for revision approaches that worked well.
    - Tag with relevant area labels.

package/{commands → dist/content/commands}/hatch3r-roadmap.md

@@ -4,7 +4,7 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Sequence delivery phases over time into a dependency-ordered milestone plan with business and technical lenses, emitting a todo.md rollout schedule rather than design docs
-tags: [planning, greenfield]
+tags: [planning, ctx:greenfield-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -35,7 +35,7 @@ Generate a dependency-aware, priority-ordered roadmap with **two parallel dimens
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run.** It contains Board Configuration, GitHub Context, Project Reference, Projects v2 sync procedure, and tooling directives. Cache all values for the duration of this run.
+**Read the `hatch3r-board-shared` skill at the start of the run.** It contains Board Configuration, GitHub Context, Project Reference, Projects v2 sync procedure, and tooling directives. Cache all values for the duration of this run.
 
 ## Token-Saving Directives
 

package/{commands → dist/content/commands}/hatch3r-security-audit.md

@@ -3,7 +3,7 @@ id: hatch3r-security-audit
 type: command
 orchestrator: false
 description: Open an OWASP ASI security epic reviewing auth boundaries, input validation, and supply-chain risks with one hardening sub-issue per module plus trust-boundary audit
-tags: [maintenance, security]
+tags: [maintenance, floor:security]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -34,7 +34,7 @@ Create a security audit epic on **{owner}/{repo}** with one sub-issue per logica
 
 ## Shared Context
 
-**Read the project's shared board context at the start of the run** (e.g., `.agents/commands/hatch3r-board-shared.md` or equivalent). It contains GitHub Context, Project Reference, Projects v2 sync procedure, and Board Overview template. Cache all values for the duration of this run.
+**Read the project's shared board context at the start of the run** (e.g., `commands/hatch3r-board-shared/SKILL.md` or equivalent). It contains GitHub Context, Project Reference, Projects v2 sync procedure, and Board Overview template. Cache all values for the duration of this run.
 
 ## Token-Saving Directives
 

package/{commands → dist/content/commands}/hatch3r-test-plan.md

@@ -4,7 +4,7 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Plan a comprehensive test strategy -- spawn parallel researchers, produce test plan spec with coverage targets, priority ordering, test case outlines, and structured todo.md entries for board-fill.
-tags: [core, planning]
+tags: [planning, orchestration]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -35,7 +35,7 @@ Take a test planning scope (feature, module, or codebase area) and produce a com
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that downstream commands like `hatch3r-board-fill` rely on. Cache any values found.
+**Read the `hatch3r-board-shared` skill at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that downstream commands like `hatch3r-board-fill` rely on. Cache any values found.
 
 ## Token-Saving Directives
 
@@ -122,11 +122,11 @@ Answer these now, or say 'use defaults' for any where you're comfortable with a
    - `docs/specs/` -- project specifications (read TOC/headers first, expand relevant sections only)
    - `docs/adr/` -- architectural decision records (scan for testing-related decisions)
    - `README.md` -- project overview
-   - `.agents/hatch.json` -- board configuration
+   - `.hatch3r/hatch.json` -- board configuration
    - Existing `todo.md` -- current backlog (check for overlap or related items)
    - Feature spec -- if mode is feature-scoped, look for the referenced feature spec in `docs/specs/`
 2. Scan GitHub issues via `search_issues` for existing testing-related work. Note duplicates or partial overlaps.
-3. If `.agents/learnings/` exists, scan for learnings relevant to testing, coverage, or quality.
+3. If `.hatch3r/learnings/` exists, scan for learnings relevant to testing, coverage, or quality.
 4. Present a context summary:
 
 ```
@@ -534,7 +534,7 @@ If `hatch3r-board-fill`: instruct the user to invoke `hatch3r-board-fill`. Note
 - **Sub-agent failure:** Retry the failed sub-agent once. If it fails again, present partial results from the remaining sub-agents and ask the user how to proceed (continue without that researcher's input / provide the missing information manually / abort).
 - **Conflicting researcher outputs:** Present both options side by side with trade-offs. Ask the user to decide. Do not silently pick one.
 - **File write failure:** Report the error and provide the full file content so the user can create the file manually.
-- **Missing project context:** If no `hatch3r-board-shared` or `.agents/hatch.json` exists, proceed without board context -- this command does not require board configuration.
+- **Missing project context:** If no `hatch3r-board-shared` or `.hatch3r/hatch.json` exists, proceed without board context -- this command does not require board configuration.
 - **No existing tests:** Switch to bootstrapping strategy -- the test plan becomes a greenfield test setup plan. Include infrastructure setup (framework installation, config, CI gates) as P0 items. Warn that coverage baselines will be unavailable.
 - **No coverage tooling:** Recommend coverage setup as a prerequisite. Include coverage tooling installation as a P0 infrastructure item in the test plan. Proceed with estimated coverage from code analysis rather than measured coverage.
 - **Feature spec not found (feature-scoped mode):** Warn that the test plan will be less informed without a feature spec. Recommend running `hatch3r-feature-plan` first for best results. Proceed with what's available from codebase analysis.

package/{commands → dist/content/commands}/hatch3r-workflow.md

@@ -4,7 +4,7 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-researcher, hatch3r-implementer, hatch3r-reviewer, hatch3r-fixer, hatch3r-test-writer, hatch3r-security-auditor, hatch3r-docs-writer, hatch3r-lint-fixer, hatch3r-a11y-auditor, hatch3r-perf-profiler]
 description: Guided development lifecycle with 4 phases (Analyze, Plan, Implement, Review) and scale-adaptive Quick Mode for small tasks.
-tags: [core, implementation]
+tags: [implementation, orchestration]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -51,7 +51,7 @@ If **no**: all browser verification steps are skipped silently throughout the en
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run.** It contains Board Configuration, GitHub Context, Project Reference, Projects v2 sync procedure, and tooling directives. Cache all values for the duration of this run.
+**Read the `hatch3r-board-shared` skill at the start of the run.** It contains Board Configuration, GitHub Context, Project Reference, Projects v2 sync procedure, and tooling directives. Cache all values for the duration of this run.
 
 ## Global Rule Overrides
 
@@ -151,7 +151,7 @@ Cache the researcher outputs for use in Phase 2 and Phase 3.
 
 #### 1d. Consult Learnings
 
-If `.agents/learnings/` exists:
+If `.hatch3r/learnings/` exists:
 
 1. Search for learnings tagged with relevant areas or technologies.
 2. Surface any applicable past experiences that inform this task.
@@ -261,8 +261,8 @@ The implementer sub-agent prompt MUST include:
 - The task description, acceptance criteria, and type.
 - The researcher output from Step 3a (if not skipped).
 - The selected hatch3r skill name and instructions.
-- All `scope: always` rule directives from `.agents/rules/`.
-- Relevant learnings from `.agents/learnings/`.
+- All `scope: always` rule directives from `rules/`.
+- Relevant learnings from `.hatch3r/learnings/`.
 - Explicit instruction: do NOT create branches, commits, or PRs.
 - **Reference conventions** from `similar-implementation` output (Tier 2/3) — triggers the implementer's Convention Lock step.
 - **Resolved requirements** from `requirements-elicitation` answers (Tier 2/3) — explicit decisions on ambiguities.
@@ -310,7 +310,7 @@ After each reviewer iteration, assess the reviewer's findings confidence: if the
 
 Each reviewer/fixer sub-agent prompt MUST include:
 - The agent protocol to follow.
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 - The diff or file changes to review/fix.
 - The task's acceptance criteria.
 - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
@@ -336,7 +336,7 @@ Each reviewer/fixer sub-agent prompt MUST include:
 
 Each specialist sub-agent prompt MUST include:
 - The agent protocol to follow.
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 - The diff or file changes to review.
 - The task's acceptance criteria.
 - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
@@ -371,10 +371,10 @@ Review Results:
 
 #### 4e. Capture Learnings
 
-If `.agents/learnings/` exists:
+If `.hatch3r/learnings/` exists:
 
 1. Extract learnings from this implementation session (patterns discovered, pitfalls encountered, decisions made).
-2. Store in `.agents/learnings/` with appropriate area tags.
+2. Store in `.hatch3r/learnings/` with appropriate area tags.
 
 ---
 

package/{commands → dist/content/commands}/revision/revision-delegation.md

@@ -63,9 +63,9 @@ Each sub-agent prompt MUST include:
 
 1. The specific findings to address (file paths, line numbers, descriptions, expected behavior).
 2. Instruction to follow the corresponding agent protocol (e.g., "Follow the hatch3r-implementer agent protocol").
-3. All `scope: always` rule directives from `.agents/rules/` — sub-agents do not inherit rules automatically.
+3. All `scope: always` rule directives from `rules/` — sub-agents do not inherit rules automatically.
 4. Acceptance criteria from linked issues (if available from Step 1b).
-5. Relevant learnings from `.agents/learnings/` (if found in Step 1d).
+5. Relevant learnings from `.hatch3r/learnings/` (if found in Step 1d).
 6. Explicit instruction: do NOT create branches, commits, or PRs.
 7. Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 8. Revision-specific constraint: "You are fixing existing code, not implementing new features. Stay within the architecture established by the original implementation."

package/{commands → dist/content/commands}/revision/revision-quality.md

@@ -38,7 +38,7 @@ Run an iterative review loop (max 3 iterations) until 0 Critical + 0 Warning fin
 
 The reviewer prompt MUST include:
 - The diff of all changes made (use `git diff` on the working tree).
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 - Iteration number and previous findings (if not the first iteration).
 - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 
@@ -82,7 +82,7 @@ After the review loop is clean, spawn specialist agents in parallel via the Task
 
 Each specialist sub-agent prompt MUST include:
 - The agent protocol to follow (e.g., "Follow the hatch3r-test-writer agent protocol").
-- All `scope: always` rule directives from `.agents/rules/` (sub-agents do not inherit rules automatically).
+- All `scope: always` rule directives from `rules/` (sub-agents do not inherit rules automatically).
 - The diff or file changes to review.
 - The linked issue's acceptance criteria (if available).
 - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.

package/{github-agents → dist/content/github-agents}/hatch3r-docs-agent.md

@@ -3,7 +3,7 @@ name: hatch3r-docs-agent
 type: github-agent
 description: Technical writer who maintains specs, ADRs, and documentation
 # Simplified agent for GitHub Copilot/Codex
-tags: [team, devops]
+tags: [devops, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{github-agents → dist/content/github-agents}/hatch3r-lint-agent.md

@@ -3,7 +3,7 @@ name: hatch3r-lint-agent
 type: github-agent
 description: Code quality enforcer who fixes style, formatting, and type issues
 # Simplified agent for GitHub Copilot/Codex
-tags: [team, devops]
+tags: [devops, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{github-agents → dist/content/github-agents}/hatch3r-security-agent.md

@@ -3,7 +3,7 @@ name: hatch3r-security-agent
 type: github-agent
 description: Security analyst who audits code, rules, and data flows
 # Simplified agent for GitHub Copilot/Codex
-tags: [team, devops]
+tags: [devops, floor:security, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{github-agents → dist/content/github-agents}/hatch3r-test-agent.md

@@ -3,7 +3,7 @@ name: hatch3r-test-agent
 type: github-agent
 description: QA engineer who writes and maintains tests
 # Simplified agent for GitHub Copilot/Codex
-tags: [team, devops]
+tags: [review, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{hooks → dist/content/hooks}/hatch3r-ci-failure.md

@@ -4,7 +4,7 @@ type: hook
 event: ci-failure
 agent: ci-watcher
 description: Diagnose CI pipeline failures
-tags: [core]
+tags: [devops]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -22,7 +22,7 @@ When this hook fires, the assigned agent should:
 4. For test failures: identify the specific failing test(s), expected vs. actual values, and the source file(s) involved.
 5. For build/type errors: extract the compiler error message and the source location.
 6. Produce a root-cause hypothesis with a concrete suggested fix (code change, config change, or retry recommendation for flaky failures).
-7. If the failure matches a known pattern from `.agents/learnings/`, reference the relevant learning.
+7. If the failure matches a known pattern from `.hatch3r/learnings/`, reference the relevant learning.
 
 ## Expected Output
 
@@ -33,7 +33,7 @@ A structured diagnostic report containing:
 - **Root cause**: Concise explanation of why the failure occurred.
 - **Error excerpt**: The relevant log output (truncated to key lines).
 - **Suggested fix**: Specific, actionable remediation steps.
-- **Related learnings**: Links to any matching entries in `.agents/learnings/` (if applicable).
+- **Related learnings**: Links to any matching entries in `.hatch3r/learnings/` (if applicable).
 
 ## Configuration
 

package/{hooks → dist/content/hooks}/hatch3r-file-save.md

@@ -5,7 +5,7 @@ event: file-save
 agent: context-rules
 description: Activate context-specific rules on file save
 globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
-tags: [core]
+tags: [orchestration]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -17,7 +17,7 @@ Activate context-specific rules when a file is saved, applying relevant coding s
 
 When this hook fires, the assigned agent should:
 
-1. Determine the saved file's path and match it against the project's rule definitions in `.agents/rules/`.
+1. Determine the saved file's path and match it against the project's rule definitions in `rules/`.
 2. Load all rules where `scope: always` applies, plus any rules with glob patterns matching the saved file's path.
 3. Evaluate the saved file's contents against the loaded rules — check for convention violations, pattern mismatches, or missing required elements (e.g., missing error handling in API routes, missing accessibility attributes in components).
 4. If violations are found, surface them as inline warnings or suggestions (not blocking — file-save hooks should be non-disruptive).
@@ -31,5 +31,5 @@ When this hook fires, the assigned agent should:
 ## Configuration
 
 - **Globs**: Controlled by the `globs` frontmatter field. Adjust to match your project's source file extensions.
-- **Rule sources**: Reads from `.agents/rules/`. Rules with matching `globs` or `scope: always` are activated.
+- **Rule sources**: Reads from `rules/`. Rules with matching `globs` or `scope: always` are activated.
 - **Debounce**: To avoid excessive processing during rapid saves, the agent debounces with a 2-second window (configurable via `debounceMs`).

package/{hooks → dist/content/hooks}/hatch3r-post-merge.md

@@ -4,7 +4,7 @@ type: hook
 event: post-merge
 agent: ci-watcher
 description: Check CI pipeline status after merge
-tags: [core]
+tags: [devops]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{hooks → dist/content/hooks}/hatch3r-pre-commit.md

@@ -5,7 +5,7 @@ event: pre-commit
 agent: lint-fixer
 description: Auto-fix lint and formatting issues before commit
 globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
-tags: [core]
+tags: [implementation]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{hooks → dist/content/hooks}/hatch3r-pre-push.md

@@ -4,7 +4,7 @@ type: hook
 event: pre-push
 agent: security-auditor
 description: Scan for secrets and security issues before push
-tags: [core]
+tags: [floor:security]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -29,6 +29,6 @@ When this hook fires, the assigned agent should:
 
 ## Configuration
 
-- **Allowlist**: Add known false positives to `.agents/security/secret-allowlist.json` (patterns or file paths to ignore).
-- **Pattern extensions**: The agent uses built-in patterns for common secret types. Add project-specific patterns via `.agents/security/custom-patterns.json`.
+- **Allowlist**: Add known false positives to `.hatch3r/security/secret-allowlist.json` (patterns or file paths to ignore).
+- **Pattern extensions**: The agent uses built-in patterns for common secret types. Add project-specific patterns via `.hatch3r/security/custom-patterns.json`.
 - **Scope**: By default, scans only the diff of outgoing commits. Set `scanFullHistory: true` to scan all files (slower, useful for initial audits).

package/{hooks → dist/content/hooks}/hatch3r-session-start.md

@@ -4,7 +4,7 @@ type: hook
 event: session-start
 agent: learnings-loader
 description: Load relevant learnings at session start
-tags: [core]
+tags: [orchestration]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -16,11 +16,11 @@ Activate the learnings-loader agent when a new coding session starts to surface
 
 When this hook fires, the assigned agent should:
 
-1. Read the `.agents/learnings/` directory and index all available learning files by area, tags, and recency.
+1. Read the `.hatch3r/learnings/` directory and index all available learning files by area, tags, and recency.
 2. Identify the most relevant learnings based on recently modified files in the working tree (using `git diff` and `git log` to infer the active work area).
 3. Surface the top 3-5 most relevant learnings as a brief summary, prioritizing: (a) learnings from the last 7 days, (b) learnings matching the current branch's area labels, (c) learnings tagged as high-impact or cross-cutting.
 4. If there are recent architectural decisions or convention changes, highlight them prominently.
-5. If `.agents/learnings/` does not exist or is empty, skip silently.
+5. If `.hatch3r/learnings/` does not exist or is empty, skip silently.
 
 ## Expected Output
 

package/{rules → dist/content/rules}/hatch3r-accessibility-standards.md

@@ -3,7 +3,8 @@ id: hatch3r-accessibility-standards
 type: rule
 description: Accessibility standards covering WCAG 2.2 AA compliance, keyboard navigation, screen readers, and ARIA patterns
 scope: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/components/**,**/*.html,**/*a11y*,**/*accessibility*"
-tags: [a11y]
+tags: [floor:ui-ux, a11y]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{rules → dist/content/rules}/hatch3r-accessibility-standards.mdc

@@ -2,6 +2,7 @@
 description: Accessibility standards covering WCAG 2.2 AA compliance, keyboard navigation, screen readers, and ARIA patterns
 globs: ["**/*.vue", "**/*.jsx", "**/*.tsx", "**/*.svelte", "**/components/**", "**/*.html", "**/*a11y*", "**/*accessibility*"]
 alwaysApply: false
+precedence: high
 ---
 # Accessibility Standards
 

package/{rules → dist/content/rules}/hatch3r-agent-orchestration-detail.md

@@ -3,8 +3,8 @@ id: hatch3r-agent-orchestration-detail
 type: rule
 description: Extended orchestration reference — PipelineContext schemas, resilience protocols, observability integration, and auto-mode guardrails
 scope: conditional
-globs: "**/.agents/**,**/pipeline/**,**/*orchestrat*,**/*agent*"
-tags: [core]
+globs: "**/.hatch3r/**,**/pipeline/**,**/*orchestrat*,**/*agent*"
+tags: [orchestration, floor:protocol]
 precedence: normal
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true

package/{rules → dist/content/rules}/hatch3r-agent-orchestration-detail.mdc

@@ -1,6 +1,6 @@
 ---
 description: Extended orchestration reference — PipelineContext schemas, resilience protocols, observability integration, and auto-mode guardrails
-globs: ["**/.agents/**", "**/pipeline/**", "**/*orchestrat*", "**/*agent*"]
+globs: ["**/.hatch3r/**", "**/pipeline/**", "**/*orchestrat*", "**/*agent*"]
 alwaysApply: false
 precedence: normal
 detail_rule: true

package/{rules → dist/content/rules}/hatch3r-agent-orchestration.md

@@ -3,7 +3,7 @@ id: hatch3r-agent-orchestration
 type: rule
 description: Mandatory agent delegation, skill loading, and subagent usage directives for ALL tasks in ALL contexts
 scope: always
-tags: [core]
+tags: [orchestration, floor:protocol]
 precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
@@ -371,6 +371,6 @@ All `scope: always` rules apply to every task including subagent work. Include r
 - `hatch3r-dependency-management` -- dependency-auditor
 
 **Tier 3 -- On-demand:**
-- `hatch3r-api-design`, `hatch3r-secrets-management`, `hatch3r-data-classification`, `hatch3r-performance-budgets`, `hatch3r-browser-verification`, `hatch3r-component-conventions`, `hatch3r-i18n`, `hatch3r-theming`, `hatch3r-migrations`, `hatch3r-feature-flags`, `hatch3r-observability-logging`, `hatch3r-observability-metrics`, `hatch3r-observability-tracing`, `hatch3r-observability-tracing-detail`
+- `hatch3r-api-design`, `hatch3r-secrets-management`, `hatch3r-data-classification`, `hatch3r-performance-budgets`, `hatch3r-browser-verification`, `hatch3r-component-conventions`, `hatch3r-i18n`, `hatch3r-theming`, `hatch3r-migrations`, `hatch3r-feature-flags`, `hatch3r-observability-logging`, `hatch3r-observability-metrics`, `hatch3r-observability-tracing`
 
 For limited context windows, Tier 1 is mandatory. Tier 2/3 included selectively by agent role and task scope.

package/{rules → dist/content/rules}/hatch3r-agent-orchestration.mdc

@@ -366,6 +366,6 @@ All `scope: always` rules apply to every task including subagent work. Include r
 - `hatch3r-dependency-management` -- dependency-auditor
 
 **Tier 3 -- On-demand:**
-- `hatch3r-api-design`, `hatch3r-secrets-management`, `hatch3r-data-classification`, `hatch3r-performance-budgets`, `hatch3r-browser-verification`, `hatch3r-component-conventions`, `hatch3r-i18n`, `hatch3r-theming`, `hatch3r-migrations`, `hatch3r-feature-flags`, `hatch3r-observability-logging`, `hatch3r-observability-metrics`, `hatch3r-observability-tracing`, `hatch3r-observability-tracing-detail`
+- `hatch3r-api-design`, `hatch3r-secrets-management`, `hatch3r-data-classification`, `hatch3r-performance-budgets`, `hatch3r-browser-verification`, `hatch3r-component-conventions`, `hatch3r-i18n`, `hatch3r-theming`, `hatch3r-migrations`, `hatch3r-feature-flags`, `hatch3r-observability-logging`, `hatch3r-observability-metrics`, `hatch3r-observability-tracing`
 
 For limited context windows, Tier 1 is mandatory. Tier 2/3 included selectively by agent role and task scope.

package/{rules → dist/content/rules}/hatch3r-ai-evals.md

@@ -4,6 +4,7 @@ type: rule
 description: AI feature evaluation, prompt versioning, cost telemetry, prompt caching, model fallback, and hallucination-as-SLI for end-user projects shipping LLM features
 scope: "**/ai/**,**/llm/**,**/chat/**,**/assistant/**,**/agents/**,**/copilot/**,**/evals/**,**/prompts/**,**/rag/**"
 tags: [review, implementation, ai]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -67,7 +68,7 @@ Match the metric to the task class:
 
 Every LLM call logs: `tokens_in`, `tokens_out`, `cache_hit` (boolean + cached_tokens count), `model`, `cost_usd`, `latency_ms`, `cost_center` (feature ID), `prompt_version`, `prompt_hash`, `user_id_hash`.
 
-Aggregate dashboards in the observability stack — cross-reference `rules/hatch3r-observability-metrics.md` and `rules/hatch3r-observability-tracing-detail.md` for the SLI/SLO vocabulary, and `skills/hatch3r-observability-verify` for the wiring checklist. Per-feature budget alerts fire at 50%, 75%, and 90% of monthly budget; abuse-detection alert at 10x user p99 cost over a 1-hour window.
+Aggregate dashboards in the observability stack — cross-reference `rules/hatch3r-observability-metrics.md` and `rules/hatch3r-observability-tracing.md` for the SLI/SLO vocabulary, and `skills/hatch3r-observability-verify` for the wiring checklist. Per-feature budget alerts fire at 50%, 75%, and 90% of monthly budget; abuse-detection alert at 10x user p99 cost over a 1-hour window.
 
 ## Prompt Caching (Anthropic)
 

package/{rules → dist/content/rules}/hatch3r-ai-evals.mdc

@@ -2,6 +2,7 @@
 description: AI feature evaluation, prompt versioning, cost telemetry, prompt caching, model fallback, and hallucination-as-SLI for end-user projects shipping LLM features
 globs: ["**/ai/**", "**/llm/**", "**/chat/**", "**/assistant/**", "**/agents/**", "**/copilot/**", "**/evals/**", "**/prompts/**", "**/rag/**"]
 alwaysApply: false
+precedence: high
 ---
 # AI Feature Evaluation and Cost Governance (2026)
 
@@ -63,7 +64,7 @@ Match the metric to the task class:
 
 Every LLM call logs: `tokens_in`, `tokens_out`, `cache_hit` (boolean + cached_tokens count), `model`, `cost_usd`, `latency_ms`, `cost_center` (feature ID), `prompt_version`, `prompt_hash`, `user_id_hash`.
 
-Aggregate dashboards in the observability stack — cross-reference `rules/hatch3r-observability-metrics.md` and `rules/hatch3r-observability-tracing-detail.md` for the SLI/SLO vocabulary, and `skills/hatch3r-observability-verify` for the wiring checklist. Per-feature budget alerts fire at 50%, 75%, and 90% of monthly budget; abuse-detection alert at 10x user p99 cost over a 1-hour window.
+Aggregate dashboards in the observability stack — cross-reference `rules/hatch3r-observability-metrics.md` and `rules/hatch3r-observability-tracing.md` for the SLI/SLO vocabulary, and `skills/hatch3r-observability-verify` for the wiring checklist. Per-feature budget alerts fire at 50%, 75%, and 90% of monthly budget; abuse-detection alert at 10x user p99 cost over a 1-hour window.
 
 ## Prompt Caching (Anthropic)
 

package/{rules → dist/content/rules}/hatch3r-ai-ux-patterns.md

@@ -3,7 +3,7 @@ id: hatch3r-ai-ux-patterns
 type: rule
 description: 2026 AI/agentic UX patterns for end-user projects shipping AI features — streaming, tool-call UI, human-approval gates, cancel/abort/undo, citations
 scope: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/ai/**,**/chat/**,**/assistant/**,**/agents/**,**/llm/**,**/copilot/**"
-tags: [ux, ai, frontend]
+tags: [implementation, floor:ui-ux, ux, ai, frontend]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{rules → dist/content/rules}/hatch3r-api-versioning.md

@@ -4,6 +4,7 @@ type: rule
 description: API versioning, deprecation lifecycle, and idempotency — RFC 9457 errors, RFC 9745 Deprecation header, RFC 8594 Sunset, OAuth 2.1, Idempotency-Key, semver vs CalVer for APIs
 scope: "**/api/**,**/openapi*,**/asyncapi*,**/*.proto,**/routes/**,**/handlers/**,**/controllers/**"
 tags: [implementation, devops]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{rules → dist/content/rules}/hatch3r-api-versioning.mdc

@@ -2,6 +2,7 @@
 description: API versioning, deprecation lifecycle, and idempotency — RFC 9457 errors, RFC 9745 Deprecation header, RFC 8594 Sunset, OAuth 2.1, Idempotency-Key, semver vs CalVer for APIs
 globs: ["**/api/**", "**/openapi*", "**/asyncapi*", "**/*.proto", "**/routes/**", "**/handlers/**", "**/controllers/**"]
 alwaysApply: false
+precedence: high
 ---
 # API Versioning, Deprecation & Idempotency
 

package/{rules → dist/content/rules}/hatch3r-auth-patterns.md

@@ -3,7 +3,8 @@ id: hatch3r-auth-patterns
 type: rule
 description: Authentication and authorization patterns for end-user apps — OAuth 2.1, OIDC, DPoP, JWT rotation, cookie security, RBAC vs ABAC vs ReBAC rubric
 scope: "**/auth/**,**/login/**,**/session/**,**/oauth/**,**/oidc/**,**/jwt/**,**/permissions/**,**/policies/**,**/middleware/**"
-tags: [security, implementation]
+tags: [implementation, floor:security]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{rules → dist/content/rules}/hatch3r-auth-patterns.mdc

@@ -2,6 +2,7 @@
 description: Authentication and authorization patterns for end-user apps — OAuth 2.1, OIDC, DPoP, JWT rotation, cookie security, RBAC vs ABAC vs ReBAC rubric
 globs: ["**/auth/**", "**/login/**", "**/session/**", "**/oauth/**", "**/oidc/**", "**/jwt/**", "**/permissions/**", "**/policies/**", "**/middleware/**"]
 alwaysApply: false
+precedence: high
 ---
 # Authentication & Authorization Patterns