hatch3r 1.5.1 → 1.6.2

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

@@ -8,30 +8,23 @@ quality_charter: agents/shared/quality-charter.md
 
 > **Platform detection:** Check `platform` in `.agents/hatch.json` to determine which CI/CD system to use. Defaults to `"github"`.
 
-This skill guides setup for AI-powered CI/CD automation in hatch3r-managed projects across all supported platforms.
+This skill guides setup for AI-powered CI/CD automation in hatch3r-managed projects. The core SKILL covers GitHub Actions (the default); non-GitHub platforms load on demand from `references/`.
 
-## Overview
+## Progressive Disclosure (Anthropic 2026 skills spec)
 
-### GitHub Actions (Agentic Workflows)
+| Target platform | File to read |
+|-----------------|--------------|
+| GitHub Actions (default) | This file — read sections below |
+| Azure DevOps Pipelines | `references/azure-devops.md` |
+| GitLab CI/CD | `references/gitlab-ci.md` |
 
-GitHub Agentic Workflows (technical preview, Feb 2026) bring AI agent orchestration into
-GitHub Actions. Agentic Workflows are markdown files in `.github/workflows/` with YAML frontmatter that
-compile to GitHub Actions jobs. They support multiple AI engines (GitHub Copilot, Claude,
-OpenAI Codex) and use MCP for tool access.
+Load only the references file that matches `platform` in `.agents/hatch.json`. Do not eagerly load all three.
 
-### Azure DevOps Pipelines
+## Overview (GitHub Actions)
 
-Azure Pipelines use YAML files in the repo (typically `azure-pipelines.yml` or files under `.azuredevops/`) to define CI/CD jobs. Use the `az pipelines` CLI for management and monitoring.
+GitHub Agentic Workflows (technical preview, Feb 2026) bring AI agent orchestration into GitHub Actions. Agentic Workflows are markdown files in `.github/workflows/` with YAML frontmatter that compile to GitHub Actions jobs. They support multiple AI engines (GitHub Copilot, Claude, OpenAI Codex) and use MCP for tool access.
 
-### GitLab CI/CD
-
-GitLab CI uses `.gitlab-ci.yml` at the repo root to define pipelines. Use the `glab ci` CLI for management and monitoring.
-
-## Available Workflow Templates
-
-### Platform: GitHub Actions
-
-hatch3r recommends these agentic workflow patterns for GitHub-hosted projects:
+## Available Workflow Templates (GitHub)
 
 ### 1. Continuous Test Improvement
 
@@ -71,8 +64,7 @@ permissions:
 ---
 ```
 
-When a new issue is opened, analyze it, apply labels from the hatch3r taxonomy
-(type:*, priority:*, area:*), and add a triage summary comment.
+When a new issue is opened, analyze it, apply labels from the hatch3r taxonomy (type:*, priority:*, area:*), and add a triage summary comment.
 
 ### 3. Continuous Documentation
 
@@ -97,65 +89,6 @@ Replace `{defaultBranch}` with `board.defaultBranch` from `.agents/hatch.json` (
 
 After a PR is merged, check if documentation needs updating and open a follow-up PR.
 
-### Platform: Azure DevOps Pipelines
-
-Equivalent pipeline patterns for Azure DevOps:
-
-#### 1. Continuous Test Improvement (ADO)
-
-```yaml
-# azure-pipelines/hatch3r-continuous-testing.yml
-trigger: none
-schedules:
-  - cron: '0 6 * * 1'
-    displayName: Weekly test improvement
-    branches:
-      include: [{defaultBranch}]
-    always: true
-
-pool:
-  vmImage: 'ubuntu-latest'
-
-steps:
-  - script: echo "Analyze test coverage gaps and create PRs with new tests"
-    displayName: 'AI-assisted test improvement'
-```
-
-Replace `{defaultBranch}` with `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
-
-#### 2. Continuous Triage (ADO)
-
-Use Azure Boards service hooks to trigger a pipeline when a new work item is created. The pipeline applies labels and adds a triage comment.
-
-#### 3. Continuous Documentation (ADO)
-
-Trigger a pipeline on PR completion to the default branch. Check if documentation needs updating and open a follow-up PR via `az repos pr create`.
-
-### Platform: GitLab CI/CD
-
-Equivalent pipeline patterns for GitLab:
-
-#### 1. Continuous Test Improvement (GitLab)
-
-```yaml
-# .gitlab-ci.yml (or included file)
-continuous-test-improvement:
-  rules:
-    - if: $CI_PIPELINE_SOURCE == "schedule"
-  script:
-    - echo "Analyze test coverage gaps and create MRs with new tests"
-```
-
-Configure a pipeline schedule in GitLab (Settings → CI/CD → Schedules) for weekly runs.
-
-#### 2. Continuous Triage (GitLab)
-
-Use GitLab webhooks on issue creation to trigger a pipeline that applies labels from the hatch3r taxonomy and adds a triage comment via `glab issue update`.
-
-#### 3. Continuous Documentation (GitLab)
-
-Trigger on merge to the default branch. Check if documentation needs updating and open a follow-up MR via `glab mr create`.
-
 ## Security Considerations
 
 - Workflows run in sandboxed environments with minimal permissions
@@ -170,62 +103,39 @@ Trigger on merge to the default branch. Check if documentation needs updating an
 - The hatch3r-docs-writer agent's patterns can inform continuous documentation
 - Board management commands complement continuous triage
 
-## Setup
+## Setup (GitHub)
 
-### GitHub
 1. Enable GitHub Agentic Workflows in your repository settings
 2. Create workflow files in `.github/workflows/` using the templates above
 3. Configure the AI engine (copilot is default, claude and codex are alternatives)
 4. Set appropriate permissions for each workflow
 5. Monitor workflow runs in the Actions tab
 
-### Azure DevOps
-1. Create pipeline YAML files in the repo (e.g., `azure-pipelines/`)
-2. Register each pipeline in Azure DevOps (Pipelines → New Pipeline → Existing YAML)
-3. Configure service connections and variable groups for secrets
-4. Set appropriate pipeline permissions and approvals
-5. Monitor runs in Azure Pipelines
-
-### GitLab
-1. Define jobs in `.gitlab-ci.yml` (or use `include:` for modular files)
-2. Configure pipeline schedules for periodic jobs (Settings → CI/CD → Schedules)
-3. Set CI/CD variables for secrets (Settings → CI/CD → Variables)
-4. Configure protected branches and merge request approvals
-5. Monitor runs in CI/CD → Pipelines
-
-## Verification Steps
-
-1. **Syntax check**: Validate the workflow/pipeline definition:
-   - **GitHub:** `gh workflow view {name}` or the Actions web UI
-   - **Azure DevOps:** `az pipelines show --name {name}` or the Pipelines web UI
-   - **GitLab:** CI Lint (CI/CD → Editor → Validate) or `glab ci lint`
-2. **Dry run**: Trigger manually and monitor:
-   - **GitHub:** `gh workflow run {name}` → `gh run watch`
-   - **Azure DevOps:** `az pipelines run --name {name}` → `az pipelines runs show --id {id}`
-   - **GitLab:** `glab ci run` → `glab ci view`
-3. **Output review**: Check the AI-generated output (PR/MR, comment, label) for quality and correctness.
-4. **Permission audit**: Verify the workflow cannot access resources beyond its declared permissions.
-5. **Idempotency**: Run the workflow twice on the same input — it should not create duplicate artifacts.
-6. **Error handling**: Trigger with invalid/edge-case input — workflow should fail gracefully with clear error.
-
-## Monitoring
-
-- **Execution tracking**:
-  - **GitHub:** `gh run list --workflow={name}`
-  - **Azure DevOps:** `az pipelines runs list --pipeline-name {name}`
-  - **GitLab:** `glab ci list`
-- **Failure alerts**:
-  - **GitHub:** Settings → Notifications → Actions
-  - **Azure DevOps:** Pipeline notifications (Project Settings → Notifications)
-  - **GitLab:** Pipeline email notifications (Settings → Integrations)
-- **Cost awareness**: Monitor AI token usage per workflow run. Set spending limits in org settings.
-- **Quality metrics**: Track: success rate, output acceptance rate (merged PRs/MRs / total), mean time per run.
+For Azure DevOps setup: see `references/azure-devops.md`. For GitLab setup: see `references/gitlab-ci.md`.
+
+## Verification Steps (GitHub)
+
+1. **Syntax check:** `gh workflow view {name}` or the Actions web UI
+2. **Dry run:** `gh workflow run {name}` → `gh run watch`
+3. **Output review:** Check the AI-generated output (PR, comment, label) for quality and correctness.
+4. **Permission audit:** Verify the workflow cannot access resources beyond its declared permissions.
+5. **Idempotency:** Run the workflow twice on the same input — it should not create duplicate artifacts.
+6. **Error handling:** Trigger with invalid/edge-case input — workflow should fail gracefully with clear error.
+
+Platform-equivalent verification for ADO/GitLab: see the platform reference files.
+
+## Monitoring (GitHub)
+
+- **Execution tracking:** `gh run list --workflow={name}`
+- **Failure alerts:** Settings → Notifications → Actions
+- **Cost awareness:** Monitor AI token usage per workflow run. Set spending limits in org settings.
+- **Quality metrics:** Track success rate, output acceptance rate (merged PRs / total), mean time per run.
 
 ## Error Handling
 
-- **Workflow file has YAML syntax errors**: Validate the workflow file locally before pushing (e.g., `actionlint` for GitHub Actions, Azure Pipelines schema validation, or `glab ci lint` for GitLab). Fix all reported errors before committing.
-- **AI engine produces low-quality or empty output**: Add explicit context to the workflow prompt (file references, examples, constraints). If the output is still poor after enrichment, switch to a more capable model.
-- **Workflow runs exceed cost or time limits**: Add `timeout-minutes` to the workflow, scope file references to reduce context size, and add concurrency groups to prevent parallel runs.
+- **Workflow file has YAML syntax errors:** Validate the workflow file locally before pushing (e.g., `actionlint` for GitHub Actions). Fix all reported errors before committing.
+- **AI engine produces low-quality or empty output:** Add explicit context to the workflow prompt (file references, examples, constraints). If the output is still poor after enrichment, switch to a more capable model.
+- **Workflow runs exceed cost or time limits:** Add `timeout-minutes` to the workflow, scope file references to reduce context size, and add concurrency groups to prevent parallel runs.
 
 ## Troubleshooting
 
@@ -238,20 +148,16 @@ Trigger on merge to the default branch. Check if documentation needs updating an
 | Rate limiting | Too many workflow runs | Add concurrency groups, reduce trigger frequency |
 | Workflow hangs | Large repo context or slow AI response | Set timeout-minutes, scope file references |
 
-## Rollback
+## Rollback (GitHub)
 
 If a workflow produces undesirable results:
 
-1. **Disable immediately**:
-   - **GitHub:** `gh workflow disable {name}` or toggle in repo Settings → Actions
-   - **Azure DevOps:** `az pipelines update --name {name} --enabled false` or toggle in Pipelines UI
-   - **GitLab:** Pause pipeline schedules in Settings → CI/CD → Schedules, or use the GitLab API
-2. **Revert outputs**: Close AI-generated PRs/MRs, remove applied labels, revert merged changes if needed.
-3. **Diagnose**: Review recent run logs:
-   - **GitHub:** `gh run view {run-id} --log`
-   - **Azure DevOps:** `az pipelines runs show --id {run-id}` and download logs from the Pipelines UI
-   - **GitLab:** `glab ci view {pipeline-id}` or check CI/CD → Pipelines in the web UI
-4. **Fix and re-enable**: Update the workflow/pipeline file, test via manual dispatch, then re-enable.
+1. **Disable immediately:** `gh workflow disable {name}` or toggle in repo Settings → Actions
+2. **Revert outputs:** Close AI-generated PRs, remove applied labels, revert merged changes if needed.
+3. **Diagnose:** `gh run view {run-id} --log`
+4. **Fix and re-enable:** Update the workflow file, test via manual dispatch, then re-enable.
+
+Platform-equivalent rollback for ADO/GitLab: see the platform reference files.
 
 ## Definition of Done
 

package/skills/hatch3r-gh-agentic-workflows/references/azure-devops.md

@@ -0,0 +1,60 @@
+# Azure DevOps Pipelines — Agentic Workflow Patterns
+
+Loaded on demand when `platform: azure-devops` in `.agents/hatch.json` or when user is setting up Azure DevOps CI.
+
+Azure Pipelines use YAML files in the repo (typically `azure-pipelines.yml` or files under `.azuredevops/`) to define CI/CD jobs. Use the `az pipelines` CLI for management and monitoring.
+
+## 1. Continuous Test Improvement (ADO)
+
+```yaml
+# azure-pipelines/hatch3r-continuous-testing.yml
+trigger: none
+schedules:
+  - cron: '0 6 * * 1'
+    displayName: Weekly test improvement
+    branches:
+      include: [{defaultBranch}]
+    always: true
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+steps:
+  - script: echo "Analyze test coverage gaps and create PRs with new tests"
+    displayName: 'AI-assisted test improvement'
+```
+
+Replace `{defaultBranch}` with `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+
+## 2. Continuous Triage (ADO)
+
+Use Azure Boards service hooks to trigger a pipeline when a new work item is created. The pipeline applies labels and adds a triage comment.
+
+## 3. Continuous Documentation (ADO)
+
+Trigger a pipeline on PR completion to the default branch. Check if documentation needs updating and open a follow-up PR via `az repos pr create`.
+
+## Setup
+
+1. Create pipeline YAML files in the repo (e.g., `azure-pipelines/`)
+2. Register each pipeline in Azure DevOps (Pipelines → New Pipeline → Existing YAML)
+3. Configure service connections and variable groups for secrets
+4. Set appropriate pipeline permissions and approvals
+5. Monitor runs in Azure Pipelines
+
+## Verification
+
+- **Syntax check:** `az pipelines show --name {name}` or the Pipelines web UI
+- **Dry run:** `az pipelines run --name {name}` → `az pipelines runs show --id {id}`
+
+## Monitoring
+
+- **Execution tracking:** `az pipelines runs list --pipeline-name {name}`
+- **Failure alerts:** Pipeline notifications (Project Settings → Notifications)
+
+## Rollback
+
+1. Disable: `az pipelines update --name {name} --enabled false` or toggle in Pipelines UI
+2. Revert outputs: close AI-generated PRs, remove applied labels, revert merged changes if needed
+3. Diagnose: `az pipelines runs show --id {run-id}` and download logs from the Pipelines UI
+4. Fix and re-enable: update the pipeline file, test via manual dispatch, then re-enable

package/skills/hatch3r-gh-agentic-workflows/references/gitlab-ci.md

@@ -0,0 +1,51 @@
+# GitLab CI/CD — Agentic Workflow Patterns
+
+Loaded on demand when `platform: gitlab` in `.agents/hatch.json` or when user is setting up GitLab CI.
+
+GitLab CI uses `.gitlab-ci.yml` at the repo root to define pipelines. Use the `glab ci` CLI for management and monitoring.
+
+## 1. Continuous Test Improvement (GitLab)
+
+```yaml
+# .gitlab-ci.yml (or included file)
+continuous-test-improvement:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+  script:
+    - echo "Analyze test coverage gaps and create MRs with new tests"
+```
+
+Configure a pipeline schedule in GitLab (Settings → CI/CD → Schedules) for weekly runs.
+
+## 2. Continuous Triage (GitLab)
+
+Use GitLab webhooks on issue creation to trigger a pipeline that applies labels from the hatch3r taxonomy and adds a triage comment via `glab issue update`.
+
+## 3. Continuous Documentation (GitLab)
+
+Trigger on merge to the default branch. Check if documentation needs updating and open a follow-up MR via `glab mr create`.
+
+## Setup
+
+1. Define jobs in `.gitlab-ci.yml` (or use `include:` for modular files)
+2. Configure pipeline schedules for periodic jobs (Settings → CI/CD → Schedules)
+3. Set CI/CD variables for secrets (Settings → CI/CD → Variables)
+4. Configure protected branches and merge request approvals
+5. Monitor runs in CI/CD → Pipelines
+
+## Verification
+
+- **Syntax check:** CI Lint (CI/CD → Editor → Validate) or `glab ci lint`
+- **Dry run:** `glab ci run` → `glab ci view`
+
+## Monitoring
+
+- **Execution tracking:** `glab ci list`
+- **Failure alerts:** Pipeline email notifications (Settings → Integrations)
+
+## Rollback
+
+1. Disable: pause pipeline schedules in Settings → CI/CD → Schedules, or use the GitLab API
+2. Revert outputs: close AI-generated MRs, remove applied labels, revert merged changes if needed
+3. Diagnose: `glab ci view {pipeline-id}` or check CI/CD → Pipelines in the web UI
+4. Fix and re-enable: update the pipeline file, test via manual dispatch, then re-enable

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

@@ -62,35 +62,16 @@ Output a structured plan before writing code:
 
 ## Step 4b: Sub-Agent Delegation
 
-Every issue MUST be delegated to a dedicated `hatch3r-implementer` sub-agent — never implement inline. The board-pickup command orchestrates this automatically, but if running issue-workflow standalone, follow the pattern below.
+Every issue MUST be delegated to a dedicated `hatch3r-implementer` sub-agent — never implement inline. The board-pickup command orchestrates this automatically; if running issue-workflow standalone, apply the pattern that matches your scenario:
 
-### Single Issue
+| Scenario | Pattern |
+|----------|---------|
+| Single issue | Spawn one `hatch3r-implementer` sub-agent via the Task tool with issue number, body, acceptance criteria, issue type, researcher output, and spec references. Await result. |
+| Epic with sub-issues | Load `references/delegation-patterns.md` — Pattern 2 |
+| Batch of standalone issues | Load `references/delegation-patterns.md` — Pattern 3 |
+| Plain chat with multiple tasks | Load `references/delegation-patterns.md` — Pattern 4 |
 
-Spawn one `hatch3r-implementer` sub-agent via the Task tool. Include: issue number, body, acceptance criteria, issue type, researcher output, and spec references. Await the result.
-
-### Epic with Sub-Issues
-
-1. **Group sub-issues by dependency level** from the epic's Implementation Order.
-2. **Spawn one implementer sub-agent per sub-issue** using the Task tool. Include: issue number, body, acceptance criteria, issue type, parent epic context, and spec references.
-3. **Launch sub-issues at the same dependency level in parallel** — as many concurrently as the platform supports.
-4. **Await all sub-agents at a level** before starting the next level.
-5. **Review results** from each sub-agent. Resolve any file conflicts between parallel outputs.
-
-### Multiple Standalone Issues (Batch)
-
-When working on multiple standalone issues (not part of an epic), apply the same parallel pattern:
-
-1. **Group issues by dependency level.** Independent issues (no mutual dependencies) share the same level and run in parallel.
-2. **Spawn one researcher sub-agent per issue** in parallel — as many concurrently as the platform supports. Each issue gets individual context gathering since standalone issues are unrelated.
-3. **Spawn one implementer sub-agent per issue per level** in parallel — as many concurrently as the platform supports. Each receives its own researcher output.
-4. **Await all sub-agents at a level** before starting the next level.
-5. **Review results** from each sub-agent. Resolve any cross-issue file conflicts.
-
-### 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 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.
+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.
 
 ## Step 5: Implement
 

package/skills/hatch3r-issue-workflow/references/delegation-patterns.md

@@ -0,0 +1,51 @@
+# Sub-Agent Delegation Patterns
+
+Loaded on demand during Step 4b of the issue workflow when the active task goes beyond a single issue — epic decomposition, batch standalone issues, or multi-task plain chat. For a single issue, the inline summary in SKILL.md Step 4b is sufficient.
+
+## Pattern 1: Single Issue
+
+Spawn one `hatch3r-implementer` sub-agent via the Task tool. Include:
+
+- Issue number
+- Issue body
+- Acceptance criteria
+- Issue type
+- Researcher output
+- Spec references
+
+Await the result.
+
+## Pattern 2: Epic with Sub-Issues
+
+1. **Group sub-issues by dependency level** from the epic's Implementation Order.
+2. **Spawn one implementer sub-agent per sub-issue** using the Task tool. Include:
+   - Issue number
+   - Issue body
+   - Acceptance criteria
+   - Issue type
+   - Parent epic context
+   - Spec references
+3. **Launch sub-issues at the same dependency level in parallel** — as many concurrently as the platform supports.
+4. **Await all sub-agents at a level** before starting the next level.
+5. **Review results** from each sub-agent. Resolve any file conflicts between parallel outputs.
+
+## Pattern 3: Multiple Standalone Issues (Batch)
+
+When working on multiple standalone issues (not part of an epic), apply the same parallel pattern:
+
+1. **Group issues by dependency level.** Independent issues (no mutual dependencies) share the same level and run in parallel.
+2. **Spawn one researcher sub-agent per issue** in parallel — as many concurrently as the platform supports. Each issue gets individual context gathering since standalone issues are unrelated.
+3. **Spawn one implementer sub-agent per issue per level** in parallel — as many concurrently as the platform supports. Each receives its own researcher output.
+4. **Await all sub-agents at a level** before starting the next level.
+5. **Review results** from each sub-agent. Resolve any cross-issue file conflicts.
+
+## Pattern 4: 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 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.
+
+## Protocol Notes
+
+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.

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

@@ -1,6 +1,6 @@
 ---
 id: hatch3r-rule-customize
-description: Rule customization — redirects to the unified hatch3r-customize skill.
+description: Redirect to adjust glob patterns, always-on triggers, and precedence tiers under .hatch3r/rules/ -- use when narrowing or reprioritizing a canonical lint rule
 tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 ---

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

@@ -1,6 +1,6 @@
 ---
 id: hatch3r-skill-customize
-description: Skill customization — redirects to the unified hatch3r-customize skill.
+description: Redirect to rewrite dispatch text that the model uses for auto-selection under .hatch3r/skills/ -- use when a capability is chosen for the wrong task or vice versa
 tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 ---