H4tcher Capability Refactor

> Last updated: 2026-06-06

Capability Refactor (Maintainer)

Lifecycle preset for renaming, splitting, merging, or restructuring an existing artifact (agent, skill, rule, command, hook, adapter, pipeline module, governance file). Owns the cross-reference scrubber. Stops before commit so the maintainer reviews the rename map and diff.

§0.1: Ambiguity Gate (P8 B1)

Per CONSTITUTION §2 P8 B1: every framework-dev workflow mutating canonical artifacts detects and resolves ambiguity via agents/shared/user-question-protocol.md BEFORE executing — default behavior, not exception-driven. Apply the protocol when any hold: (a) ambiguous scope (rename vs split vs merge unclear, or which artifact is the target), (b) multiple valid interpretations with materially different cross-reference blast radius, (c) irreversible action (public artifact id rename, frontmatter-field drop, agentPipeline: member rename), or (d) missing acceptance criteria (no rename map, no definition of done). Use the platform-native question tool; one question per turn; 2-4 numbered options with one-line trade-offs; declare the default-if-no-response. Do NOT proceed to Step 0 until resolved or the default is confirmed.

Step 0: Triage

Classify the refactor scope first:

• T1 — body restructure only; no rename; no cross-reference impact. Inline; skip Step 4.
• T2 — rename of one artifact with ≤10 cross-references. 3 parallel sub-agents per Step 4.
• T3 — split / merge, agentPipeline: impact, or rename touching governance/inventory.json registry plus governance/CONSTITUTION.md references. ≥3 parallel sub-agents per Step 4; CL-3 flag if D16 or AUDIT files touched.

Record the tier in the Step 7 summary header.

Step 1: Preflight

1. Confirm clean working tree: git status --short returns empty.
2. Confirm branch: git branch --show-current.
3. Cache governance lean limits from governance/CONSTITUTION.md §2 P5 for any governance file the refactor will touch.
4. Resolve the target artifact: file path, id, type (agent | skill | rule | command | hook | adapter | pipeline | governance).
5. Capture baseline wc -l for the target plus every governance file near the lean threshold.

Step 2: Discover (Cross-Reference Scan)

1. Run the canonical cross-reference scan against the old name or id. Substitute ` with the artifact id (e.g., hatch3r-fixer`):

``bash grep -r "" agents/ skills/ rules/ commands/ hooks/ checks/ prompts/ github-agents/ src/ governance/ docs/ docs-site/ tests/ CLAUDE.md README.md CHANGELOG.md ``

1. Read governance/inventory.json to enumerate every registry citation of `` (ids field, managedFiles paths, counts).
2. For agent renames, list every commands/hatch3r-*.md whose frontmatter agentPipeline: array contains `` — these orchestrator commands resolve the agent by id, so any miss leaves a broken pipeline.
3. Bucket every hit into one of three surfaces: code/tests (src/, tests/, scripts/), governance/docs (governance/, docs/, docs-site/, CLAUDE.md, README.md, CHANGELOG.md), canonical artifacts (agents/, skills/, rules/, commands/, hooks/, checks/, prompts/, github-agents/).

Step 3: Web Research

Skip for pure rename or in-file restructure with no empirical claim. Required when the refactor adopts a new industry pattern (e.g., restructuring an adapter around a vendor's new feature surface). Per agents/shared/rigor-contract.md §"Web Research Mandate": ≥2 independent sources, trust tier (official-docs > peer-reviewed > vendor-note > independent-analysis > blog-post), recency (≤90d CVE, ≤12mo vendor docs, ≤36mo peer-reviewed). Sources recorded in Step 7.

Step 4: Sub-Agent Dispatch (T2 / T3 only)

Spawn 3 parallel Task sub-agents. Each updates references on its disjoint surface slice and writes a diff manifest:

| Slot | Scope | Manifest | |------|-------|----------| | 1 | code/tests — src/, tests/, scripts/ | .audit-workspace/capability-refactor-1.md | | 2 | governance/docs — governance/, docs/, docs-site/, CLAUDE.md, README.md, CHANGELOG.md | .audit-workspace/capability-refactor-2.md | | 3 | canonical artifacts — agents/, skills/, rules/, commands/, hooks/, checks/, prompts/, github-agents/ | .audit-workspace/capability-refactor-3.md |

Each sub-agent prompt MUST include: the slot's bucket from Step 2, the h4tcher-development context block (pillar test, lean thresholds, anti-slop wordlist ref, commit format) modeled on .claude/skills/h4tcher-pr-resolve/SKILL.md, confidence-with-basis per the rigor contract, the workspace target path, and an explicit "no branches, no commits, no PRs" guardrail.

Fan-out is task-derived (P8 B2): 0 sub-agents on T1 (inline), 3 on T2/T3 across the disjoint reference-surface slices above. Token cost never serializes independent work (.claude/rules/fan-out-discipline.md Cost-dominance clause). Emit sub_agents_spawned: { count, rationale } in your output (the Sub-agents field of the Step 7 summary).

Step 5: Cross-Skill Delegation

Body-content rewrites delegate to the matching author skill — set up context only, do not author inline:

| Refactor target | Delegate to | |-----------------|-------------| | agents/*.md, skills/*/SKILL.md, rules/*.md, commands/*.md, hooks/*.md body | h4tcher-content-author | | Audit domain file (governance/audit/domains/D*.md) | h4tcher-domain-author | | Adapter under src/adapters/ | h4tcher-adapter-author | | Mechanical cross-reference rewrites (id replacement, path bumps) | Inline — no delegation |

The orchestrator retains: rename-map authorship, Step 4 sub-agent coordination, Step 6 gates, Step 7 summary.

Step 6: Governance Gates

1. Run the full gate battery, blocking on any failure:

``bash npm run validate && npm test && npx tsc --noEmit && npm run lint && \ npm run build && npm run validate:rule-parity && npm run validate:efficiency ``

1. Reference-orphan check. Re-run the Step 2 grep command against the post-refactor tree. Hit count MUST be zero for the old name:

``bash grep -r "" agents/ skills/ rules/ commands/ hooks/ checks/ prompts/ github-agents/ src/ governance/ docs/ docs-site/ tests/ CLAUDE.md README.md CHANGELOG.md | wc -l ``

1. Regenerate the registry and inspect the diff:

``bash npm run inventory git diff governance/inventory.json `` The diff must reflect every renamed id; investigate any unexpected drift before proceeding.

1. Anti-slop scan on every modified .md / .mdc file using the wordlist regex from .claude/rules/anti-slop-enforcement.md; any hit blocks commit and is fixed via that file's replacement column.
2. Pillar Compliance Test (.claude/rules/pillar-compliance.md) on every modified file; lean threshold check against the Step 1 baselines.

Step 7: Stop-Before-Commit Summary

1. Emit the summary below to the conversation. Do not commit, push, or merge.

Capability Refactor Summary
---------------------------
Tier:      T1 | T2 | T3
Branch:    
Target:      ->  
Refactor:  rename | split | merge | restructure

Rename map:  ->  (one row per artifact)

Reference updates: code/tests  | governance/docs  | canonical  | total 
Inventory delta: 
Reference-orphan grep hits on old name:  (must be 0)

Gates:
  npm run validate               
  npm test                       
  npx tsc --noEmit               
  npm run lint                   
  npm run build                  
  npm run validate:rule-parity   
  npm run validate:efficiency    
  Anti-slop hits                  (must be 0)

Pillars served: P[, P, ...]
Lean threshold deltas:  after / limit>
Sub-agents: count=, rationale=
Sources (if Step 3 ran): 

Suggested commit message:
  refactor():  -> 

  
  

  Pillars: P, P

Status:     SUCCESS | PARTIAL | BLOCKED
Confidence: high | medium | low

Next action (run manually):
  git add 
  git commit -s -m ""

References

• Cross-skill: .claude/skills/h4tcher-content-author/SKILL.md, .claude/skills/h4tcher-adapter-author/SKILL.md, .claude/skills/h4tcher-domain-author/SKILL.md
• Triage skeleton: .claude/skills/h4tcher-pr-resolve/SKILL.md
• Web research mandate: agents/shared/rigor-contract.md
• Anti-slop wordlist: .claude/rules/anti-slop-enforcement.md
• Pillar Compliance Test: .claude/rules/pillar-compliance.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hatch3r
• Source: hatch3r/hatch3r
• License: MIT
• Homepage: https://docs.hatch3r.com

Install and usage instructions live in the source repository linked above.