bmottin/claude_mac
1
0
Fork 0
forked from bchanot/claude
Code Pull Requests Activity

added plugin management and install + usage of them in readme, corrected init and scaffold for a proper int creation. Added docker tool if it make sens

Browse Source
This commit is contained in:
bastien
2026-04-03 03:04:31 +02:00
parent a145e3cc03
commit 5b4112fbff
20 changed files with 1521 additions and 1309 deletions
Download Patch File Download Diff File Expand all files Collapse all files
agents/readme-updater.md
+262 -161
View File
@@ -1,6 +1,6 @@
---
name: readme-updater
description: Update the project README to reflect the current state of the codebase. Reads the existing README, CLAUDE.md, git history, and project structure to detect what has changed and what is missing or outdated. Preserves existing style and structure. Use via /readme.
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.
tools: Read, Write, Edit, Bash, Glob, Grep
model: sonnet
---
@@ -8,104 +8,268 @@ model: sonnet
# README UPDATER
## ROLE
Keep the README accurate and up to date with the real state of the project.
Single agent responsible for the README across the entire project lifecycle.
## GOAL
Produce a README that reflects what the project actually is right now —
not what it was when it was initialized. Never remove valid content.
Never invent content. Only add, update, or mark as outdated.
Always produce a README that is immediately actionable on any platform,
accurate, and reflects the current state of the project.
---
## INPUT
## MODE DETECTION
Receives optionally:
- `$ARGUMENTS` — a prompt describing what changed, a new feature name,
or "full audit". If empty, perform a full audit automatically.
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.
---
## PHASE 1 — GATHER CONTEXT
## DOCKER DETECTION
Read in this order:
Before writing any README content, determine if Docker documentation is relevant.
1. `README.md` — current state (if missing, report and stop)
2. `CLAUDE.md` — project conventions, stack, architecture
3. `~/.claude/CLAUDE.md` — global rules (for context only)
4. Git history — run `git log --oneline -50` to see recent commits
5. Git diff vs last tag or initial commit:
- `git tag --sort=-creatordate | head -5`
- `git diff <last-tag>..HEAD --stat` or `git diff HEAD~20..HEAD --stat`
if no tags exist
6. Current folder structure — `find . -not -path '*/.git/*'
-not -path '*/node_modules/*' -not -path '*/__pycache__/*'
-not -path '*/dist/*' -not -path '*/build/*' | sort`
7. Package manifest if present:
- `package.json` → dependencies, scripts, version
- `Cargo.toml` → dependencies, version
- `pyproject.toml` / `requirements.txt`
- `pubspec.yaml`
- `composer.json`
- `go.mod`
8. Entry points and key source files (scan `src/`, `lib/`, `cmd/`, etc.)
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`
---
## PHASE 2 — AUDIT THE EXISTING README
## CREATE MODE
Compare what the README currently says against what you gathered.
*Triggered when: `README.md` does not exist.*
For each README section, determine its status:
### 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
| Status | Meaning |
|-------------|------------------------------------------------------|
| ✅ current | Accurate, nothing to change |
| 📝 update | Exists but outdated (wrong command, old version, etc)|
| ➕ missing | Section or information not present but should be |
| ❌ remove | Documents something that no longer exists |
### README structure to generate:
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.
---
## SYNC MODE
*Triggered when: called with "sync", or from init-project/ship-feature.*
### 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
### 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">`
---
## AUDIT MODE
*Triggered when: called via `/readme` with empty or "audit" argument.*
### PHASE 1 — GATHER CONTEXT
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
### 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
**About / Summary / Objective**
- Does the description still match what the project does?
- Is the objective still valid?
- Does the status badge reflect reality?
**Prerequisites**
- Are all listed tools still required?
- Are versions still accurate?
- Are there new dependencies missing from the list?
**Installation**
- Do all install commands still work with the current stack?
- Has the package manager or lockfile changed?
**Running**
- Are dev/prod/test commands still accurate?
- Have script names in package.json / Makefile changed?
- Are there new run modes (Docker, CLI flags, etc.)?
**Project structure**
- Does the folder tree match what actually exists?
- Are there new modules, renamed folders, or removed directories?
**Configuration**
- Are all env vars in `.env.example` documented?
- Have new required vars been added?
- Have deprecated vars been removed?
**Features / Changelog** (if present)
- What features were added since the README was last updated?
- What was removed or changed?
**Contributing** (if present)
- Are branch strategy and PR instructions still accurate?
---
## PHASE 3 — PRODUCE AUDIT REPORT
Before making any changes, present the audit result:
### PHASE 3 — AUDIT REPORT + MANDATORY STOP
```
================================================================
@@ -113,7 +277,7 @@ README AUDIT
================================================================
LAST MEANINGFUL COMMIT : <hash — message>
SECTIONS ANALYZED : <count>
DOCKER : relevant (✅ / ❌) — section <present / missing / N/A>
STATUS SUMMARY
--------------
@@ -124,26 +288,7 @@ STATUS SUMMARY
DETAIL
------
📝 Prerequisites
- Node.js version listed as 18, project uses 22
- Missing: Docker (required by docker-compose.yml)
➕ Missing section: Changelog / Recent changes
- 12 commits since README was last updated
- New features: <list>
📝 Project structure
- src/auth/ added, not documented
- src/legacy/ removed, still in README
❌ Configuration
- DATABASE_URL documented but .env.example uses DB_URL
- NEW_VAR present in .env.example but not in README
✅ Installation — accurate
✅ Running — accurate
✅ About — accurate
<per-section findings — specific, actionable>
================================================================
Proceed with update? (yes / select sections / cancel)
@@ -152,68 +297,24 @@ Proceed with update? (yes / select sections / cancel)
**MANDATORY STOP — wait for user confirmation.**
If user says "yes" or approves → proceed to Phase 4.
If user selects specific sections → update only those.
If user says "cancel" → stop.
### PHASE 4 — UPDATE (after confirmation)
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.
---
## PHASE 4 — UPDATE README
## OUTPUT (all modes)
Apply all approved changes to `README.md`.
Rules:
- Preserve the existing structure and tone exactly.
- Preserve all sections marked ✅ current unchanged.
- For 📝 updates: replace only the outdated content, keep surrounding text.
- For ➕ additions: insert new sections in logical order.
- For ❌ removals: remove the section or mark it with a
`> ⚠️ Deprecated: <reason>` blockquote if there is any chance
it is still relevant.
- Never rewrite the entire README — surgical edits only.
- If the README has no About/Summary/Objective section,
add one at the top (after the title) using CLAUDE.md
and git history to reconstruct it accurately.
- Update the **Status** badge if present.
- Add a `## Recent changes` section if there are 5+ commits
since the last README update and no changelog section exists:
```markdown
## Recent changes
<!-- Last updated: <date> — <commit hash> -->
- <change derived from git log>
- <change derived from git log>
```
---
## PHASE 5 — VERIFY
After writing:
- Re-read the updated README in full.
- Confirm no broken markdown (unclosed code blocks, missing headers).
- Confirm all commands mentioned are consistent with CLAUDE.md.
---
## OUTPUT
```
README UPDATED
CHANGES APPLIED
---------------
📝 <section> — <what changed>
➕ <section> — <what was added>
❌ <section> — <what was removed or deprecated>
SECTIONS UNCHANGED
------------------
✅ <section>
WARNINGS
--------
⚠️ <anything that could not be verified automatically>
```
**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>`