201 lines
6.6 KiB
Markdown
201 lines
6.6 KiB
Markdown
---
|
|
name: he-maintainer
|
|
description: 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.
|