Skip to content

getting-started.md

Latest commit

 

History

History
164 lines (113 loc) · 5.45 KB

getting-started.md

File metadata and controls

164 lines (113 loc) · 5.45 KB
title Getting Started with PitchDocs
description Install PitchDocs, generate your first README, and explore all 16 commands.
type how-to
difficulty beginner
time_to_complete 5 minutes
last_verified 2.1.0
related
guides/workflows.md
guides/command-reference.md
guides/customising-output.md
order 1

Getting Started with PitchDocs

Summary: Install PitchDocs, generate your first README, and explore all 16 commands.

Time to Hello World: Under 60 seconds for your first README. Full walkthrough below: ~5 minutes.

Prerequisites

Using a different AI tool? PitchDocs also works with Codex CLI, Cursor, Windsurf, Cline, Gemini CLI, Aider, and Goose. See Use with Other AI Tools for setup instructions.

1. Install PitchDocs

Open Claude Code in your terminal and run:

# Add the LBA plugin marketplace (once per machine)
/plugin marketplace add littlebearapps/lba-plugins

# Install PitchDocs
/plugin install pitchdocs@lba-plugins

Verify it worked: The skills and commands are loaded automatically. You should see PitchDocs skills available when you start a new session.

Note: When installed as a plugin, all commands use the pitchdocs: prefix (e.g., /pitchdocs:readme). The short form /readme only works inside the pitchdocs source directory.

2. Generate Your First README

Navigate to the project you want to document, then run:

/pitchdocs:readme

PitchDocs will:

  1. Scan your codebase (manifest files, project structure, git history)
  2. Extract features with file-level evidence across 10 signal categories
  3. Translate features into benefit-driven language
  4. Generate a README.md with a hero section, quick start, features table, and proper badges

Tip: If a README.md already exists, PitchDocs reads it first and improves it rather than overwriting from scratch.

3. Audit Your Documentation

Check what other docs your project needs:

/pitchdocs:docs-audit

This scans your repo against a 20+ file checklist across 3 priority tiers and reports what's missing. To auto-generate everything that's missing in one go:

/pitchdocs:docs-audit fix

4. Extract Features

See what PitchDocs detects in your codebase:

# Full feature inventory with evidence
/pitchdocs:features

# Output as a benefits table for your README
/pitchdocs:features table

# Output as emoji+bold+em-dash bullets
/pitchdocs:features bullets

# Extract user benefits for a "Why?" section (auto-scan or conversational)
/pitchdocs:features benefits

# Audit: compare what's documented vs what's in the code
/pitchdocs:features audit

5. Generate Individual Docs

Use any command on its own for specific doc types:

/pitchdocs:changelog          # CHANGELOG.md from git history
/pitchdocs:roadmap            # ROADMAP.md from GitHub milestones
/pitchdocs:user-guide         # User guides in docs/guides/
/pitchdocs:llms-txt           # llms.txt for AI discoverability
/pitchdocs:docs-verify        # Validate links, freshness, and consistency
/pitchdocs:launch             # Dev.to articles, HN posts, Reddit posts, Twitter threads

6. Verify Everything

Before shipping your docs, run the verification suite:

/pitchdocs:docs-verify

This checks for:

  • Broken internal and external links (with case-sensitivity and fragment validation)
  • Stale content (files not updated in 90+ days)
  • llms.txt sync (all referenced files exist)
  • Heading hierarchy issues (no level skipping)
  • Badge URL validity
  • Security issues (leaked credentials, internal paths, internal hostnames)
  • AI context health (lightweight presence and staleness check — install ContextDocs for full scoring)
  • Quality score (0–100 across 6 dimensions with A–F grade bands)
  • Token budget compliance (skill files within size targets)

7. AI Context Files and Context Guard (Optional)

For AI context file management (AGENTS.md, CLAUDE.md, .cursorrules, etc.) and Context Guard hooks, install ContextDocs separately:

/plugin install contextdocs@lba-plugins
/contextdocs:ai-context init          # Bootstrap all 7 context file types
/contextdocs:context-guard install    # Install drift detection hooks (Claude Code only)

What's Next?

  • Manage AI context files — Install ContextDocs for AI context file generation, drift detection, and MEMORY.md promotion.
  • Improve your README further — Run /pitchdocs:readme again with specific focus areas (e.g., /pitchdocs:readme focus on the comparison table)
  • Check your quality score — Run /pitchdocs:docs-verify score to get a numeric rating and actionable suggestions for improvement
  • Set up CI verification — The /pitchdocs:docs-verify command outputs CI-friendly results for GitHub Actions
  • Launch your project — Run /pitchdocs:launch to generate Dev.to articles, Hacker News posts, and awesome list submissions
  • Explore skills — Each command loads specialised reference knowledge. See the Available Skills table for the full inventory.

Need help? See SUPPORT.md for getting help, common questions, and contact details.
⚡