readme-standard

Configuration

Optional, shared with the rest of the github-manager plugin: ${GITHUB_MANAGER_HOME:-$HOME/.agents/github-manager}/config.json. Keys used here:

With no config there are no mirrors: write only README.md. A mirror that already exists in the repo but isn't configured is kept and synced in Fix mode; ask before deleting it. User instructions in the conversation override the config ("add a Turkish mirror", "no badges").

Generated READMEs

Before Create or Fix, check whether README.md is produced by a tool: a marker in the first lines (Generated, auto-generated, DO NOT EDIT, <!-- generated by), a readme script in package.json, a workflow that writes or checks README.md, or a template (README.tmpl, docs/README*, scripts/*readme*). If so, edit the source and run the generator instead, or stop and ask when the source is unclear. Audit mode still reports on the output.

Standard structure

README.md (primary language)

[badges]
[nav line]            ← include only if ≥8 sections or ≥200 lines (Rule 14)

# Project Name

One-line description.

[mirror link line]    ← include only if mirrors exist (Rule 4), e.g. > 🇹🇷 Türkçe için [README.tr.md](README.tr.md)

[value paragraph]     ← include only if published package/product (Rule 20)

---

## Quick Start
## Features           ← table form if ≥7 features (Rule 19)
## Requirements
## Installation
   ### Uninstall      ← include only if project installs something persistent
## Usage              ← per-command template if CLI/plugin (Rule 21)
## Configuration      ← include only if user-facing config exists
## How It Works       ← include only if internal mechanics are non-obvious
## Project Structure  ← include only for multi-component projects
## Limitations        ← include only if known user-facing constraints exist
## Troubleshooting    ← include only if predictable failure scenarios exist
## <project-specific> ← optional slot, see Rule 10 (readme.extraSections)
## Contributing       ← include only if contributions are accepted
## Community          ← include only if community channels exist
## Documentation      ← include only if external docs site exists
## License
[footer]              ← include only if GitHub repo and ≥200 lines (Rule 23)

Section selection is governed by Conditional sections below: a conditional section is included only when its detection signal is present, and is never emitted empty or as a placeholder.

Mirrors (README.<code>.md, optional)

Only for codes in readme.mirrors or mirrors that already exist. Each mirror is a full translation of README.md:

• Back link right after the translated description (Rule 5), e.g. > 🇬🇧 For English see [README.md](README.md)
• All prose and section headings translated; for Turkish use references/tr-translations.md, for other languages translate consistently
• Badges: identical (same shields.io URLs)
• Code blocks: identical to README.md except comments, which are translated (Rule 6)
• Same section set and order as README.md

Conditional sections

Each optional section has a defined inclusion condition and detection signal. Check the signals during Create and Fix modes; include the section only when the signal is present.

Rules:

• Placement is relative order, not a dependency. The "Placement" column defines the canonical order of the table; "After X" does not require X to exist. When a predecessor is omitted, the section slots in after the nearest present section that precedes it in the table (e.g. if How It Works is omitted, Project Structure goes directly after Configuration — or after Usage if Configuration is also omitted).
• User instruction always overrides detection — "uninstall ekleme" / "skip troubleshooting" removes the section even when the signal is present; "troubleshooting ekle" adds it even without a signal (ask the user for content if none is detectable).
• A conditional section whose condition is not met is omitted entirely — never emitted empty, as "N/A", or as a placeholder (that is a FAIL, Rule 17).
• In Audit mode, conditional sections produce ⚠️ WARN only, never ❌ FAIL:
  • section present but signal absent → ⚠️ 'Uninstall' present but project installs nothing persistent
  • signal present but section missing → ⚠️ Project installs globally; 'Uninstall' section recommended
• Section names and order are fixed (Rule 11 discipline applies to conditional sections too). Every mirror must contain exactly the same section set.

Mode workflows

Only Audit mode is read-only. Create, Fix and Mirror Sync always show the list of files they will write or overwrite and wait for the user's explicit yes; nothing is written before that.

Audit mode

1. Read README.md and every mirror (configured codes plus existing README.*.md translations)
2. Check each rule against references/rules.md
3. Check conditional sections two-way (section↔signal, WARN only — see Conditional sections)
4. Print checklist — ✅ PASS / ❌ FAIL / ⚠️ WARN per rule, with line reference where it fails
5. Do NOT write any files

Create mode

1. Detect project type and read metadata → see Project type detection below
2. Evaluate conditional section signals → see Conditional sections (user instructions override)
3. Build badge line → see references/badge-patterns.md
4. Generate README.md from assets/templates/README.md.tmpl — for CLI/plugin projects build Usage from assets/templates/usage-cli-command.tmpl
5. For each configured mirror, generate README.<code>.md (Turkish: assets/templates/README.tr.md.tmpl; other languages: same structure, translated)
6. List the files that will be written and which of them already exist, then wait for an explicit yes
7. Write the files to the current directory

If README.md already exists, never overwrite it in Create mode: say so and switch to Fix mode.

Fix mode

1. Read existing README.md (required — error if missing)
2. Detect project type and read metadata
3. Evaluate conditional section signals → see Conditional sections (user instructions override; add sections whose signal is present, remove sections whose condition cannot be met)
4. Rewrite README.md: remap existing content to correct sections, apply all rules
5. Regenerate each mirror (configured or already present) as a full translation of the new README.md
6. List the files that will be overwritten and wait for an explicit yes before writing

Mirror Sync mode

1. Read README.md (must exist — error if missing)
2. For each configured or existing mirror (or only the language the user names), translate fully; Turkish follows references/tr-translations.md
3. List the mirror files that will be written or overwritten and wait for an explicit yes
4. Write the mirror files only

Project type detection

Read these files in order (first match wins):

Package + plugin hybrids. When the repo is a publishable npm, NuGet or PyPI package (a package.json without "private": true, a packable *.csproj, or a pyproject.toml with a version) and also ships an agent plugin or skill layer, the package type wins: detect it as the package, put its registry badges first, and treat the plugin as a feature (mention it in Features and Usage). The agentskills.io badge is optional there, placed after the package badges.

A private app (private repo, no publishable manifest) still gets the core sections; Installation then means local setup (clone, env vars, run).

GitHub username and repo: git remote get-url origin → parse from URL. If no git remote exists, ask the user explicitly.

Monorepo / multiple manifests (tiebreakers):

1. A manifest at the repo root always beats one in a subdirectory.
2. Multiple different manifest types at the root → the table order above decides (package.json beats pyproject.toml, etc.).
3. Multiple same-type manifests in subdirectories and none at the root → the README is being written for the repo, not one package: use the directory name + git remote (Generic) and ask the user which package, if any, should drive the badges.

Badge generation

Exact markdown for each type: references/badge-patterns.md

Key rules summary

Full rules with correct/wrong examples: references/rules.md

1. No **EN:** ... **TR:** ... inline bilingual patterns — ever
2. Quick Start is always the FIRST section after the description (and mirror link line)
3. Quick Start: install command + minimal working example, ≤15 lines total
4. (mirrors) One mirror link line in README.md after the description, e.g. > 🇹🇷 Türkçe için [README.tr.md](README.tr.md)
5. (mirrors) Back link in each mirror, e.g. > 🇬🇧 For English see [README.md](README.md)
6. (mirrors) Code blocks stay identical — commands, paths, prompts, trees, output — only comments are translated
7. Tables: monolingual, one language per file
8. Section heading emojis: only if the project already uses them consistently
9. License section: always last ## section — <SPDX id> — see [LICENSE](LICENSE).
10. All 5 core sections mandatory in order: Quick Start → Features → Requirements → Installation → Usage; project-specific sections go in one slot after Troubleshooting, before Contributing
11. Section names must match exactly — approved aliases only: "Commands" (CLI/plugin) and "Get Started" (multi-step install)
12. --- horizontal rule between every ## section (blank line above and below)
13. Description is plain text, one line — no blockquote (>), no multi-paragraph
14. Nav line below badges when ≥8 sections or ≥200 lines — max 6 anchor links, • separator
15. Troubleshooting = **Symptom** — solution pattern; Limitations = constraint + reason + workaround
16. <details> only for secondary depth (alternative paths, methodology) — primary path never collapsed
17. Conditional sections: omit entirely when condition unmet — empty/placeholder sections are FAIL
18. Callouts: only > **⚠️ Important:**, > **Note:**, > **Heads up:** — no freeform variants
19. Features: 2-column table mandatory at ≥7 features, recommended at ≥4 — never mix table and bullets
20. Value paragraph (≤4 sentences, bold opener) after the description — only for published packages/products
21. CLI/plugin Usage: command cheat-sheet block + per-command ### subsections
22. Hero block / banner / demo GIF only if visual assets exist in assets/
23. Footer (Report Bug · Request Feature, centered) after License — GitHub repos ≥200 lines only

Section heading translations

Turkish mirrors: references/tr-translations.md. Other languages: translate the same headings once and reuse them across all files of that language.