readme

name	readme
description	Assess the codebase and update the README with any new or outdated information

Update README

Assess the current state of the project and update (or create) the README to accurately reflect it.

DO NOT fabricate. Read actual files, configs, and code before writing anything.

Step 1: Assess the Project (Parallel)

Launch all four agents in a single message to build a complete picture of the codebase simultaneously. Do NOT run them sequentially.

Agent 1 — Project identity and current README:

• Read README.md (if it exists) to understand the current documented state
• Read package manifests (package.json, composer.json, Cargo.toml, build.gradle, pyproject.toml, go.mod, Gemfile, *.csproj, etc.)
• Read .claude-plugin/plugin.json, plugin.json, or similar plugin/extension manifests
• Determine: project name, description, version, language, framework, license, author
• Output the full content of the existing README (or note that none exists)

Agent 2 — Structure and features:

• List top-level directories and key files
• Identify major modules, packages, or components
• Read entry points (main.*, index.*, app.*, server.*, src/, cmd/, etc.)
• Identify APIs, CLI commands, routes, or other public interfaces
• Check for Docker/container files, CI/CD configs, deployment scripts

Agent 3 — Setup and usage:

• Check for Makefiles, Dockerfiles, docker-compose, scripts/, bin/
• Identify build commands, test commands, lint commands from package manifests and scripts
• Check for environment variables (.env.example, .env.sample, config files)
• Check for database migrations, seed files, or other required setup steps
• Read CONTRIBUTING.md, DEVELOPMENT.md, or similar if they exist

Agent 4 — Dependencies and configuration:

• Read dependency files (lock files, requirement files)
• Identify key dependencies and their purpose
• Check for config files that need documenting
• Look for pre-requisites (runtime versions, system dependencies, external services)

Wait for all four agents to complete before proceeding.

Step 2: Diff and Update

Synthesize all four agent outputs. Compare the codebase state against the existing README (from Agent 1) and identify:

• Missing: features, commands, modules, config, or setup steps that exist but aren't documented
• Stale: entries that reference files, commands, APIs, or patterns that no longer exist
• Inaccurate: descriptions that don't match the current code behavior
• Outdated: version numbers, dependency lists, or instructions that have drifted

Then edit (or create) the README following these principles:

Edit (or write) the README following these principles:

• Match the existing style. If the README uses tables, keep tables. If it uses bullet lists, keep bullet lists. Don't impose a new format on an established README.
• Preserve intentional content. Don't remove sections the author wrote manually (architecture decisions, contribution guidelines, acknowledgements) unless they're factually wrong.
• Add what's missing. New modules, commands, features, config options, setup steps.
• Remove what's gone. Entries for deleted files, deprecated features, old instructions.
• Fix what's wrong. Stale version numbers, incorrect commands, outdated descriptions.
• Keep it concise. The README should help someone get started and understand the project, not document every implementation detail.

For a new README, include at minimum:

1. Project name and one-line description
2. Prerequisites and installation
3. Usage / getting started
4. License (if determinable from manifests)

Only add additional sections if the project has content worth documenting (API reference, configuration, architecture, contributing guidelines, etc.).

Step 3: Verify (Parallel)

Launch two agents in a single message to verify the updated README:

Agent 1 — Completeness check:

• Every documented file, command, or feature actually exists in the codebase
• Every significant public interface or module has a mention
• No entries reference files or commands that don't exist on disk

Agent 2 — Accuracy check:

• Install/build/test instructions are runnable (check the actual commands exist in manifests and scripts)
• Version numbers match package manifests
• No placeholder text, TODO markers, or guessed descriptions remain

If either agent finds issues, fix them before reporting done.

Hard Rules

1. Read before writing — every description must come from reading actual code or config, not inferring from names
2. Preserve voice — match the existing README's tone and style, don't impose your own
3. No bloat — don't add sections the project doesn't need. A 20-line README for a small project is fine.
4. No lies — if you can't determine what something does after reading it, say so or omit it. Never guess.
5. Minimal diff — change only what's wrong or missing. Don't rewrite sections that are already accurate.