hatch3r 1.0.0 → 1.2.0

package/github-agents/hatch3r-docs-agent.md

@@ -2,6 +2,7 @@
 name: hatch3r-docs-agent
 description: Technical writer who maintains specs, ADRs, and documentation
 # Simplified agent for GitHub Copilot/Codex
+tags: [team, devops]
 ---
 
 You are an expert technical writer for the project.

package/github-agents/hatch3r-lint-agent.md

@@ -2,6 +2,7 @@
 name: hatch3r-lint-agent
 description: Code quality enforcer who fixes style, formatting, and type issues
 # Simplified agent for GitHub Copilot/Codex
+tags: [team, devops]
 ---
 
 You are a code quality engineer for the project.

package/github-agents/hatch3r-security-agent.md

@@ -2,6 +2,7 @@
 name: hatch3r-security-agent
 description: Security analyst who audits code, rules, and data flows
 # Simplified agent for GitHub Copilot/Codex
+tags: [team, devops]
 ---
 
 You are an expert security analyst for the project.

package/github-agents/hatch3r-test-agent.md

@@ -2,6 +2,7 @@
 name: hatch3r-test-agent
 description: QA engineer who writes and maintains tests
 # Simplified agent for GitHub Copilot/Codex
+tags: [team, devops]
 ---
 
 You are an expert QA engineer for the project.

package/hooks/hatch3r-ci-failure.md

@@ -4,7 +4,37 @@ type: hook
 event: ci-failure
 agent: ci-watcher
 description: Diagnose CI pipeline failures
+tags: [core]
 ---
 # Hook: ci-failure → ci-watcher
 
 Activate the ci-watcher agent when a CI pipeline fails to diagnose the root cause, suggest fixes, and report actionable next steps.
+
+## Agent Behavior
+
+When this hook fires, the assigned agent should:
+
+1. Fetch the full CI run logs for the failed workflow run (using `gh run view {run-id} --log` or equivalent).
+2. Identify the failing job(s) and step(s) — extract the error output, exit code, and stack trace (if present).
+3. Classify the failure type: build error, test failure, lint violation, type error, dependency issue, infrastructure/flaky, timeout, or permission error.
+4. For test failures: identify the specific failing test(s), expected vs. actual values, and the source file(s) involved.
+5. For build/type errors: extract the compiler error message and the source location.
+6. Produce a root-cause hypothesis with a concrete suggested fix (code change, config change, or retry recommendation for flaky failures).
+7. If the failure matches a known pattern from `.agents/learnings/`, reference the relevant learning.
+
+## Expected Output
+
+A structured diagnostic report containing:
+
+- **Failed job**: Name and step of the failing CI job.
+- **Error type**: Classification (build, test, lint, type, dependency, infra, timeout, permission).
+- **Root cause**: Concise explanation of why the failure occurred.
+- **Error excerpt**: The relevant log output (truncated to key lines).
+- **Suggested fix**: Specific, actionable remediation steps.
+- **Related learnings**: Links to any matching entries in `.agents/learnings/` (if applicable).
+
+## Configuration
+
+- **CI provider**: Auto-detected from repository config. Override with `ciProvider` in hook config if needed.
+- **Log depth**: Default fetches the last 200 lines of the failing step. Adjust via `logLines` for more verbose failures.
+- **Auto-retry**: Set `autoRetryFlaky: true` to automatically re-run the workflow when the failure is classified as infrastructure/flaky (max 1 retry).

package/hooks/hatch3r-file-save.md

@@ -5,7 +5,29 @@ event: file-save
 agent: context-rules
 description: Activate context-specific rules on file save
 globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
+tags: [core]
 ---
 # Hook: file-save → context-rules
 
 Activate context-specific rules when a file is saved, applying relevant coding standards and patterns based on the file's location and type.
+
+## Agent Behavior
+
+When this hook fires, the assigned agent should:
+
+1. Determine the saved file's path and match it against the project's rule definitions in `.agents/rules/`.
+2. Load all rules where `scope: always` applies, plus any rules with glob patterns matching the saved file's path.
+3. Evaluate the saved file's contents against the loaded rules — check for convention violations, pattern mismatches, or missing required elements (e.g., missing error handling in API routes, missing accessibility attributes in components).
+4. If violations are found, surface them as inline warnings or suggestions (not blocking — file-save hooks should be non-disruptive).
+5. Cache loaded rules for the session to avoid re-reading on every save.
+
+## Expected Output
+
+- **If violations found**: Non-blocking inline suggestions with rule ID, description, and the specific line(s) that violate the rule.
+- **If clean**: No output (silent pass — do not emit noise on every save).
+
+## Configuration
+
+- **Globs**: Controlled by the `globs` frontmatter field. Adjust to match your project's source file extensions.
+- **Rule sources**: Reads from `.agents/rules/`. Rules with matching `globs` or `scope: always` are activated.
+- **Debounce**: To avoid excessive processing during rapid saves, the agent debounces with a 2-second window (configurable via `debounceMs`).

package/hooks/hatch3r-post-merge.md

@@ -4,7 +4,30 @@ type: hook
 event: post-merge
 agent: ci-watcher
 description: Check CI pipeline status after merge
+tags: [core]
 ---
 # Hook: post-merge → ci-watcher
 
 Activate the ci-watcher agent after a merge completes to verify the CI pipeline passes on the updated branch.
+
+## Agent Behavior
+
+When this hook fires, the assigned agent should:
+
+1. Detect the branch that was just merged into and the merge commit SHA.
+2. Poll the CI pipeline (GitHub Actions, CircleCI, etc.) for the status of the merge commit.
+3. Wait for pipeline completion with exponential backoff (initial: 30s, max: 5min, timeout: 15min).
+4. If the pipeline fails, fetch the failure logs, identify the failing step(s), and produce a root-cause summary.
+5. If new dependencies were added or lockfiles changed during the merge, flag this for the developer's awareness.
+
+## Expected Output
+
+- **On success**: "CI passed for merge commit `{sha}` on `{branch}` — all checks green."
+- **On failure**: A structured diagnostic including the failing job name, step, error excerpt, and suggested fix. If the failure appears related to the merge (e.g., test conflict), flag it explicitly.
+- **On timeout**: "CI pipeline for `{sha}` has not completed after 15 minutes. Check manually: {link}."
+
+## Configuration
+
+- **CI provider**: Auto-detected from repository config (`.github/workflows/`, `.circleci/`, etc.). Override with `ciProvider` in hook config.
+- **Timeout**: Default 15 minutes. Adjust via `timeoutMinutes` in hook config.
+- **Notifications**: Set `notifyOnFailure: true` to post a comment on the merge PR when CI fails.

package/hooks/hatch3r-pre-commit.md

@@ -5,7 +5,30 @@ event: pre-commit
 agent: lint-fixer
 description: Auto-fix lint and formatting issues before commit
 globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
+tags: [core]
 ---
 # Hook: pre-commit → lint-fixer
 
 Activate the lint-fixer agent before each commit to automatically detect and fix lint errors, formatting issues, and style violations in staged files.
+
+## Agent Behavior
+
+When this hook fires, the assigned agent should:
+
+1. Identify all staged files matching the configured globs.
+2. Run the project's configured linter (ESLint, Biome, etc.) and formatter (Prettier, dprint, etc.) against only the staged files.
+3. Auto-fix any fixable violations (formatting, import ordering, unused imports, trailing whitespace).
+4. If unfixable violations remain, report them clearly with file paths and line numbers so the developer can address them before committing.
+5. Re-stage any auto-fixed files so the commit includes the corrections.
+
+## Expected Output
+
+- A summary of fixes applied (e.g., "Fixed 3 formatting issues in 2 files").
+- If unfixable issues remain: a list of violations with file, line, rule ID, and message.
+- If all files pass: a short confirmation ("All staged files pass lint and formatting checks").
+
+## Configuration
+
+- **Globs**: Controlled by the `globs` frontmatter field. Adjust to match your project's source file extensions.
+- **Tooling**: The agent auto-detects the project's lint/format stack from config files (`eslint.config.*`, `.prettierrc`, `biome.json`, etc.).
+- **Severity**: By default, only errors block the commit. Set `blockOnWarnings: true` in the hook config to also block on warnings.

package/hooks/hatch3r-pre-push.md

@@ -4,7 +4,29 @@ type: hook
 event: pre-push
 agent: security-auditor
 description: Scan for secrets and security issues before push
+tags: [core]
 ---
 # Hook: pre-push → security-auditor
 
 Activate the security-auditor agent before pushing to scan for accidentally committed secrets, API keys, credentials, and other security-sensitive content.
+
+## Agent Behavior
+
+When this hook fires, the assigned agent should:
+
+1. Identify all commits being pushed that are not yet on the remote.
+2. Scan the diff of those commits for high-entropy strings, known secret patterns (API keys, tokens, passwords, private keys, connection strings), and files that commonly contain secrets (`.env`, `credentials.json`, `*.pem`).
+3. Cross-reference findings against an allowlist (if configured) to suppress known false positives.
+4. If secrets are detected, block the push and report the findings with file paths, line numbers, and the type of secret detected.
+5. If no secrets are found, allow the push to proceed.
+
+## Expected Output
+
+- If secrets are found: a blocking report listing each finding with file, line, secret type, and remediation advice (e.g., "Rotate this key and move it to environment variables").
+- If clean: a short confirmation ("No secrets detected in outgoing commits").
+
+## Configuration
+
+- **Allowlist**: Add known false positives to `.agents/security/secret-allowlist.json` (patterns or file paths to ignore).
+- **Pattern extensions**: The agent uses built-in patterns for common secret types. Add project-specific patterns via `.agents/security/custom-patterns.json`.
+- **Scope**: By default, scans only the diff of outgoing commits. Set `scanFullHistory: true` to scan all files (slower, useful for initial audits).

package/hooks/hatch3r-session-start.md

@@ -4,7 +4,29 @@ type: hook
 event: session-start
 agent: learnings-loader
 description: Load relevant learnings at session start
+tags: [core]
 ---
 # Hook: session-start → learnings-loader
 
 Activate the learnings-loader agent when a new coding session starts to surface relevant project learnings, recent decisions, and context from previous sessions.
+
+## Agent Behavior
+
+When this hook fires, the assigned agent should:
+
+1. Read the `.agents/learnings/` directory and index all available learning files by area, tags, and recency.
+2. Identify the most relevant learnings based on recently modified files in the working tree (using `git diff` and `git log` to infer the active work area).
+3. Surface the top 3-5 most relevant learnings as a brief summary, prioritizing: (a) learnings from the last 7 days, (b) learnings matching the current branch's area labels, (c) learnings tagged as high-impact or cross-cutting.
+4. If there are recent architectural decisions or convention changes, highlight them prominently.
+5. If `.agents/learnings/` does not exist or is empty, skip silently.
+
+## Expected Output
+
+- A concise summary block (max 10 lines) showing relevant learnings, each with: title, area, one-line takeaway, and file path for deeper reading.
+- If no relevant learnings are found: skip output entirely (do not emit "no learnings found" noise).
+
+## Configuration
+
+- **Max learnings**: Default 5. Adjust via `maxLearnings` in hook config.
+- **Recency window**: Default 7 days. Adjust via `recencyDays` to widen or narrow the time window.
+- **Area filter**: If set, only surface learnings matching the specified areas. By default, infers areas from the working tree.

package/mcp/mcp.json

@@ -35,7 +35,7 @@
       "_disabled": true,
       "_description": "Error tracking and performance monitoring (enable and configure with your Sentry auth token)",
       "command": "npx",
-      "args": ["-y", "@sentry/mcp-server@latest"],
+      "args": ["-y", "@sentry/mcp-server@0.29.0"],
       "env": {
         "SENTRY_AUTH_TOKEN": "${env:SENTRY_AUTH_TOKEN}"
       }
@@ -44,7 +44,7 @@
       "_disabled": true,
       "_description": "PostgreSQL database queries and schema inspection (enable and configure with your connection string)",
       "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-postgres"],
+      "args": ["-y", "@modelcontextprotocol/server-postgres@0.6.2"],
       "env": {
         "POSTGRES_URL": "${env:POSTGRES_URL}"
       }
@@ -53,10 +53,29 @@
       "_disabled": true,
       "_description": "Linear issue tracking and project management (enable and configure with your Linear API key)",
       "command": "npx",
-      "args": ["-y", "@mkusaka/mcp-server-linear"],
+      "args": ["-y", "@mkusaka/mcp-server-linear@1.0.15"],
       "env": {
         "LINEAR_API_KEY": "${env:LINEAR_API_KEY}"
       }
+    },
+    "azure-devops": {
+      "_disabled": true,
+      "_description": "Azure DevOps work items, repos, pipelines, and boards",
+      "command": "npx",
+      "args": ["-y", "@tiberriver256/mcp-server-azure-devops@0.1.45"],
+      "env": {
+        "AZURE_DEVOPS_PAT": "${env:AZURE_DEVOPS_PAT}",
+        "AZURE_DEVOPS_ORG": "${env:AZURE_DEVOPS_ORG}"
+      }
+    },
+    "gitlab": {
+      "_disabled": true,
+      "_description": "GitLab issues, merge requests, pipelines, and project management",
+      "command": "npx",
+      "args": ["-y", "glab", "mcp"],
+      "env": {
+        "GITLAB_TOKEN": "${env:GITLAB_TOKEN}"
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hatch3r",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Battle-tested agentic coding setup framework. One command to hatch your agent stack -- agents, skills, rules, commands, and MCP for every major AI coding tool.",
   "type": "module",
   "bin": {
@@ -40,16 +40,17 @@
     "type": "git",
     "url": "https://github.com/hatch3r/hatch3r.git"
   },
-  "homepage": "https://github.com/hatch3r/hatch3r#readme",
+  "homepage": "https://docs.hatch3r.com",
   "bugs": {
     "url": "https://github.com/hatch3r/hatch3r/issues"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "files": [
     "dist/",
     "agents/",
+    "checks/",
     "commands/",
     "rules/",
     "skills/",
@@ -64,14 +65,10 @@
     "boxen": "^8.0.1",
     "chalk": "^5.4.0",
     "commander": "^13.0.0",
-    "glob": "^11.0.0",
     "inquirer": "^12.0.0",
     "ora": "^9.3.0",
     "yaml": "^2.7.0"
   },
-  "overrides": {
-    "minimatch": ">=10.2.1"
-  },
   "devDependencies": {
     "@types/node": "^25.3.0",
     "@vitest/coverage-v8": "^3.2.4",

package/prompts/hatch3r-bug-triage.md

@@ -2,6 +2,7 @@
 id: hatch3r-bug-triage
 type: prompt
 description: Triage a bug report and suggest investigation steps
+tags: [core]
 ---
 # Bug Triage
 

package/prompts/hatch3r-code-review.md

@@ -2,6 +2,7 @@
 id: hatch3r-code-review
 type: prompt
 description: Review code changes for quality, security, and correctness
+tags: [core]
 ---
 # Code Review
 

package/prompts/hatch3r-pr-description.md

@@ -2,6 +2,7 @@
 id: hatch3r-pr-description
 type: prompt
 description: Generate a pull request description from staged changes
+tags: [core]
 ---
 # PR Description
 

package/rules/hatch3r-accessibility-standards.md

@@ -3,6 +3,7 @@ id: hatch3r-accessibility-standards
 type: rule
 description: Accessibility standards covering WCAG 2.2 AA compliance, keyboard navigation, screen readers, and ARIA patterns
 scope: always
+tags: [a11y]
 ---
 # Accessibility Standards