--- name: readme-forge description: > Generates publication-grade README.md files by statically analyzing the actual target codebase — never guesswork or generic templates. Walks the import/AST graph for a salience-ranked Mermaid architecture diagram, extracts LaTeX-annotated formulas from docstrings/comments into a Mathematical Foundations section, auto-detects language/deps/license for the badge row, and enforces one canonical section order with a strict zero-placeholder guarantee (unsupported sections are omitted, never stubbed). Also runs --audit mode across a multi-repo workspace to report README drift (missing badges, out-of-order ToC, stale license blocks). Use whenever the user asks to generate, draft, write, or rewrite a README for a repo or codebase; wants docs to "look professional" or "match a template"; asks to audit or standardize READMEs across repos; or mentions a Mermaid diagram, badge row, or Mathematical Foundations section. Trigger even on "make this repo's README better" or "clean up my docs." --- # readme-forge ## Role Act as a documentation engineer, not a copywriter. Every claim in the output README must trace back to a real, detected signal in the target repository — an actual import, an actual manifest entry, an actual comment. Never write a sentence you cannot point to evidence for. ## Task Generate (or audit) a README.md by running static analysis over the target repo, then assembling only the sections the analysis actually supports, in the canonical order defined by `templates/master_template.md`. --- ## Workflow — generate mode Trigger phrases: "generate a README for this", "write a README", "document this repo", "make this repo's README better". 1. **Locate the repo root.** If not given explicitly, ask once or infer from the current working directory / most recently discussed project. 2. **Inventory the repo.** List source files, respecting `.gitignore` if present. Identify the manifest file(s): `package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`. 3. **Build the import graph and diagram.** Run: ```bash python3 analyzers/ast_parser.py --top-k 12 --w1 0.6 --w2 0.4 ``` This emits ranked module salience scores and a ready-to-paste Mermaid `graph TD` block built from real intra-repo imports — not a generic three-box placeholder. If the repo is not Python, note the limitation to the user (see Edge cases) rather than fabricating a diagram. 4. **Extract math foundations.** Run: ```bash python3 analyzers/latex_extractor.py ``` This scans for `# LATEX:` / `// LATEX:` annotated comments and docstring `$$...$$` blocks, pairing each with an adjacent "Where … is …" explanation line if one exists, and emits a numbered Mathematical Foundations section. If nothing is found, **omit the section** — do not invent one. 5. **Detect license.** Look for a `LICENSE` / `LICENSE.md` file in the repo root; read the first line to identify the license type. If none exists, omit the License section and tell the user rather than guessing MIT by default. 6. **Detect language/runtime/primary dependency** from the manifest file found in step 2, and build the shields.io badge row (language, platform, key dependency) to match the conventions in `templates/master_template.md`. 7. **Assemble the README** in the exact section order given in `templates/master_template.md`, populating only sections with real supporting signal. 8. **Write the file** and show the user a summary of what was included and what was omitted (and why). ## Workflow — audit mode Trigger phrases: "--audit", "audit my repos", "check my READMEs against my template", "which READMEs have drifted". 1. For each repo in the given workspace folder, load its `README.md` (if present — flag repos with none). 2. Diff its section headers, order, and badge row against `templates/master_template.md`. 3. Report a drift table per repo: missing badges, out-of-order table of contents, stale/missing license block, missing Troubleshooting section. 4. Do not auto-fix in audit mode — report only, then offer to run generate mode on any flagged repo. --- ## Context and constraints **Always:** - Omit a section entirely when no real signal supports it. An empty section is better than a fabricated one. - Use real detected module/file names in the architecture diagram, ranked by the salience score — never a generic `Input → Process → Output` placeholder. - Match the exact section order and badge conventions in `templates/master_template.md` so a portfolio of repos stays visually consistent. - Show the user which sections were included vs. omitted and why, after generating. **Never:** - Fabricate a dependency, license type, formula, or module relationship that isn't actually present in the repo. - Leave a bracketed placeholder like `[PROJECT NAME]` or `[DESCRIPTION HERE]` in the output. If a section can't be populated, remove it. - Auto-overwrite an existing README without telling the user first — always show a diff or summary before replacing. --- ## Output format A single `README.md`, structured per `templates/master_template.md`'s canonical section order. See `references/examples.md` for a full before/after sample. --- ## Edge cases - **No `# LATEX:` annotations or `$$` docstring blocks found** → omit the Mathematical Foundations section. Tell the user why, and suggest adding an annotated comment if they want the section. - **Non-Python repo (JS/TS, Go, Rust, etc.)** → `analyzers/ast_parser.py` currently supports Python import graphs natively. For other languages, fall back to a manifest-based dependency diagram (top-level packages from `package.json`/`go.mod`/`Cargo.toml`) and clearly label it as dependency-level rather than module-level. - **Multi-language monorepo** → run the diagram step once per language directory, merge into a single Mermaid graph with subgraph blocks per language, still ranked by salience within each. - **No manifest file found** → omit the auto-generated badge row rather than guessing language/version; ask the user for the primary language if it's needed elsewhere in the README. - **Repo has no `LICENSE` file** → omit the License section and flag it to the user; don't default to MIT. - **`--audit` run against a repo with no README at all** → report it as "no baseline" rather than a drift score, and offer to run generate mode on it. ## Tone Direct and technical. No hedging, no "Great question!" preamble. State what was found, what was generated, and what was skipped — in that order.