oprogramadorreal/optimus-claude / skills/how-to-run
how-to-run
FlaggedGenerates or updates a project's HOW-TO-RUN.md — one verified document teaching a new developer to set up their environment and run the project locally. Detects toolchain, source dependencies, external services, and env config via a read-only agent; audits an existing file against actual project state and offers a display-only guided walkthrough. Never runs setup commands; writes only HOW-TO-RUN.md.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 4.5 KB |
| SKILL.md | skill md | 15.0 KB |
| agents/how-to-run-auditor.md | markdown | 6.2 KB |
| agents/openai.yaml | config | 198 B |
| agents/project-environment-detector.md | markdown | 34.9 KB |
| agents/shared-constraints.md | markdown | 1.7 KB |
| references/detector-framework-config-services.md | markdown | 4.3 KB |
| references/detector-native-and-embedded.md | markdown | 1.7 KB |
| references/external-services-docker.md | markdown | 29.4 KB |
| references/guided-walkthrough.md | markdown | 5.5 KB |
| references/how-to-run-sections.md | markdown | 20.9 KB |
| references/step6-verification-audits.md | markdown | 11.5 KB |
references/step6-verification-audits.md
View on GitHub# Verification Audits and Unverifiable-Content Sanitization
Record-time validation (Step 3), render-time sanitization (Step 4), and the Step 6 audit passes. These are the last line of defense against hallucinated tokens and markdown/link injection from untrusted README prose — apply every rule exactly as written; never drop or reorder a rule.
## Record-time validation (Step 3 — approved unverifiable items)
- `source_file`: must match `^[A-Za-z0-9][A-Za-z0-9._/-]{0,128}$`; split on `/` and drop the entry if any segment is empty, `.`, or `..` (so `docs/../etc/passwd` cannot render as a plausible attribution).
- `source_heading`: truncate to 80 chars; strip every backtick, `<`, `>`, `\`, `&`, newline, carriage return, NUL, and Cc/Cf character; then escape every remaining `[` as `\[` and `]` as `\]` (a heading like `[Source](javascript:alert(1))` must not form a clickable link; the `&` strip prevents CommonMark numeric character references from resurrecting brackets at render time; `\` is stripped, not escaped, because stacked backslashes can produce unclosed link labels). Do not whitelist heading characters — legitimate headings contain varied punctuation.
## Render-time sanitization (Step 4 — before writing each approved item)
- Sanitize `text`: truncate to 240 characters; strip every backtick, `<`, `>`, `\`, `&`, newline, carriage return, NUL, and Cc/Cf character (the `&` strip closes the numeric-character-reference decode path in CommonMark renderers).
- Keep `[`, `]`, `(`, `)` so legitimate links render — but scan EVERY `](` in the sanitized text and reject the entry entirely if any is followed by anything other than `https://`, `http://`, or a relative-path target matching `^[^:/\s\\][^:)%\s\\]*\)` (the inner class excludes `:` so embedded schemes like `javascript:` are rejected, `%` so percent-encoded schemes are rejected on pre-decoding renderers, and `\\` as a UNC backstop); additionally split the matched path on `/` and reject the entry if any segment equals `..`.
- Reject every occurrence of `![` — the markdown image opener (inline and reference-style) is never legitimate in an attribution and can smuggle active content into previewers.
- Reject reference-style link definitions (`]` + optional whitespace + `:` + destination) whose destination contains `:` or `%` unless it begins with `http://` or `https://` (case-insensitive) — rejects `[x]: javascript:alert(1)`, `[x]: data:text/html,...`, `[x]: javascript%3Aalert(1)`. Destinations with neither `:` nor `%` pass (they cannot form a scheme even after percent-decoding).
- Entries failing any check are **removed** from the `approved-unverifiable-items` list (so `rendered_line` can never stay unset and exempt blank lines). Entries that pass store the full rendered line — including any leading list marker or indentation — into `rendered_line`.
## Step 6 audits (against the written HOW-TO-RUN.md)
Every audit here checks the written file against evidence Step 4 could not consult — the filesystem, a re-read citation, a live count. Step 4's own render rules are not re-run: an identical deterministic regex over output it just produced cannot find anything.
On any failure, show the correction and wait for approval before applying it. Never silently accept an ungrounded token.
- **External Services, read-back only** — a bare moving label (`latest`, `stable`, `edge`, `nightly`, `canary`, `main`, `current`, `rolling`) must match Step 4's recorded exception for that service and image. Re-read its canonical source and verify that no numeric tag is documented; otherwise select a compatible explicit tag or use the fallback. Every `-v` left side must match `^[A-Za-z0-9][A-Za-z0-9._-]*-[A-Za-z0-9][A-Za-z0-9._-]*-data$`, validating the substituted volume name. Verify its destination against the selected image version, especially PostgreSQL 17 versus 18+. A kept downgrade option is not exempt from these checks. Surface failed evidence before correcting the section.
- **Detector-token re-validation** — in the written file: package identifiers must match `^[A-Za-z0-9][A-Za-z0-9._+:@/-]{0,99}$` with no `://` and no empty/`.`/`..` segments after splitting on `/` or `:`; the project name must match `^[A-Za-z0-9._ -]{1,64}$` or be exactly `(unknown)`; hardware/OS and recommended-tool mentions must be canonical tokens from the detector's Task 0d / 0d2 lists; schema-bootstrap filenames in invocations must match `^[A-Za-z0-9][A-Za-z0-9._/-]{0,128}$` with no empty/`.`/`..` segments and no segment starting with `-`; config-file section names echoed anywhere must match `^:?[A-Za-z_][A-Za-z0-9_.-]{0,63}$`; config-file paths echoed anywhere must match `^[A-Za-z0-9][A-Za-z0-9._/-]{0,128}$` with no empty/`.`/`..` segments. Reject any line outside skill-generated code fences that echoes free-text prose from other docs or from the user's Step 1 corrections — EXCEPT lines matching, by full-line equality after trimming leading/trailing whitespace, the `rendered_line` of an `approved-unverifiable-items` entry. Substring matches are NOT exempt — otherwise adversarial prose containing an approved fragment could bypass the check.
- **Specific-Token Audit** — build a `grounded-tokens` set from the detector's return format: **ports** (External Services Port cells + Runtime Ports cells + the host port of each rendered External Services `-p 127.0.0.1:<host-port>:<container-port>` line — re-read each Runtime Ports `<file>:<line>` citation at audit time); **paths** (Source Dependencies, Environment Setup *File*, Schema Bootstrap *File* + *Directory*, Subprojects *Path*, Repos *Path* — verbatim only, no prefix/suffix expansion: `scripts/database/` does NOT ground `scripts/database/26.10.00/`); **versions** (Runtime Version Constraints — re-read each `<file>:<line>` citation at audit time — Build System Min version, and pinned version-manager file contents re-read at audit time); **counts** (row counts of detector tables + each `Variable count` cell). Then for every specific token in prose (outside skill-generated fences):
- **Ports:** any integer 1–65535 following `port`, `localhost:`, `127.0.0.1:`, `listens on`, `bound to`, `listening at`, or as the `:`-suffix of an `http(s)://<host>:` URL must be in the grounded set (context tokens required — `Expected result: responds within 5 seconds` must not trigger on `5`). On miss, re-read the cited source; if it differs, rewrite with the observed value or delete the port (omit the URL — never substitute a framework default).
- **Paths:** a version-manager selector that exactly matches the re-read pin file (such as `lts/iron` or `lts/*`) is a version, not a filesystem path. Neither are `http(s)://` URLs, hostnames, dotted config keys (`engines.node`) or runtime/framework names (`Node.js`, `ASP.NET`). For all other tokens, every `<dir>/<subdir>` or `<name>.<ext>` fragment must be grounded verbatim OR still exist on disk. Escape glob metacharacters (`*`, `?`, `[`, `]`, `{`, `}`) in the fragment before globbing (they survive render-time sanitization; an unescaped `src/[a-z]/x` would spuriously match). Fragments with `/`: Glob the escaped literal. Bare filenames: Glob `**/<escaped-full-name>` as one token (never split on `.` — `Dockerfile` / `Makefile` / `Procfile` have no extension). Exclude `node_modules/`, `vendor/`, `.venv/`, `venv/`, `target/`, `dist/`, `build/`, `.git/`, `.next/`, `.nuxt/`, `coverage/`, `__pycache__/` (a hallucinated `src/utils/helpers.js` must not match a transitive dependency copy). Reject fragments failing both checks. Skip the commands in Verify bullets and the Diagnostic Ladder: they come verbatim from `external-services-docker.md` §Verify Commands and the `how-to-run-sections.md` ladder template, run inside the container, and Step 4 already confirmed their absolute paths against the vendor page.
- **Versions:** any `X.Y.Z`, `vX.Y`, or `X.Y+` in Prerequisites / Toolchain prose must match a grounded version verbatim or a version-manager file's current content. A major-only selector or named alias such as `lts/iron` is valid when it matches the cited file; preserve it as a selected version, never rewrite it into a guessed numeric lower bound.
A failed token is rewritten with a grounded value or deleted in favor of hedged phrasing ("the bound port", "the latest folder", "a supported version").
- **Detector-state cross-checks** — classes no audit above can reach, because each compares a written token against what the detector actually FOUND rather than against a shape or the filesystem. A shape regex accepts every one of these; the reader hits them on their first command.
- **Package-manager prefix:** every install / run / script invocation must use the manager the detector reported. `npm run build` is a well-formed identifier in a pnpm project, so only the detected manager can catch it.
- **Build commands:** each command in the Build section must correspond to a build file the detector found (`CMakeLists.txt`, `*.sln`/`*.csproj`, `Makefile`, `build.gradle`, `pom.xml`, a `package.json` script). The Debug+Release pair check below tests only that both fences exist — a documented `make build` in a repo with no `Makefile` passes it.
- **Workspace commands:** combine the task runner with the detected package manager and supported manager version. Go build/test commands must cover the actual `go.work` modules, with each working directory and package path checked; a root `./...` pattern alone is not evidence of workspace coverage.
- **Service names:** every service named in a `docker compose ... <name>` invocation must be a key under `services:` in the compose file — re-read it at audit time. A bare name (`db`, `cache`, `postgres`) carries no `/` and no `.`, so the Paths audit never sees it, and `docker compose up -d postgres` against a compose file defining `db` fails at the user's first run.
- **Environment variables:** every `VAR_NAME` documented in Environment Setup must appear in the `.env.example` (or equivalent) the detector cited — re-read that file at audit time. The grounded set holds its PATH, not the names inside it, so a hallucinated `DATABASE_URL` renders clean against a file that says `DB_URL`.
- **Unverified-Count filter** — strip backticks from each line first (so `` 15 `.csproj` projects `` normalizes to `15 .csproj projects`), then scan lines outside fences against the case-insensitive regex `\b\d{1,4}\s+(?:[\w.@/_-]+\s+){0,2}(?:projects?|modules?|packages?|services?|subprojects?|repos?|files?|dependencies|jars?|binaries|microservices?|workspaces?|crates?|components?|containers?|env(?:ironment)?[\s-]*(?:vars?|files?|variables?)|configurations?|profiles?|endpoints?|schemas?|tables?)\b`. A matched count passes only when it equals (a) a detector-table row count from the grounded set, or (b) a live `Glob` count for the claimed noun. Unbacked counts are rewritten — drop the number or hedge (`"multiple"`, `"several"`).
- **Section ordering** — when the *Private registry* signal is set or *Local TLS cert* is `mkcert` and the language-level install renders at or before Environment Setup, surface the conflict to the user (no auto-rewrite — reordering is editorial).
- **Build Debug+Release pair** — when the build system is CMake, MSBuild, .NET, or Xcode, the Build section must carry both a Debug and a Release fence (per-system flag forms in `how-to-run-sections.md` Section Shapes' Build rule). A half-documented build is a grounding gap, not a layout preference. Skip when Build is omitted entirely.
Layout itself is not audited — the Step 4 section shapes govern it, and re-checking your own formatting against a row-count threshold catches nothing a reader would notice.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |