| name | harness-refine |
| description | This skill should be used when the user asks to "refine the harness", "self-improve the blueprint", "restructure .claude/ to match best practices", "audit harness configuration", or mentions "harness refine", "best-practice alignment", "self-refine", "harness self-audit", "rework skill/agent/team layout". Self-scores and refines the `.claude/` harness scaffolding (skills / agents / teams / rules) under `project-blueprint/` and `project-blueprint-en/` against refreshed official best practices, in lockstep across both language mirrors. Source code and `docs/`/`output/` content are out of scope. Runs a non-mutating Round 0 best-practice refresh, then self-score → self-improve → self-review for 2 fixed rounds, escalating to a human if not approved. Takes optional argument: /harness-refine <target-dir or instruction>
|
| argument-hint | <target-directory or refinement instruction (optional)> |
| allowed-tools | Read, Glob, Grep, Bash(ls *, find *, wc *, diff *, grep *, git *), Edit, Write, WebFetch, WebSearch, Agent, mcp__plugin_context7_context7__resolve-library-id, mcp__plugin_context7_context7__query-docs |
| context | main |
Harness Refine — Self-strengthening best-practice refinement (Round 0 refresh + 2 fixed rounds)
A meta-skill that refines the harness scaffolding under project-blueprint/ and
project-blueprint-en/ by running self-score → self-improve → self-review for
2 rounds, using Claude Code official best practices (re-fetched each run in Round 0)
and the 7 inviolable principles of constitution.md as the dual rubric.
Source code, docs/ content, output/ deliverables, and testreport/ raw data are
out of scope. Only template scaffolding is touched.
Self-strengthening mechanism (the core of this skill)
This skill does not freeze its rubric; it gets stronger autonomously on every run, via three mechanisms:
- Round 0 refresh (non-mutating): re-fetch the official primary sources (see "Best-practice
reference sources" below) via WebFetch / Context7, and fold the delta against the latest guidance
into the provisional scoring criteria for this run. Never judge from training data alone.
- Adaptive loop: read prior reports (
output/reports/harness-refine/), extract unresolved
findings and issues that recurred 2+ times, and promote them to top-priority fixes
(turning failure into learning rather than a loop).
- Rubric self-evolution: if Round 0 discovers a new official best practice, propose a new
scoring item. Any change touching
constitution.md is never auto-adopted — it requires human approval.
Prerequisites
| Reference | Purpose | Editable? |
|---|
constitution.md (repo root) | 7 inviolable principles (rubric supremum) | ❌ Immutable |
project-config.md §1 / §4-§10 / §12 / §13 | Human decision area | ❌ Immutable |
project-config.md §2 / §3 / §11 | AI-mutable sections | ⚠️ Structure only (do not change values) |
project-config.md §13 | Opus/Sonnet/Haiku tier strategy (referenced by item 11) | ❌ Immutable (reference only) |
.claude/CLAUDE.md | Cross-cutting rules (principle ⑥: ≤200 lines target) | ✅ |
.claude/skills/*/SKILL.md | Skill skeletons (frontmatter / pipeline / description) | ✅ |
.claude/agents/*.md | Single-shot specialist definitions (least privilege / single responsibility) | ✅ |
.claude/teams/TEAM_*.md | Orchestration | ✅ |
.claude/hooks/*.sh | 3-layer defense — Layer 1 | ❌ Out of scope for this skill (debate in a separate PR) |
.claude/rules/*.md | Path / language rule extensions | ✅ (preserve .example convention) |
Prior reports (output/reports/harness-refine/) | Learning input for the adaptive loop | Read-only |
| Official docs | Latest best practice | WebFetch / Context7 MCP |
Principles (edit boundary — MUST hold)
| Area | Editable? | Notes |
|---|
constitution.md | ❌ | Changes require a separate PR + .constitution.sha256 update |
project-config.md §1 / §4-§10 / §12 / §13 | ❌ | Human decision area |
project-config.md §2 / §3 / §11 | ⚠️ | Structural tidying only; values untouched |
.claude/CLAUDE.md | ✅ | Stay within 200-line target (220-line hard ceiling) |
.claude/{skills,agents,teams,rules,output-styles}/ | ✅ | No name clashes / cyclic references |
.claude/hooks/*.sh | ❌ | Body edits forbidden here (principle ⑤) |
docs/, output/, testreport/ content | ❌ | Out of scope (only output/reports/harness-refine/ is written) |
input/requirements/ | ❌ | Human input |
If any of the immutable boundaries would be crossed, halt immediately and ask the human.
scan-harness.sh may also block via hooks.
Usage
/harness-refine <target-dir or instruction>
When the argument is omitted, the entire project-blueprint/ and project-blueprint-en/ tree is targeted. Representative triggers:
- "Refine the harness"
- "Restructure to follow best practices"
- "Run a self-refine pass"
- "Audit the .claude/ layout"
- "Re-align skill / agent / team placement"
- "Bring
project-blueprint/ and project-blueprint-en/ back in sync"
Overall workflow (Round 0 + 2 fixed rounds — no auto round 3)
Round 0 (non-mutating / self-strengthening) Round 1 Round 2
┌─────────────────┐ ┌─────────────┐ ┌─────────────┐
│ Re-fetch BP │ │ 1-A Score │ │ 2-A Score │
│ Learn from past │ ─── rubric delta ──────→ │ (rubric) │ │ (delta) │
│ Rubric delta │ injected └─────┬────────┘ └─────┬───────┘
└─────────────────┘ ▼ ▼
┌─────────────┐ ┌─────────────┐
│ 1-B Improve │─JP/EN sync──→ │ 2-B Improve │─sync→
└─────┬────────┘ └─────┬───────┘
▼ ▼
┌─────────────┐ ┌─────────────┐
│ 1-C Review │(code-reviewer)│ 2-C Review │(code-reviewer)
└─────┬────────┘ └─────┬───────┘
└──────► Round 2 input ──────┘
▼
Final report
- Round 0 does best-practice re-fetch + learning from past reports (edits no files at all)
- Round 1 handles broad corrections (naming drift, misplacement, missing frontmatter, mirror divergence)
- Round 2 handles round-1 residuals + second-order effects (broken
@import, CLAUDE.md catalog drift, 404 links)
- Each round's review is delegated to the
pr-review-toolkit:code-reviewer agent for independent judgement
- If round 2 does not get an approval, escalate to a human — no automatic round 3
Round 0 — best-practice refresh (self-strengthening preflight / non-mutating)
Edits no files. Research and delta generation only. Steps:
- Fetch the latest official guidance: WebFetch the URLs in "Best-practice reference sources"
below; use Context7 for library-style docs. On fetch failure, continue in degraded mode using
training data + prior reports, and state this explicitly in conversation and the report
(never silently regress to training data).
- Learn from past reports: read
output/reports/harness-refine/REFINE_*.md (the latest 2-3, if any)
and extract (a) unresolved findings (b) issues that recurred 2+ times.
- Generate the live rubric delta: compare the fetched guidance against the 15-item rubric below, and
- if an item's criteria are stale, update them as the provisional criteria for this run
- if there is a strong new official recommendation, record it as a candidate new scoring item
- promote recurring findings to top-priority fixes
- Human approval gate: proposing a new scoring item, or any change that ripples into
constitution.md, must be presented to the human for approval before adoption (no auto-edits).
Round 0 output (recorded in conversation + final report): "fetched sources and success/degraded status",
"list of recurring findings", "rubric delta applied this run".
Round 1 — broad corrections
1-A. Self-score (15 items × 0/1/2 points = 30 max)
Score as an acceptance checklist (spec-kit style): judge YES/NO whether each item's 2-point
condition holds, with evidence attached.
Group A — constitution / structural invariants
| # | Item | 0 pts | 1 pt | 2 pts |
|---|
| 1 | Adherence to constitution 7 principles | Violation present | Formally compliant | + Tested by scan-harness.sh |
| 2 | CLAUDE.md ≤200 lines (principle ⑥) | >220 lines | 200-220 lines | ≤200 lines + true reduction via path-scoped rules/ (understand @import does not cut context) |
| 3 | Skill frontmatter convention | Missing name / description | All present | + allowed-tools (least privilege) / context / argument-hint complete |
| 4 | 3-layer separation (skill ⇄ agent ⇄ team, principle ④) | Cycles / mixing | Linear | + Selection guide in agents/README.md |
| 5 | 3-layer defense preserved (principle ⑤) | Hooks removed | Count preserved | + Responsibility header comment on each hook |
| 6 | JP/EN mirror sync (principle ②) | File count / structure diff | File count matches | + Headings & line counts match (mechanical diff = 0) |
| 7 | Rules opt-in pattern | .example missing or directly loaded | .example present | + Naming convention (language-*, path-*, rule-*) held |
| 8 | 5 quality gates (principle ③) | Reduced | All 5 present | + Each skill @imports @.claude/quality-gates.md |
Group B — Anthropic official best practices + GitHub TOP5 essence
| # | Item | 0 pts | 1 pt | 2 pts |
|---|
| 9 | Pipeline links & discoverability (superpowers style) | No upstream/downstream note / dead skills | Partial | "prev → this → next" table on all skills + no skill orphaned from every entry path |
| 10 | Official best-practice compliance | Outdated form | Partial | Conforms to the latest form fetched in Round 0 |
| 11 | Skill description quality (third person / explicit triggers) | First/second person or vague | Third person | + ≤1024 chars / concrete triggers / no duplicate triggers |
| 12 | Progressive disclosure | SKILL.md bloated (>500 lines) / verbose background | ≤500 lines | + Mutually-exclusive detail split into 3rd tier (reference files) |
| 13 | Agent least privilege & single responsibility | Read-only agent has Write/Edit / multi-responsibility | tools allowlist present | + Read-only agents lack Write / 1 agent = 1 task / "returns summary only" contract stated |
| 14 | Model tier placement (§13 / BMAD style) | No tier note | Tier noted | + Sound placement: planning = high tier / mechanical work = low tier |
| 15 | Eval-first / acceptance checklist (spec-kit style) | No verification angle | Output contract present | + Representative scenarios + PASS conditions stated in SKILL.md |
Targets (expressed as % so future item additions don't break them): round 1 ≥ 80% (≥24/30), round 2 ≥ 95% (≥28/30).
Always cite file path + line number for every score (no "feels low" justifications).
Judge items 10 / 11 / 12 against the latest official guidance fetched in Round 0.
1-B. Self-improve (apply fixes)
Address every item scoring 0 / 1, in this priority order (recurring findings promoted in Round 0 come first):
- Constitution violations: halt → human confirmation (never auto-fix; report bullet-by-bullet)
- CLAUDE.md overflow: extract a topic into
@.claude/rules/<topic>.md → path-scope it to truly cut context
- Missing frontmatter / naming drift / description quality: unify to third person, explicit triggers, least-privilege allowlist
- 3-layer separation violations: re-orient calls to one direction (skill → agent OK, agent → team forbidden)
- Mirror divergence: copy to the missing side, translate prose to match
README-en.md tone
.example convention breach: revert real files to .example or rename to follow convention
Mirror application rules:
- Whenever JP is changed, apply the EN change in the same turn (do not stop with one side updated)
- Structure must be bit-identical; only prose is translated. Section numbering, table columns, code blocks stay identical
- Preserve EN-only formatting (e.g., serial commas) where intentional
1-C. Self-review (independent judgement)
Invoke pr-review-toolkit:code-reviewer once via Agent. Context passed in:
- The full
git diff of round-1 Edit / Write actions
- An explicit request to verify the constitution 7 principles
- JP/EN diff (
diff -r project-blueprint/.claude/skills/ project-blueprint-en/.claude/skills/)
Roll review findings (MUST / SHOULD / CONSIDER) into the round 2 input.
Round 2 — residuals and second-order effects (adaptive)
2-A. Self-score (delta-focused + resolution rate)
Re-score every item that came in at 1 or 0 in round 1. Add the following new score targets:
- Side-effects of round-1 edits (broken
@import, broken links, mismatched CLAUDE.md skill catalog)
- Changes the mirror failed to pick up
- The code-reviewer's findings (every MUST must be reflected in the score)
- Resolution-rate tracking: were the recurring findings extracted in Round 0 resolved this run?
(a 3rd-or-more recurrence is a human-escalation candidate)
2-B. Self-improve (closing pass)
-
Only nudge remaining items up to 2 points; no new large-scale changes
-
Verify every @import target exists:
grep -rh '^@\.claude' project-blueprint/ project-blueprint-en/ | sort -u | \
while read line; do
path="${line#@}"
test -e "project-blueprint/$path" || echo "MISSING(JP): $path"
test -e "project-blueprint-en/$path" || echo "MISSING(EN): $path"
done
-
Rebuild the CLAUDE.md skill catalog table (cross-check .claude/skills/*/SKILL.md name: fields)
-
Drive the file-count delta to 0:
diff <(cd project-blueprint && find .claude -type f | sort) \
<(cd project-blueprint-en && find .claude -type f | sort)
2-C. Self-review (final)
Invoke pr-review-toolkit:code-reviewer again. Decision matrix:
| Reviewer verdict | Next action |
|---|
| Approved | Emit final report → end the skill |
| Conditional approval | Check if remaining MUSTs are fixable; if yes, fix; otherwise escalate |
| Requires rework | Halt and escalate to human — auto round 3 is forbidden |
Output Contract
Final report (required)
Write to output/reports/harness-refine/REFINE_<YYYY-MM-DD>_<HHMM>.md:
# Harness Refinement Report — <date>
## Summary
- Round 1 score: NN/30 (N%) → Round 2 score: MM/30 (M%) (target ≥95%)
- Files refined: JP X / EN Y (delta MUST be 0)
- Constitution violations: detected N / fixed N (auto-fix count is 0 — every fix went through human)
- code-reviewer verdict: Approved / Conditional / Requires rework
## Round 0 — best-practice refresh
- Fetched sources: [per URL: success / degraded]
- Recurring findings (from prior reports): [bulleted / resolution rate]
- Rubric delta applied this run: [updated criteria / new-item proposals (pending human approval)]
## Round 1
### Score (15 items)
[Each item: points + evidence file:line]
### Improvements
[Per-file change summary + WHY]
### Review outcome
[code-reviewer agent summary]
## Round 2
[same shape + resolution rate]
## Outstanding items
- (Bulleted; only items requiring human judgement)
## Mirror parity verification
- File-count diff: matches / N files differ
- Section-heading diff: none / N (enumerated)
- Broken `@import`: 0 / N (enumerated)
Live commentary
- At Round 0 start, state "the official sources to fetch and the prior-report learning result"
- Announce each round explicitly ("Now running round N scoring")
- Score output is one line per item (bulleted)
- For improvements, always report what / why / where (no silent edits)
- Mirror application is reported as JP → EN in the same turn
Pipeline links
| Upstream | This skill | Downstream |
|---|
| (none — meta-skill) | /harness-refine | /code-review (code side) / /refactoring (code side) |
/refactoring restructures source code; this skill restructures harness scaffolding. Do not conflate.
Prohibitions
- Editing
constitution.md (fully immutable)
- Editing
project-config.md §1 / §4-§10 / §12 / §13
- Editing
.claude/hooks/*.sh bodies (principle ⑤)
- Treating one-sided updates as complete (principle ②)
- Using
--no-verify / --force in git operations
- Running 3+ rounds automatically (round-2 non-approval → human)
- Editing files during Round 0 (Round 0 is non-mutating / research only)
- Auto-adopting new scoring items or constitution-rippling changes without human approval
- Touching source code /
docs/ content / output/ (outside this skill's report) / testreport/
- Presenting scores without per-item evidence / silently regressing to training data on a Round 0 fetch failure
Best-practice reference sources (re-fetched in Round 0 — official primary sources preferred)
| Source | Purpose | Rubric items |
|---|
platform.claude.com/docs agent-skills/best-practices | SKILL.md / frontmatter / progressive disclosure / eval-first | 3, 11, 12, 15 |
docs.claude.com claude-code/sub-agents | subagent least privilege / single responsibility / summary return | 13 |
docs.claude.com claude-code/memory | CLAUDE.md line count / @import doesn't cut context / path-scoped rules | 2 |
anthropic.com/engineering writing-tools-for-agents | tool-definition clarity / token efficiency | 10, 11 |
anthropic.com/engineering effective-context-engineering-for-ai-agents | context curation / sub-agent isolation | 12, 13 |
anthropic.com/engineering effective-harnesses-for-long-running-agents | startup orientation / verification loop | 9, 15 |
| GitHub: spec-kit / BMAD-METHOD / SuperClaude / agent-os / superpowers | acceptance checklist / model tier / standards consolidation / discoverability | 9, 14, 15 |
Flag any source that fails to fetch as degraded; score the corresponding rubric items provisionally against the prior criteria.
See also (loaded on demand)
@.claude/guardrails.md
@.claude/quality-gates.md
@.claude/rules/workflow-advanced.md
@.claude/pitfalls.md
