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

name, description

name

description

he-maintainer

Create, audit, evolve, and maintain project-specific harness engineering systems for software repositories. Use when the user wants to bootstrap or improve AGENTS.md, CLAUDE.md, project maps, task contracts, validation commands, guardrails, ADR/spec/test-plan workflows, status docs, 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, audit, or evolve a repository's harness engineering operating surface.

This skill is not mainly about writing better prompts. It is about making the repository easier for coding agents to work in correctly, repeatedly, and with less re-exploration.

What this skill owns

This skill helps with:

• creating or updating AI-facing repository guides such as AGENTS.md, CLAUDE.md, or AI_GUIDE.md
• defining and maintaining project maps, task contracts, guardrails, validation commands, and status surfaces
• establishing durable architecture and workflow decision records
• improving multi-agent or long-running coding workflows through specs, test plans, and role separation
• auditing repeated AI failures and converting them into durable harness improvements
• keeping harness artifacts aligned with the real repository state

Prefer durable harness changes over one-off prompting fixes.

Core operating model

Harness engineering gives coding agents a stable work surface:

• grounded repository context
• clear subsystem boundaries
• explicit task contracts
• durable architecture decisions
• reliable validation commands
• short feedback loops
• visible active state for long-running work

The goal is not maximum documentation. The goal is enough structure that implementation, review, and validation become more reliable.

Evidence policy

Never let the agent invent project authority.

Separate harness content into:

1. Observed facts — directly supported by repository files, commands, tests, config, CI, or accepted docs.
2. Human decisions — product, architecture, workflow, or risk 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 and existing harness artifacts
2. Identify stack, tooling, and validation surface
3. Determine which coordination problems are already solved vs missing
4. Find repeated ambiguity, failure loops, or stale guidance
5. Update or create the smallest durable artifact set that improves reliability
6. Report harness health, gaps, and next improvements

Repository inspection

Look for:

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

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

Harness artifact hierarchy

Use repository harness artifacts as a layered system.

1. Working guide

Examples:

• AGENTS.md
• CLAUDE.md
• AI_GUIDE.md

Purpose:

• shortest practical operational guide
• key commands
• core constraints
• essential repo structure
• important patterns and extension points

2. Project map

Examples:

• ai/project-map.md
• docs/project-map.md

Purpose:

• stable directory responsibilities
• entrypoints
• subsystem boundaries
• important control or data flow notes

3. ADRs

Examples:

• ai/adr/<number>-<decision>.md
• docs/adr/<number>-<decision>.md

Purpose:

• durable architecture or workflow decisions
• tradeoffs that should not be renegotiated in every implementation task
• clear default decisions for future agents

4. Specs

Examples:

• ai/specs/<task>.md
• docs/specs/<task>.md

Purpose:

• task- or subsystem-level contract
• scope, non-goals, shapes, constraints, acceptance criteria
• implementation interface between planning and execution roles

5. Test plans

Examples:

• ai/test-plans/<task>.md
• docs/specs/<task>-test-plan.md

Purpose:

• validate a spec or risky change
• capture happy path, edge cases, regressions, and manual checks

6. Status docs

Examples:

• ai/work-status.md
• ai/status/<topic>.md
• docs/ci-status.md

Purpose:

• track active work, owners, blockers, validation state, and linked artifacts
• coordinate long-running or multi-agent efforts without polluting long-term guidance

ADRs settle durable decisions. Specs fill in implementation detail. Test plans verify specs. Status docs track active execution state. Working guides and project maps remain short and stable.

Preferred outputs

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

• AGENTS.md
• CLAUDE.md
• ai/project-map.md
• ai/task-templates.md
• ai/risk-guardrails.md
• ai/harness-health.md
• ai/specs/<task>.md
• ai/test-plans/<task>.md
• ai/adr/<number>-<decision>.md
• ai/work-status.md or ai/status/<topic>.md

Prefer short, maintainable artifacts over one giant document.

Scaling rule

Scale harness weight to project risk, duration, and coordination complexity.

• Small repos: prefer a strong single AGENTS.md or CLAUDE.md
• Medium repos: split out project map, task templates, or guardrails when the main guide becomes noisy
• Large or high-risk repos: add specs, test plans, ADRs, and status docs when they reduce ambiguity or rework

Do not create more files unless they reduce confusion, prevent repeated failures, or improve validation reliability.

Role ownership model

When the repository or task is complex enough, assign ownership by artifact, not only by prompt style.

• Architect owns architecture notes, ADRs, system boundaries, tradeoff records, and durable technical rules
• PM / planner owns roadmap breakdown, milestone framing, task ordering, and acceptance framing
• Engineer owns implementation changes and implementation-local tests
• Reviewer owns issue identification, drift checks against spec / ADR / guardrails, and blocking vs non-blocking findings
• QA owns test plans, validation evidence, CI health summaries, and regression checklists

Prefer explicit artifact ownership when multiple agents or long-running sessions are involved.

Agent role templates

When creating task templates, keep responsibilities separate:

• Architect mode: analyze architecture, tradeoffs, risks, and options; do not implement
• Engineer mode: implement according to the accepted plan, spec, or ADR; do not silently redesign
• Reviewer mode: identify blocking and non-blocking issues; do not defend the implementation
• QA mode: define and verify test coverage and acceptance evidence; do not expand product scope

Use these role modes in ai/task-templates.md only when the repo or task complexity justifies them.

Task contract policy

When creating or updating task templates, prefer requests that specify:

• objective
• scope
• out-of-scope
• relevant files or directories
• constraints
• validation commands
• acceptance criteria
• review notes or risk notes
• linked ADRs, specs, or prior decisions when relevant

If a non-trivial task is underspecified, prefer creating or suggesting a task contract instead of relying on a loose natural-language prompt.

Spec-driven coordination

For complex work, use specs as coordination interfaces between roles.

A good spec may include:

• objective
• non-goals
• config or input shape
• type, data, or API shapes
• error cases
• divergences or compatibility notes
• acceptance criteria
• linked validation plan

Use specs when multiple agents, long timelines, migrations, integrations, or upstream compatibility work would otherwise cause repeated re-analysis.

Status document pattern

For long-running features, migrations, ports, or multi-agent efforts, suggest a focused status document that tracks:

• task list and state such as todo, in-progress, blocked, done
• owner or role
• linked spec / ADR / PR / commit
• validation status
• unresolved decisions

Use status docs for active coordination. Do not overload AGENTS.md, CLAUDE.md, or ai/harness-health.md with transient execution state.

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
• keep durable decisions easy to find
• mark uncertain items as needing confirmation

If a file is mostly wrong, empty, or structurally misaligned with the repo, 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
• explicit high-risk zones and generated-file boundaries

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

Enforcement ladder

Prefer the strongest reasonable control:

1. executable enforcement
2. CI or validation enforcement
3. task-contract constraints
4. harness documentation
5. one-off prompt guidance

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

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, CLAUDE.md, or ai/project-map.md
• ambiguous task shape → ai/task-templates.md or a dedicated spec
• risky behavior → ai/risk-guardrails.md
• missing validation → validation commands, test plan, or CI guidance
• repeated review issue → reviewer checklist or task contract
• unresolved architecture decision → ADR
• recurring coordination confusion → status doc or ownership clarification
• mechanically enforceable rule → lint, test, typecheck, schema check, generated-file check, or CI enforcement

Prefer the smallest durable fix that prevents the same class of failure from recurring.

Context reset policy

For long-running or multi-agent work, treat milestone boundaries and major scope shifts as reset points.

At those boundaries:

• ensure important state is written into durable artifacts
• update roadmap, status docs, specs, or ADRs as needed
• prefer restarting fresh agent sessions over carrying stale conversational context
• avoid relying on unresolved chat history when a durable file can carry the state

Use files as the primary coordination surface. Use chat context as temporary working memory.

Memory policy for harness work

When proposing persistent memory for agent behavior, prefer short operational feedback over general project knowledge.

Good memory candidates:

• repeated harmful behaviors to avoid
• subtle validation traps
• non-obvious environment constraints
• milestone or session-reset operating rules

Poor memory candidates:

• facts already obvious from code or docs
• routine project structure
• temporary task state
• generic architecture descriptions

If knowledge belongs in the repository, prefer a harness artifact over memory.

Harness health rubric

Assess these areas briefly:

• project map clarity
• runnable validation commands
• fast feedback availability
• task contract quality
• guardrail clarity
• architecture decision durability
• spec / test-plan usefulness when complexity requires them
• 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 or CLAUDE.md
• a concise project map
• reusable task contracts
• a small ADR
• a focused spec and test plan for risky work
• a harness health report with top priorities
• a status doc for active multi-step work

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