hatch3r 1.8.0 → 1.9.0

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

@@ -4,7 +4,7 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-researcher, hatch3r-implementer, hatch3r-reviewer, hatch3r-fixer, hatch3r-test-writer, hatch3r-security-auditor]
 description: Standalone debug-and-fix workflow — add strategic debug logging, collect runtime logs from the user, perform root cause analysis, implement the fix, and clean up all debug artifacts.
-tags: [core, implementation]
+tags: [implementation, orchestration]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -57,7 +57,7 @@ It retains:
 - Quality checks (lint, typecheck, test) — always mandatory
 - Sub-agent delegation for all non-trivial work
 - Full review pipeline in Stage 5 (reviewer, test-writer, security-auditor)
-- `scope: always` rules from `.agents/rules/`
+- `scope: always` rules from `rules/`
 - Debug artifact cleanup guarantee
 
 ---
@@ -127,8 +127,8 @@ You can also paste an error log, stack trace, or screenshot description and I'll
 1. Check for existing documentation:
    - `docs/specs/` — project specifications (read TOC/headers first, expand relevant sections only)
    - `README.md` — project overview and setup instructions
-   - `AGENTS.md` or `.agents/rules/` — agent rules and project conventions
-2. If `.agents/learnings/` exists, scan for learnings relevant to the affected area. Match by area and tags against the bug description.
+   - `AGENTS.md` or `rules/` — agent rules and project conventions
+2. If `.hatch3r/learnings/` exists, scan for learnings relevant to the affected area. Match by area and tags against the bug description.
 3. Scan the affected code area — read the primary files involved, trace imports and dependencies one level deep.
 
 **Knowledge hierarchy:** project specs → codebase exploration → Context7 MCP (`resolve-library-id` then `query-docs`) → web research. Exhaust each level before escalating to the next.
@@ -166,7 +166,7 @@ The researcher prompt MUST include:
 - The affected files and modules identified in Stage 1b.
 - Instruction to follow the **hatch3r-researcher agent protocol** with mode `symptom-trace`.
 - Instruction to identify specific instrumentation points: decision branches, data flow boundaries, error handlers, state transitions, and external call sites in the affected area.
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 
 The researcher must produce a structured list of recommended instrumentation points:
 
@@ -186,7 +186,7 @@ Spawn a `hatch3r-implementer` sub-agent via the Task tool (`subagent_type: "gene
 The implementer prompt MUST include:
 - The researcher's instrumentation points from Stage 2a.
 - The confirmed bug context from Stage 1c.
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 - Explicit instruction: do NOT create branches, commits, or PRs.
 
 **Debug logging rules** (include these verbatim in the implementer prompt):
@@ -281,7 +281,7 @@ The researcher prompt MUST include:
 - The structured log analysis from Stage 3b (full parsed output).
 - The instrumentation point list from Stage 2a (to correlate expected vs. actual behavior).
 - Instruction to follow the **hatch3r-researcher agent protocol** with mode `root-cause` and depth `deep`.
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 - Instruction to produce ranked hypotheses with evidence from the log data.
 
 **Knowledge hierarchy for the researcher:** project specs → codebase → Context7 MCP → web research. Use `gh` CLI (e.g., `gh issue list`, `gh pr list`) for reading GitHub data; prefer `gh` over GitHub MCP tools.
@@ -324,7 +324,7 @@ Spawn a `hatch3r-implementer` sub-agent via the Task tool (`subagent_type: "gene
 The implementer prompt MUST include:
 - The confirmed diagnosis from Stage 4b (root cause, evidence, recommended fix approach).
 - The full list of files modified in Stage 2b (debug logging locations) for cleanup reference.
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 - Explicit instruction: do NOT create branches, commits, or PRs.
 
 **Fix implementation rules** (include these verbatim in the implementer prompt):
@@ -355,7 +355,7 @@ Run a review-fix loop, maximum 3 iterations, until the reviewer reports a clean
    - The diff of all changes (use `git diff` on the working tree).
    - The original bug context from Stage 1c.
    - The diagnosis from Stage 4b.
-   - All `scope: always` rule directives from `.agents/rules/`.
+   - All `scope: always` rule directives from `rules/`.
    - Instruction to verify: correctness of the fix, no remaining debug artifacts, code quality, no regressions introduced.
 
 2. If the reviewer reports findings (critical or warning level):
@@ -378,12 +378,12 @@ After the review loop completes clean (or the user proceeds), spawn these two su
    - The fix diff (what was changed).
    - The root cause from Stage 4b.
    - Instruction to write tests that would have caught this bug — regression tests targeting the specific failure mode.
-   - All `scope: always` rule directives from `.agents/rules/`.
+   - All `scope: always` rule directives from `rules/`.
 
 2. **`hatch3r-security-auditor`** — security review of the fix. The prompt MUST include:
    - The fix diff.
    - The affected files and data flows.
-   - All `scope: always` rule directives from `.agents/rules/`.
+   - All `scope: always` rule directives from `rules/`.
 
 Await both sub-agents. Apply any findings (additional tests, security fixes).
 

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

@@ -4,7 +4,7 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Design a new capability -- draft user stories, acceptance criteria, data model, API surface, and sub-issue breakdown as an epic-shaped todo.md for greenfield features
-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 single feature idea and produce a complete feature specification (`docs/s
 
 ## 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
 
@@ -118,10 +118,10 @@ 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 decisions relevant to the feature 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 feature. Note duplicates or partial overlaps.
-3. If `.agents/learnings/` exists, scan for learnings relevant to the feature area. Match by area and tags against the feature brief.
+3. If `.hatch3r/learnings/` exists, scan for learnings relevant to the feature area. Match by area and tags against the feature brief.
 4. Present a context summary:
 
 ```
@@ -448,7 +448,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 feature 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 feature 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).
 

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

@@ -4,7 +4,7 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-handoff-preparer]
 description: Prepare, resume, list, complete, and prune cross-session handoff documents.
-tags: [core, maintenance]
+tags: [orchestration, maintenance]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -25,11 +25,11 @@ The `prepare` subcommand delegates to `hatch3r-handoff-preparer` via the Task to
 
 ## Learnings Consultation
 
-Before starting, scan `.agents/learnings/` for entries tagged `handoff`, `context-switch`, `resume`, or `session-state`. Apply the protocol in `rules/hatch3r-learning-consult.md` (frontmatter-first scan; surface top 5 by confidence). Skip if the directory has fewer than 3 files.
+Before starting, scan `.hatch3r/learnings/` for entries tagged `handoff`, `context-switch`, `resume`, or `session-state`. Apply the protocol in `rules/hatch3r-learning-consult.md` (frontmatter-first scan; surface top 5 by confidence). Skip if the directory has fewer than 3 files.
 
 # Handoff Management — Cross-Session Work Continuity
 
-Manage canonical handoff documents at `.agents/handoffs/active/` for mid-work state capture and resumption across sessions, tools, or developers.
+Manage canonical handoff documents at `.hatch3r/handoffs/active/` for mid-work state capture and resumption across sessions, tools, or developers.
 
 ---
 
@@ -101,13 +101,13 @@ ID                                              STATUS         BRANCH
 
 **ASK:** "Mark `{id}` completed and archive? (y/N). Reason will be recorded: `{reason or 'no reason given'}`."
 
-4. On confirm: transition `status` to `completed`, stamp `updated` to now, prepend the archival notice (mirrors learnings archival format), then atomic-rename to `.agents/handoffs/archived/<id>.md`.
+4. On confirm: transition `status` to `completed`, stamp `updated` to now, prepend the archival notice (mirrors learnings archival format), then atomic-rename to `.hatch3r/handoffs/archived/<id>.md`.
 
 ## Subcommand: prune
 
 1. Parse `--dry-run` flag.
-2. Scan `.agents/handoffs/active/`: collect entries whose `expires_after` ISO-8601 timestamp is at-or-before now (preparer default stamps `created + 30 days`).
-3. Scan `.agents/handoffs/archived/`: collect entries where `updated` is older than 90 days.
+2. Scan `.hatch3r/handoffs/active/`: collect entries whose `expires_after` ISO-8601 timestamp is at-or-before now (preparer default stamps `created + 30 days`).
+3. Scan `.hatch3r/handoffs/archived/`: collect entries where `updated` is older than 90 days.
 4. Present a two-section preview (Active expirations to archive, Archives to delete).
 5. If `--dry-run`: print the preview and exit.
 
@@ -119,7 +119,7 @@ ID                                              STATUS         BRANCH
 
 ## Error Handling
 
-- `.agents/handoffs/active/` missing or empty: emit `No active handoffs. Run 'hatch3r-handoff prepare' to capture one.` and exit 0.
+- `.hatch3r/handoffs/active/` missing or empty: emit `No active handoffs. Run 'hatch3r-handoff prepare' to capture one.` and exit 0.
 - Ambiguous `<id>` (multiple partial matches): list the matches and **ASK** the user to pick one.
 - Write conflict (concurrent prepare for same `work_item`): surface the existing handoff path and **ASK** whether to overwrite (only if existing handoff is older than 24 hours per `writeHandoff` policy).
 - `complete` or `prune` requested on a missing id: report the path that was looked up and suggest `hatch3r-handoff list`.
@@ -127,7 +127,7 @@ ID                                              STATUS         BRANCH
 ## Guardrails
 
 - **Never delete** a handoff without explicit user confirmation. Prune deletes only archives older than 90 days, and only after the confirm prompt.
-- **Never modify** a file already in `.agents/handoffs/archived/`. Archived entries are immutable history.
+- **Never modify** a file already in `.hatch3r/handoffs/archived/`. Archived entries are immutable history.
 - **Never include secrets** (API keys, tokens, credentials) in any handoff body. The preparer scans for credential-shaped strings; reject the write if any are detected.
-- **Never write** outside `.agents/handoffs/active/` for new handoffs. Archival is the only path into `archived/`.
+- **Never write** outside `.hatch3r/handoffs/active/` for new handoffs. Archival is the only path into `archived/`.
 - **Always emit the Iteration Summary block** at the end of the iteration per `rules/hatch3r-iteration-summary.md`.

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

@@ -34,7 +34,7 @@ Create a healthcheck epic on **{owner}/{repo}** with one sub-issue per logical p
 
 ## 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-hooks.md

@@ -3,7 +3,7 @@ id: hatch3r-hooks
 type: command
 orchestrator: false
 description: Define and manage event-driven hooks that activate agents on project events
-tags: [core, devops]
+tags: [devops, orchestration]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -20,7 +20,7 @@ This command runs as a single orchestrator without sub-agent delegation. Hook de
 
 ## Learnings Consultation
 
-If `.agents/learnings/` exists, scan for learnings related to hook configurations, event trigger patterns, or prior hook issues before starting.
+If `.hatch3r/learnings/` exists, scan for learnings related to hook configurations, event trigger patterns, or prior hook issues before starting.
 
 # Hooks — Event-Driven Agent Activation
 
@@ -34,8 +34,8 @@ Execute these steps in order. **Do not skip any step.** Ask the user at every ch
 
 ### Step 1: Discover Current State
 
-1. Check `.agents/hooks/` for existing hook definition files (`.md` files with frontmatter).
-2. Read `.agents/hatch.json` for configured tools and features.
+1. Check `hooks/` for existing hook definition files (`.md` files with frontmatter).
+2. Read `.hatch3r/hatch.json` for configured tools and features.
 3. List existing hooks with their event, agent, and conditions.
 
 Present the current state:
@@ -95,7 +95,7 @@ Present available hatch3r agents:
 - `dependency-auditor` — Dependency security and update checks
 - `docs-writer` — Documentation generation and updates
 
-If the user wants a custom agent name not in this list, accept it but warn that the agent must exist in `.agents/agents/`.
+If the user wants a custom agent name not in this list, accept it but warn that the agent must exist in `agents/`.
 
 **ASK:** "Select an agent to activate when this event fires."
 
@@ -108,7 +108,7 @@ If the user wants a custom agent name not in this list, accept it but warn that
 
 #### 2d. Write Hook Definition File
 
-Generate the hook definition file at `.agents/hooks/{event}-{agent-short-name}.md`:
+Generate the hook definition file at `hooks/{event}-{agent-short-name}.md`:
 
 ```markdown
 ---
@@ -150,7 +150,7 @@ For editing an existing hook:
 1. List all hooks and ask which to edit.
 2. Show current definition.
 3. Ask what to change (event, agent, conditions, description).
-4. Update the hook file in `.agents/hooks/`.
+4. Update the hook file in `hooks/`.
 
 **ASK:** "Updated hook: {summary}. Save? (yes / revert / cancel)"
 
@@ -161,7 +161,7 @@ For editing an existing hook:
 1. List all hooks and ask which to remove.
 2. Show the hook definition.
 
-**ASK:** "Remove hook '{id}'? This will delete `.agents/hooks/{filename}`. (yes / cancel)"
+**ASK:** "Remove hook '{id}'? This will delete `hooks/{filename}`. (yes / cancel)"
 
 3. Delete the file. Warn that tool-specific generated files (e.g., `.cursor/rules/hatch3r-hook-*.mdc`) will be cleaned up on the next `npx hatch3r sync`.
 
@@ -169,7 +169,7 @@ For editing an existing hook:
 
 ### Step 5: Sync Hooks to Tools
 
-1. Read all hook definitions from `.agents/hooks/`.
+1. Read all hook definitions from `hooks/`.
 2. For each configured tool in `hatch.json`, describe what will be generated:
    - **Claude Code:** Hook documentation appended to managed section of `CLAUDE.md`
    - **Cursor:** Glob-based `.mdc` rule files in `.cursor/rules/hatch3r-hook-*.mdc`
@@ -209,7 +209,7 @@ In `hatch.json`:
 }
 ```
 
-Custom events follow the same hook definition format as built-in events — create a hook file in `.agents/hooks/` with `event: custom:{domain}:{action}`.
+Custom events follow the same hook definition format as built-in events — create a hook file in `hooks/` with `event: custom:{domain}:{action}`.
 
 ---
 
@@ -284,9 +284,9 @@ For `pre-commit` with three hooks:
 
 ## Error Handling
 
-- `.agents/hooks/` doesn't exist: create it automatically.
+- `hooks/` doesn't exist: create it automatically.
 - Invalid event type: warn and show the valid events table.
-- Agent not found in `.agents/agents/`: warn but allow (agent may be added later).
+- Agent not found in `agents/`: warn but allow (agent may be added later).
 - Adapter doesn't support hooks: generate hook definition file anyway, warn that sync for that tool is a no-op.
 - Duplicate hook ID: warn and ask the user to choose a different name or overwrite.
 

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

@@ -3,7 +3,7 @@ id: hatch3r-learn
 type: command
 orchestrator: false
 description: Capture learnings from development sessions into reusable knowledge files for future consultation.
-tags: [core, maintenance]
+tags: [orchestration, maintenance]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -56,9 +56,9 @@ Execute these steps in order. **Do not skip any step.** Ask the user at every ch
 
 ### Step 3: Validate and Write Learning Files
 
-For each confirmed learning, validate content security and then create a file in `.agents/learnings/`.
+For each confirmed learning, validate content security and then create a file in `.hatch3r/learnings/`.
 
-If `.agents/learnings/` does not exist, create it.
+If `.hatch3r/learnings/` does not exist, create it.
 
 #### Content Validation (ASI06 — before write)
 
@@ -152,8 +152,8 @@ Present all saved learnings with file paths.
 
 ```
 Learnings Captured:
-  .agents/learnings/{filename1}.md -- {category}: {one-line summary}
-  .agents/learnings/{filename2}.md -- {category}: {one-line summary}
+  .hatch3r/learnings/{filename1}.md -- {category}: {one-line summary}
+  .hatch3r/learnings/{filename2}.md -- {category}: {one-line summary}
 ```
 
 Remind user that these will be auto-consulted during future board-pickup and board-fill runs.
@@ -173,7 +173,7 @@ Remind user that these will be auto-consulted during future board-pickup and boa
 To prevent unbounded context growth, the learnings system enforces a configurable maximum count of active learnings:
 
 - **Default cap:** 100 active learnings (not counting archived or deprecated entries).
-- **Configurable:** Set `learnings.maxActive` in `.agents/hatch.json` to override the default (e.g., `"learnings": { "maxActive": 150 }`).
+- **Configurable:** Set `learnings.maxActive` in `.hatch3r/hatch.json` to override the default (e.g., `"learnings": { "maxActive": 150 }`).
 - **Enforcement:** When the active count reaches the cap, the `hatch3r learn` command refuses to write new learnings until existing ones are archived or pruned. Display the message: "Active learnings limit reached ({count}/{max}). Archive or prune existing learnings before adding new ones."
 - **Per-session cap:** A single `hatch3r learn` invocation may capture at most 10 learnings. If more than 10 are identified in Step 2, present the top 10 by relevance and inform the user that the remainder can be captured in a follow-up session.
 
@@ -216,7 +216,7 @@ integrity: sha256:{hex-digest}  # SHA-256 of body content for tamper detection
 
 ### Archival
 
-Archived learnings are moved to `.agents/learnings/archived/` with their original filename. An archival notice is prepended:
+Archived learnings are moved to `.hatch3r/learnings/archived/` with their original filename. An archival notice is prepended:
 
 ```markdown
 > **Archived on {date}**: {reason — expired | deprecated | superseded by {id}}
@@ -242,7 +242,7 @@ Archived learnings are moved to `.agents/learnings/archived/` with their origina
 ```
 Learnings matching "{query}":
   [{confidence}] {title} ({date}, tags: {tags})
-    .agents/learnings/{filename}.md
+    .hatch3r/learnings/{filename}.md
     Applies when: {trigger summary}
 ```
 
@@ -288,8 +288,8 @@ When writing learning files, validate:
 
 ## Error Handling
 
-- `.agents/learnings/` directory doesn't exist: create it silently.
-- `.agents/learnings/archived/` directory doesn't exist: create it when first archival occurs.
+- `.hatch3r/learnings/` directory doesn't exist: create it silently.
+- `.hatch3r/learnings/archived/` directory doesn't exist: create it when first archival occurs.
 - Duplicate learning detected: warn and **ASK** whether to merge or create separate.
 - No learnings identified: **ASK** user directly what they learned. If still nothing, skip silently.
 - Learning exceeds quality thresholds: warn user with specific violations and suggest fixes.
@@ -302,7 +302,7 @@ When writing learning files, validate:
 - **Never delete learnings.** Use archival (move to `archived/`) instead of deletion.
 - **Learnings must be specific and actionable.** Reject generic advice like "write better tests."
 - **Always include trigger conditions** in the "Applies When" section.
-- **Tags must match project vocabulary** -- use area labels from `.agents/hatch.json`.
+- **Tags must match project vocabulary** -- use area labels from `.hatch3r/hatch.json`.
 - **Max ~20 lines per learning** file body (excluding frontmatter).
 - **Learnings without evidence must be `hypothesis`.** Do not allow `proven` or `experimental` without evidence.
 - **Expired learnings are archived, not deleted.** Preserve institutional knowledge.

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

@@ -4,7 +4,7 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-researcher, hatch3r-architect, hatch3r-docs-writer]
 description: Create a phased migration plan for a major dependency or framework upgrade. Analyzes breaking changes and produces an actionable plan with rollback procedures.
-tags: [planning, brownfield]
+tags: [planning, ctx:brownfield-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -35,7 +35,7 @@ Take a dependency or framework upgrade target and produce a complete migration p
 
 ## 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
 

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

@@ -4,7 +4,7 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Generate a comprehensive onboarding guide for a new developer joining the project -- spawn parallel researchers to analyze codebase structure, architecture, and conventions, then produce a tailored onboarding document with setup instructions, architecture walkthrough, coding conventions, key workflows, tribal knowledge, and a quick-reference cheat sheet.
-tags: [brownfield, team]
+tags: [planning, ctx:brownfield-only, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -35,7 +35,7 @@ Take a new developer's role, experience level, and focus areas 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, it establishes patterns and context (GitHub owner/repo, tooling directives) that provide project metadata useful for the onboarding guide. 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, it establishes patterns and context (GitHub owner/repo, tooling directives) that provide project metadata useful for the onboarding guide. Cache any values found.
 
 ## Token-Saving Directives
 
@@ -117,11 +117,11 @@ Answer these now, or say 'skip' for any where you'd rather I omit that section f
    - `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` — project metadata, scripts, dependencies
    - `.env.example` — environment variable template
    - `docs/` — any existing documentation
-   - `.agents/rules/` — coding standards and conventions
-   - `.agents/learnings/` — team learnings and institutional knowledge
+   - `rules/` — coding standards and conventions
+   - `.hatch3r/learnings/` — team learnings and institutional knowledge
    - CI config (`.github/workflows/`, `.gitlab-ci.yml`, etc.) — CI/CD pipeline
 2. Scan the top-level directory structure to understand project organization.
-3. If `.agents/learnings/` exists, scan for learnings relevant to onboarding, common mistakes, and gotchas. Match by area and tags.
+3. If `.hatch3r/learnings/` exists, scan for learnings relevant to onboarding, common mistakes, and gotchas. Match by area and tags.
 4. Present a context summary:
 
 ```
@@ -131,7 +131,7 @@ Context Loaded:
   Package manifest: {type — with N scripts, M dependencies}
   Env template:     {found / not found}
   Docs:             {N} files in docs/ ({key ones listed})
-  Rules:            {N} files in .agents/rules/ ({areas covered})
+  Rules:            {N} files in rules/ ({areas covered})
   Learnings:        {N} relevant learnings
   CI:               {type — N workflows}
   Gaps:             {list any missing context — e.g., "no CONTRIBUTING.md", "no .env.example"}
@@ -287,7 +287,7 @@ Recommended Follow-ups:
 - **Multiple languages/frameworks:** Generate setup sections for each language/framework detected. Organize by language with shared prerequisites listed first. Note which parts of the codebase use which stack.
 - **Missing credentials or access documentation:** Never invent or guess credentials. Include placeholder sections marked `[ACTION REQUIRED]` with instructions on who to contact for access. Flag each missing credential in the Recommended Follow-ups.
 - **File write failure:** Report the error and provide the full guide content so the user can create the file manually.
-- **Missing project context:** If no shared board context or `.agents/hatch.json` exists, proceed without board context — this command does not require board configuration.
+- **Missing project context:** If no shared board context or `.hatch3r/hatch.json` exists, proceed without board context — this command does not require board configuration.
 - **Empty or minimal codebase:** If the project has fewer than 10 source files, generate a condensed guide without the architecture and tribal knowledge sections. Note that the guide will be more useful after the project matures.
 - **Conflicting documentation:** If README instructions conflict with actual project structure or scripts, flag both versions in the guide and note the discrepancy for the developer to verify.
 

package/{commands → dist/content/commands}/hatch3r-pr-resolve.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: Read all open PR comments (inline + review summary + general discussion) across GitHub, Azure DevOps, and GitLab; evaluate each against current code via the rigor contract; implement accepted findings through the standard agent pipeline; and reply per comment with rationale. Auto-detects the PR from the current branch (or accepts an explicit PR number).
-tags: [implementation, team, review]
+tags: [implementation, review, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -58,7 +58,7 @@ Optional positional argument: `<pr-number>` (integer).
 
 ## Shared Context
 
-If board context exists (current branch has an associated PR or board configuration in `.agents/hatch.json`), **read the `hatch3r-board-shared` command at the start of the run.** Cache `board.platform`, `board.owner`, `board.repo`, `board.defaultBranch`, and `board.projectNumber` for the duration of the run.
+If board context exists (current branch has an associated PR or board configuration in `.hatch3r/hatch.json`), **read the `hatch3r-board-shared` skill at the start of the run.** Cache `board.platform`, `board.owner`, `board.repo`, `board.defaultBranch`, and `board.projectNumber` for the duration of the run.
 
 After loading `hatch3r-board-shared`, **read the platform-specific shared file** matching `board.platform`:
 - GitHub → `commands/board/shared-github.md`
@@ -67,7 +67,7 @@ After loading `hatch3r-board-shared`, **read the platform-specific shared file**
 
 Each platform file's **Cross-Cutting Tooling** table now includes PR-comment read and reply endpoints used in Steps 2 and 8.
 
-If no `.agents/hatch.json` exists, fall back to GitHub and proceed — the command can still run on any GitHub repo where `gh auth login` has been completed.
+If no `.hatch3r/hatch.json` exists, fall back to GitHub and proceed — the command can still run on any GitHub repo where `gh auth login` has been completed.
 
 ---
 
@@ -83,7 +83,7 @@ If no `.agents/hatch.json` exists, fall back to GitHub and proceed — the comma
 1. **One fetch per comment scope.** Issue exactly one paginated request per scope in Step 2; cache and reuse for Steps 3, 4, and 8.
 2. **One diff computation.** Compute `git diff {defaultBranch}...HEAD` once in Step 1; reuse for Steps 4 (outdated detection) and 7 (review loop input).
 3. **Targeted file reads.** In Step 4, read only the files referenced by a comment's `path`/`line` — not the full codebase.
-4. **No re-reading shared rules.** `scope: always` rules from `.agents/rules/` load once at session start; pass their content into sub-agent prompts (Step 6) rather than reloading.
+4. **No re-reading shared rules.** `scope: always` rules from `rules/` load once at session start; pass their content into sub-agent prompts (Step 6) rather than reloading.
 5. **Per-platform reference cache.** Load the matching `commands/board/shared-{platform}.md` once at run start (Shared Context). Step 8 reads templates from the cache, not from disk.
 
 ---
@@ -163,7 +163,7 @@ Tier assignment is recomputed after Step 4 (when severity is known). If the init
 
 #### 1b. Detect Platform
 
-1. Read `.agents/hatch.json`. Extract `board.platform` (`github | azure-devops | gitlab`).
+1. Read `.hatch3r/hatch.json`. Extract `board.platform` (`github | azure-devops | gitlab`).
 2. If absent or unreadable, default to GitHub and record a Low-confidence platform-detection finding in `run_cache.errors`.
 
 #### 1c. Look Up the PR
@@ -453,9 +453,9 @@ Each sub-agent prompt MUST include:
 
 1. The findings list for that agent: `(comment_id, file, line, comment body verbatim as the "ask", proposed_action from Step 4)`.
 2. Instruction to follow the corresponding agent protocol.
-3. All `scope: always` rule directives from `.agents/rules/`.
+3. All `scope: always` rule directives from `rules/`.
 4. Acceptance criteria from `run_cache.pr.linked_issues` (read once at Step 1, cached).
-5. Relevant `.agents/learnings/` matching the affected areas.
+5. Relevant `.hatch3r/learnings/` matching the affected areas.
 6. Explicit: do NOT create branches, commits, or PRs.
 7. Confidence expression requirement (verbatim from the Confidence Propagation Contract above).
 8. PR-resolve-specific constraint: "You are addressing reviewer comments on an existing PR. Stay within the architecture established by the PR's existing changes; do not introduce scope creep beyond the comments listed below."
@@ -543,7 +543,7 @@ All reply bodies are signed with a trailing line: `_— hatch3r-pr-resolve (conf
 
 Reply bodies are written to a `mktemp` file and passed with `-f body=@{file}` (GitHub/GitLab) or via the JSON `--body` argument (Azure); this avoids shell-quoting issues with markdown content.
 
-**Field typing for `gh api`:** Integer-typed fields like `in_reply_to` require `-F` (capital); string fields like `body` use `-f` (lowercase). Mixing them returns HTTP 422 and the reply silently fails into the retry/backoff path. See `commands/board/shared-github.md` → GitHub CLI Field-Typing Notes for the full table. **Pager:** Every `gh api` invocation from this command must run with `GH_PAGER=cat` and `PAGER=cat` set; see `commands/hatch3r-board-shared.md` → Pager-Bypass Directive.
+**Field typing for `gh api`:** Integer-typed fields like `in_reply_to` require `-F` (capital); string fields like `body` use `-f` (lowercase). Mixing them returns HTTP 422 and the reply silently fails into the retry/backoff path. See `commands/board/shared-github.md` → GitHub CLI Field-Typing Notes for the full table. **Pager:** Every `gh api` invocation from this command must run with `GH_PAGER=cat` and `PAGER=cat` set; see `commands/hatch3r-board-shared/SKILL.md` → Pager-Bypass Directive.
 
 #### 8c. Resilience
 

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

@@ -4,7 +4,7 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Translate a greenfield vision into future-state design artifacts -- ADRs, domain model, API contracts, per-module technical specs, and a board-ready todo.md
-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 @@ Take a project idea or vision and produce complete project documentation across
 
 ## 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
 
@@ -1194,7 +1194,7 @@ Which would you like to run next? (or none)"
 - **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.
 - **Business context gaps:** If the user cannot answer business discovery questions, proceed with "TBD" markers and flag these as open items in the business specs.
 - **Stage assessment unclear:** Default to "early-revenue" if the user is unsure. This provides balanced analysis depth without over- or under-engineering recommendations.
 - **Competitor research gaps:** If web search returns insufficient data for a competitor, note it as "limited public information" and present what was found.

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

@@ -4,7 +4,7 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-implementer, hatch3r-lint-fixer, hatch3r-reviewer, hatch3r-fixer, hatch3r-test-writer, hatch3r-security-auditor]
 description: Lightweight command for small changes not worth tracking on the board. Adaptive ceremony with inline or sub-agent implementation, batch support, and soft scope guards.
-tags: [core, implementation]
+tags: [implementation, orchestration]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -60,7 +60,7 @@ It retains:
 - Quality checks (lint, typecheck, test) -- always mandatory
 - Adaptive sub-agent delegation (implementer for nontrivial items)
 - Light code review (reviewer for nontrivial items only)
-- `scope: always` rules from `.agents/rules/`
+- `scope: always` rules from `rules/`
 - Soft scope guards to prevent misuse
 - Lightweight learnings consultation (file-path scan, 150-token budget)
 
@@ -163,7 +163,7 @@ Quick Change Scope:
 
 #### 2c. Lightweight Learnings Scan (Optional)
 
-If `.agents/learnings/` exists:
+If `.hatch3r/learnings/` exists:
 
 1. Collect the file paths from the affected areas identified in Step 1.
 2. Scan learning file frontmatter for `area` or `tags` that match the affected file paths or directories.
@@ -179,7 +179,7 @@ If `.agents/learnings/` exists:
 
 **Token budget:** Max 150 tokens for this entire step. Read frontmatter only — do not read learning bodies unless the frontmatter matches. Limit to 3 surfaced learnings. If more than 3 match, show the 3 with highest confidence.
 
-If `.agents/learnings/` does not exist, skip this step silently.
+If `.hatch3r/learnings/` does not exist, skip this step silently.
 
 **ASK:** "Proceed with these changes? (yes / adjust)"
 
@@ -231,7 +231,7 @@ No sub-agent delegation. No researcher. Implement and move on.
 
 For each nontrivial item (or group of related nontrivial items):
 
-1. Read `scope: always` rules from `.agents/rules/`.
+1. Read `scope: always` rules from `rules/`.
 
 2. **Lightweight research (Tier 2 items only):** If the item scored Tier 2 in Step 2b and the user chose to proceed with lightweight research, spawn a `hatch3r-researcher` sub-agent with:
    - **Modes:** `similar-implementation` at `quick` depth (1 reference implementation)
@@ -291,7 +291,7 @@ For nontrivial items, run an iterative review loop (max 3 iterations) until 0 Cr
 The reviewer prompt MUST include:
 - The diff of all changes made (use `git diff` on the working tree).
 - Focus areas: **correctness and code quality only**. Skip security deep-dive, performance profiling, and documentation review.
-- 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.
 - Requirement that the reviewer output include a top-level `confidence: high | medium | low` field (not just per-finding) so the gate in step 2 can evaluate it deterministically.
@@ -317,7 +317,7 @@ After the review loop is clean, spawn both agents in parallel via the Task tool:
 
 Both prompts MUST include:
 - The diff of all changes made.
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 - 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.
 
 Apply any resulting changes (new tests, security fixes). Re-run quality checks (Step 5a) if changes were made.