AGENTS.md

This file provides guidance to AI coding agents (Claude Code and others) when working with code in this repository.

What this repo is

improver is a Claude Code plugin — and its own marketplace — that enriches a thin, under-developed draft of a prompt, a goal, or a loop into a complete, ready-to-use artifact. It ships no application source code: no package.json, no build toolchain, nothing to compile. The entire plugin is manifests (.claude-plugin/), skill instructions (skills/*/SKILL.md), and JSON data (rules/, golden/). Treat this as a content/data repository, not a software project with a build step.

Commands

There is no build, lint, or test command in the conventional sense — the equivalents are:

• Validate manifests: claude plugin validate . (requires the claude CLI; this is also what quality-gates.yml's marketplace-validate job runs in CI).
• Run a skill's evals: each skill ships skills/<name>/evals/evals.json (3-4 cases, ≥2 expectations each, some with deterministic_checks like regex_match/file_contains/file_not_contains against a transcript). Run with any evals.json-compatible runner (e.g. the autoresearch skill/plugin). There is no bundled runner script in this repo.
• Self-calibrate grading: grade-enrichment's calibration record (golden/calibration-record.json) is regenerated by a blind LLM-judge pass over golden/{prompt,goal,loop}/case-*.json — see that skill's "Calibration gate" section for the exact procedure (never Read a golden case whole; extract only draft/enriched via grep to preserve blindness before comparing against human_verdict).
• Local plugin dev loop: claude --plugin-dir /path/to/improver loads the working checkout directly, no install/publish step required.

Architecture

The four skills, one shared pipeline

skills/{improve-prompt,improve-goal,improve-loop,grade-enrichment}/SKILL.md. The three improve-* skills all run the same four-step pipeline, described identically in each SKILL.md:

1. Load the rule pack — read rules/<kind>-rules.json.
2. Confirm the artifact kind — the skill invocation is the classification. If the draft clearly reads as a different kind, surface that as a clarifying question rather than silently reclassifying it.
3. Detect gaps — run the draft against every rule's gap_check, producing one internal {rule_id, finding_refs, description} list that feeds both elicitation modes below.
4. Elicit and synthesize — default (single-turn): fold each gap into the output as a concise clarifying question, nothing invented, no placeholder tokens ever. --interactive: batch the same gaps as AskUserQuestion calls (max 4 questions per call) before synthesizing with real answers folded in; if the user skips a question, fall back to folding it into the output rather than inventing an answer.

grade-enrichment is the deliberate exception: strictly opt-in, never chained into from an improve skill, and grades an already-enriched artifact against the same rule pack that produced it.

Each skill's output contract is narrow and enforced by its own "Critical rules" section — e.g. improve-goal must return exactly one code block prefixed /goal and strictly under 4,000 characters (compress and re-count, never truncate); improve-loop must never emit a fully autonomous loop as "ready" without all three hard gates (sandboxing, iteration cap, human checkpoint). Read the specific SKILL.md before changing any skill's behavior — the contracts differ meaningfully per kind and are exercised by that skill's evals.

Rule packs are versioned data, not prose

rules/{prompt,goal,loop}-rules.json — one independently versioned pack per artifact kind (see docs/decisions/0001-rule-packs-as-versioned-cited-data.md for the full rationale). Each rule is {id, rule, finding_refs, gap_check}; finding_refs resolves through rules/findings-index.json to a full MIF finding @id and source URL. A rule with no citation is indistinguishable from an invented one — none ship without one. When adding or changing a rule, find or produce the real research finding behind it first, add/reuse its entry in findings-index.json, then reference it by shorthand from the rule. Each pack also declares its own target_surface (consumers, budget_chars — e.g. goal's 4000 vs. prompt/loop's null), which is why the packs are separate files rather than one shared pack.

Golden sets and calibration

golden/{prompt,goal,loop}/case-*.json are hand-reviewed {draft, enriched, human_verdict} records; golden/calibration-record.json is a committed snapshot of a blind LLM-judge run over all 9 cases (current: 9/9 agreement, threshold 0.75, grader_model recorded). grade-enrichment reads this record before trusting any LLM-based verdict and degrades gracefully (never blocks) when it's missing, unreadable, or below threshold — see that skill's "Calibration gate" section.

Docs set

docs/ follows the Diátaxis framework — tutorial, how-to, reference, explanation, plus docs/decisions/ for ADRs. docs/*.md and the ADR carry MIF-conformant YAML frontmatter (id/type/relationships/ provenance); preserve that shape when editing, and update docs/README.md's index/table if a new doc is added.

CI/CD conventions

This repo consumes the modeled-information-format/.github org's reusable workflows as thin, SHA-pinned callers rather than reimplementing checks locally:

• ci.yml — pin-check (every uses: in this repo must be a full 40-char commit SHA, no tags/branches) and workflow YAML lint (actionlint).
• quality-gates.yml — SAST (CodeQL in actions-only mode — no app source to scan), SCA/OSV, Trivy, Scorecard, ShellCheck, Semgrep, secrets scanning, manifest-review, plus the canonical claude plugin validate . job. Scorecard runs without an org GitHub App token (personal repo, no access to org-scoped secrets) — a documented, intentional degradation, not a bug.
• release.yml — builds a reproducible git archive source tarball, attests it with SLSA build provenance (actions/attest-build-provenance), and fail-closed re-verifies the attestation before uploading to the GitHub release. Triggered by release: published; workflow_dispatch exercises build→attest→verify as a dry run without cutting a version.

When touching any workflow file, keep new/changed uses: pinned to a full commit SHA (the pin-check gate will otherwise fail CI) and update the SHA comment consistently with the surrounding style (@<sha> # vX.Y.Z for third-party actions, bare @<sha> for the org's own reusables, whose header comment already states the pinned ref).

Non-negotiable content rules (apply across all four skills)

• Never invent, never placeholder. Missing information becomes a clarifying question folded into the output (or an AskUserQuestion in --interactive) — never a [PLACEHOLDER] token, never a guess.
• Preserve intent, don't redirect it. Enrichment adds specificity, structure, and missing elements; it never substitutes a different task, goal, or loop than the one drafted.
• Every enrichment decision must be citable. "Why did you add X?" resolves to a rule id → finding_refs → full finding @id/URL — never a restated heuristic.
• Output format is exactly what each SKILL.md specifies — typically one code block and nothing else, with named exceptions (citations on explicit request, --interactive AskUserQuestion turns preceding the final block).