Instructions

Telemetry

.claude/skills/export-readme/export-readme.sh $ARGUMENTS
echo "sidecar exit: $?"

• it already ran, so there is no command to issue
• no argument EXPORTS: every unblocked drifted region is rewritten from its readme section
• --check reports and writes nothing, and skill names scope either mode
• mapped: N target(s) → what the map named, counting every copy a listed section fans out to
• in_sync / drift / blocked → the three states a target can be in, and they sum to mapped
• listing: N/1536 chars at its widest → the widest skill listing, which truncates silently at the cap
• help: requested from a --help invocation → read ## Help and run nothing
• fail (sidecar exit > 0) → an ERROR blocked a section, or --check found drift; quote the drift table and the findings verbatim in a code block, and edit nothing until the user has read it
• a --- refused: diff is the one finding to raise first, since it names an edit about to be lost
• success (sidecar exit = 0) → report drift and exported, then re-run --check to confirm drift: 0, since the export is idempotent by contract
• a sandboxed run cannot write .claude/skills/*/SKILL.md; that is a partial export, not a pass

the artifact

append one entry to [audit_file], in the shape under ## the entry below:

• the heading reads ## Export Audit #[next_audit]: [timestamp], both taken from the telemetry
• state is what the run measured, as hyphen bullets, one clause each
• findings is the ERROR and WARN table the sidecar printed, or one bullet saying none held
• telemetry is the sidecar's whole output, fenced and unedited, pasted last
• CREATE the file first if it does not exist, with # <audit_file> as its only line
• the sidecar names the path and the count and writes nothing, so a run nobody records leaves none

the entry

the artifact this skill appends to; /gitgud:audit grades the shape on its next run

.construct/maintainer/export-readme/YYYY-MM-DD.md

one file per day, appended to by every run:

• an entry captures one run at a moment in time, so it is never edited after the fact
• lines are hyphen bullets holding a single clause, capped at 100 characters

Export Audit #1: YYYY-MM-DD HH:MM

state

the mode, the source and map, the four target counts, the widest listing, and what exported

example:

• mode: export, source README.md mapped through map.json
• targets: 52 mapped, 51 in sync, 1 drifted, 0 blocked
• exported: 1 file(s)

findings

the ERROR and WARN table the sidecar printed, or one bullet saying every rule held

example:

| WARN | README.md:1204 | listing | 1489/1536 chars, close to the truncation cap |

telemetry

the sidecar's whole output, fenced and unedited

the shape

the readme's mapped sections are the source of truth for every managed region:

• a skill section is one bare invocation fence, one ```yaml fence, then the preamble markdown after it
• the yaml fence's inner --- ... --- becomes the skill's frontmatter, verbatim
• everything after the yaml fence, to the next heading, becomes the skill's preamble, verbatim
• the invocation fence is readme display sugar and never lands in a skill file
• .claude/skills/export-readme/map.json is one flat object: exact heading line -> target path
• a value may be a list, so one section lands in every copy that has to agree byte for byte
• a skill's managed region runs from line 1 to its first # or ## body heading; the body below that heading belongs to the skill and is never touched

the output style

### Output Style maps to one output-styles/operator.md per plugin and ### Subagent Style to one subagent-styles/operator.md; the copies exist so each plugin reaches its own CLAUDE_PLUGIN_ROOT:

• a style file carries no body heading, so its managed region is the whole file
• it earns name and description and nothing else; kind, license and the listing cap route an invocation a style never has
• name: must match the file, not a folder, since a style owns a file rather than a directory
• full runs sweep plugins/*/output-styles/*.md and its subagent-styles/ sibling; an unmapped copy is an ERROR, since drifting unseen is the exact failure the fan-out exists to stop
• the subagent copy earns a 2500-byte cap, since every skill pastes it into every invocation
• over the cap is an ERROR that blocks its own section: cut a rule, never wrap one
• never edit a copy: fix the readme section, then re-export all three

the scripts

a section may map to a shell script instead of a skill doc; NO section does today, since the shared/ libraries were unhooked once none of them fanned out to every plugin:

• a script section carries one ```bash fence; the fence's inner lines become the file, verbatim
• the prose around the fence is readme documentation and never lands in a copy
• a script has no frontmatter, so every yaml rule skips it; the fence must open #!/bin/bash
• the whole file is the managed region and a stale copy is replaced whole; there is no merge, since two edited copies is a mistake not a branch
• a data file cannot be a target at all, since the fence must open with a shebang
• shared/secrets.sh is duplicated in operator and retardify, and /gitgud:audit md5s the copies
• that audit is now the ONLY thing comparing them, so a red Shared Drift is the whole signal
• never edit a copy alone: change both, then re-run /gitgud:audit to prove they still match

the readme copies

README.md maps to one copy per plugin root, and this entry names no section: the source file itself is what lands, byte for byte, since an install takes one plugin's directory and no sibling:

• the whole file is the region and cp is the whole export; a render that shed one trailing blank would break the only contract this target has
• a copy carries no frontmatter, no heading and no fence, so cmp is every check it gets
• an absent copy is drift and not an ERROR: unlike a skill there is no body to invent, so a plugin added to the map earns its copy on the next apply
• a copy mapped into a directory that is not there is the one ERROR, since that is a typo
• full runs sweep plugins/*/README.md too, so a new plugin's copy cannot drift unmapped
• relative links resolve from the repo root, so LICENSE and every plugins/... link is dead in a copy one level down; byte-identical is the contract and those links are what it costs
• never edit a copy: fix the readme, then re-export all three

the two modes

• a bare run exports: every unblocked drifted region is rewritten from its readme section
• --check writes nothing and exits 1 on any drift or ERROR; this is the one mode ci runs
• the drift table names each skill, which half moved (frontmatter, preamble, or both), the line delta, and which side moved last
• scope either mode with skill names (credentials or operator:credentials; readme scopes its own fan-out)
• the map and the source are fixed paths, edited by hand; no flag swaps either one

the checks

this tool owns every frontmatter and preamble rule, judged at the readme source before anything lands; validate-skills owns the body, the sidecar, the pairing, and the index, and nothing else:

• required fields: name, license, compatibility, description on every skill; a trigger adds model and effort, which route an invocation and are dead config on a spec
• metadata.kind is declared; kind: trigger sets disable-model-invocation: true, a spec must not
• description stays at or under 110 characters; over the cap is a WARN, since the fix is a rewrite, and a short description that already says the whole thing is not padded to a floor
• descriptions read in the default output style, lowercase with capitals held for proper nouns and ids; a reviewer's rule the script never grades
• description + when_to_use stays under the 1536 listing cap the harness truncates silently; past 1228 is a WARN, past the cap is an ERROR, since landing silent trigger loss is worse
• name: must match the skill's folder, so a mis-mapped heading cannot overwrite a sibling
• a script section earns none of the yaml rules; a missing ```bash fence, or one not opening #!/bin/bash, is its one ERROR
• a readme copy earns none of them either; its plugin directory missing is its one ERROR
• a heading the readme lacks, a duplicated heading, a section with no yaml fence, or a mapped file that does not exist are each an ERROR naming the exact readme or skill line
• full runs sweep coverage both ways: a SKILL.md, style or readme copy on disk with no map entry is an ERROR, and a catalog #### heading the map never names is a WARN; scoped runs skip it
• an ERROR blocks only its own skill; every other drifted section still exports

the refusal

drift can be legitimate in either direction, so the fresher copy is never written over:

• the NEWER column names which side moved last, read from file mtimes, since the edit that caused the drift is usually still uncommitted
• copy means the skill side is the fresher one, and exporting over it would discard that edit
• a copy row is an ERROR that blocks its own section, prints its diff inline, and lets every other section export
• the fix is always the same: move that edit INTO its readme section, then re-run
• the source mtime is file-level, so any readme edit marks every row readme; it bounds the question rather than answering it, and copy is the row that actually needs a human
• after an export, --check must report drift: 0; the export is idempotent by contract

Verify

not part of the tool; these run after the readme or a copy changes

• RUN .claude/skills/export-readme/export-readme.sh after ANY README.md edit, since the plugin copies track the whole file, not just the mapped sections
• RECONCILE every copy_newer refusal deliberately; source of truth means the readme wins by default, not always
• FIX every ERROR in the readme section the finding points at, then re-run
• RUN .claude/skills/validate-skills/validate-skills.sh after an export, since the skill docs just changed
• RE-RUN /gitgud:audit after editing either secrets.sh copy, since nothing else compares them now
• COMMIT the readme and every exported copy together; a partial commit reintroduces the drift

Help

IF the invocation carries --help or -h, this section is the whole turn:

SKILL: /plugin:name
DESCRIPTION: <the `description` frontmatter, verbatim>
POSTURE: <the readme index's keyword for this skill>
FLAGS:
- --flag: <what it changes, in the telemetry bullet's own words>
ARGUMENTS:
- <arg>: <what it names>
ARTIFACT: <the `metadata.artifact` path, or none>
OUTPUT: <what lands in the turn: an audit entry, a handover block, an inline report>
SPEC: <this doc's own path>

• every field prints, in this order; one with nothing to say prints none
• every value is COPIED from the source named beside it, never composed fresh
• ask what they are actually trying to do, and what they have already tried
• name the flag or the sibling skill that fits their answer, then STOP
• run no step, write no file, and never fall through to step 1