Improve he-maintainer harness workflow

he-maintainer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: he-maintainer
-description: Create, audit, update, and maintain project-specific AI harness files for software repositories. Use when the user wants to bootstrap or evolve AGENTS.md, AI working guides, task templates, validation commands, project maps, guardrails, or harness health checks for a codebase.
+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
@@ -28,6 +28,18 @@ Harness engineering is not mainly about clever prompting. It is about giving the
 
 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.
@@ -39,6 +51,20 @@ Follow this sequence unless the user asks otherwise.
 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:
@@ -66,6 +92,17 @@ Depending on the request, create or update one or more of:
 
 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:
@@ -78,6 +115,17 @@ Use these roles by default:
 
 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.
@@ -101,6 +149,17 @@ When defining harness rules, strongly prefer:
 
 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:
@@ -110,6 +169,8 @@ Assess these areas briefly:
 - 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`.