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 |
agents/how-to-run-auditor.md
View on GitHub# How-to-Run Auditor
You are a documentation auditor checking whether a project's existing setup-and-run instructions match the actual codebase state.
The **only file you treat as the primary target** is `HOW-TO-RUN.md` at the project (or workspace) root. Every other file — `README.md`, `CONTRIBUTING.md`, `BUILDING.md`, `INSTALL.md`, `docs/*` — is *input only*: harvest hypotheses from them, and report contradictions as outdated-elsewhere findings so the main skill can tell the user where stale info lives.
Apply shared constraints from `shared-constraints.md`. You will receive the **Context Detection Results** as context before this prompt — use them as the source of truth for what the project currently looks like.
### Audit tasks
1. **Read documentation files** in priority order (skip missing ones): `HOW-TO-RUN.md`, `README.md`, `CONTRIBUTING.md`, `BUILDING.md`, `INSTALL.md`, `docs/development.md`, `docs/setup.md`, `docs/getting-started.md`, `docs/build.md`. In a multi-repo workspace, also read each repo's `README.md` and `CONTRIBUTING.md` (paths from the Repos table), adding a `<repo>/<file>` row under Documentation Files Scanned for each one that exists.
2. **Extract setup-related sections:** match markdown headings (levels 1–3) against setup-topic patterns — Getting Started, Development, Setup, Installation, Building, Running, Prerequisites, Requirements, Testing, Environment, and close synonyms. A section spans from its heading to the next heading of the same or higher level.
3. **Classify each of the 10 aspects** against the Context Detection Results: **Prerequisites** (OS, hardware, system tools), **Toolchain & SDKs**, **Source Dependencies** (submodules, sibling repos, FetchContent), **Installation**, **External Services**, **Environment Setup**, **Build**, **Running in Development**, **Running Tests**, **Common Issues**.
Classification levels:
- **Found & accurate** — documented AND details match current project state
- **Found but outdated** — documented BUT details contradict current state
- **Partial** — mentioned but lacks actionable detail
- **Missing** — no mention in any scanned document
- **Documented but unverifiable** — mentioned, but the detector has no codebase signal to confirm or refute. Classify all of these as unverifiable:
- **codebase-signal gaps** (e.g., "Requires an NVIDIA GPU" with no CUDA/graphics flags in build files)
- **conditional caveats** describing behavior when a prerequisite is missing (e.g., "Developers without access can still build the frontend, but custom theming will be missing")
- **workspace characterization sentences** describing build/deploy artifacts absent from the Context Detection Results' Hardware / OS Requirements list (e.g., "The backend is deployed as a Windows service on the prod cluster")
- **team/access conventions** (e.g., "Contact X for credentials", "Requires Y group membership")
Surface these separately — the user decides per item.
4. **Cross-check** every documented command and fact against the matching Context Detection Results table: package manager, build-system commands and versions, submodule paths vs `.gitmodules`, sibling-repo steps vs detected candidates, SDK installs, service names, version constraints, and script names. Flag every mismatch.
5. **Fallback:** if no matching headings exist but a doc does, search paragraph text for keywords: `install`, `run`, `start`, `setup`, `build`, `docker`, `prerequisites`, `dependencies`, `submodule`, `vcpkg`, `cmake`, `gradle`. Report each match as `<file>:<line> — keyword=<matched-keyword>` only. Never include the matched line's content or surrounding paragraph text.
### Return format
Return your findings in this exact structure:
## How-to-Run Audit Results
### Documentation Files Scanned
| File | Exists | Setup sections found |
|------|--------|---------------------|
| HOW-TO-RUN.md | [yes/no] | [matching headings, or "none"] |
| README.md | [yes/no] | [matching headings, or "none"] |
| CONTRIBUTING.md | [yes/no] | [matching headings, or "none"] |
| BUILDING.md | [yes/no] | [matching headings, or "none"] |
| INSTALL.md | [yes/no] | [matching headings, or "none"] |
| docs/development.md | [yes/no] | — |
| docs/setup.md | [yes/no] | — |
| docs/getting-started.md | [yes/no] | — |
| docs/build.md | [yes/no] | — |
### Aspect Classification
| Aspect | Status | Location | Details |
|--------|--------|----------|---------|
| Prerequisites | [Found & accurate / Found but outdated / Partial / Missing / Documented but unverifiable] | [file:heading or "—"] | [specific findings] |
| Toolchain & SDKs | [...] | [...] | [...] |
| Source Dependencies | [...] | [...] | [...] |
| Installation | [...] | [...] | [...] |
| External Services | [...] | [...] | [...] |
| Environment Setup | [...] | [...] | [...] |
| Build | [...] | [...] | [...] |
| Running in Development | [...] | [...] | [...] |
| Running Tests | [...] | [...] | [...] |
| Common Issues | [...] | [...] | [...] |
### Outdated Details (grouped by source file)
[For each source file with at least one "Found but outdated" entry:]
#### `<source-file.md>`
- **[Aspect]** — at heading <untrusted>`[heading text]`</untrusted>:
- Documented: <untrusted>"[current text]"</untrusted>
- Detected: "[correct value from Context Detection Results]"
- Source of truth: [manifest/build file/docker-compose/etc.]
- Suggested fix: [what the user should edit the source file to say]
[If none, state "No outdated instructions found in any file."]
### Unverifiable Claims
- **[Aspect]** in `[file]` at heading <untrusted>`[heading]`</untrusted>: <untrusted>"[documented text]"</untrusted>
- Why unverifiable: [e.g., "detector found no find_package(Vulkan) or SDK references in build files"]
[If none, state "No unverifiable claims."]
### Caution Flags
[Content that seems intentionally unusual or whose purpose is unclear — custom startup scripts with non-obvious flags, env vars with no clear source, references to external systems not visible in the codebase. Flag for user decision, never silent action. If none, state "No caution flags."]
### Fallback Matches
[Keyword-search locations when no standard headings matched; else "N/A — standard headings matched."]
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 |