feat: bootstrap he maintainer skill

.gitignore

@@ -0,0 +1,2 @@
+*.log
+.DS_Store

README.md

@@ -0,0 +1,22 @@
+# he-skill-repo
+
+A local repository for harness-engineering-oriented AgentSkills.
+
+## Included skill
+
+- `he-maintainer/` — create, audit, and maintain project-specific AI harness assets such as AGENTS.md, project maps, task templates, validation guidance, and guardrails.
+
+## Design stance
+
+This repo follows a hybrid model:
+
+- keep **the method** in a reusable skill
+- keep **project facts** inside each target repository
+
+That avoids baking one project's assumptions into every other project, while still making the maintenance workflow reusable.
+
+## Suggested next steps
+
+1. Add example target-repo outputs under a separate examples area if you want templates
+2. Add more stack references if your projects use specific frameworks
+3. Optionally create a second skill later for task-template generation only

he-maintainer/SKILL.md

@@ -0,0 +1,127 @@
+---
+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.
+---
+
+# 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.
+
+## 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
+
+## 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.
+
+## 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.
+
+## Harness health rubric
+
+Assess these areas briefly:
+
+- project map clarity
+- runnable validation commands
+- fast feedback availability
+- task template quality
+- guardrail clarity
+- 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.

he-maintainer/references/go.md

@@ -0,0 +1,32 @@
+# Go Harness Notes
+
+Use this reference for Go repositories.
+
+## Common files to inspect
+
+- `go.mod`
+- `go.sum`
+- `cmd/`
+- `internal/`
+- `pkg/`
+- `Makefile`
+- `.golangci.*`
+
+## Common validation commands
+
+Typical examples:
+
+- `go test ./...`
+- `go build ./...`
+- `golangci-lint run`
+- `make test`
+- `make build`
+
+Prefer repo-defined commands when available.
+
+## Common guardrails
+
+- avoid broad package churn when a local fix is enough
+- identify whether generated code exists before editing
+- note whether integration tests require external services
+- keep command examples copy-pasteable

he-maintainer/references/monorepo.md

@@ -0,0 +1,23 @@
+# Monorepo Harness Notes
+
+Use this reference when the repository contains multiple apps, packages, crates, or services.
+
+## What to map clearly
+
+- workspace root vs package roots
+- shared libraries vs deployable apps
+- root-level commands vs package-level commands
+- ownership boundaries between packages
+
+## Common risks
+
+- commands at the root may not validate a specific package well
+- agents may edit shared packages when a local override is safer
+- build, lint, and test commands may vary by package manager and workspace tool
+
+## Good harness patterns
+
+- include a short workspace map
+- show how to run commands for one package
+- define allowed scope for a task
+- prefer targeted validation for the touched package first

he-maintainer/references/node-typescript.md

@@ -0,0 +1,39 @@
+# Node / TypeScript Harness Notes
+
+Use this reference for Node.js or TypeScript repositories.
+
+## Common files to inspect
+
+- `package.json`
+- `tsconfig.json`
+- `eslint.config.*` or `.eslintrc*`
+- `vitest.config.*`, `jest.config.*`, `playwright.config.*`
+- `src/`, `apps/`, `packages/`, `tests/`
+
+## Common validation commands
+
+Prefer commands already defined by the repo. Typical examples:
+
+- `npm test`
+- `npm run lint`
+- `npm run build`
+- `npm run typecheck`
+- `pnpm test`
+- `pnpm lint`
+- `pnpm build`
+- `pnpm tsc --noEmit`
+
+## Suggested AGENTS.md sections
+
+- project purpose
+- important directories
+- install / build / test / lint commands
+- constraints on schema, dependencies, and generated files
+- validation order
+
+## Common guardrails
+
+- do not edit generated clients unless the task is specifically about generation
+- avoid lockfile churn unless dependencies truly changed
+- prefer targeted tests before full test suite
+- note whether e2e tests are slow or environment-dependent

he-maintainer/references/python.md

@@ -0,0 +1,33 @@
+# Python Harness Notes
+
+Use this reference for Python repositories.
+
+## Common files to inspect
+
+- `pyproject.toml`
+- `requirements.txt`
+- `poetry.lock`
+- `uv.lock`
+- `src/`
+- `tests/`
+- `tox.ini`
+- `noxfile.py`
+
+## Common validation commands
+
+Typical examples:
+
+- `pytest`
+- `ruff check .`
+- `mypy .`
+- `python -m build`
+- `tox`
+
+Prefer environment-specific commands already documented by the repo.
+
+## Common guardrails
+
+- avoid mixing package managers in guidance
+- be explicit about virtualenv or tool runner if required
+- note when tests depend on services, fixtures, or secrets
+- prefer local, minimal edits over package-wide rewrites

he-maintainer/references/rust.md

@@ -0,0 +1,28 @@
+# Rust Harness Notes
+
+Use this reference for Rust repositories.
+
+## Common files to inspect
+
+- `Cargo.toml`
+- `Cargo.lock`
+- `src/`
+- `crates/`
+- `tests/`
+- `rust-toolchain.toml`
+
+## Common validation commands
+
+Typical examples:
+
+- `cargo test`
+- `cargo build`
+- `cargo clippy --all-targets --all-features -- -D warnings`
+- `cargo fmt --check`
+
+## Common guardrails
+
+- do not casually update `Cargo.lock`
+- check for workspace crates before describing structure
+- prefer the smallest crate-local change that solves the task
+- distinguish unit, integration, and benchmark targets when relevant

he-maintainer/references/scoring-rubric.md

@@ -0,0 +1,51 @@
+# Harness Health Scoring Rubric
+
+Use this when asked to audit or score a repository's harness quality.
+
+## Dimensions
+
+### 1. Project map clarity
+- strong: key directories and entrypoints are documented and current
+- partial: some structure is documented but stale or incomplete
+- weak: little or no useful repo map exists
+
+### 2. Validation commands
+- strong: build, test, lint, and typecheck are clear and runnable
+- partial: some commands exist but are incomplete or ambiguous
+- weak: commands are missing, stale, or unverified
+
+### 3. Fast feedback
+- strong: targeted checks or quick tests exist
+- partial: only slower validation exists
+- weak: no obvious quick validation path
+
+### 4. Task templates
+- strong: reusable templates exist for common work types
+- partial: ad hoc instructions exist but are inconsistent
+- weak: every task must be reinvented
+
+### 5. Guardrails
+- strong: high-risk areas and forbidden changes are explicit
+- partial: some constraints exist but are vague
+- weak: almost no constraints are documented
+
+### 6. Doc-code alignment
+- strong: harness docs match the current repo layout and commands
+- partial: mixed accuracy
+- weak: obviously stale or misleading
+
+## Output format
+
+Keep the score compact. Example:
+
+- project map clarity: partial
+- validation commands: strong
+- fast feedback: weak
+- task templates: weak
+- guardrails: partial
+- doc-code alignment: partial
+
+Top priorities:
+1. Add a fast unit test or package-scoped validation command
+2. Refresh AGENTS.md directory map
+3. Document forbidden change areas

he-maintainer/scripts/inspect-harness.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="${1:-.}"
+cd "$repo_root"
+
+echo "== Harness files =="
+find . -maxdepth 3 \( -name 'AGENTS.md' -o -name 'CLAUDE.md' -o -name 'AI_GUIDE.md' \) | sort || true
+
+echo
+echo "== Stack markers =="
+find . -maxdepth 3 \( -name 'package.json' -o -name 'pnpm-workspace.yaml' -o -name 'turbo.json' -o -name 'Cargo.toml' -o -name 'go.mod' -o -name 'pyproject.toml' -o -name 'requirements.txt' \) | sort || true
+
+echo
+echo "== CI files =="
+find . -maxdepth 4 \( -path '*/.github/workflows/*' -o -path '*/.gitlab-ci.yml' \) | sort || true
+
+echo
+echo "== Common test/build/lint config =="
+find . -maxdepth 3 \( -name 'tsconfig.json' -o -name 'vitest.config.*' -o -name 'jest.config.*' -o -name 'playwright.config.*' -o -name 'tox.ini' -o -name 'noxfile.py' -o -name '.golangci*' -o -name 'rust-toolchain.toml' -o -name 'Makefile' \) | sort || true