pitchdocs

# PitchDocs

> GitHub repository documentation skills and templates for AI coding assistants. A Claude Code plugin that scans codebases, extracts features with file-level evidence, and generates marketing-quality docs — README, CHANGELOG, ROADMAP, user guides, llms.txt, launch artifacts, and 20+ files total. Includes quality scoring, security scanning, and project type auto-detection. GEO-optimised for AI citation. Pure Markdown, zero runtime dependencies. Also works with OpenCode, Codex CLI, Cursor, Windsurf, Cline, Gemini CLI, Aider, and Goose. For AI context file management, see [ContextDocs](https://github.com/littlebearapps/contextdocs).

## Core Docs

- [README](./README.md): Project overview, value proposition, quick start, commands table, comparison table, and features list — get your first generated README in under 60 seconds
- [SKILL.md](./SKILL.md): Root-level skill manifest for directory submissions — plugin overview, installation, all commands, and output format
- [Changelog](./CHANGELOG.md): Version history with user-facing change descriptions, updated automatically from conventional commits
- [Roadmap](./ROADMAP.md): Future direction from GitHub milestones with emoji status indicators and community involvement section
- [Supporting Documentation](./SUPPORT.md): Getting help, common questions, contact details, and support response times

## Learning & Guides

- [Documentation Hub](./docs/README.md): Complete learning path with tutorials, guides, and reference documentation — pick your learning style (hands-on, task-oriented, or conceptual)
- [Tutorial: Build Your First Documentation Suite](./docs/tutorials/build-your-first-docs-suite.md): Hands-on 20-minute journey — walk through generating README, changelog, guides, and verification on a real project
- [Getting Started Guide](./docs/guides/getting-started.md): Step-by-step installation, first README generation, and full command walkthrough (5 minutes)
- [Workflow Recipes](./docs/guides/workflows.md): Copy-paste-ready workflows for public-ready repos, releases, launches, and docs maintenance
- [Command Reference](./docs/guides/command-reference.md): All 16 commands with arguments, generated files, cross-tool support, and examples
- [Customising Output Guide](./docs/guides/customising-output.md): Steer PitchDocs — prompt patterns, tone control, monorepo support, iterative refinement
- [Concepts Guide](./docs/guides/concepts.md): How PitchDocs thinks — evidence-based features, GEO, 4-question test, Diataxis, Lobby Principle, Time to Hello World
- [Troubleshooting & FAQ](./docs/guides/troubleshooting.md): Content filter errors, quality score interpretation, feature extraction issues, badge failures, cross-tool limitations
- [Frequently Asked Questions](./docs/faq/index.md): Quick answers on installation, AI tool support, data privacy, monorepos, content filter errors, headless mode, updates, and uninstall — also rendered on https://littlebearapps.com/help/pitchdocs/ as `Schema.org/FAQPage` JSON-LD (load-bearing — do not delete)
- [Other AI Tools Setup](./docs/guides/other-ai-tools.md): Per-tool instructions and compatibility matrix for Codex CLI, Cursor, Windsurf, Cline, Gemini CLI, Aider, and Goose
- [Untether Integration Guide](./docs/guides/untether-integration.md): Use PitchDocs via Untether's Telegram bridge — hook behaviour, environment variables, security considerations

## Skills (Reference Knowledge)

- [Public README Skill](./.claude/skills/public-readme/SKILL.md): Three-part hero template, value proposition, features with evidence-based benefits, Time to Hello World targets, and Daytona/Banesullivan marketing framework
- [Public README Reference](./.claude/skills/public-readme/SKILL-reference.md): Extended reference — logo guidelines, registry-specific badges, credibility rows, bold-outcome bullets, use-case framing, visual elements (loaded on demand)
- [Feature Benefits Skill](./.claude/skills/feature-benefits/SKILL.md): 7-step codebase scanning — extracts concrete features from code, translates to benefit-driven language across 5 categories (time saved, confidence gained, pain avoided, capability unlocked, cost reduced). Generates features/benefits sections, "Why [Project]?" content, and feature audit reports
- [Feature Benefits Signals](./.claude/skills/feature-benefits/SKILL-signals.md): Extended reference — 10 signal categories, JTBD mapping, persona inference, conversational path prompts, per-ecosystem patterns (loaded on demand)
- [Changelog Skill](./.claude/skills/changelog/SKILL.md): Keep a Changelog format with language rules that rewrite commits into user-facing benefit language
- [Roadmap Skill](./.claude/skills/roadmap/SKILL.md): ROADMAP.md structure from GitHub milestones with emoji indicators and community involvement
- [PitchDocs Suite Skill](./.claude/skills/pitchdocs-suite/SKILL.md): 20+ file inventory, GitHub metadata, visual assets, licence selection — comprehensive docs orchestration
- [PitchDocs Suite Reference](./.claude/skills/pitchdocs-suite/SKILL-reference.md): Extended reference — topic suggestions, social preview, licence framework, package registry config, visual assets guidance (loaded on demand)
- [PitchDocs Suite Templates](./.claude/skills/pitchdocs-suite/SKILL-templates.md): Companion templates for CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, issue/PR templates, FUNDING, SUPPORT, release.yml, CITATION.cff (loaded on demand)
- [llms.txt Skill](./.claude/skills/llms-txt/SKILL.md): llmstxt.org specification reference with generation patterns for repositories and documentation sites
- [Package Registry Skill](./.claude/skills/package-registry/SKILL.md): npm and PyPI metadata auditing, README cross-renderer compatibility, trusted publishing, registry badges
- [Package Registry Reference](./.claude/skills/package-registry/SKILL-reference.md): Extended reference — npm/PyPI field tables, SPDX licence guidance, badge templates, audit checklists (loaded on demand)
- [User Guides Skill](./.claude/skills/user-guides/SKILL.md): Task-oriented how-to documentation with Diataxis framework, frontmatter standard, title conventions, numbered steps, copy-paste code
- [User Guides Reference](./.claude/skills/user-guides/SKILL-reference.md): Extended reference — frontmatter tables, title conventions, video placeholders, troubleshooting template (loaded on demand)
- [User Guide Templates](./.claude/skills/user-guides/SKILL-templates.md): Companion templates for tutorial, reference, explanation, hub page, troubleshooting, and cross-link document types (loaded on demand)
- [Docs Verify Skill](./.claude/skills/docs-verify/SKILL.md): Validate docs — broken links, stale content, llms.txt sync, heading hierarchy, badge URLs, quality scoring (0–100), security scanning
- [Docs Verify Reference](./.claude/skills/docs-verify/SKILL-reference.md): Extended reference — scoring dimensions, grade bands, freshness thresholds, image URL patterns, report format examples (loaded on demand)
- [Launch Artifacts Skill](./.claude/skills/launch-artifacts/SKILL.md): Platform-specific launch content — Dev.to articles, Hacker News posts, Reddit posts, Twitter/X threads, awesome list submissions
- [API Reference Skill](./.claude/skills/api-reference/SKILL.md): API reference generator guidance — TypeDoc, Sphinx, godoc, rustdoc configuration and docstring conventions
- [Doc Refresh Skill](./.claude/skills/doc-refresh/SKILL.md): Version-bump docs orchestration — change detection from git, selective refresh, release-please integration, quality tracking
- [Visual Standards Skill](./.claude/skills/visual-standards/SKILL.md): Visual formatting standards — emoji heading prefixes, horizontal rules, TOC anchors, callouts
- [Visual Standards Reference](./.claude/skills/visual-standards/SKILL-reference.md): Extended reference — screenshot dimensions, HTML patterns, captions, borders, annotations, image optimisation (loaded on demand)
- [GEO Optimisation Skill](./.claude/skills/geo-optimisation/SKILL.md): Generative Engine Optimisation patterns for AI citation — capsules, definitions, atomic sections, statistics, tables
- [Platform Profiles Skill](./.claude/skills/platform-profiles/SKILL.md): Platform detection and Markdown compatibility for GitHub, GitLab, Bitbucket
- [Platform Profiles Tables](./.claude/skills/platform-profiles/SKILL-tables.md): Extended reference — full lookup tables for templates, badges, CLI tools, CI/CD, features, URLs (loaded on demand)

## Agents (Orchestration)

- [Docs Writer Agent](./.claude/agents/docs-writer.md): Orchestration agent — adaptive research (inline for small projects, sub-agent for large), Daytona framework, conditional reviewer, content filter mitigation
- [Docs Researcher Agent](./.claude/agents/docs-researcher.md): Codebase discovery — platform detection, 7-step feature extraction across 10 signals, security scanning, lobby split planning, structured research packets
- [Docs Reviewer Agent](./.claude/agents/docs-reviewer.md): Quality validation — banned phrases, citation capsule completeness, GEO readiness, 6-dimension quality scoring (0–100 rubric)
- [Docs Freshness Agent (Installed)](./.claude/agents/docs-freshness.md): Installed copy of freshness checker — auto-loaded locally in this repo (source: agents/docs-freshness.md)

## Slash Commands

- [/pitchdocs:readme](./commands/readme.md): Generate or update a marketing-friendly README.md — supports --review (force review) and --no-review (skip review) flags
- [/pitchdocs:features](./commands/features.md): Extract features from code and translate to user benefits — auto-scan or conversational path
- [/pitchdocs:changelog](./commands/changelog.md): Generate CHANGELOG.md from git history with benefit-driven language
- [/pitchdocs:roadmap](./commands/roadmap.md): Generate ROADMAP.md from GitHub milestones with emoji indicators
- [/pitchdocs:docs-audit](./commands/docs-audit.md): Audit docs completeness against 20+ file checklist with Diataxis coverage
- [/pitchdocs:llms-txt](./commands/llms-txt.md): Generate llms.txt and llms-full.txt for AI discoverability
- [/pitchdocs:user-guide](./commands/user-guide.md): Generate task-oriented user guides with Diataxis classification in docs/guides/
- [/pitchdocs:docs-verify](./commands/docs-verify.md): Verify documentation links, freshness, llms.txt sync, badge URLs, quality score, and security
- [/pitchdocs:launch](./commands/launch.md): Generate platform-specific launch artifacts — Dev.to articles, HN posts, Reddit posts, Twitter threads, awesome lists
- [/pitchdocs:doc-refresh](./commands/doc-refresh.md): Refresh all docs after version bumps — CHANGELOG, README features, user guides, llms.txt
- [/pitchdocs:platform](./commands/platform.md): Detect hosting platform (GitHub/GitLab/Bitbucket) and report feature support
- [/pitchdocs:visual-standards](./commands/visual-standards.md): Load visual formatting standards for screenshots, emoji headings, image specs
- [/pitchdocs:geo](./commands/geo.md): Load GEO optimisation patterns for AI citation — capsules, definitions, atomic sections
- [/pitchdocs:activate](./commands/activate.md): Install, uninstall, or check status of per-project PitchDocs features — rules, agent, and hook
- [/pitchdocs:ai-context](./commands/ai-context.md): Stub — redirects to [ContextDocs](https://github.com/littlebearapps/contextdocs) for AI context file management
- [/pitchdocs:context-guard](./commands/context-guard.md): Stub — redirects to [ContextDocs](https://github.com/littlebearapps/contextdocs) for Context Guard hooks

## Launch Artifacts

- [Launch Coordination Hub](./docs/launch/README.md): Complete checklist for planning, timing, messaging, and tracking multi-platform launch — review all artifacts, set timeline, track success metrics
- [Dev.to Article](./docs/launch/devto-article.md): 2.2 KB narrative article with problem-solution framing — post to Dev.to for long-form discovery and SEO
- [Hacker News Post](./docs/launch/hackernews-post.md): "Show HN" title and technical-depth first comment — post Tue–Thu 9–11 AM US Eastern for maximum visibility
- [Reddit Post Templates](./docs/launch/reddit-post.md): Three subreddit variants (r/programming, r/webdev, r/opensource) with author context and community angles — space posts 24+ hours apart
- [Twitter Thread](./docs/launch/twitter-thread.md): 5-tweet narrative (hook → problem → features → proof → CTA) — all under 280 chars per tweet with visual guidance
- [Awesome List Submission](./docs/launch/awesome-list-submission.md): Curated awesome list submission with PR template and strategy — stagger submissions every 2–3 days
- [Social Preview Guide](./docs/launch/social-preview-guide.md): 1280×640 image specs, design guidance, and testing checklist for GitHub social preview card

## Project Context

- [CLAUDE.md](./CLAUDE.md): Project architecture — plugin structure, conventions, key files, modification guide, testing and validation procedures
- [AGENTS.md](./AGENTS.md): Codex CLI compatibility file with condensed skills reference and docs-writer agent overview
- [Cursor Rules](./.cursorrules): Cursor IDE project context — architecture, writing standards, sync requirements
- [Copilot Instructions](./.github/copilot-instructions.md): GitHub Copilot project context — structure, conventions, sync points
- [Windsurf Rules](./.windsurfrules): Windsurf (Cascade AI) project context — architecture, coding standards, key files
- [Cline Rules](./.clinerules): Cline VS Code extension project context — tech stack, important paths, pre-commit checklist
- [Gemini Context](./GEMINI.md): Gemini CLI project context — tech stack, conventions, key paths

## Optional & Supporting

- [Security Policy](./SECURITY.md): Vulnerability reporting process and response timeline
- [Code of Conduct](./CODE_OF_CONDUCT.md): Community behaviour standards (Contributor Covenant v3.0)
- [Contributing Guide](./CONTRIBUTING.md): Development setup, how to improve templates, add skills/commands, submit PRs with conventional commits
- [License](./LICENSE): MIT licence terms
- [Plugin Manifest](./.claude-plugin/plugin.json): Plugin metadata, version, keywords, author info
- [Content Filter Reference](./.claude/rules/content-filter.md): Auto-loaded quick reference for handling API filter when generating CODE_OF_CONDUCT, LICENSE, SECURITY (Claude Code only)
- [Doc Standards (Installed)](./.claude/rules/doc-standards.md): Installed copy of quality standards — auto-loaded locally in this repo (source: rules/doc-standards.md)
- [Documentation Awareness (Installed)](./.claude/rules/docs-awareness.md): Installed copy of documentation trigger map — auto-loaded locally in this repo (source: rules/docs-awareness.md)
- [Doc Standards Template](./rules/doc-standards.md): Quality standards — installed per-project by /pitchdocs:activate. 4-question framework, Lobby Principle, benefit-driven language, file naming
- [Documentation Awareness Template](./rules/docs-awareness.md): Documentation trigger map — installed per-project by /pitchdocs:activate. Suggests PitchDocs commands at documentation moments (Claude Code only)
- [Docs Freshness Agent Template](./agents/docs-freshness.md): Read-only freshness checker agent — installed per-project by /pitchdocs:activate. Checks version alignment, changelog coverage, doc staleness, suggests commands
- [Content Filter Hook](./hooks/content-filter-guard.sh): PreToolUse hook blocking writes to high-risk OSS files — installed per-project by /pitchdocs:activate install strict (Claude Code only)
- [Activate Command](./commands/activate.md): Install, uninstall, or check status of per-project PitchDocs features — rules, agent, and hook
- [Upstream Versions](./upstream-versions.json): Pinned versions of 7 referenced specifications (Keep a Changelog, Contributor Covenant, Conventional Commits, Semantic Versioning, GitHub Issue Forms, npm/PyPI Trusted Publishing)
- [Test Evaluations](./tests/evaluations.json): 24 test scenarios for command routing verification — maps commands to expected skills with negative cases
- [Test Results](./tests/RESULTS.md): Documentation and status of all validation tests
- [Activation Eval Runner](./tests/run-activation-evals.sh): Measure skill activation accuracy via Claude's prompt caching mode (-p flag) — runs 24 test scenarios
- [Frontmatter Validator](./tests/validate-frontmatter.py): Validate YAML metadata in skills, commands, and agents
- [Token Budget Checker](./tests/check-token-budgets.sh): Enforce size limits on skills, rules, and agents
- [Banned Phrase Checker](./tests/check-banned-phrases.sh): Scan docs for AI-speak and forbidden phrases
- [llms.txt Validator](./tests/validate-llms-txt.sh): Verify all referenced files exist and no orphans remain
- [Content Filter Hook Test](./tests/test-hook-content-filter.sh): Validate content filter write guard for CODE_OF_CONDUCT, LICENSE, SECURITY
- [Activation Results](./tests/activation-results/): Test run outputs tracking skill routing accuracy over time