jimweller/documenter-plugin

Documentation Creation

Write markdown content based on the current conversation context and folder contents.

README is current state specification for a human user, not a changelog, not a decision log, not historical record. Never record historical information or choices made, only the specification as it stands at the time of writing the README.

Scope

Find all README.md files in the project and update each. Folder contents are at the README's level and below (siblings and subfolders), never above (parents). Pay attention to subfolder layers, scope and bounded contexts. Do not leak concepts between documents at different layers. Each README covers its own directory level and below, never parent concerns.

If the user provided specific guidance or focus areas, apply that context when deciding what to emphasize in the documentation.

Gather Context

Never run git directly. The baseline script that ships with this plugin covers everything this skill needs from git. Run each command from the repository root and write the script's full path every time, because shell variables do not persist between commands.

Start with the plan. It finds every README, adds a root README when none exists, resolves each README's baseline, lists what changed since it, and says what to do with each README. When the user's guidance names directories to focus on, pass them after readme. Otherwise pass nothing.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" plan readme [<focus-dir>...]

The plan prints one block per action.

• ## update names a baseline, a scope, and the README, followed by the commits, diff stat, and status since that baseline. Bring the README up to date. A README the changes do not affect keeps its content.
• ## new lists READMEs to write from the current code. They need no history.
• ## unchanged and ## outside the focus list READMEs to leave exactly as they are.

head none means the repository has no commits. Every README is new.

For an update block, count the files in its stat. At more than 20, skip the full diff and read the changed files directly. At 20 or fewer, read the diff. Untracked files, marked ??, appear in no diff, so read them directly either way. The scope can be the block's scope or a single file, because it is a git pathspec.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" diff <sha> <scope>

Then, for each README to update or write, scoped to its directory:

1. Read current README (if exists)

2. Explore codebase at that directory level and below

3. Review conversation history for relevant decisions, changes, or lessons learned

4. Use the changes and conversation context to identify what sections need updating. Verify code against docs and docs against code. When the code drops a function, flag, or module, grep every README for its name, then reread each hit and each README's overview for a plain-language description of the same thing.

   grep -rn '<dropped name>' <dir>/README.md
   

Never include the marker line in text you write or edit. finish adds it after writing. When editing a README that already ends with one, leave that line alone.

If nothing changed that warrants a README update, say so and move on. finish still applies.

README.md Outline

Section order and content for a README.md. Every section is filled from the target project. Omit a section the project has nothing for.

• # Title and an overview of no more than five sentences
• Optional image or video
• ## Architecture - components as a bullet list, each with its purpose
• ## Prerequisites - accounts, keys, credentials, tools, runtimes, CLIs, each with the reason it is needed
• ## Project Structure - folders only, no files, each with a one-line purpose
• ## Installation - the commands that install it
• ## Usage - the commands that run it
• ## Testing - omitted when the project has no tests

Target under 500 lines. Split a longer README by moving detail into a nested README beside the code it describes.

Shape

# Title

Brief overview. No more than five sentences.

<!-- OPTIONAL IMAGE OR VIDEO HIGHLIGHT -->
<img src="demo.png" alt="Demo" width="800"/>

## Architecture

High level components and purpose

- Component - purpose
- Component - purpose

## Prerequisites

- Prerequisite - description and reason (accounts, keys, credentials, tools, runtimes, CLIs)

## Project Structure

Show folder structure. Don't include files.

```text
project/
├── src/
│   ├── component-a/     # purpose - see src/component-a/README.md
│   └── component-b/     # purpose - see src/component-b/README.md
├── scripts/             # purpose
└── tests/               # purpose
```

## Installation

```bash
# how the project is installed
<install command>
```

## Usage

```bash
# how the project is run
<run command>
```

## Testing

```bash
# how the tests are run
<test command>
```

Finish

Run finish, every time, including a run that wrote nothing. plan left a plan file behind and only finish removes it, so a run that skips finish leaves state for the next one to trip over.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" finish readme

It stamps every README the plan marked new or update, and every README created since the plan, with the HEAD the plan checked. The stamp is a marker line at the end of the README, an HTML comment naming that commit. finish leaves unchanged READMEs and READMEs outside the focus alone, and stamps nothing when the repository has no commits. Exit 4 means a planned README is missing. Write it and run finish again.

• Never call stamp directly and never write or edit the marker line by hand. finish writes it.
• The marker is metadata. The rule against recording history does not apply to it.