mx-harness CLAUDE.md

mx-harness

A collection of user-invocable agent skills (slash commands) that wrap the engineering lifecycle: spec → plan → TDD → review → commit → PR. Not an app. Nothing to build, nothing to test in the runtime sense.

Before editing anything here

Read mx-doctrine/references/maintenance.md first — it defines what you may change autonomously vs. what needs the user, the lesson write-back format, and the compaction triggers. mx-doctrine/references/diagnosis.md records why the suite is structured this way (2026-07-07 restructure) and includes a 60-second re-audit procedure. Two rules worth restating even here: keep every SKILL.md description: ≤ 50 words (it loads into every session on every installed machine), and never state the same rule in two places — point at the canonical copy instead.

Repo layout

Each top-level directory is one skill. The contract per skill:

<skill>/
  SKILL.md           # required — the prompt the agent loads
  README.md          # required — human-facing docs
  references/        # optional — supporting files referenced from SKILL.md

SKILL.md frontmatter schema (all current skills follow this):

name: <slug>                                    # must match dir name
description: >                                  # multi-line, used for skill discovery
  ...
author: Maxence Yang
github: https://github.com/maxence2997/mx-harness
source: https://github.com/maxence2997/mx-harness/tree/main/<slug>
user-invocable: true
allowed-tools:
  - Bash
  - Read
  - Glob
  - Grep

The source: field is load-bearing — install.sh and downstream tooling read it. Don't drop it when editing frontmatter.

When you change a skill

Three places must stay in sync — change them together or the repo lies:

1. <skill>/SKILL.md — the actual change
2. <skill>/README.md — user-facing "what it does" list
3. README.md (root) — skills table, if the one-liner changed

When adding a new skill, also append it to install.sh's SKILLS=(...) array (line ~25) or it won't ship.