Implement docs-readme: README generation and maintenance

[vredchenko]

Summary

The docs-readme plugin generates and maintains project READMEs by analyzing the codebase, extracting metadata from manifests, and following a consistent structure. This is valuable because writing a good README from scratch is tedious and Claude's default behavior is to generate either too much or too little without a consistent format.

Original Intent

Plugin to maintain a project README file — what purpose it serves, what it needs to communicate, as well as keeping it up-to-date.

Commands

/readme:generate

Purpose: Generate a comprehensive README from project analysis.

Behavior:

1. Analyze the project:

   • Read manifest files (package.json, pyproject.toml, Cargo.toml, go.mod)
   • Extract: name, description, version, license, author, repository URL
   • Detect tech stack from dependencies and config files
   • Find entry points and main exports
   • Identify scripts/commands from package.json, Makefile, etc.
   • Check for existing docs/, examples/, CONTRIBUTING.md, CHANGELOG.md

2. Detect badge candidates:

   Badge	Condition	Source
   npm version	package.json exists	shields.io
   PyPI version	pyproject.toml with [project]	shields.io
   License	License file or manifest field	shields.io
   CI status	.github/workflows/ exists	GitHub Actions
   Coverage	Coverage config detected	Codecov/Coveralls
   TypeScript	tsconfig.json exists	shields.io

3. Generate README with this structure:

   # <Project Name>
   
   <badges>
   
   <One-paragraph description from manifest or inferred from code>
   
   ## Features
   
   - <Feature 1 — inferred from main exports/routes/commands>
   - <Feature 2>
   
   ## Installation
   
   <Package manager command based on project type>
   
   ## Quick Start
   
   <Minimal working example based on main entry point>
   
   ## Usage
   
   <More detailed usage with code examples>
   
   ## API Reference
   
   <If library: document main exports>
   <If CLI: document commands and flags>
   <If web app: skip or link to docs/>
   
   ## Configuration
   
   <Environment variables, config files>
   
   ## Development
   
   <How to set up for development, run tests, etc.>
   
   ## Contributing
   
   <Link to CONTRIBUTING.md if exists, otherwise brief guide>
   
   ## License
   
   <License name + link>

4. Ask user before writing:

   • Show generated README preview
   • Allow editing each section
   • Confirm before writing/overwriting

Edge cases:

• README already exists → offer to regenerate specific sections or fully replace
• Monorepo → generate root README linking to package READMEs
• No manifest files → ask user for project description
• Private/internal project → skip badges, focus on setup instructions

/readme:update (new)

Purpose: Update specific sections of an existing README without regenerating the whole thing.

Behavior:

1. Read existing README.md
2. Parse into sections (by ## headings)
3. Ask user which sections to update:
   • Installation (re-detect from manifest)
   • Usage (re-analyze entry points)
   • API Reference (re-scan exports)
   • Configuration (re-scan env vars and config files)
   • Development (re-detect scripts/commands)
   • Badges (re-detect and refresh)
   • Or "Add missing sections" — identify sections in template not in current README
4. For each selected section:
   • Regenerate from current project state
   • Show diff between old and new
   • Apply if user approves
5. Preserve all user-written content in non-selected sections
6. Output: summary of updated sections

Edge cases:

• Non-standard README structure → best-effort section matching by heading text
• README uses different heading levels → normalize to ## for main sections
• HTML content in README → preserve as-is

Hooks

None — this plugin operates through commands only.

File Manifest

File	Est. Lines	Purpose
commands/generate.md	100-120	Generate README from scratch
commands/update.md	80-100	Update specific sections
README.md	120-150	Full plugin documentation
.claude-plugin/plugin.json	15-20	Plugin manifest

README Outline

1. Overview — What docs-readme does: structured README generation and maintenance
2. Quick Start — Installation + /readme:generate
3. Commands — Table with both commands
4. README Template — Full reference of the generated structure with explanations
5. Badge Support — Table of auto-detected badges
6. Section Reference — What each README section should contain
7. Customization — How user-written sections are preserved during updates

Prerequisites

• No external tools required

Quality Checklist

• Each command .md is 60+ lines with concrete steps
• README is 100+ lines with examples and reference tables
• README template is comprehensive and production-ready
• Badge detection covers common cases
• Plugin provides clear value (consistent structure + section-level updates)