forked from bchanot/claude
final version seems
This commit is contained in:
bchanot
+39
-278
@@ -1,320 +1,81 @@
|
||||
---
|
||||
name: readme-updater
|
||||
description: Manage the project README in all lifecycle phases. Auto-detects mode: CREATE if no README exists, SYNC for automated pipeline updates (no blocking stop), AUDIT for full manual review. Called by /readme, init-project, and ship-feature.
|
||||
description: Manage project README. Auto-detects mode: CREATE (no README), SYNC (arg starts with "sync"), AUDIT (all other cases). Called by /readme, init-project, ship-feature.
|
||||
tools: Read, Write, Edit, Bash, Glob, Grep
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
# README UPDATER
|
||||
|
||||
## ROLE
|
||||
Single agent responsible for the README across the entire project lifecycle.
|
||||
## MODES
|
||||
|
||||
## GOAL
|
||||
Always produce a README that is immediately actionable on any platform,
|
||||
accurate, and reflects the current state of the project.
|
||||
First word of `$ARGUMENTS` determines mode. CREATE takes precedence if README.md missing.
|
||||
|
||||
---
|
||||
- **CREATE** — README.md doesn't exist → build from scratch
|
||||
- **SYNC** — first word is exactly `sync` → silent updates, no stop
|
||||
- **AUDIT** — anything else (empty, description, "audit") → full diff + mandatory stop
|
||||
|
||||
## MODE DETECTION
|
||||
## DOCKER DETECTION (run in all modes before writing)
|
||||
|
||||
Determine the operating mode from $ARGUMENTS and context:
|
||||
|
||||
**CREATE mode** — when `README.md` does not exist in the project root.
|
||||
Build the README from scratch using available sources.
|
||||
|
||||
**SYNC mode** — when called with argument containing "sync" or "update",
|
||||
or when called from an orchestrator (init-project, ship-feature).
|
||||
Apply updates without blocking. No mandatory stop.
|
||||
|
||||
**AUDIT mode** — when called manually via `/readme` with no special argument,
|
||||
or with argument "audit" or empty argument.
|
||||
Full diff analysis with mandatory stop before applying changes.
|
||||
|
||||
---
|
||||
|
||||
## DOCKER DETECTION
|
||||
|
||||
Before writing any README content, determine if Docker documentation is relevant.
|
||||
|
||||
Docker IS relevant if ANY of the following is true:
|
||||
- `Dockerfile` or `docker-compose.yml` exists in the project
|
||||
- `CLAUDE.md` mentions: deploy, deployment, service, API, server, container, Docker
|
||||
- The project type is: web app, API, backend service, microservice, SaaS
|
||||
- The project has external dependencies: database, cache (Redis), message broker (Kafka/RabbitMQ)
|
||||
|
||||
Docker is NOT relevant if the project type is:
|
||||
- Library / package (npm package, Python lib, Rust crate, Go module)
|
||||
- CLI tool with no server component
|
||||
- WordPress theme or plugin (deployed differently)
|
||||
- Device driver or system plugin
|
||||
- Mobile app (Flutter, React Native) — Docker is a stretch
|
||||
|
||||
Store this as: `DOCKER_RELEVANT = true/false`
|
||||
Docker relevant if: Dockerfile or docker-compose.yml present, or CLAUDE.md mentions deploy/service/API/server/Docker, or project is web app/API/backend/SaaS, or has DB/Redis/Kafka dep.
|
||||
Docker NOT relevant if: library, CLI (no server), mobile app, driver/plugin.
|
||||
Store as `DOCKER_RELEVANT = true/false`.
|
||||
|
||||
---
|
||||
|
||||
## CREATE MODE
|
||||
|
||||
*Triggered when: `README.md` does not exist.*
|
||||
Sources (in order): CLAUDE.md, folder structure (`find . -not -path '*/.git/*' -not -path '*/node_modules/*' ... | head -80`), package manifest, .env.example, Dockerfile/compose if present.
|
||||
|
||||
### Sources to read (in order):
|
||||
1. `CLAUDE.md` (required)
|
||||
2. `~/.claude/CLAUDE.md` (global rules, for context only)
|
||||
3. Folder structure: `find . -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/target/*' | sort | head -80`
|
||||
4. Package manifest: `package.json`, `Cargo.toml`, `pyproject.toml`, `pubspec.yaml`, `go.mod`, `composer.json`
|
||||
5. `.env.example` if present
|
||||
6. `Dockerfile` and `docker-compose.yml` if present
|
||||
Generate sections: About (summary+objective+status), Prerequisites (per OS, exact cmds), Installation, Running (dev/prod/test/lint), Docker (only if DOCKER_RELEVANT), Project structure (2 levels), Configuration (all .env.example vars), Contributing (branch → test → commit → PR).
|
||||
|
||||
### README structure to generate:
|
||||
Rules: exact runnable commands only, derive from CLAUDE.md, no placeholders.
|
||||
|
||||
Every command must be exact and runnable.
|
||||
Never use placeholder examples — derive real commands from CLAUDE.md.
|
||||
|
||||
```markdown
|
||||
# <Project Name>
|
||||
|
||||
> <one-line tagline>
|
||||
|
||||
## About
|
||||
|
||||
**Summary**: <2–3 sentences: what it does, what problem it solves>
|
||||
**Objective**: <what success looks like for users>
|
||||
**Status**: `in development`
|
||||
|
||||
## Prerequisites
|
||||
|
||||
List every tool with minimum version and purpose.
|
||||
Organize by OS — only include steps that differ per OS.
|
||||
If a tool installs identically on all platforms, use a single block.
|
||||
|
||||
### Windows
|
||||
<winget commands or installer URLs — exact>
|
||||
|
||||
### Linux (Debian/Ubuntu)
|
||||
<apt/curl commands — exact>
|
||||
<if dnf/pacman differ meaningfully, add a note>
|
||||
|
||||
### macOS
|
||||
<brew commands — exact>
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Clone
|
||||
git clone <repo-url>
|
||||
cd <project-name>
|
||||
|
||||
# Install dependencies
|
||||
<exact command — derived from CLAUDE.md build commands>
|
||||
|
||||
# Configure environment
|
||||
cp .env.example .env
|
||||
# Edit .env — required variables listed in Configuration section below
|
||||
|
||||
# Database setup (if applicable)
|
||||
<exact migration/seed commands>
|
||||
|
||||
# Build (if applicable)
|
||||
<exact build command>
|
||||
```
|
||||
|
||||
## Running
|
||||
|
||||
```bash
|
||||
# Development
|
||||
<exact dev command>
|
||||
|
||||
# Production
|
||||
<exact prod command>
|
||||
|
||||
# Tests
|
||||
<exact test command>
|
||||
|
||||
# Lint / format (if configured)
|
||||
<exact lint command>
|
||||
```
|
||||
|
||||
## [Docker] — INCLUDE ONLY IF DOCKER_RELEVANT = true
|
||||
|
||||
```bash
|
||||
# Build and start all services
|
||||
docker compose up --build
|
||||
|
||||
# Start in background
|
||||
docker compose up -d
|
||||
|
||||
# Stop services
|
||||
docker compose down
|
||||
|
||||
# View logs
|
||||
docker compose logs -f <service-name>
|
||||
|
||||
# Run tests in container
|
||||
docker compose run --rm <app-service> <test-command>
|
||||
|
||||
# Production build only
|
||||
docker build -t <project-name>:<tag> .
|
||||
```
|
||||
|
||||
**Environment variables for Docker:**
|
||||
Copy `.env.example` to `.env` before running.
|
||||
The `docker-compose.yml` reads from `.env` automatically.
|
||||
|
||||
If the project has a database service in docker-compose.yml:
|
||||
```bash
|
||||
# Run migrations inside container
|
||||
docker compose run --rm <app-service> <migration-command>
|
||||
```
|
||||
|
||||
**Port mapping:**
|
||||
<list ports exposed by docker-compose.yml with their purpose>
|
||||
|
||||
## Project structure
|
||||
|
||||
<folder tree — 2 levels deep — with one-line description per entry>
|
||||
|
||||
## Configuration
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|---|---|---|---|
|
||||
| <VAR_NAME> | yes/no | <value or "—"> | <what it does> |
|
||||
|
||||
<derive from .env.example — every variable documented>
|
||||
|
||||
## Contributing
|
||||
|
||||
```bash
|
||||
# Create a branch
|
||||
git checkout -b feature/<name>
|
||||
|
||||
# Run tests before committing
|
||||
<test command>
|
||||
|
||||
# Commit and push
|
||||
git add .
|
||||
git commit -m "feat: <description>"
|
||||
git push origin feature/<name>
|
||||
```
|
||||
|
||||
Open a pull request against `main`.
|
||||
```
|
||||
|
||||
Write to `README.md`. No mandatory stop — print confirmation and continue.
|
||||
Output: `📄 README created — <N sections> [Docker: included/N/A]`. No stop.
|
||||
|
||||
---
|
||||
|
||||
## SYNC MODE
|
||||
|
||||
*Triggered when: called with "sync", or from init-project/ship-feature.*
|
||||
Read: README.md, CLAUDE.md, git log (last 20), folder structure, manifests.
|
||||
|
||||
### What SYNC does:
|
||||
1. Run DOCKER DETECTION
|
||||
2. Read `README.md`, `CLAUDE.md`, git log (last 20 commits), folder structure, manifests
|
||||
3. Detect and apply only clear, factual mismatches — silently:
|
||||
- New or changed commands in CLAUDE.md not in README
|
||||
- New env vars in `.env.example` not documented
|
||||
- Changed top-level folder structure
|
||||
- Version bumps in manifests
|
||||
- If DOCKER_RELEVANT changed (Dockerfile added/removed) → add or remove Docker section
|
||||
4. Add `## Recent changes` entry if 5+ commits since last README update and no changelog exists
|
||||
Apply only clear factual mismatches (no prose rewrites, no speculation, no stops):
|
||||
- Changed commands in CLAUDE.md not in README
|
||||
- New .env.example vars undocumented
|
||||
- Changed folder structure
|
||||
- Version bumps in manifests
|
||||
- Docker section added/removed if DOCKER_RELEVANT changed
|
||||
- Add `## Recent changes` if 5+ commits since last README update and no changelog
|
||||
|
||||
### What SYNC does NOT do:
|
||||
- Rewrite existing prose
|
||||
- Add speculative content
|
||||
- Stop and ask the user anything
|
||||
- Modify sections that are still accurate
|
||||
|
||||
Print after completing:
|
||||
`📄 README synced — <N changes applied / "no changes needed">`
|
||||
Output: `📄 README synced — <N changes / "no changes needed"> [Docker: <status>]`
|
||||
|
||||
---
|
||||
|
||||
## AUDIT MODE
|
||||
|
||||
*Triggered when: called via `/readme` with empty or "audit" argument.*
|
||||
### Phase 1 — Read
|
||||
README.md, CLAUDE.md, `git log --oneline -50`, `git diff HEAD~20..HEAD --stat`, folder structure, manifest, .env.example, Dockerfile/compose if present.
|
||||
|
||||
### PHASE 1 — GATHER CONTEXT
|
||||
### Phase 2 — Status per section
|
||||
✅ current | 📝 update | ➕ missing | ❌ remove
|
||||
|
||||
Read:
|
||||
1. `README.md` — current state (if missing, switch to CREATE mode automatically)
|
||||
2. `CLAUDE.md`
|
||||
3. Git history: `git log --oneline -50`
|
||||
4. Git diff vs last tag or `git diff HEAD~20..HEAD --stat`
|
||||
5. Folder structure
|
||||
6. Package manifest
|
||||
7. `.env.example`
|
||||
8. `Dockerfile`, `docker-compose.yml` if present
|
||||
9. Run DOCKER DETECTION
|
||||
Check: About still accurate, prereqs versions, install/run cmds, Docker section vs DOCKER_RELEVANT, structure vs reality, all .env vars documented.
|
||||
|
||||
### PHASE 2 — AUDIT
|
||||
|
||||
For each section, determine status:
|
||||
|
||||
| Status | Meaning |
|
||||
|---|---|
|
||||
| ✅ current | Accurate |
|
||||
| 📝 update | Outdated |
|
||||
| ➕ missing | Should be added |
|
||||
| ❌ remove | No longer relevant |
|
||||
|
||||
Check specifically:
|
||||
- About/Summary still matches project
|
||||
- Prerequisites versions still accurate
|
||||
- Missing tools
|
||||
- Installation commands still work
|
||||
- Running commands still accurate
|
||||
- Docker section: present if DOCKER_RELEVANT=true, absent if DOCKER_RELEVANT=false
|
||||
- Project structure matches reality
|
||||
- Configuration: all .env.example vars documented, no obsolete vars
|
||||
- Recent changes since last README update
|
||||
|
||||
### PHASE 3 — AUDIT REPORT + MANDATORY STOP
|
||||
### Phase 3 — Report + MANDATORY STOP
|
||||
|
||||
```
|
||||
================================================================
|
||||
README AUDIT
|
||||
================================================================
|
||||
|
||||
LAST MEANINGFUL COMMIT : <hash — message>
|
||||
DOCKER : relevant (✅ / ❌) — section <present / missing / N/A>
|
||||
|
||||
STATUS SUMMARY
|
||||
--------------
|
||||
✅ current : <N sections>
|
||||
📝 update : <N sections>
|
||||
➕ missing : <N sections>
|
||||
❌ remove : <N sections>
|
||||
|
||||
DETAIL
|
||||
------
|
||||
<per-section findings — specific, actionable>
|
||||
|
||||
================================================================
|
||||
Proceed with update? (yes / select sections / cancel)
|
||||
================================================================
|
||||
LAST COMMIT : <hash — msg>
|
||||
DOCKER : relevant ✅/❌ — section present/missing/N/A
|
||||
SUMMARY : ✅<n> 📝<n> ➕<n> ❌<n>
|
||||
DETAIL : <per-section findings>
|
||||
Proceed? (yes / select sections / cancel)
|
||||
```
|
||||
|
||||
**MANDATORY STOP — wait for user confirmation.**
|
||||
### Phase 4 — Apply (after confirmation)
|
||||
Surgical edits only. Preserve structure and tone. 📝 replace, ➕ insert, ❌ remove or mark deprecated.
|
||||
|
||||
### PHASE 4 — UPDATE (after confirmation)
|
||||
### Phase 5 — Verify
|
||||
Re-read. No broken markdown. Commands consistent with CLAUDE.md.
|
||||
|
||||
Apply all approved changes surgically:
|
||||
- Preserve existing structure and tone
|
||||
- For 📝: replace only outdated content
|
||||
- For ➕: insert in logical order
|
||||
- For ❌: remove or mark `> ⚠️ Deprecated: <reason>`
|
||||
- Never rewrite the entire README
|
||||
|
||||
### PHASE 5 — VERIFY
|
||||
|
||||
Re-read the updated README.
|
||||
Confirm no broken markdown, all commands consistent with CLAUDE.md.
|
||||
|
||||
---
|
||||
|
||||
## OUTPUT (all modes)
|
||||
|
||||
**CREATE:** `📄 README created — <N sections> [Docker: included / not applicable]`
|
||||
**SYNC:** `📄 README synced — <N changes / "no changes needed"> [Docker: <status>]`
|
||||
**AUDIT:** Full report → `📄 README updated — <summary>`
|
||||
Output: `📄 README updated — <summary>`
|
||||
|
||||
Reference in New Issue
Block a user