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