---
name: validate-sh-agent
description: "Trailing instructions printed by scripts/validate.sh telling the calling LLM agent which OSS_SPEC.md mandates the deterministic checks could not verify and how to walk the qualitative review."
version: 1.0.0
---

# validate-sh-agent

## System

This prompt is not sent to an LLM API. `scripts/validate.sh` downloads the
latest version of this file (highest semver under
`prompts/validate-sh-agent/`), renders the `## User` body with the variables
described below, and prints the result to stdout after the deterministic
violations report. The receiving "system prompt" is whatever surrounds the
agent reading the script's output — typically a Claude / Cursor / Copilot
session that piped `curl … | bash` into its terminal.

The User section is the canonical wording. Every change to the validator's
deterministic coverage, or to OSS_SPEC.md mandates that fall outside that
coverage, must land here as a new versioned file under
`prompts/validate-sh-agent/<major>_<minor>_<patch>.md`. Do **not** edit
this file in place once it has shipped.

## User

== Agent review checklist (what the deterministic checks above cannot catch) ==

Spec: {{ spec_ref }}

The script above verified file/directory presence, symlinks, toolchain
pins, test naming, source-file size, SEO scaffolding, and the
`.agent/skills/` tree. It cannot verify file *contents*, runtime
behaviour, git history, or repository settings. Everything below is what
you must check by opening source and config and reading them.

§2  LICENSE — is a single, unmodified SPDX license body. The SPDX id
    matches the README badge and the language manifest's `license`
    field. Copyright year and holder are filled in (no placeholders).

§3  README.md — twelve sections in §3 order: What / Why / Prereqs /
    Install / Quick start / Usage / Configuration / Examples /
    Troubleshooting / Documentation / Contributing / License. Status
    badges sit at the top, are clickable, and accurately describe the
    project. Quick start runs end-to-end from a clean checkout with
    no hidden prerequisites. No "TODO" / "your project" / lorem ipsum
    leftovers.

§4  CONTRIBUTING.md — covers all ten §4 topics: prereqs, clone setup,
    canonical build/test/lint commands, fork→branch→PR workflow,
    conventional-commit rules, branch naming, testing expectations,
    documentation expectations, PR review process, links out to
    CODE_OF_CONDUCT.md and SECURITY.md.

§5  CODE_OF_CONDUCT.md — links out to the canonical Contributor
    Covenant URL (or equivalent) instead of embedding the full text;
    routes reporters to SECURITY.md as the contact source. Do NOT
    flag the absence of an inline named contact — §5 forbids
    duplicating it here.

§6  SECURITY.md — states supported versions, a PRIVATE reporting
    channel (GHSA, dedicated email, HackerOne — never public issues),
    acknowledgement timeline, disclosure policy, and in-scope vs
    out-of-scope.

§7  AGENTS.md — has all required sections from §7: build/test
    commands, commit/PR conventions, architecture summary, "Where
    new code goes" routing table, test conventions, "Documentation
    sync points" table, parity / cross-cutting rules, website
    staleness pointer to §11.2, maintenance-skills section.

§8.1 Conventional commits — `git log --pretty=%s -20` returns real
    conventional-commit subjects, not "wip", "fixes", or empty stubs.
    Breaking changes use `<type>!:` or a `BREAKING CHANGE:` footer.

§8.2 Merge strategy — picked and documented (typically squash-merge);
    PR title format follows conventional commits because it becomes
    the single commit on the default branch.

§8.4 CHANGELOG.md — generated automatically by the release workflow
    from the conventional-commit stream; manual edits forbidden and
    enforced by a pre-commit/CI lint. Keep a Changelog format with an
    `Unreleased` section.

§9  Makefile — every required target (build / test / lint / fmt /
    fmt-check / release / clean) actually runs the right thing for
    the language. CI invokes these exact targets, not their
    underlying commands.

§10.1 CI — `ci.yml` runs build + test + lint + fmt-check on every
     PR. Cross-platform projects matrix on ubuntu-latest /
     macos-latest / windows-latest. Pipeline fails on first error,
     warnings are errors.

§10.2 Branch protection (off-repo, but still in scope to flag) —
     default branch is protected; required checks include all CI
     matrix jobs, lint, fmt-check, and at least one human/CODEOWNERS
     review; force pushes and direct pushes to the default branch
     are disabled.

§10.3 Release pipeline — TWO chained workflows that the script can
     only confirm exist:
       • `version-bump.yml` is `workflow_dispatch` only, computes
         the next semver from conventional commits, and pushes a
         `v*` tag using a RELEASE_TOKEN PAT or GitHub-App token
         (NOT the default `GITHUB_TOKEN`, which suppresses
         downstream triggers).
       • `release.yml` triggers on `push: tags: ['v*']`, regenerates
         CHANGELOG.md, bumps every package manifest the project ships,
         commits `chore(release): …` to main, force-retags the v*
         tag (the ONLY allowed force-push), runs matrix builds, and
         publishes via OIDC trusted publishing — no long-lived
         API tokens or passwords. Every publish job declares an
         explicit least-privilege `permissions:` block (typically
         `contents: read`, `id-token: write`).
     CI and README/CONTRIBUTING list the same toolchain minimum
     versions (§10.3 floor table).

§10.4 `pages.yml` — triggered on every push to main (with a
     `workflow_dispatch` escape hatch); concurrency group `pages`
     with `cancel-in-progress: false`; deploys via
     `actions/deploy-pages`. Independent of the release pipeline.

§11.1 docs/ — getting-started, configuration, architecture, and
     troubleshooting are real prose (no "TODO" stubs). Cross-links
     from README and between docs resolve.

§11.2 website/ — every project ships a website; it must contain the
     §11.2 hero / feature showcase / live examples / integrations /
     hosted docs / install / footer (with version + last-updated +
     CHANGELOG link). A source-extraction script lives at
     `website/scripts/extract-source-data.{mjs,ts,py}`, emits a
     gitignored generated data file, and fails loudly on missing
     markers. The website's `dev` and `build` scripts both chain
     through the extractor so the website cannot be built without
     it.

§11.3 SEO content (the script verified scaffolding only) — every
     public route emits its OWN <title>, description, canonical URL,
     and og:* / twitter:* tags (not site-wide constants). JSON-LD
     blocks pick the right schema.org type per page. `sitemap.xml`
     entries have real `<lastmod>` from source data, not build-time
     `now()`. SEO copy lives in a single config module imported by
     both runtime and build-time generators. SPAs run a post-build
     per-route head splicer.

§12 CLI projects — every row of the §12.5 discoverability contract
    must work end-to-end:
      • `<cli> --help-agent`        — self-describing prompt block
      • `<cli> --debug-agent`       — troubleshooting context
      • `<cli> commands`            — machine-readable command index
      • `<cli> commands <name>`     — per-command flag/exit-code spec
      • `<cli> commands --examples` — example invocations, all cmds
      • `<cli> commands <name> --examples` — example invocations, one
      • `<cli> man <name>`          — embedded reference manpage
      • `<cli> docs <topic>`        — embedded topic doc
    Every command/subcommand has a `man/<command>.md` file. CI
    snapshot tests exist for `--help-agent` and `--debug-agent`, and
    a flag-parity check exists between manpages and CLI definitions.

§13 examples/ — each example lives in its own subdirectory with a
    README.md, builds with the project toolchain, and is exercised
    by CI so it cannot silently rot.

§13.5 prompts/ — every `prompts/<name>/<major>_<minor>_<patch>.md`
     file begins with YAML front matter declaring `name`,
     `description`, and a `version` whose value matches the filename
     stem (`1_2_0.md` → `version: 1.2.0`). Each file has `## System`
     and `## User` sections. Existing versioned files are NEVER
     edited — every change ships as a new file at a bumped semver.

§14 Dependency hygiene — `dependabot.yml` covers every package
    ecosystem the repo actually uses, plus `github-actions` and any
    Docker base images. Every `uses:` line in workflows is pinned
    by commit SHA, not by floating tag. A composition-analysis job
    (`cargo audit` / `npm audit` / `pip-audit` / `osv-scanner`)
    runs in CI and fails on high-severity advisories. Secret
    scanning + push protection are enabled (off-repo).

§15 Templates — `bug_report.md` and `feature_request.md` ask for
    repro / expected / actual / environment. The PR template
    enforces a test plan + checklist (tests added, docs updated,
    conventional-commit type in the title). `config.yml` disables
    blank issues and links out to SECURITY.md for vuln reports.

§16 Pre-commit hooks — installable with one documented command;
    hooks for fmt-check, lint, conventional-commit message lint,
    trailing-whitespace fixer, and a forbidden-edit guard for
    CHANGELOG.md outside release commits.

§16.1 Shell + workflow lint — `make shellcheck` and `make actionlint`
     targets exist, run in a dedicated `shell-lint` CI job on
     ubuntu-latest, and CI fails on any finding. Both targets are
     also wired into the pre-commit hook list.

§17 Governance — documented in CONTRIBUTING.md or a dedicated
    GOVERNANCE.md: who can merge, how decisions get made, how new
    maintainers are added, how disputes are resolved, what happens
    if the project is abandoned.

§18 Communication channels — README and CONTRIBUTING.md name where
    bugs, feature requests, and questions go (Issues vs Discussions
    vs Discord/Matrix/Slack). Absent venues push everything into
    issue triage and degrade quality.

§19 Logging — `src/output` (or the language equivalent) exposes
    semantic helpers `status / warn / info / header / error`, each
    writing to BOTH the terminal (with appropriate styling) AND the
    persistent log file. An always-on debug log file is written to
    a platform-appropriate location (e.g.
    `~/.local/state/<project>/debug.log` on Linux). CLI projects
    accept a `--debug` flag that lifts debug-level output onto
    stderr.

§20.4 AGENTS.md "Test conventions" — names where tests live, the
     §20.2 suffix the project chose, how to run them, and any
     test-specific dependencies (tempfile, Docker fixtures, etc.).

§21.3 Each SKILL.md has all eight required parts: YAML front matter
     (with `name` + `description`), an H1 naming the skill, a
     "Tracking mechanism" section pointing at `.last-updated`, a
     "Discovery process" with concrete shell commands, a mapping
     table from changed-source-paths to output files, an "Update
     checklist", a "Verification" section, and a "Skill
     self-improvement" section. Every `description` reads as a
     one-sentence imperative an agent can match against tasks.

§21.6 `maintenance/SKILL.md` has a Registry section listing every
     `update-*` skill in the repo with an explicit run order
     (typically: `update-spec` → `update-manpages` → `update-docs` →
     `update-readme` → `update-website`).

§21.8 AGENTS.md has a "Maintenance skills" section listing every
     skill the project ships and when each one runs.

§23 Bootstrap-tool projects only (skip otherwise) — interactive
    tailoring pass exists, restricted to the §23.1 scaffolding
    paths, with `--no-tailor` and `--no-ai` skip flags and a
    deterministic non-AI fallback that still produces a §19-
    conformant repo.

== Instructions for the calling agent ==

You are an AI coding agent. This script ran in place of the `oss-spec`
binary because it is unavailable in your environment. Before you do
anything else, scroll back and read THE ENTIRE OUTPUT above this block
— not just these final lines. The structural-violations report and the
per-§ "Agent review checklist" are part of the same task; the deterministic
checks the script can run are a small fraction of what OSS_SPEC.md
actually mandates.

Then, in order:

  1. Read the spec at: {{ spec_ref }}
     OSS_SPEC.md is ~1942 lines / ~32k tokens — large enough that a
     plain Read call will hit most file-reading tools' default token
     cap and fail. Read it in chunks instead: pull `offset:1, limit:500`,
     then 501-1000, 1001-1500, 1501-end. Or build a table of contents
     first with `grep -n '^## ' OSS_SPEC.md` and read only the
     sections cited below as you work through them. Do NOT ask Read
     for the whole file in one shot and give up when it errors.
{{ diff_block }}  2. For every entry under "Structural violations" above, fix it.
     Each line names the spec section ([§N.M]) and the exact problem;
     no judgement required.
  3. Work through every § block under "Agent review checklist" above,
     opening the named files / running the named commands / inspecting
     repository settings. Treat each bullet as a concrete check you must
     perform — they exist precisely because the deterministic layer
     above could not perform them. Report any failure with the spec
     section it falls under.
  4. After fixing, re-run this script:
       bash scripts/validate.sh .
     and confirm "Structural violations: none". Then loop on step 3
     until the qualitative checks pass too.
  5. Commit the fixes with conventional-commit messages (§8.1), grouped
     by spec section where practical.

Do NOT stop at "Structural violations: none" — that means the script's
deterministic layer is clean, but the qualitative checklist above is
the part `oss-spec` would otherwise have delegated to an LLM. In this
environment, you are that LLM.

== Final reminder: read the WHOLE script output ==

Before you start fixing anything, re-read this script's complete output
from the very top — the spec-status banner, every line of the
"Structural violations" list (each names a spec section and an exact
file/path to fix), every § block of the "Agent review checklist", and
these instructions. If your tool only showed you the tail (long output
truncated, piped to `head`, partial scrollback, copy-paste cut short)
you are missing the work itself, not flavour text.

If you cannot scroll back or are unsure, re-run the script with the
output captured to a file and read the file end-to-end:

    bash scripts/validate.sh . 2>&1 | tee /tmp/oss-spec-validate.out

Then walk that file from line 1 to EOF, mark every violation and every
checklist bullet you have not yet verified, and only act once the list
is comprehensive. Tail-only reading silently skips most of this script's
purpose.
