From e35c6088d2d328d5a50a7b9be6eb53546c9c7902 Mon Sep 17 00:00:00 2001 From: OpenClaw Date: Sun, 3 May 2026 22:18:00 +0800 Subject: [PATCH] Release he-maintainer v1 --- he-maintainer/references/monorepo.md | 26 ++++++++-- he-maintainer/references/scoring-rubric.md | 58 +++++++++++++--------- he-maintainer/scripts/inspect-harness.sh | 43 ++++++++++++++-- 3 files changed, 95 insertions(+), 32 deletions(-) diff --git a/he-maintainer/references/monorepo.md b/he-maintainer/references/monorepo.md index e5454d1..b916e27 100644 --- a/he-maintainer/references/monorepo.md +++ b/he-maintainer/references/monorepo.md @@ -7,17 +7,33 @@ Use this reference when the repository contains multiple apps, packages, crates, - workspace root vs package roots - shared libraries vs deployable apps - root-level commands vs package-level commands -- ownership boundaries between packages +- ownership or responsibility boundaries between packages +- which decisions are global vs package-local ## 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 +- root-level commands may not validate a specific package well +- agents may edit shared packages when a package-local change is safer +- build, lint, and test commands may vary by package manager, workspace tool, or package type +- one package may require a spec, ADR, or risk note even when the rest of the repo does not +- status can become ambiguous when several packages move in parallel ## Good harness patterns - include a short workspace map -- show how to run commands for one package +- show how to run commands for one package or crate - define allowed scope for a task - prefer targeted validation for the touched package first +- record cross-package rules in a durable place +- use specs or status docs for multi-package migrations or coordinated refactors + +## Artifact guidance + +In monorepos, keep the top-level working guide short. Push detail into focused supporting artifacts when needed: + +- project map for workspace layout and boundaries +- task contracts for per-package scope +- ADRs for cross-cutting decisions +- status docs for migrations spanning several packages + +Do not duplicate every package's README into the harness. diff --git a/he-maintainer/references/scoring-rubric.md b/he-maintainer/references/scoring-rubric.md index 998c848..b35290f 100644 --- a/he-maintainer/references/scoring-rubric.md +++ b/he-maintainer/references/scoring-rubric.md @@ -5,34 +5,44 @@ 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 +- strong: key directories, entrypoints, and subsystem boundaries are documented and current +- partial: some structure is documented but stale, shallow, 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 +- strong: build, test, lint, typecheck, or equivalent validation commands are clear and runnable +- partial: some commands exist but are incomplete, stale, or ambiguous +- weak: commands are missing, misleading, or unverified ### 3. Fast feedback -- strong: targeted checks or quick tests exist -- partial: only slower validation exists -- weak: no obvious quick validation path +- strong: targeted package-, crate-, app-, or feature-scoped checks exist +- partial: only slower validation paths exist, or quick checks are incomplete +- weak: no obvious fast validation path exists -### 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 +### 4. Task contract quality +- strong: reusable task contracts or templates define scope, constraints, validation, and acceptance criteria +- partial: ad hoc task instructions exist but are inconsistent or underspecified +- weak: every task must be reinvented from scratch ### 5. Guardrails -- strong: high-risk areas and forbidden changes are explicit -- partial: some constraints exist but are vague -- weak: almost no constraints are documented +- strong: high-risk areas, forbidden changes, generated-file boundaries, and slow validations are explicit +- partial: some constraints exist but are vague or fragmented +- weak: almost no meaningful 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 +### 6. Architecture decision durability +- strong: durable decisions are easy to find in ADRs, accepted docs, or equivalent records +- partial: some decisions are documented but scattered, stale, or inconsistently applied +- weak: important architecture or workflow decisions must be rediscovered from chat or code archaeology + +### 7. Failure feedback loop quality +- strong: repeated AI or implementation failures are converted into durable harness, validation, or CI improvements +- partial: some failures are documented, but fixes remain mostly conversational or one-off +- weak: the same classes of failure recur without system updates + +### 8. Doc-code alignment +- strong: harness docs match the current repo layout, commands, and constraints +- partial: mixed accuracy with some stale sections +- weak: obviously stale or misleading guidance dominates ## Output format @@ -41,11 +51,13 @@ Keep the score compact. Example: - project map clarity: partial - validation commands: strong - fast feedback: weak -- task templates: weak +- task contract quality: weak - guardrails: partial +- architecture decision durability: weak +- failure feedback loop quality: weak - 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 +1. Add a targeted validation command for the touched package or crate +2. Record one durable architecture decision in an ADR or accepted design note +3. Turn the most common repeated failure into a task-contract, guardrail, or CI rule diff --git a/he-maintainer/scripts/inspect-harness.sh b/he-maintainer/scripts/inspect-harness.sh index c81d544..8519f19 100755 --- a/he-maintainer/scripts/inspect-harness.sh +++ b/he-maintainer/scripts/inspect-harness.sh @@ -5,16 +5,51 @@ 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 +find . -maxdepth 4 \( \ + -name 'AGENTS.md' -o \ + -name 'CLAUDE.md' -o \ + -name 'AI_GUIDE.md' -o \ + -path '*/ai/*.md' -o \ + -path '*/ai/*/*.md' -o \ + -path '*/docs/adr/*.md' -o \ + -path '*/docs/specs/*.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 +find . -maxdepth 4 \( \ + -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 +find . -maxdepth 5 \( -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 +find . -maxdepth 4 \( \ + -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 + +echo +echo "== Likely status / roadmap files ==" +find . -maxdepth 4 \( \ + -iname '*roadmap*.md' -o \ + -iname '*status*.md' -o \ + -iname '*plan*.md' -o \ + -iname '*vision*.md' \ +\) | sort || true