he-skill-repo/he-maintainer/SKILL.md

name, description

name

description

he-maintainer

Create, audit, update, and maintain project-specific harness engineering systems for software repositories. Use when the user wants to bootstrap or evolve AGENTS.md, CLAUDE.md, AI working guides, project maps, task templates, validation commands, guardrails, harness health checks, ADR/spec/test-plan workflows, or durable fixes for repeated AI coding-agent failures. Prefer grounded repo inspection, minimal targeted edits, and practical harness artifacts over abstract advice.

HE Maintainer

Use this skill when the task is to build or maintain a repository's harness engineering setup.

What this skill owns

This skill helps with:

• creating or updating project AI guide files such as AGENTS.md, CLAUDE.md, or AI_GUIDE.md
• maintaining project maps, task templates, validation commands, and guardrails
• auditing harness quality and identifying missing feedback loops
• keeping harness files aligned with the real repository state

Core idea

Harness engineering is not mainly about clever prompting. It is about giving the coding agent a stable work surface:

• a clear repo map
• reliable commands
• explicit constraints
• short feedback loops
• repeatable task formats

This skill should prefer improving those assets over writing abstract advice.

Evidence policy

Never let the agent invent project authority.

Separate harness content into:

1. Observed facts: directly supported by repository files, commands, tests, config, or existing docs.
2. Human decisions: explicitly provided by the user or accepted project documentation.
3. Assumptions / needs confirmation: useful inferences that are not fully proven.

Do not present assumptions as facts. Mark uncertain items as Needs confirmation.

Workflow

Follow this sequence unless the user asks otherwise.

1. Inspect the repository
2. Identify the stack and tooling
3. Find existing harness files and conventions
4. Check whether commands are real and runnable
5. Update or create harness artifacts with minimal disruption
6. Report harness health, gaps, and next actions

Failure-to-harness workflow

When the user reports a repeated AI failure, prefer durable harness updates over one-off prompt advice.

Classify the failure and update the right artifact:

• missing repo context → AGENTS.md or ai/project-map.md
• ambiguous task shape → ai/task-templates.md
• risky behavior → ai/risk-guardrails.md
• missing validation → validation commands, test plan, or CI guidance
• repeated review issue → reviewer checklist or task template
• unresolved architecture decision → suggest an ADR if appropriate
• mechanically enforceable rule → recommend lint, test, typecheck, or CI enforcement

Inspect the repository

Look for:

• README.md
• package.json, pnpm-workspace.yaml, turbo.json
• Cargo.toml
• go.mod
• pyproject.toml, requirements.txt
• CI files under .github/, .gitlab/, or similar
• test directories and test config
• existing AI-facing files such as AGENTS.md, CLAUDE.md, AI_GUIDE.md

Do not invent commands or architecture details. Ground all harness content in the real repo.

Preferred outputs

Depending on the request, create or update one or more of:

• AGENTS.md
• ai/project-map.md
• ai/task-templates.md
• ai/risk-guardrails.md
• ai/harness-health.md

Prefer short, maintainable files over one giant document.

Optional heavier artifacts

For complex features, migrations, rewrites, integrations, or high-risk changes, suggest or create:

• ai/specs/<task>.md
• ai/test-plans/<task>.md
• ai/adr/<number>-<decision>.md
• ai/role-prompts.md

Do not create these for small tasks unless they reduce ambiguity or prevent repeated failures.

Target-repo file roles

Use these roles by default:

• AGENTS.md: the shortest practical working guide; key commands, constraints, and major repo structure
• ai/project-map.md: directory responsibilities, entrypoints, and important data or control flow notes
• ai/task-templates.md: reusable task request formats for bugfix, feature, refactor, migration, and test-writing work
• ai/risk-guardrails.md: high-risk areas, forbidden changes, slow validations, generated files, and deployment-sensitive zones
• ai/harness-health.md: current harness audit snapshot and next improvement priorities

If the repo is small, keep most content in AGENTS.md and delay the extra files until needed.

Agent role templates

When creating task templates, separate responsibilities:

• Architect mode: analyze architecture, risks, and options; do not implement.
• Engineer mode: implement according to the accepted plan/spec; do not redesign.
• Reviewer mode: identify blocking and non-blocking issues; do not defend the implementation.
• QA mode: define and verify test coverage; do not add product scope.

Use these roles in ai/task-templates.md when the repo or task complexity justifies it.

Update policy

Prefer targeted edits over full rewrites.

• preserve useful human-written guidance
• remove clearly stale commands and paths
• add missing constraints and validation steps
• mark uncertain items as needing confirmation

If a file is mostly wrong or empty, a rewrite is acceptable.

Guardrail policy

When defining harness rules, strongly prefer:

• minimal diffs
• no dependency upgrades unless requested
• no schema or migration changes unless requested
• no disabling tests just to get green
• targeted validation before full validation when possible

Project-specific exceptions are fine if the repo clearly requires them.

Enforcement ladder

Prefer the strongest reasonable control:

1. executable enforcement
2. task-template constraints
3. harness documentation
4. one-off prompt guidance

If a rule can be enforced mechanically, prefer that over documentation alone.

Harness health rubric

Assess these areas briefly:

• project map clarity
• runnable validation commands
• fast feedback availability
• task template quality
• guardrail clarity
• architecture decision durability
• failure feedback loop quality
• alignment between docs and codebase

Use simple ratings like strong, partial, or weak.

References

Read only the most relevant reference file for the current stack:

• references/node-typescript.md
• references/go.md
• references/rust.md
• references/python.md
• references/monorepo.md
• references/scoring-rubric.md

Do not read all references by default.

Deliverable style

Keep deliverables practical. Good outputs include:

• an updated AGENTS.md
• concise task templates
• a harness gap report with top priorities
• a small list of suggested next improvements

Avoid long theory dumps unless the user explicitly asks for theory.