# H4tcher Capability Refactor

> Rename, split, merge, or restructure an existing canonical artifact with cross-reference scrubbing and an explicit rename-map deliverable.

- **Type:** Skill
- **Install:** `agentstack add skill-hatch3r-hatch3r-h4tcher-capability-refactor`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hatch3r](https://agentstack.voostack.com/s/hatch3r)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hatch3r](https://github.com/hatch3r)
- **Source:** https://github.com/hatch3r/hatch3r/tree/main/.claude/skills/h4tcher-capability-refactor
- **Website:** https://docs.hatch3r.com

## Install

```sh
agentstack add skill-hatch3r-hatch3r-h4tcher-capability-refactor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> 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)

6. 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
   ```
7. Read `governance/inventory.json` to enumerate every registry citation of `` (ids field, managedFiles paths, counts).
8. 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.
9. 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

10. 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
    ```
11. **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
    ```
12. 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.
13. 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.
14. 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

15. 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](https://github.com/hatch3r)
- **Source:** [hatch3r/hatch3r](https://github.com/hatch3r/hatch3r)
- **License:** MIT
- **Homepage:** https://docs.hatch3r.com

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hatch3r-hatch3r-h4tcher-capability-refactor
- Seller: https://agentstack.voostack.com/s/hatch3r
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.