---
description: Create or update comprehensive README.md files for any project
mode: subagent
tools:
  read: true
  write: true
  edit: true
  bash: true
  glob: true
  grep: true
  webfetch: false
  task: true
---

<!-- SPDX-License-Identifier: MIT -->
<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->

# README Create/Update Workflow

<!-- AI-CONTEXT-START -->

## Quick Reference

- **Trigger**: `/readme` or `@readme-create-update`
- **Output**: `README.md` in project root (or specified location)
- **Command doc**: `scripts/commands/readme.md` (section mapping, argument parsing, examples)

**Three Purposes**: Local Development · Understanding the System · Production Deployment

**Core Principles**:

- Explore codebase BEFORE writing (detect stack, deployment, structure)
- Prioritize maintainability over exhaustive detail
- Avoid staleness: no hardcoded counts, version numbers, or full file listings
- Use generated `docs/metrics` artifacts for LOC, language, and dependency badges; use approximate prose counts (`~15 agents`, `100+ scripts`) elsewhere

**Dynamic Counts (aidevops repo)**:

```bash
~/.aidevops/agents/scripts/readme-helper.sh check    # check staleness
~/.aidevops/agents/scripts/readme-helper.sh counts   # current counts
~/.aidevops/agents/scripts/readme-helper.sh update --apply  # apply updates
```

**Repository Metrics (all repos)**:

```bash
~/.aidevops/agents/scripts/repo-metrics-helper.sh generate
# or: aidevops metrics generate
```

This writes `docs/metrics/repo-metrics.json`, `docs/metrics/repo-metrics.md`,
and local SVG badges for lines of code, languages, and dependencies. README
badge sections should reference those relative files instead of remote LOC or
GitHub language badge services.

**Commands**:

```bash
/readme                              # full create/update
/readme --sections "installation,usage"  # update specific sections only
```

Use `--sections` after adding a feature, changing install steps, or when full regeneration would lose custom content.

<!-- AI-CONTEXT-END -->

## Before Writing

### Step 0: Load voice and style guidance when requested

If the user asks to humanise copy, match their writing style, improve tone, reduce AI writing patterns, make prose sound more natural, or rewrite marketing/introductory copy, read `content/humanise.md` before drafting. Use it alongside this README workflow so wording changes keep project facts accurate while avoiding generic AI phrasing.

### Step 1: Detect Project Type and Deployment

**CRITICAL**: Explore before writing. Never assume — verify.

| File | Project Type | | File | Platform |
|------|--------------|-|------|----------|
| `package.json` | Node.js/JS/TS | | `Dockerfile`, `docker-compose.yml` | Docker |
| `Cargo.toml` | Rust | | `fly.toml` | Fly.io |
| `go.mod` | Go | | `vercel.json`, `.vercel/` | Vercel |
| `requirements.txt`, `pyproject.toml` | Python | | `netlify.toml` | Netlify |
| `Gemfile` | Ruby | | `render.yaml` | Render |
| `composer.json` | PHP | | `railway.json` | Railway |
| `*.sln`, `*.csproj` | .NET | | `serverless.yml` | Serverless |
| `setup.sh`, `Makefile` only | Shell/scripts | | `k8s/`, `*.tf` | K8s / Terraform |

### Step 2: Check Existing README

If README.md exists: read fully, identify accurate vs outdated sections, preserve custom content and structure, update only what needs updating. Don't reorganize unless requested.

### Step 3: Ask Only If Critical

Only ask if you cannot determine: what the project does, specific deployment credentials/URLs, or business context. Otherwise proceed.

## README Structure (Recommended Section Order)

1. **Title & Description** — what it is, who it's for (2-3 sentences max)
2. **Badges** (optional) — build/CI, code quality, version, license (only if configured)
3. **Key Features** — bullet list of capabilities
4. **Quick Start** — fastest path to running
5. **Installation** — detailed setup options
6. **Usage** — common commands and examples
7. **Architecture** (complex projects) — high-level structure only, max 2-3 levels deep
8. **Configuration** — environment variables table, point to `.env.example`
9. **Development** — contributing, testing, building
10. **Deployment** — production setup (platform-specific)
11. **Troubleshooting** — common issues with cause + fix commands
12. **License & Credits**

## Maintainability Guidelines

### Staleness Patterns to Avoid

| Pattern | Problem | Alternative |
|---------|---------|-------------|
| `"32 services supported"` | Count changes | `"30+ services"` or omit |
| `"Version 2.5.1"` | Outdated quickly | Badge (auto-updates) or omit |
| `"Last updated: 2024-01-15"` | Always wrong | Rely on git history |
| Full file listings | Files change constantly | High-level structure only |
| Inline code examples from source | Drift from actual code | Point to source files |
| Remote LOC/language badges | Third-party badge APIs fail or lag | `docs/metrics/badges/*.svg` generated by `repo-metrics-helper.sh` |
| Hardcoded URLs | URLs change | Relative links where possible |

### Key Rules

- **Point to source, don't duplicate**: `See src/config/defaults.ts for all options` > listing every option inline
- **AI-CONTEXT blocks**: Place `<!-- AI-CONTEXT-START -->` / `<!-- AI-CONTEXT-END -->` around Quick Reference sections for agent consumption
- **Collapsible sections**: Use `<details open>` for detailed content most readers can skip. Default open — users collapse what they've read. Don't hide important content by default.

## Platform-Specific Guidance

| Platform | Key Points |
|----------|-----------|
| **Node.js** | Document `engines` from package.json; list key scripts; note package manager; TypeScript setup if applicable |
| **Python** | Specify Python version; document venv setup; include pip/poetry/uv options; note system deps |
| **Docker** | Include both Docker and non-Docker paths; document env vars; provide docker-compose examples; note volume mounts |
| **Monorepo** | Document workspace structure at high level; explain package relationships; provide per-package commands |

## Updating Existing READMEs

When using `/readme --sections`: read entire existing README first, preserve structure and custom content, update only specified sections, maintain consistent style. See `scripts/commands/readme.md` for section mapping table.

## Quality Checklist

Before finalizing, verify:

- Can someone clone and run in under 5 minutes?
- All commands copy-pasteable?
- Architecture section high-level enough to stay accurate?
- No hardcoded counts or versions that will drift?
- Code examples point to source files where possible?
- Troubleshooting covers common issues?
- Environment variables documented with examples?
- License clearly stated?

## Related

- `workflows/changelog.md` — Changelog updates
- `workflows/version-bump.md` — Version bumping
- `workflows/wiki-update.md` — Wiki documentation
- `scripts/commands/full-loop.md` — Full development loop
- `scripts/commands/readme.md` — `/readme` command (arguments, section mapping, examples)
