Agent Harness

Agent engineering harness for any repo. Creates a short AGENTS.md table-of-contents, structured docs/ knowledge base (ARCHITECTURE, QUALITY, CONVENTIONS, COO...

Security Scan

The skill's code largely matches its purpose (scaffolding docs, linting, plan generation), but there are mismatches and surprising behaviors (hard-coded git identity/SSH key usage and undeclared binary dependencies) that should be reviewed before installing.

Purpose & Capability

Name/description promise: scaffold docs, linters, CI, and audit. The included scripts implement those features. However the SKILL metadata claims no required binaries or env vars while the scripts clearly rely on standard developer tools (git, grep, gh CLI, bash, possibly cargo/go/npm/uv for lint/test commands). The omission of those runtime requirements is an incoherence: the skill will fail or behave unpredictably if those binaries are absent.

Instruction Scope

The SKILL.md instructs running scaffold.py, doc_garden.py, and plan.py which inspect repo structure and create files. That matches the stated purpose. doc_garden.py can open fix PRs (writes docs/STALE_REFS.md, creates a git branch, commits and pushes, and calls 'gh pr create'). These write-and-push actions are within the harness purpose but are sensitive operations (create branches/commits/pushes to remotes). There is no unexpected data exfiltration, but the scripts will act on the user's repo and remote without further confirmation if invoked with flags that allow writes (e.g., --pr).

Install Mechanism

No install spec (instruction-only with code files). That is lower risk than arbitrary downloads. The files are plain Python scripts and generated shell scripts; nothing is fetched from remote during install. This is coherent with the skill being instruction+scripts only.

Credentials

The skill declares no required environment variables, but doc_garden.py pushes via git and uses the 'gh' CLI and SSH for push. Notably, open_fix_pr sets GIT_SSH_COMMAND to 'ssh -i ~/.ssh/id_ed25519_alexchen' and commits with user.name/user.email hard-coded to 'Alex Chen <[e-mail]>'. These are unexpected and disproportionate: they assume a specific SSH key path and identity that are unrelated to most users' repos. The scripts implicitly require access to the user's git credentials, SSH keys, and GH CLI authentication, which is not documented in the metadata.

Persistence & Privilege

The skill is not always:true and is user-invocable; it does not request persistent privileges in the registry metadata. The scripts create files/branches in the repository and may push/open PRs when run with write flags, which is expected behavior for a scaffolding/audit tool. There is no evidence the skill attempts to modify agent/system-wide settings beyond operating on the target repo.

What to consider before installing

This skill mostly does what it says (scaffolding docs, generating lint scripts, checking docs and creating execution plans). Before installing or running it, review and consider the following: - These scripts call standard developer tools (git, grep, bash, gh CLI, and language-specific tools like cargo/go/npm/uv). The skill metadata lists no required binaries — make sure those tools are present and acceptable for your environment. - doc_garden.py can create branches, commit a docs/STALE_REFS.md, push to origin, and open GitHub PRs. Run it first with --dry-run (or avoid --pr) to see what it would change. - doc_garden.py contains a hard-coded commit author (Alex Chen) and forces git pushes using GIT_SSH_COMMAND pointing to '~/.ssh/id_ed25519_alexchen'. That is unexpected: it may fail on your machine, or (if that key exists) cause pushes using that key/identity. Remove or modify these hard-coded values to use your own git identity and auth flow (or rely on the existing git/gh auth) before allowing automatic pushes. - If you intend to let the tool open PRs automatically, ensure your GH CLI and git credentials are configured, and consider auditing the exact commit/branch behavior (branch names, commit messages) so that automated commits don't obscure authorship. - If you want higher assurance, run the scripts in a disposable clone or invoke only the read-only modes (dry-run / output-only) until you are comfortable with generated content and CI changes. If you want, I can point out the exact lines to change to remove the hard-coded GIT_SSH_COMMAND and commit identity or produce a safer variant that asks before pushing.

harness — Agent Engineering Harness

Implements the OpenAI Codex team's agent-first engineering harness pattern for any repo: short AGENTS.md TOC, structured docs/, custom linters with agent-readable errors, CI enforcement, execution plan templates, doc-gardening.

Validated against: Agent Tool Design Guidelines (2026-03-09)

When to use

• Setting up a new repo for agent-first development
• Upgrading an existing repo's AGENTS.md to table-of-contents style
• Adding architectural lint enforcement to a repo
• Any repo where agents are doing most of the coding

Supported Languages

• Rust (Substrate pallets, cargo workspace)
• Go (internal/ package structure)
• TypeScript (src/, npm)
• Python (pyproject.toml, uv/pytest) ← added 2026-03-09

Usage

SKILL_DIR="$HOME/.openclaw/workspace/skills/harness"

# Scaffold harness for a repo (language auto-detected: Rust/Go/TypeScript/Python)
uv run python "$SKILL_DIR/scripts/scaffold.py" --repo /path/to/repo

# Scaffold with force-overwrite of existing AGENTS.md
uv run python "$SKILL_DIR/scripts/scaffold.py" --repo /path/to/repo --force

# Audit harness freshness (tool lifecycle check — no writes)
uv run python "$SKILL_DIR/scripts/scaffold.py" --repo /path/to/repo --audit

# Run lints locally
bash /path/to/repo/scripts/agent-lint.sh

# Check doc freshness (finds stale references in docs/)
uv run python "$SKILL_DIR/scripts/doc_garden.py" --repo /path/to/repo --dry-run

# Check doc freshness and open a fix PR
uv run python "$SKILL_DIR/scripts/doc_garden.py" --repo /path/to/repo --pr

# Generate execution plan for a complex task
uv run python "$SKILL_DIR/scripts/plan.py" \
  --task "Add IBC timeout handling" \
  --repo /path/to/repo

What gets created

File	Description
AGENTS.md	~100 line TOC with L1/L2/L3 progressive disclosure markers
docs/ARCHITECTURE.md	Layer diagram + dependency rules (auto-generated from repo structure)
docs/QUALITY.md	Coverage targets + security invariants
docs/CONVENTIONS.md	Naming rules (language-specific)
docs/COORDINATION.md	Multi-agent task ownership + conflict resolution rules
docs/RESILIENCE.md	Agent recovery protocols, 7-point checklist, VBR standards ← from agent-motivator
docs/EXECUTION_PLAN_TEMPLATE.md	Structured plan format for complex tasks
scripts/agent-lint.sh	Custom linter with agent-readable errors (WHAT / FIX / REF)
.github/workflows/agent-lint.yml	CI gate on every PR

Lint error format

Every lint error produced by scripts/agent-lint.sh follows this format:

LINT ERROR [<rule-id>]: <description of the problem>
  WHAT: <why this is a problem>
  FIX:  <exact steps to resolve it>
  REF:  <which doc to consult>

This means agents can read lint output and fix problems without asking a human.

Agent Design Checklist (from tool design guidelines)

Before shipping any tool or skill change, verify:

• Is the tool shaped to what this model can actually do?
• Does it schema-enforce structured output where correctness matters?
• Is context loaded progressively (L1→L2→L3), not dumped upfront?
• Does it support multi-agent coordination if needed? (see COORDINATION.md)
• Have you measured model affinity (call frequency) vs just output quality?
• Is the total tool count at or below your ceiling? (target: ≤ 20 per agent)
• Do you have a plan to revisit this tool as model capabilities change?

Progressive Disclosure Layers

The harness enforces a 3-layer context discipline:

Layer	Where	When to load
L1	AGENTS.md	Always — orientation, commands, invariants
L2	docs/	Before coding — architecture, quality, conventions
L3	Source files	On demand — grep/read specific files as needed

Rule: Start with L1. Pull L2 before touching code. Pull L3 only when you need it. Never pre-load all three layers — it crowds out working context.

Tool Lifecycle (--audit)

Run --audit quarterly to check harness freshness:

• AGENTS.md has depth layer markers
• COORDINATION.md present (multi-agent support)
• Lint script uses current language tooling
• Python: ruff + pyright checks present
• AGENTS.md under 150 lines

Safety

• Never overwrites existing AGENTS.md without --force flag
• Reads existing code structure before generating docs (no hallucinated APIs)
• All writes are previewed in --dry-run mode before committing

References

• OpenAI Codex harness engineering
• Agent Tool Design Guidelines
• ClawChain harness PR
• EvoClaw harness PR