From harness-engineer
Garbage collect the harness: find and fix stale documentation, architectural layer violations, inconsistent feature states, dead context, and entropy accumulated from agent-generated code. Run periodically (weekly or after large sprints) to keep the harness healthy and agents oriented correctly. Produces a prioritized cleanup report and applies fixes — all written by the agent, never manually. Based on OpenAI's "garbage collection agents" pattern and the principle that documentation for agents must be maintained by agents. Trigger on: "gc the harness", "clean up harness", "docs are stale", "harness drift", "garbage collect", "harness maintenance", "agent keeps getting confused", "clean up features.json".
npx claudepluginhub lauraflorentin/skills-marketplace --plugin harness-engineerThis skill uses the workspace's default tool permissions.
Fights harness entropy. Agent-generated code and docs accumulate drift differently than
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Fights harness entropy. Agent-generated code and docs accumulate drift differently than human-written code — this skill finds and fixes it systematically.
passes=true that actually fail when testedin_progress=true that haven't been touched in 2+ commitscircuit_broken=true that are now resolvedrepo/ importing from ui/).claude/settings.json hooks referencing scripts that moved# Documentation references
echo "=== Checking AGENTS.md references ==="
python3 .harness/scripts/check-doc-refs.py
# Feature integrity
echo "=== Feature list status ==="
python3 -c "
import json
with open('features.json') as f:
data = json.load(f)
features = data if isinstance(data, list) else data.get('features', [])
issues = []
for f in features:
if f.get('in_progress') and not f.get('passes'):
issues.append(f'STUCK_IN_PROGRESS: {f[\"id\"]} - {f[\"description\"][:60]}')
if f.get('circuit_broken') and f.get('passes'):
issues.append(f'BROKEN_BUT_PASSING: {f[\"id\"]} - inconsistent state')
for i in issues:
print(i)
print(f'Total issues: {len(issues)}')
"
# Layer violations
echo "=== Layer constraint check ==="
bash .harness/scripts/check-layers.sh 2>/dev/null || echo "Layer check script not found"
# Stale locks
echo "=== Stale locks ==="
find current_tasks/ -name "*.txt" -mmin +60 2>/dev/null | head -20
# Dead docs
echo "=== Docs referencing dead paths ==="
grep -r "src/" docs/ 2>/dev/null | while read line; do
path=$(echo "$line" | grep -o 'src/[^"` ]*')
[ -n "$path" ] && [ ! -e "$path" ] && echo "DEAD REF: $line"
done | head -20
# Quality grades — flag unassessed domains
echo "=== Quality grade coverage ==="
python3 -c "
import re, sys
try:
with open('docs/quality.md') as f:
content = f.read()
unassessed = re.findall(r'\|\s*(\w+)\s*\|\s*—\s*\|', content)
if unassessed:
print(f'UNASSESSED DOMAINS ({len(unassessed)}): {', '.join(unassessed)}')
print('Run harness-gc Step 5 to assign grades.')
else:
print('All domains have grades assigned.')
except FileNotFoundError:
print('WARNING: docs/quality.md not found — run harness-init')
"
# Execution plans — check for orphans and stale plans
echo "=== Execution plan integrity ==="
python3 -c "
import json, os, glob
try:
with open('features.json') as f:
data = json.load(f)
features = data if isinstance(data, list) else data.get('features', [])
feature_ids = {f['id'] for f in features}
passing_ids = {f['id'] for f in features if f.get('passes')}
except:
print('Could not read features.json')
exit()
plans = glob.glob('docs/plans/plan-*.md')
for plan_path in plans:
basename = os.path.basename(plan_path)
feat_id = basename.replace('plan-', '').replace('.md', '')
if feat_id not in feature_ids:
print(f'ORPHANED_PLAN: {plan_path} — no matching feature id')
elif feat_id in passing_ids:
print(f'COMPLETED_PLAN: {plan_path} — feature passes=true, consider archiving to docs/history/')
print(f'Plans checked: {len(plans)}')
"
Classify by severity:
P0 — Breaks agent orientation (fix immediately)
P1 — Causes agent confusion (fix this GC run)
P2 — Accumulating entropy (fix this GC run if time)
P3 — Nice to have (log in tech debt tracker)
Apply all P0 and P1 fixes. For each fix:
Stale doc references:
# Update the doc to reflect current paths
# Or remove the reference entirely if the component is gone
Stuck in_progress features:
# Reset to in_progress=False so next agent can pick them up cleanly
feature['in_progress'] = False
feature['passes'] = False
Resolved circuit_broken features:
# Clear the flag so agents will attempt them again
feature['circuit_broken'] = False
feature['break_reason'] = None
Stale locks:
find current_tasks/ -name "*.txt" -mmin +60 -delete
Layer violations:
# Move the offending import or restructure the module
# Add the violation to AGENTS.md as a specific prohibition:
echo "LAYER CONSTRAINT: [module] must NEVER import from [layer]. Use [interface] instead." >> AGENTS.md
Archive old progress notes:
# Summarize entries older than 30 days into docs/history/progress-archive.md
# Truncate claude-progress.txt to last 30 days
git add AGENTS.md features.json docs/ current_tasks/ .harness/ 2>/dev/null
git commit -m "harness-gc: apply P0/P1 fixes — $(date '+%Y-%m-%d')"
After fixing issues, update docs/quality.md grades for any domain touched this GC run.
# Grade each domain based on current state:
# A: all features passing, no violations, clean
# B: minor issues, no critical failures
# C: some features failing or untested
# D: multiple failures, layer violations
# F: broken, blocks other work
# Read features.json, count pass/fail per domain
# Read check-layers.sh output for violations per domain
# Update the grade table in docs/quality.md with today's date
This is mandatory — quality.md without grades is an empty file, not a quality tracker.
Create docs/gc-report-[date].md:
# Harness GC Report — [date]
## Summary
- P0 issues found: [n] | Fixed: [n]
- P1 issues found: [n] | Fixed: [n]
- P2 issues found: [n] | Fixed: [n]
- P3 issues logged: [n]
## Fixes Applied
[list each fix with before/after]
## Tech Debt Logged
[list P3 items added to tracker]
## Harness Health Score
[overall assessment: Healthy / Needs Attention / Degraded]
## Recommended Next Run
[date — suggest 1 week for active projects, 1 month for stable ones]
git add docs/quality.md docs/gc-report-*.md docs/history/ 2>/dev/null
git commit -m "harness-gc: update quality grades + GC report — $(date '+%Y-%m-%d')"
For active agent-first projects, run GC:
The goal is a harness that gets better over time, not one that slowly decays.