hatch3r 1.0.0 → 1.2.0

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

@@ -1,12 +1,13 @@
 ---
 id: hatch3r-issue-workflow
-description: Guides the 8-step agentic development workflow for GitHub issues. Covers parsing issues, loading skills, reading specs, planning, implementing, testing, opening PRs, and addressing review. Use when working on any GitHub issue or when the user mentions an issue number.
+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
 
 ## Quick Start
 
-When assigned a GitHub issue, follow these 8 steps in order:
+When assigned an issue or work item (GitHub Issue, Azure DevOps Work Item, or GitLab Issue — check `platform` in `.agents/hatch.json`), follow these 8 steps in order:
 
 ```
 Task Progress:
@@ -86,7 +87,7 @@ When working on multiple standalone issues (not part of an epic), apply the same
 
 ### Plain Chat with Multiple Tasks
 
-When working from plain chat instructions with multiple tasks (numbered lists, multiple issue references, or distinct requests), parse into discrete tasks and apply the batch delegation pattern above. For GitHub issue references, fetch issue details. For natural language tasks, derive title, acceptance criteria, and type from the instruction.
+When working from plain chat instructions with multiple tasks (numbered lists, multiple issue references, or distinct requests), parse into discrete tasks and apply the batch delegation pattern above. For issue references (GitHub Issues, ADO Work Items, or GitLab Issues), fetch issue details using the appropriate platform CLI. For natural language tasks, derive title, acceptance criteria, and type from the instruction.
 
 The implementer sub-agent protocol is defined in the hatch3r-implementer agent. Each sub-agent handles its own implementation and testing but does NOT create branches, commits, or PRs.
 
@@ -114,11 +115,15 @@ Skip this step if the issue has no user-facing UI changes.
 - Check the browser console for errors or warnings.
 - Capture screenshots as evidence for the PR.
 
-## Step 7: Open PR
+## Step 7: Open PR / MR
 
-- Use the project's PR template. Fill every section.
-- Link to the issue. Include plan, implementation summary, test evidence.
-- **Base branch:** Use `board.defaultBranch` from `/.agents/hatch.json` when creating PRs (fallback: `"main"`). Use `gh pr create --base {defaultBranch}` or equivalent.
+- Use the project's PR/MR template. Fill every section.
+- Link to the issue/work item. Include plan, implementation summary, test evidence.
+- **Base branch:** Use `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+- Open a code review using the platform CLI (check `platform` in `.agents/hatch.json`):
+  - **GitHub:** `gh pr create --base {defaultBranch} --head {branch} --title "..." --body "..."`
+  - **Azure DevOps:** `az repos pr create --source-branch {branch} --target-branch {defaultBranch} --title "..." --description "..."`
+  - **GitLab:** `glab mr create --source-branch {branch} --target-branch {defaultBranch} --title "..." --description "..."`
 - Self-review against the Definition of Done from the loaded skill.
 
 ## Step 8: Address Review

package/skills/hatch3r-logical-refactor/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-logical-refactor
 description: Workflow for changing behavior or logic flow without adding new features or overhauling UI. Use when modifying business logic, data flows, behavioral rules, or working on logical refactor issues.
+tags: [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-migration/SKILL.md

@@ -2,6 +2,7 @@
 id: hatch3r-migration
 type: skill
 description: Plan and execute migrations for databases, frameworks, and dependencies. Covers breaking change analysis, phased rollout, and rollback procedures.
+tags: [implementation, brownfield]
 ---
 
 # Migration Workflow

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

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-perf-audit
 description: Profile and optimize application performance against defined budgets. Use when investigating performance issues, auditing performance budgets, or optimizing hot paths.
+tags: [review, performance]
 ---
 > **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool as appropriate.
 
@@ -79,7 +80,7 @@ Common strategies:
 ## Step 5: Implement Optimizations
 
 - Apply changes incrementally. Measure before and after each change.
-- Document before/after for each metric in PR or audit report.
+- Document before/after for each metric in PR/MR or audit report (check `platform` in `.agents/hatch.json` for PR vs MR terminology).
 - Respect `prefers-reduced-motion` — do not add animations that ignore it.
 - Run full test suite after each optimization to avoid functional regressions.
 

package/skills/hatch3r-pr-creation/SKILL.md

@@ -1,10 +1,13 @@
 ---
 id: hatch3r-pr-creation
-description: Create a pull request following project conventions including branch naming, PR template, checklist, and rollout plan. Use when opening or preparing a pull request, or when the user asks to create a PR.
+description: Create a pull request or merge request following project conventions including branch naming, PR/MR template, checklist, and rollout plan. Use when opening or preparing a PR/MR, or when the user asks to create a PR or MR.
+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.
 
-# PR Creation Workflow
+# PR / MR Creation Workflow
+
+> **Platform detection:** Check `platform` in `.agents/hatch.json` to determine terminology and CLI. GitHub/Azure DevOps use "Pull Request" (PR); GitLab uses "Merge Request" (MR).
 
 ## Quick Start
 
@@ -12,8 +15,8 @@ description: Create a pull request following project conventions including branc
 Task Progress:
 - [ ] Step 1: Verify branch naming
 - [ ] Step 2: Self-review against checklist
-- [ ] Step 3: Fill PR template
-- [ ] Step 4: Create the PR
+- [ ] Step 3: Fill PR/MR template
+- [ ] Step 4: Create the PR/MR
 ```
 
 ## Step 1: Branch Naming
@@ -43,33 +46,40 @@ Before creating the PR, verify:
 
 **Accessibility (if UI):** Animations respect `prefers-reduced-motion`. Color contrast meets WCAG AA. Interactive elements keyboard accessible.
 
-## Step 3: Fill PR Template
+## Step 3: Fill PR/MR Template
 
-Use the project's PR template. Fill every section:
+Use the project's PR/MR template. Fill every section:
 
 - **Summary:** 1-3 sentences on what and why
 - **Type:** Feature / Bug fix / Refactor / QA / Docs / Infra
-- **Related Issues:** `Closes #N` or `Relates to #N`
+- **Related Issues:** `Closes #N` or `Relates to #N` (GitHub/GitLab), or link ADO Work Items via `AB#N`
 - **Changes:** Bullet list of key changes
 - **Screenshots:** Required for UI changes (before/after)
 - **Testing:** Which tests added/updated, manual test steps
 - **Rollout Plan:** Feature flag / gradual / direct
 - **Rollback Plan:** How to revert
 
-## Step 4: Create the PR
+## Step 4: Create the PR/MR
 
-PR title format: `{type}: {short description} (#issue)`
+PR/MR title format: `{type}: {short description} (#issue)`
 
 Examples:
 
 - `feat: add user preferences panel (#42)`
 - `fix: correct validation for email field (#87)`
 
+Create the PR/MR using the platform CLI (check `platform` in `.agents/hatch.json`):
+- **GitHub:** `gh pr create --base {defaultBranch} --head {branch} --title "..." --body "..."`
+- **Azure DevOps:** `az repos pr create --source-branch {branch} --target-branch {defaultBranch} --title "..." --description "..."`
+- **GitLab:** `glab mr create --source-branch {branch} --target-branch {defaultBranch} --title "..." --description "..."`
+
+Use `board.defaultBranch` from `.agents/hatch.json` as the target branch (fallback: `"main"`).
+
 ## Required Agent Delegation
 
 You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`) at the appropriate points:
 
-- **`hatch3r-reviewer`** — MUST spawn before PR creation for code review. Include the full diff and acceptance criteria in the prompt. Apply reviewer feedback before creating the PR.
+- **`hatch3r-reviewer`** — MUST spawn before PR/MR creation for code review. Include the full diff and acceptance criteria in the prompt. Apply reviewer feedback before creating the PR/MR.
 
 ## Related Skills
 

package/skills/hatch3r-qa-validation/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-qa-validation
 description: E2E validation workflow producing a structured pass/fail report with evidence. Use when running QA validation, acceptance testing, verifying releases, or working on QA E2E validation issues.
+tags: [core, review]
 ---
 # QA E2E Validation Workflow
 
@@ -73,7 +74,7 @@ Produce a structured report with:
 
 - File new issues for bugs discovered during validation.
 - If validation fails, state what must be fixed before re-validation.
-- Post report as comment on the issue or linked PR.
+- Post report as comment on the issue/work item or linked PR/MR (check `platform` in `.agents/hatch.json`).
 
 ## Definition of Done
 

package/skills/hatch3r-recipe/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-recipe
 description: Create, test, and manage workflow recipes that compose hatch3r capabilities into guided sequences. Use when creating new recipes, customizing existing ones, or troubleshooting recipe execution.
+tags: [core]
 ---
 # Recipe Management
 

package/skills/hatch3r-refactor/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-refactor
 description: Internal code quality improvement workflow without changing external behavior. Use when refactoring code structure, simplifying modules, or improving maintainability.
+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.
 
@@ -23,6 +24,8 @@ Task Progress:
 - Read project quality standards documentation.
 - Read specs for the area being refactored.
 - Review all existing tests — every one must still pass after refactoring.
+- **Review reference implementations**: If the orchestrator provided `similar-implementation` researcher output, read the reference implementations and their extracted conventions. The refactored code should align with these established codebase patterns.
+- **Review resolved requirements**: If the orchestrator provided `requirements-elicitation` answers, use them to understand explicit user decisions on behavioral invariants and scope.
 - For external library docs and current best practices, follow the project's tooling hierarchy.
 
 ## Step 2: Refactor Plan
@@ -31,6 +34,7 @@ Before changing code, output:
 
 - **Goal:** what improves (readability, performance, maintainability)
 - **Strategy:** how the refactor works
+- **Convention alignment:** which reference implementation's patterns the refactored code will follow (from `similar-implementation` output), with divergences noted. If no reference was provided, note "using existing codebase conventions."
 - **Files to modify:** list with what changes
 - **Behavioral invariant:** what must NOT change
 - **Risk assessment:** what could go wrong, how to detect
@@ -65,9 +69,11 @@ Use the project's PR template. Include:
 
 ## Required Agent Delegation
 
+> **Note:** When this skill is invoked via the orchestration pipeline (board-pickup or workflow commands), skip this section — the orchestrator handles agent delegation in Phases 3 and 4.
+
 You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`) at the appropriate points:
 
-- **`hatch3r-researcher`** — MUST spawn before implementation with modes `current-state`, `refactoring-strategy`, `migration-path`. Skip only for trivially simple refactors (`risk:low` AND `priority:p3`).
+- **`hatch3r-researcher`** — MUST spawn before implementation with modes `current-state`, `refactoring-strategy`, `migration-path`. For Tier 2+ tasks (per `hatch3r-deep-context`), also include `similar-implementation` (refactors benefit most from convention alignment — ensures the refactored code follows established patterns) and `requirements-elicitation`. Skip only for trivially simple refactors (`risk:low` AND `priority:p3`).
 - **`hatch3r-reviewer`** — MUST spawn after implementation for code review, verifying behavioral preservation.
 
 ## Related Skills

package/skills/hatch3r-release/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-release
 description: Cut a release with version bump, changelog, tagging, and deploy verification. Use when preparing a release, cutting a version, or deploying to production.
+tags: [devops]
 ---
 > **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool as appropriate.
 
@@ -14,15 +15,18 @@ Task Progress:
 - [ ] Step 2: Generate changelog from merged PRs and commit history
 - [ ] Step 3: Update version in package.json and any other version references
 - [ ] Step 4: Verify quality gates (lint, typecheck, all tests)
-- [ ] Step 5: Create git tag and GitHub release with changelog
+- [ ] Step 5: Create git tag and platform release with changelog
 - [ ] Step 6: Deploy and verify (staging first if applicable, then production)
 - [ ] Step 7: Monitor post-deploy for errors/regressions
 ```
 
 ## Step 1: Determine Version Bump
 
-- Review changes since last release: merged PRs, commit history.
-- Use **GitHub MCP** (`search_issues`, PR search) to list merged PRs since last tag.
+- Review changes since last release: merged PRs/MRs, commit history.
+- List merged PRs/MRs since last tag using the platform tools (check `platform` in `.agents/hatch.json`):
+  - **GitHub:** Use **GitHub MCP** (`search_issues`, PR search) or `gh pr list --state merged --base {defaultBranch}`
+  - **Azure DevOps:** `az repos pr list --status completed --target-branch {defaultBranch}`
+  - **GitLab:** `glab mr list --state merged --target-branch {defaultBranch}`
 - Apply [Semantic Versioning](https://semver.org/):
   - **Major:** Breaking changes (API, data model, config)
   - **Minor:** New features, backward-compatible
@@ -31,7 +35,7 @@ Task Progress:
 
 ## Step 2: Generate Changelog
 
-- List merged PRs since last release (e.g., `git log v1.2.0..HEAD --oneline` or GitHub Releases API).
+- List merged PRs/MRs since last release (e.g., `git log v1.2.0..HEAD --oneline` or the platform's release/PR API).
 - Group by category: Features, Bug Fixes, Security, Dependencies, Chore.
 - Format each entry: `- description (#PR-number)` or `- description (commit hash)`.
 - Include breaking changes section if major bump.
@@ -57,15 +61,15 @@ npm run build
 - No TODO without linked issue.
 - See project quality documentation for full pre-release gates.
 
-## Step 5: Create Tag and GitHub Release
+## Step 5: Create Tag and Release
 
 - Create annotated tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"`.
 - Push tag: `git push origin vX.Y.Z`.
-- Create GitHub Release with:
-  - Title: `vX.Y.Z`
-  - Changelog as release notes
-  - Attach build artifacts if applicable
-- Use **GitHub MCP** if available for release creation; otherwise use `gh release create` or GitHub UI.
+- Create the release using the platform CLI (check `platform` in `.agents/hatch.json`):
+  - **GitHub:** `gh release create vX.Y.Z --title "vX.Y.Z" --notes "{changelog}"` (or use **GitHub MCP** if available)
+  - **Azure DevOps:** `az repos tag create vX.Y.Z` — attach release notes as a wiki page or work item, and upload build artifacts via Azure Artifacts
+  - **GitLab:** `glab release create vX.Y.Z --name "vX.Y.Z" --notes "{changelog}"`
+- Attach build artifacts if applicable.
 
 ## Step 6: Deploy and Verify
 
@@ -87,7 +91,7 @@ npm run build
 - [ ] Version bumped in package.json
 - [ ] Changelog generated and included in release
 - [ ] Git tag created and pushed
-- [ ] GitHub release published with changelog
+- [ ] Release published with changelog (GitHub Release / ADO wiki + tag / GitLab Release)
 - [ ] Deployed to production and verified
 - [ ] Post-deploy monitoring completed (no critical regressions)
 - [ ] All release gates satisfied

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

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-rule-customize
 description: Create and manage per-rule customization files for scope overrides, description changes, enable/disable control, and project-specific markdown instructions. Use when tailoring rules to project-specific needs.
+tags: [customize]
 ---
 # Rule Customization Management
 

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

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-skill-customize
 description: Create and manage per-skill customization files for description overrides, enable/disable control, and project-specific markdown instructions. Use when tailoring skill workflows to project-specific needs.
+tags: [customize]
 ---
 # Skill Customization Management
 

package/skills/hatch3r-visual-refactor/SKILL.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-visual-refactor
 description: UI/UX change workflow matching design, accessibility, and responsiveness requirements. Use when making visual changes, updating components, working on UI issues, or implementing design mockups.
+tags: [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/dist/cli/hooks-ZOTFDEA3.js

@@ -1,59 +0,0 @@
-#!/usr/bin/env node
-
-// src/hooks/index.ts
-import { readdir, readFile } from "fs/promises";
-import { join } from "path";
-import { parse as parseYaml } from "yaml";
-async function readHookDefinitions(agentsDir) {
-  const hooksDir = join(agentsDir, "hooks");
-  let entries;
-  try {
-    const dirEntries = await readdir(hooksDir);
-    entries = dirEntries.filter((f) => f.endsWith(".md"));
-  } catch {
-    return [];
-  }
-  const hooks = [];
-  for (const entry of entries) {
-    const content = await readFile(join(hooksDir, entry), "utf-8");
-    const hook = parseHookFrontmatter(content);
-    if (hook) {
-      hooks.push(hook);
-    }
-  }
-  return hooks;
-}
-function parseHookFrontmatter(content) {
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!match) return null;
-  const parsed = parseYaml(match[1]);
-  if (!parsed || typeof parsed !== "object") return null;
-  if (!parsed.id || !parsed.event || !parsed.agent) return null;
-  const hook = {
-    id: String(parsed.id),
-    event: String(parsed.event),
-    agent: String(parsed.agent),
-    description: parsed.description ? String(parsed.description) : ""
-  };
-  const condition = {};
-  let hasCondition = false;
-  if (parsed.globs) {
-    condition.globs = String(parsed.globs).split(",").map((g) => g.trim());
-    hasCondition = true;
-  }
-  if (parsed.labels) {
-    condition.labels = String(parsed.labels).split(",").map((l) => l.trim());
-    hasCondition = true;
-  }
-  if (parsed.branches) {
-    condition.branches = String(parsed.branches).split(",").map((b) => b.trim());
-    hasCondition = true;
-  }
-  if (hasCondition) {
-    hook.condition = condition;
-  }
-  return hook;
-}
-export {
-  readHookDefinitions
-};

package/rules/hatch3r-error-handling.md

@@ -1,17 +0,0 @@
----
-id: hatch3r-error-handling
-type: rule
-description: Error handling patterns and conventions for the project
-scope: always
----
-# Error Handling
-
-- Define a structured error hierarchy: base error class with `code`, `message`, `cause`.
-- Never swallow errors silently. Always re-throw or log with context.
-- Use typed error codes (not raw strings). Reference codes in project glossary when applicable.
-- User-facing errors are separate from internal errors. Never expose internal details to clients.
-- Retry with exponential backoff for transient failures (network, rate limits). Honor `Retry-After` on 429.
-- API endpoints return structured error responses `{ code, message, details? }`. Never return stack traces.
-- Use framework error boundaries for UI components. Surface user-friendly fallback UI.
-- Include `correlationId` in all error logs for tracing across client and server.
-- Security: no secrets, tokens, or PII in error messages or logs.

package/rules/hatch3r-error-handling.mdc

@@ -1,15 +0,0 @@
----
-description: Error handling patterns and conventions for the project
-alwaysApply: false
----
-# Error Handling
-
-- Define a structured error hierarchy: base error class with `code`, `message`, `cause`.
-- Never swallow errors silently. Always re-throw or log with context.
-- Use typed error codes (not raw strings). Reference codes in project glossary when applicable.
-- User-facing errors are separate from internal errors. Never expose internal details to clients.
-- Retry with exponential backoff for transient failures (network, rate limits). Honor `Retry-After` on 429.
-- API endpoints return structured error responses `{ code, message, details? }`. Never return stack traces.
-- Use framework error boundaries for UI components. Surface user-friendly fallback UI.
-- Include `correlationId` in all error logs for tracing across client and server.
-- Security: no secrets, tokens, or PII in error messages or logs.