generating-project-docs

Generating Project Documentation

Overview

This plugin's documentation describes a live system whose surface (skills, agents, config schema, CLI) keeps changing. Generated docs go stale fast.

Core principle: Derive every fact from the live repository. Preserve the existing document's evolved structure. Never regress to a generic template.

If you cannot point at a file or command that justifies a sentence, do not write it.

When to Use

• Refreshing README.md after new skills, agents, or features land
• Fixing documentation drift (counts, structure, CLI output, runtime claims)
• Updating ARCHITECTURE.md or STRUCTURE.md when the codebase layout changes
• Adding or refreshing a scoped section (e.g. only the "Quick Install" block)

When NOT to Use

• Writing planning docs (docs/plans/, docs/brainstorms/) — those follow their own templates
• Authoring skill or agent files — those have their own format rules

Arguments

$ARGUMENTS

• Empty or readme — Update README.md (default)
• architecture — Update ARCHITECTURE.md
• structure — Update STRUCTURE.md
• all — Update all three docs
• <section-name> — Update only that named section within the target doc (e.g. skills, agents, cli)

For scoped updates: read the current document, locate the section by heading, replace only that section's content. Preserve surrounding structure exactly.

Pre-Generation Inventory

Before writing anything, gather these from the live repo:

Source	What to extract
package.json	name, version, description, scripts, repository URL
bun src/cli.ts list skills 2>/dev/null	exact skill count and names
bun src/cli.ts list agents 2>/dev/null	exact agent count, names, categories
bun src/cli.ts list commands 2>/dev/null	command inventory
find skills -name SKILL.md -exec head -6 {} \; -exec echo --- \;	skill frontmatter (name, description)
find agents -maxdepth 2 -name '*.md' -exec head -4 {} \; -exec echo --- \;	agent frontmatter (name, description), category from path
Current target doc	existing structure, badges, nav links, voice
git log --oneline -15	recent change context