hatch3r 1.3.0 → 1.4.0

package/rules/hatch3r-observability.mdc

@@ -163,3 +163,292 @@ Every telemetry-producing service must declare resource attributes at startup:
 - Attribute values should be low-cardinality. Never use unbounded values (full URLs with query params, raw SQL, user-generated content) as attribute values.
 - For high-cardinality identifiers (user IDs, request IDs), use span attributes sparingly and rely on correlated logs for detail.
 - Prefer semantic convention attributes over custom attributes. When custom attributes are necessary, prefix them with your organization or project namespace (e.g., `myapp.feature.flag_key`).
+
+### AI Agent Semantic Conventions
+
+Follow the [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) (experimental, introduced 2024) for instrumenting AI/LLM agent systems. These conventions provide consistent attribute naming for generative AI operations, enabling interoperability across agent frameworks and observability backends.
+
+#### `gen_ai.*` Span Attributes
+
+Use these attributes on all spans that represent interactions with generative AI models:
+
+| Attribute | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `gen_ai.system` | string | The GenAI provider system name | `openai`, `anthropic`, `azure_openai` |
+| `gen_ai.request.model` | string | Model name as specified in the request | `gpt-4o`, `claude-sonnet-4-20250514` |
+| `gen_ai.response.model` | string | Model name as returned in the response (may differ from request) | `gpt-4o-2024-08-06` |
+| `gen_ai.request.max_tokens` | int | Maximum number of tokens requested for generation | `4096` |
+| `gen_ai.request.temperature` | float | Temperature parameter sent in the request | `0.7` |
+| `gen_ai.request.top_p` | float | Top-p (nucleus sampling) parameter | `0.9` |
+| `gen_ai.response.finish_reasons` | string[] | Reasons the model stopped generating | `["stop"]`, `["length"]`, `["tool_calls"]` |
+| `gen_ai.usage.input_tokens` | int | Number of tokens in the input/prompt | `1250` |
+| `gen_ai.usage.output_tokens` | int | Number of tokens in the generated output | `530` |
+
+- Always set `gen_ai.system` and `gen_ai.request.model` on every GenAI span. These are required for meaningful filtering and cost attribution.
+- Record `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` from the API response to enable token usage dashboards and cost tracking.
+- Use `gen_ai.response.finish_reasons` to detect truncated outputs (`length`) and trigger re-prompting or alerting logic.
+
+#### Agent Invocation Spans
+
+Instrument the full lifecycle of an agent invocation with a dedicated span. This span is the parent for all LLM calls, tool executions, and sub-agent delegations within a single agent run.
+
+- **Span name pattern:** `agent.{agent_name}.invoke` (e.g., `agent.code_reviewer.invoke`, `agent.research_assistant.invoke`)
+- **Required attributes:**
+
+| Attribute | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `agent.id` | string | Unique identifier for this agent invocation | `agent-run-a1b2c3d4` |
+| `agent.name` | string | Logical name of the agent | `code_reviewer` |
+| `agent.parent_id` | string | ID of the parent agent (for sub-agent delegation chains) | `agent-run-x9y8z7` |
+| `agent.task` | string | High-level description of the agent's assigned task | `review PR #42` |
+| `agent.framework` | string | Agent framework in use | `langchain`, `autogen`, `custom` |
+
+- **Span events for state transitions:** Record span events to mark key lifecycle transitions within the agent invocation:
+  - `agent.planning` — Agent begins task decomposition or reasoning.
+  - `agent.tool_selection` — Agent selects a tool to invoke.
+  - `agent.awaiting_human` — Agent pauses for human-in-the-loop confirmation.
+  - `agent.delegating` — Agent spawns a sub-agent.
+  - `agent.completed` — Agent finishes its task and produces a final output.
+  - `agent.error` — Agent encounters a non-recoverable error. Include `exception.type` and `exception.message` attributes on the event.
+
+```typescript
+const agentSpan = tracer.startSpan('agent.code_reviewer.invoke', {
+  attributes: {
+    'agent.id': invocationId,
+    'agent.name': 'code_reviewer',
+    'agent.parent_id': parentAgentId ?? '',
+    'agent.task': `review PR #${prNumber}`,
+    'agent.framework': 'custom',
+  },
+});
+
+agentSpan.addEvent('agent.planning');
+// ... agent reasoning and tool calls happen as child spans ...
+agentSpan.addEvent('agent.completed');
+agentSpan.end();
+```
+
+#### Tool Call Spans
+
+Every tool invocation by an agent creates a child span of the agent invocation span. This enables tracing the full sequence of tool calls within an agent run, measuring tool latency, and detecting tool failures.
+
+- **Span name pattern:** `tool.{tool_name}.execute` (e.g., `tool.file_read.execute`, `tool.web_search.execute`)
+- **Required attributes:**
+
+| Attribute | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `tool.name` | string | Canonical name of the tool | `file_read`, `git_diff`, `web_search` |
+| `tool.input_hash` | string | SHA-256 hash of the tool input (for deduplication, not logging raw input) | `sha256:3a7f...` |
+| `tool.output_status` | string | Outcome of the tool execution | `success`, `error`, `timeout`, `rejected` |
+| `tool.duration_ms` | float | Wall-clock execution time of the tool in milliseconds | `142.5` |
+| `tool.parameters_count` | int | Number of parameters passed to the tool | `3` |
+
+- **Parent-child relationship:** Tool spans must be children of the invoking agent span. Use `context.with(trace.setSpan(context.active(), agentSpan))` to propagate the agent span context to tool execution.
+- Set span status to `ERROR` when `tool.output_status` is `error` or `timeout`. Attach exception details as a span event.
+- For tools that perform I/O (HTTP requests, file system operations, database queries), create nested child spans using the appropriate semantic conventions (`http.*`, `db.*`) under the tool span.
+
+```typescript
+const toolSpan = tracer.startSpan(
+  'tool.git_diff.execute',
+  { attributes: { 'tool.name': 'git_diff' } },
+  trace.setSpan(context.active(), agentSpan),
+);
+
+const startTime = performance.now();
+try {
+  const result = await tools.gitDiff(params);
+  toolSpan.setAttributes({
+    'tool.output_status': 'success',
+    'tool.duration_ms': performance.now() - startTime,
+    'tool.input_hash': hashInput(params),
+  });
+} catch (err) {
+  toolSpan.setAttributes({
+    'tool.output_status': 'error',
+    'tool.duration_ms': performance.now() - startTime,
+  });
+  toolSpan.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+  toolSpan.recordException(err);
+  throw err;
+} finally {
+  toolSpan.end();
+}
+```
+
+#### LLM Request/Response Tracing
+
+Instrument every LLM API call with a dedicated span. These spans are typically children of an agent invocation span and capture model, token usage, and latency data for cost analysis and performance monitoring.
+
+- **Span name pattern:** `gen_ai.{operation}` (e.g., `gen_ai.chat`, `gen_ai.completion`, `gen_ai.embeddings`)
+- **Required attributes:** All applicable `gen_ai.*` attributes from the table above, plus:
+
+| Attribute | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `gen_ai.operation.name` | string | The specific API operation | `chat`, `completion`, `embeddings` |
+| `gen_ai.request.stop_sequences` | string[] | Stop sequences sent in the request | `["\n\n", "END"]` |
+| `server.address` | string | Hostname of the GenAI API endpoint | `api.openai.com` |
+| `server.port` | int | Port of the GenAI API endpoint | `443` |
+
+- **Input/output token tracking:** Always capture `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` from the API response. Aggregate these in metrics for cost dashboards:
+  - Counter: `gen_ai.tokens_total` with labels `{direction=input|output, model, agent_name}`
+  - Histogram: `gen_ai.request_duration_ms` with labels `{model, operation, agent_name}`
+
+- **Model version tracking:** Record both `gen_ai.request.model` (what was requested) and `gen_ai.response.model` (what was actually used). API providers may silently route to different model versions; capturing both enables drift detection.
+
+- **Error handling and retry spans:** When an LLM request fails and is retried, each attempt is a separate child span under the same parent. Record the error on the failed span and create a new span for the retry:
+  - Set `gen_ai.request.retries` (int) on the final successful span to indicate total retry count.
+  - Record `http.response.status_code` on failed spans to distinguish rate-limit errors (429) from server errors (500+).
+  - Use exponential backoff; the retry span's start time naturally captures the wait duration.
+
+```typescript
+const llmSpan = tracer.startSpan(
+  'gen_ai.chat',
+  {
+    attributes: {
+      'gen_ai.system': 'openai',
+      'gen_ai.operation.name': 'chat',
+      'gen_ai.request.model': 'gpt-4o',
+      'gen_ai.request.max_tokens': 4096,
+      'gen_ai.request.temperature': 0.2,
+      'server.address': 'api.openai.com',
+    },
+  },
+  trace.setSpan(context.active(), agentSpan),
+);
+
+try {
+  const response = await openai.chat.completions.create({ /* ... */ });
+  llmSpan.setAttributes({
+    'gen_ai.response.model': response.model,
+    'gen_ai.response.finish_reasons': response.choices.map(c => c.finish_reason),
+    'gen_ai.usage.input_tokens': response.usage.prompt_tokens,
+    'gen_ai.usage.output_tokens': response.usage.completion_tokens,
+  });
+
+  // Record token usage in metrics for cost tracking
+  tokenCounter.add(response.usage.prompt_tokens, {
+    direction: 'input', model: response.model, agent_name: agentName,
+  });
+  tokenCounter.add(response.usage.completion_tokens, {
+    direction: 'output', model: response.model, agent_name: agentName,
+  });
+} catch (err) {
+  llmSpan.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+  llmSpan.recordException(err);
+  throw err;
+} finally {
+  llmSpan.end();
+}
+```
+
+- Never log raw prompt content or full model responses as span attributes — these are high-cardinality and may contain sensitive data. Use `gen_ai.usage.*` token counts for cost tracking and correlated logs for prompt debugging in non-production environments.
+- In production, sample GenAI spans at a higher rate than general spans (e.g., 50-100%) because each call is expensive and lower volume than typical HTTP traffic. Adjust sampling based on call volume and observability budget.
+
+### Tool Call Audit Trail
+
+Maintain a structured audit log for every tool invocation in agentic workflows. This log is separate from tracing spans and serves as an immutable compliance and debugging record.
+
+#### Schema Definition
+
+Every tool call audit log entry must include the following fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tool.name` | string | Name of the tool invoked |
+| `tool.input_hash` | string | SHA-256 hash of the tool input (for privacy, never log raw input) |
+| `tool.output_status` | string | Outcome of the tool execution: `success`, `error`, `timeout`, or `denied` |
+| `tool.duration_ms` | float | Execution time in milliseconds |
+| `agent.id` | string | ID of the agent that invoked the tool |
+| `agent.name` | string | Human-readable agent name |
+| `correlation.id` | string | Trace correlation ID linking this entry to the broader workflow |
+| `timestamp` | string | ISO 8601 timestamp of the invocation |
+| `session.id` | string | Session identifier for grouping related tool calls |
+
+#### Logging Requirements
+
+- Log every tool invocation at `info` level with the full schema above.
+- Log tool failures at `error` level with additional `error.type` and `error.message` fields describing the failure.
+- Aggregate tool call counts per agent per session for anomaly detection (e.g., an agent invoking an unusual number of tools may indicate a loop or misconfiguration).
+- Retain audit logs for a minimum of 90 days to support post-incident investigation and compliance review.
+
+#### Example Log Entry
+
+```json
+{
+  "timestamp": "2026-02-15T14:32:07.891Z",
+  "level": "info",
+  "correlation.id": "agent-run-550e8400-e29b-41d4-a716-446655440000",
+  "session.id": "sess-8f14e45f-ceea-467f-a8f0-3b5c6d7e8f9a",
+  "agent.id": "agent-run-a1b2c3d4",
+  "agent.name": "code_reviewer",
+  "tool.name": "git_diff",
+  "tool.input_hash": "sha256:3a7f2c9e8b1d4f6a0e5c7b9d2f4a6e8c0b3d5f7a9e1c3b5d7f9a2c4e6b8d0f",
+  "tool.output_status": "success",
+  "tool.duration_ms": 142.5
+}
+```
+
+### Correlation IDs for Agent Workflows
+
+Correlation IDs provide the connective thread linking all telemetry signals (logs, spans, metrics) across a multi-agent workflow. Every participant in the workflow uses the same correlation ID, enabling end-to-end traceability from the initial trigger through all agent delegations and tool calls.
+
+#### ID Generation
+
+- Use UUIDv4 for correlation IDs. Generate the ID at the workflow entry point (the first agent invocation or the orchestrator that initiates the run).
+- Format: `{workflow-type}-{uuid}` (e.g., `agent-run-550e8400-e29b-41d4-a716-446655440000`, `review-flow-7c9e6679-7425-40de-944b-e07fc1f90ae7`).
+- The workflow-type prefix provides human-readable context when scanning logs and makes it possible to filter by workflow category without parsing the full ID.
+
+#### Propagation
+
+- The correlation ID propagates from the parent agent to all sub-agents via context. Pass it explicitly when delegating to sub-agents or invoking tools.
+- Every log entry, span, and metric produced during the workflow must include the `correlation.id` attribute.
+- When crossing process boundaries (e.g., HTTP calls between services), propagate the correlation ID via a custom header (`X-Correlation-ID`) alongside standard W3C Trace Context headers.
+
+#### Parent-Child Span Linking
+
+- The parent agent's span ID becomes the `parent_span_id` attribute on child agent spans, establishing a clear hierarchy in trace visualizations.
+- For cross-workflow references (e.g., an agent run triggered by a CI pipeline event), use OpenTelemetry `SpanLink` to connect the agent workflow trace to the originating trace without creating a parent-child relationship.
+- SpanLinks preserve the independence of each workflow trace while enabling navigation between related workflows in the observability backend.
+
+#### Implementation Pattern
+
+```typescript
+import { randomUUID } from 'node:crypto';
+import { context, trace, SpanStatusCode } from '@opentelemetry/api';
+
+function generateCorrelationId(workflowType: string): string {
+  return `${workflowType}-${randomUUID()}`;
+}
+
+async function runAgentWorkflow(task: string): Promise<void> {
+  const correlationId = generateCorrelationId('agent-run');
+  const tracer = trace.getTracer('agent-orchestrator');
+
+  const rootSpan = tracer.startSpan('agent.orchestrator.invoke', {
+    attributes: {
+      'correlation.id': correlationId,
+      'agent.name': 'orchestrator',
+      'agent.task': task,
+    },
+  });
+
+  const ctx = trace.setSpan(context.active(), rootSpan);
+
+  try {
+    // Sub-agent inherits the correlation ID from context
+    await context.with(ctx, async () => {
+      await delegateToSubAgent('code_reviewer', {
+        correlationId,
+        parentSpanId: rootSpan.spanContext().spanId,
+        task: 'review changes',
+      });
+    });
+  } catch (err) {
+    rootSpan.setStatus({ code: SpanStatusCode.ERROR, message: (err as Error).message });
+    rootSpan.recordException(err as Error);
+    throw err;
+  } finally {
+    rootSpan.end();
+  }
+}
+```

package/rules/hatch3r-security-patterns.mdc

@@ -61,6 +61,11 @@ alwaysApply: true
 - Enforce parameter schemas on every tool call. Reject calls with unexpected, missing, or out-of-range arguments.
 - Rate-limit tool invocations per agent per time window. Alert on anomalous tool usage patterns.
 - Sandbox tool execution: restrict file system access, network egress, and subprocess spawning.
+- **MCP server filesystem scope:** MCP servers with filesystem access must be scoped to the minimum necessary directories:
+  - Restrict filesystem access to the project directory. MCP servers should never have access to the home directory, system directories, or unrelated project directories.
+  - Document which MCP servers have filesystem access and define their intended scope (read-only vs read-write, which directories).
+  - Configure `allowedDirectories` in MCP server configs where supported. If the server does not support directory restrictions, document this as a known risk and apply compensating controls (monitoring, read-only mode).
+  - Audit MCP server filesystem access on configuration changes. Verify that added servers do not expand the filesystem attack surface beyond the project boundary.
 
 ### ASI03 — Identity & Privilege Abuse
 
@@ -75,6 +80,12 @@ alwaysApply: true
 - Verify package integrity (checksums, signatures) before loading tools or plugins.
 - Audit third-party prompt templates for injected instructions before use.
 - Maintain an allowlist of approved MCP servers and tool sources.
+- **`npx -y` safety:** The `-y` flag auto-confirms installation of unknown packages without prompts, creating a supply chain attack vector:
+  - Never use `npx -y` with untrusted, unknown, or typo-squattable package names.
+  - Always pin explicit versions when using npx: `npx package@1.2.3` instead of `npx package`.
+  - Prefer `npm exec --package=package@version -- command` for critical tooling — it provides explicit version control and avoids silent auto-install.
+  - In CI pipelines, install tools as explicit `devDependencies` with pinned versions rather than relying on `npx` at runtime.
+  - Verify the package name and publisher on the npm registry before first use. Typosquatting attacks exploit `npx -y` by registering names similar to popular packages.
 
 ### ASI05 — Unexpected Code Execution
 

package/rules/hatch3r-testing.mdc

@@ -13,7 +13,7 @@ alwaysApply: true
 - **Named clearly.** Describe behavior: `"should award 15 XP for 25-min focus block"`.
 - **Regression.** Every bug fix includes a test that fails before the fix and passes after.
 - **No network.** Unit tests must not make network calls. Use mocks.
-- No `any` types in tests. No `.skip` without a linked issue.
+- No type escape hatches in tests. No `.skip` without a linked issue.
 - Write tests to `tests/unit/`, `tests/integration/`, `tests/e2e/`, or equivalent.
 - Use test fixtures from `tests/fixtures/` or equivalent.
 - **Browser verification.** For UI changes, verify visually in the browser via browser automation MCP after automated tests pass. Capture screenshots as evidence.

package/rules/hatch3r-theming.mdc

@@ -1,6 +1,5 @@
 ---
 description: Theming, dark mode, and color system conventions for the project
-globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx, src/**/*.css, src/**/*.scss
 alwaysApply: false
 ---
 # Theming & Dark Mode

package/rules/hatch3r-tooling-hierarchy.mdc

@@ -10,25 +10,39 @@ alwaysApply: true
 
 Read `platform` from `.agents/hatch.json` to determine which platform tools to use.
 
+### Prerequisites
+
+| Platform | Auth Setup |
+|----------|-----------|
+| **GitHub** | `gh auth login` or `GITHUB_TOKEN` env var. For Projects v2: `gh auth refresh -s project` |
+| **Azure DevOps** | `az login` and `az devops configure --defaults organization=ORG project=PROJECT` |
+| **GitLab** | `glab auth login` or `GITLAB_TOKEN` env var |
+
+### Platform CLI Fallback Reference
+
 **Fallback to the platform CLI only when:**
 - The MCP tool catalog lacks the specific capability.
 - An MCP call fails repeatedly and the CLI provides a viable alternative.
 
 **Never** use the platform CLI for operations that have a direct MCP equivalent (issue CRUD, PR/MR CRUD, search, labels).
 
-### Platform CLI Fallback Reference
-
 | Action | GitHub | Azure DevOps | GitLab |
 |--------|--------|--------------|--------|
 | Create issue | `gh issue create` | `az boards work-item create` | `glab issue create` |
+| Edit issue | `gh issue edit` | `az boards work-item update` | `glab issue update` |
 | View issue | `gh issue view` | `az boards work-item show --id N` | `glab issue view` |
 | List issues | `gh issue list` | `az boards work-item list` | `glab issue list` |
 | Create PR/MR | `gh pr create` | `az repos pr create` | `glab mr create` |
 | View PR/MR | `gh pr view` | `az repos pr show` | `glab mr view` |
 | List PRs/MRs | `gh pr list` | `az repos pr list` | `glab mr list` |
+| Merge PR/MR | `gh pr merge` | `az repos pr complete` | `glab mr merge` |
+| Search issues | `gh search issues` | `az boards query` | `glab issue list --search` |
+| Search PRs | `gh search prs` | `az repos pr list --status all` | `glab mr list --search` |
 | Search code | `gh search code` | `az repos show` | `glab search` |
-| CI runs | `gh run list/view` | `az pipelines run list/show` | `glab ci list/view` |
+| Labels | `gh label create/list` | `az boards work-item update --fields` | `glab label create/list` |
 | Releases | `gh release create` | `az repos release` | `glab release create` |
+| CI runs | `gh run list/view/watch` | `az pipelines run list/show` | `glab ci list/view` |
+| Projects | `gh project item-add/edit/list` | `az boards iteration/area` | GitLab Boards API |
 
 ## B. Documentation MCP for Library Documentation
 
@@ -94,7 +108,7 @@ Use browser automation MCP tools to visually verify UI changes after automated t
 When seeking information, follow this priority order:
 
 1. **Project specs and ADRs** — authoritative for project-specific behavior, constraints, and decisions.
-2. **Codebase exploration** (Grep, SemanticSearch) — ground truth for current implementation.
+2. **Codebase exploration** (code search tools, semantic code search) — ground truth for current implementation.
 3. **Documentation MCP** — authoritative for external library/framework APIs and patterns.
 4. **Web research** — current events, best practices, security advisories, novel problems.
 5. **Browser verification** — visual confirmation of UI changes after automated tests pass.

package/skills/hatch3r-agent-customize/SKILL.md

@@ -1,78 +1,10 @@
 ---
 id: hatch3r-agent-customize
-description: Create and manage per-agent customization files for model overrides, description changes, and project-specific markdown instructions. Use when tailoring agent behavior to project-specific needs.
+description: Agent customization — redirects to the unified hatch3r-customize skill.
 tags: [customize]
 ---
-# Agent Customization Management
+# Agent Customization
 
-## Quick Start
+> **This skill has been consolidated.** Use the `hatch3r-customize` skill with `type: agent`.
 
-```
-Task Progress:
-- [ ] Step 1: Identify which agent to customize
-- [ ] Step 2: Determine customization needs
-- [ ] Step 3: Create the customization files
-- [ ] Step 4: Sync to propagate changes
-- [ ] Step 5: Verify the customized output
-```
-
-## Step 1: Identify Agent
-
-Determine which hatch3r agent needs customization:
-- Review the agents in `.agents/agents/` and their default behaviors
-- Identify gaps between default behavior and project needs
-- Check for existing customization files in `.hatch3r/agents/`
-
-## Step 2: Determine Customization Needs
-
-Decide which customization approach to use:
-
-**YAML (`.customize.yaml`)** — for structured overrides:
-- **Model**: Override the agent's preferred model (e.g., `model: opus`)
-- **Description**: Change how the agent is described in adapter frontmatter
-- **Enabled**: Set to `false` to disable the agent entirely
-
-**Protected agents:** Some agents have `protected: true` in their canonical frontmatter. For these security-critical agents (e.g., reviewer, security-auditor, test-writer), customization cannot override `scope`, `description`, or `enabled` — only `model` and markdown instructions can be customized. See the `hatch3r-agent-customize` command for full details.
-
-**Markdown (`.customize.md`)** — for free-form instructions:
-- Domain-specific review checklists
-- Architecture context and constraints
-- Project-specific workflow steps
-- Compliance and security requirements
-
-## Step 3: Create Customization Files
-
-Create files in `.hatch3r/agents/`:
-
-**For YAML overrides:**
-```yaml
-# .hatch3r/agents/{agent-id}.customize.yaml
-model: opus
-description: "Security-focused reviewer for healthcare platform"
-```
-
-**For markdown instructions:**
-Create `.hatch3r/agents/{agent-id}.customize.md` with project-specific instructions. This content is injected into the managed block under `## Project Customizations`.
-
-Set only the fields/content you need — partial customization is valid.
-
-## Step 4: Sync
-
-Run `npx hatch3r sync` to propagate customizations to all adapter outputs. The sync:
-- Reads `.customize.yaml` for structured overrides (model, description, enabled)
-- Reads `.customize.md` and appends it inside the managed block
-- Generates updated output for every configured adapter (Cursor, Claude, etc.)
-
-## Step 5: Verify
-
-Confirm customizations appear in adapter output files:
-- Check model appears in frontmatter (e.g., `.cursor/agents/hatch3r-reviewer.md`)
-- Check markdown instructions appear inside the managed block
-- Verify disabled agents are absent from adapter outputs
-
-## Definition of Done
-
-- [ ] Customization files created in `.hatch3r/agents/`
-- [ ] `npx hatch3r sync` completes without errors
-- [ ] Adapter output files reflect the customizations
-- [ ] Customization files committed to the repository
+For agent-specific reference (model resolution, protected agents, YAML schema), see the `hatch3r-agent-customize` command.

package/skills/hatch3r-command-customize/SKILL.md

@@ -1,68 +1,10 @@
 ---
 id: hatch3r-command-customize
-description: Create and manage per-command customization files for description overrides, enable/disable control, and project-specific markdown instructions. Use when tailoring command behavior to project-specific needs.
+description: Command customization — redirects to the unified hatch3r-customize skill.
 tags: [customize]
 ---
-# Command Customization Management
+# Command Customization
 
-## Quick Start
+> **This skill has been consolidated.** Use the `hatch3r-customize` skill with `type: command`.
 
-```
-Task Progress:
-- [ ] Step 1: Identify which command to customize
-- [ ] Step 2: Determine customization needs
-- [ ] Step 3: Create the customization files
-- [ ] Step 4: Sync to propagate changes
-- [ ] Step 5: Verify the customized output
-```
-
-## Step 1: Identify Command
-
-Determine which hatch3r command needs customization:
-- Review the commands in `.agents/commands/` and their default behavior
-- Identify gaps between default behavior and project needs
-- Check for existing customization files in `.hatch3r/commands/`
-
-## Step 2: Determine Customization Needs
-
-Decide which customization approach to use:
-
-**YAML (`.customize.yaml`)** — for structured overrides:
-- **Description**: Change how the command is described in adapter outputs
-- **Enabled**: Set to `false` to disable the command entirely
-
-**Markdown (`.customize.md`)** — for free-form instructions:
-- Project-specific workflow steps
-- Additional prerequisites or constraints
-- Custom deployment or release procedures
-
-## Step 3: Create Customization Files
-
-Create files in `.hatch3r/commands/`:
-
-**For YAML overrides:**
-```yaml
-# .hatch3r/commands/{command-id}.customize.yaml
-description: "Release workflow with staging validation"
-```
-
-**For markdown instructions:**
-Create `.hatch3r/commands/{command-id}.customize.md` with project-specific additions. This content is injected into the managed block under `## Project Customizations`.
-
-## Step 4: Sync
-
-Run `npx hatch3r sync` to propagate customizations to all adapter outputs.
-
-## Step 5: Verify
-
-Confirm customizations appear in adapter output files:
-- Check description in adapter outputs (where applicable)
-- Check markdown instructions appear inside the managed block
-- Verify disabled commands are absent from adapter outputs
-
-## Definition of Done
-
-- [ ] Customization files created in `.hatch3r/commands/`
-- [ ] `npx hatch3r sync` completes without errors
-- [ ] Adapter output files reflect the customizations
-- [ ] Customization files committed to the repository
+For command-specific reference (YAML schema, examples), see the `hatch3r-command-customize` command.

package/skills/hatch3r-customize/SKILL.md

@@ -0,0 +1,117 @@
+---
+id: hatch3r-customize
+description: Create and manage customization files for any hatch3r artifact type (agents, commands, rules, skills). Supports model overrides, description changes, scope overrides, enable/disable control, and project-specific markdown instructions.
+tags: [customize]
+---
+# Artifact Customization Management
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Identify what to customize (and why)
+- [ ] Step 2: Determine customization needs
+- [ ] Step 3: Multi-stakeholder review
+- [ ] Step 4: Create the customization files
+- [ ] Step 5: Sync to propagate changes
+- [ ] Step 6: Verify the customized output
+```
+
+## Artifact Types
+
+This skill handles customization for all artifact types. The `type` parameter determines file locations, available YAML fields, and verification steps.
+
+| Type | Source Directory | Customization Directory | YAML Fields |
+|------|-----------------|------------------------|-------------|
+| `agent` | `.agents/agents/` | `.hatch3r/agents/` | `model`, `description`, `enabled` |
+| `command` | `.agents/commands/` | `.hatch3r/commands/` | `description`, `enabled` |
+| `rule` | `.agents/rules/` | `.hatch3r/rules/` | `scope`, `description`, `enabled` |
+| `skill` | `.agents/skills/` | `.hatch3r/skills/` | `description`, `enabled` |
+
+**Protected agents:** Some agents have `protected: true` in their canonical frontmatter. For these agents, `description` and `enabled` overrides are ignored — only `model` and markdown instructions can be customized.
+
+## Step 1: Identify and Root-Cause
+
+Determine which artifact needs customization and **why**:
+
+1. Review the artifacts in the appropriate source directory and their default behaviors.
+2. Identify gaps between default behavior and project needs.
+3. Check for existing customization files in the appropriate `.hatch3r/{type}s/` directory.
+4. **Root-cause analysis:** Before proceeding, consider:
+   - Is this a genuine project-specific need, or a workaround for a bug in the default content?
+   - Would this customization be better addressed upstream (by modifying the canonical artifact)?
+   - Could a rule or learning achieve the same effect with less coupling?
+
+   If the customization is working around a default content issue, note it as a candidate for upstream contribution before proceeding.
+
+## Step 2: Determine Customization Needs
+
+Decide which customization approach to use:
+
+**YAML (`.customize.yaml`)** — for structured overrides:
+
+| Field | Available For | Description |
+|-------|--------------|-------------|
+| `model` | agent only | Override the agent's preferred model |
+| `scope` | rule only | Override when the rule applies (`always` or glob patterns) |
+| `description` | all types | Change how the artifact is described in adapter outputs |
+| `enabled` | all types | Set to `false` to exclude from adapter output generation |
+
+**Markdown (`.customize.md`)** — for free-form instructions:
+- Domain-specific checklists, constraints, or workflow additions
+- Architecture context relevant to the artifact's function
+- Project-specific requirements (compliance, testing, deployment)
+
+Set only the fields/content you need — partial customization is valid.
+
+## Step 3: Multi-Stakeholder Review
+
+Before creating customization files, consider the impact from multiple perspectives:
+
+1. **Developer experience:** Does this customization make the developer's workflow better or worse? Will it cause confusion for new team members?
+2. **Quality impact:** Does disabling or weakening an artifact (especially agents or rules) reduce quality safeguards? What compensating controls exist?
+3. **Maintenance burden:** Will this customization need updating when the upstream canonical artifact changes? Is the coupling acceptable?
+4. **Consistency:** Does this customization create inconsistency with other artifacts or team conventions?
+
+**Confidence expression:** State your confidence in the customization decision:
+- **High confidence:** Clear project-specific need with no quality trade-offs.
+- **Medium confidence:** Reasonable need but with trade-offs worth noting.
+- **Low confidence:** Workaround or uncertain benefit — recommend revisiting after more experience.
+
+## Step 4: Create Customization Files
+
+Create files in `.hatch3r/{type}s/`:
+
+**For YAML overrides:** Create `.hatch3r/{type}s/{artifact-id}.customize.yaml` with the applicable fields from the Step 2 table.
+
+**For markdown instructions:** Create `.hatch3r/{type}s/{artifact-id}.customize.md` with project-specific content. This is injected into the managed block under `## Project Customizations`.
+
+## Step 5: Sync
+
+Run `npx hatch3r sync` to propagate customizations to all adapter outputs. The sync reads `.customize.yaml` for structured overrides, reads `.customize.md` and appends it inside the managed block, and generates updated output for every configured adapter.
+
+## Step 6: Verify
+
+Confirm customizations appear in adapter output files:
+- Check YAML fields are reflected in adapter-specific frontmatter
+- Check markdown instructions appear inside the managed block
+- Verify disabled artifacts are absent from adapter outputs
+- **For rules:** verify scope is applied correctly in adapter-specific frontmatter
+
+### Quality Gate
+
+Verification is not just "sync completes." Confirm:
+- [ ] The adapter output for the customized artifact contains the expected changes
+- [ ] No unrelated artifacts were affected by the sync
+- [ ] If an artifact was disabled, verify no command or skill references it as a required dependency
+- [ ] If a rule scope was narrowed, verify the excluded file patterns do not lose important coverage
+
+## Definition of Done
+
+- [ ] Root-cause considered (Step 1) — not working around an upstream issue
+- [ ] Multi-stakeholder impact reviewed (Step 3)
+- [ ] Customization files created in `.hatch3r/{type}s/`
+- [ ] `npx hatch3r sync` completes without errors
+- [ ] Adapter output files reflect the customizations
+- [ ] Quality gate checks pass (Step 6)
+- [ ] Customization files committed to the repository