hatch3r 1.1.0 → 1.3.0

package/rules/hatch3r-code-standards.md

@@ -3,6 +3,7 @@ id: hatch3r-code-standards
 type: rule
 description: Code quality and file naming conventions for the project
 scope: always
+tags: [core]
 ---
 # Code Standards
 
@@ -102,6 +103,14 @@ Enforce consistent import ordering via linter rules (e.g., `eslint-plugin-import
 
 Separate each group with a blank line. Sort alphabetically within each group.
 
+## Monorepo Conventions
+
+When working in a monorepo (multiple packages or apps in a single repository):
+
+- **Scope changes to a single package at a time.** A PR should touch one package unless the change requires a coordinated cross-package update (e.g., a shared type change and its consumers). Coordinated changes must be documented in the PR description.
+- **Run tests only for affected packages.** Use the monorepo tool's filtering (e.g., `--filter`, `--scope`, `--since`) to run tests, lint, and builds only for packages affected by the current change.
+- **Respect package boundaries — do not import across packages without explicit dependency.** If package A needs something from package B, B must be declared as a dependency in A's `package.json` (or equivalent manifest). Direct file-path imports across package boundaries are forbidden.
+
 ## Dead Code Prevention
 
 - Remove unused imports, variables, functions, and type definitions immediately. Do not comment them out "for later."

package/rules/hatch3r-component-conventions.md

@@ -4,6 +4,7 @@ type: rule
 description: Rules for component development in web applications
 scope: conditional
 globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx
+tags: [implementation]
 ---
 # Component Conventions
 

package/rules/hatch3r-data-classification.md

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

package/rules/hatch3r-deep-context.md

@@ -3,6 +3,7 @@ id: hatch3r-deep-context
 type: rule
 description: Adaptive pre-implementation analysis — complexity scoring, requirements elicitation, similar implementation discovery, and transitive dependency tracing before coding
 scope: always
+tags: [core]
 ---
 # Deep Context Analysis
 

package/rules/hatch3r-dependency-management.md

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

package/rules/hatch3r-feature-flags.md

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

package/rules/hatch3r-git-conventions.md

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

package/rules/hatch3r-i18n.md

@@ -4,6 +4,7 @@ type: rule
 description: Internationalization, localization, and RTL support conventions for the project
 scope: conditional
 globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx, src/**/*.ts
+tags: [implementation]
 ---
 # Internationalization & RTL
 

package/rules/hatch3r-learning-consult.md

@@ -3,6 +3,7 @@ id: hatch3r-learning-consult
 type: rule
 description: Auto-consult project learnings before implementation
 scope: always
+tags: [core]
 ---
 # Learning Consultation
 

package/rules/hatch3r-migrations.md

@@ -3,6 +3,7 @@ id: hatch3r-migrations
 type: rule
 description: Database migration and schema change patterns for the project
 scope: always
+tags: [implementation, brownfield]
 ---
 # Migrations
 
@@ -15,3 +16,14 @@ scope: always
 - Document schema changes in project data model spec.
 - Rollback plan required for every migration. Never run destructive migrations without backup verification.
 - Hot documents must stay within size limits after migration.
+
+## Data Validation During Migration
+
+- Validate data integrity after each migration step, not just at the end. Check that migrated records match the expected schema, required fields are populated, and no data was silently dropped.
+- Include count checks: the number of records processed should match the number of records in the source collection. Log discrepancies as errors, not warnings.
+- For large datasets, migrate in batches with progress checkpoints. If a batch fails, resume from the last checkpoint rather than restarting the entire migration.
+
+## Migration Coordination in Multi-Service Environments
+
+- When a migration affects shared data (e.g., a schema used by multiple services), coordinate the migration order across services. The consuming services must be deployed with backward-compatible readers before the migration runs.
+- Never assume that all service instances will be running the same code version during a migration window. Design migrations to tolerate mixed-version reads and writes during the rollout period.

package/rules/hatch3r-observability.md

@@ -3,6 +3,7 @@ id: hatch3r-observability
 type: rule
 description: Logging, metrics, and tracing conventions for the project
 scope: conditional
+tags: [devops]
 ---
 # Observability
 
@@ -165,3 +166,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-performance-budgets.md

@@ -3,6 +3,7 @@ id: hatch3r-performance-budgets
 type: rule
 description: Performance budgets and targets for the project
 scope: conditional
+tags: [performance]
 ---
 # Performance Budgets
 

package/rules/hatch3r-secrets-management.md

@@ -3,6 +3,7 @@ id: hatch3r-secrets-management
 type: rule
 description: Secret management, rotation, and secure handling patterns for the project
 scope: always
+tags: [security]
 ---
 # Secrets Management
 

package/rules/hatch3r-security-patterns.md

@@ -3,6 +3,7 @@ id: hatch3r-security-patterns
 type: rule
 description: Security patterns including input validation, auth enforcement, and AI/agentic security for the project
 scope: always
+tags: [security]
 ---
 # Security Patterns
 
@@ -63,6 +64,11 @@ scope: always
 - 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
 
@@ -77,6 +83,12 @@ scope: always
 - 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.md

@@ -3,6 +3,7 @@ id: hatch3r-testing
 type: rule
 description: Test standards and conventions for the project
 scope: always
+tags: [core]
 ---
 # Testing Standards
 

package/rules/hatch3r-theming.md

@@ -4,6 +4,7 @@ type: rule
 description: Theming, dark mode, and color system conventions for the project
 scope: conditional
 globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx, src/**/*.css, src/**/*.scss
+tags: [implementation]
 ---
 # Theming & Dark Mode
 

package/rules/hatch3r-tooling-hierarchy.md

@@ -3,6 +3,7 @@ id: hatch3r-tooling-hierarchy
 type: rule
 description: Priority order for tools and knowledge sources
 scope: always
+tags: [core]
 ---
 # Tooling Hierarchy
 

package/skills/hatch3r-a11y-audit/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-a11y-audit
 description: Comprehensive WCAG AA accessibility audit with findings and fixes. Use when auditing accessibility, verifying WCAG compliance, or improving a11y across the application.
+tags: [review, a11y]
 ---
 # Accessibility Audit Workflow
 

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

@@ -1,6 +1,7 @@
 ---
 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.
+tags: [customize]
 ---
 # Agent Customization Management
 

package/skills/hatch3r-api-spec/SKILL.md

@@ -2,6 +2,7 @@
 id: hatch3r-api-spec
 type: skill
 description: Generate and validate OpenAPI specifications from codebase. Covers endpoint design, schema validation, and documentation generation.
+tags: [planning]
 ---
 
 # API Specification Workflow

package/skills/hatch3r-architecture-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-architecture-review
 description: Evaluate architectural decisions and produce ADRs following the project template. Use when making architectural decisions, evaluating trade-offs, or creating ADRs.
+tags: [review]
 ---
 # Architecture Review Workflow
 

package/skills/hatch3r-bug-fix/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-bug-fix
 description: Step-by-step bug fix workflow. Diagnose root cause, implement minimal fix, write regression test. Use when fixing bugs, working on bug report issues, or when the user mentions a bug.
+tags: [core, implementation]
 ---
 > **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool as appropriate.
 

package/skills/hatch3r-ci-pipeline/SKILL.md

@@ -2,6 +2,7 @@
 id: hatch3r-ci-pipeline
 type: skill
 description: Design and optimize CI/CD pipelines. Covers stage design, test parallelization, artifact management, and pipeline performance.
+tags: [devops]
 ---
 
 # CI Pipeline Workflow

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

@@ -1,6 +1,7 @@
 ---
 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.
+tags: [customize]
 ---
 # Command Customization Management
 

package/skills/hatch3r-context-health/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-context-health
 description: Monitor and maintain conversation context health during long sessions. Use when context may be degrading, after many turns, or when experiencing repeated errors.
+tags: [maintenance]
 ---
 # Context Health Monitoring
 

package/skills/hatch3r-cost-tracking/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-cost-tracking
 description: Track token usage and estimate costs for agent sessions. Use when monitoring spend, approaching budget limits, or generating cost reports.
+tags: [maintenance]
 ---
 # Cost Tracking Workflow
 

package/skills/hatch3r-dep-audit/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-dep-audit
 description: Audit and update npm dependencies for security, freshness, and bundle impact. Use when auditing dependencies, responding to CVEs, or upgrading packages.
+tags: [maintenance, security]
 ---
 > **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool as appropriate.
 
@@ -34,7 +35,7 @@ For critical and high vulnerabilities:
   - **GitHub:** GitHub Security Advisories (`gh api /repos/{owner}/{repo}/security-advisories`)
   - **Azure DevOps:** Azure Artifacts security scanning and Azure Boards advisory tracking
   - **GitLab:** GitLab Dependency Scanning (Security & Compliance → Vulnerability Report)
-- Prioritize: critical first, then high. Moderate/low can be batched.
+- Prioritize: critical first, then high. Medium/low can be batched.
 - Note any packages with no fix available — document mitigation or deferral rationale.
 
 ## Step 3: Plan Upgrades

package/skills/hatch3r-feature/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-feature
 description: End-to-end feature implementation workflow. Covers data model, domain logic, API, and UI as a vertical slice. Use when implementing new features or working on feature request issues.
+tags: [core, implementation]
 ---
 > **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool as appropriate.
 

package/skills/hatch3r-gh-agentic-workflows/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-gh-agentic-workflows
 description: Set up CI/CD agentic workflows for continuous AI-powered repository automation (GitHub Actions, Azure Pipelines, GitLab CI)
+tags: [devops, team]
 ---
 # CI/CD Agentic Workflows Integration
 

package/skills/hatch3r-incident-response/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-incident-response
 description: Handle production incidents with structured triage, mitigation, and post-mortem. Use when responding to production issues, outages, or security incidents.
+tags: [devops]
 ---
 # Incident Response Workflow
 

package/skills/hatch3r-issue-workflow/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-issue-workflow
 description: Guides the 8-step agentic development workflow for issues/work items. Covers parsing issues, loading skills, reading specs, planning, implementing, testing, opening PRs/MRs, and addressing review. Use when working on any issue/work item or when the user mentions an issue number.
+tags: [core, implementation]
 ---
 # Issue Workflow