fp-docs

fp-docs

Note: This repository contains only the fp-docs plugin engine — the commands, agents, workflows, and modules that drive documentation operations. It does not contain any generated documentation, source code, or sensitive information from the Foreign Policy codebase. Those live in separate, access-controlled private repositories.

fp-docs is prototyped against the foreignpolicy.com WordPress codebase, which serves as its immediate proving ground. However, the architecture is designed to be fully adaptable — any codebase, in any language or framework, can be documented using this same system. The FP integration is a reference implementation, not a hard dependency.

Documentation management system for the Foreign Policy WordPress codebase. fp-docs is a Claude Code plugin that automates the creation, revision, validation, and maintenance of technical documentation by reading your source code directly and keeping docs in sync with every change.

fp-docs enforces zero-tolerance verbosity (every source item must be documented), cross-references every claim against actual code, manages citations with provenance tracking, and maintains a separate docs git repo that branch-mirrors your codebase. It ships 31 commands, 13 specialized agents (fp-docs-* prefix), workflows that orchestrate multi-agent execution, and an automated 8-stage post-modification pipeline that runs after every documentation change.

What Problems It Solves

• Documentation drift: Code changes but docs don't. fp-docs detects git diffs and auto-updates affected documentation.
• Inaccurate documentation: Docs claim things that aren't true. fp-docs sanity-checks every factual claim against actual source code with zero-tolerance verification.
• Incomplete documentation: LLMs naturally summarize and truncate. fp-docs enforces anti-compression rules that ban summarization phrases ("etc.", "and more", "various") and require exhaustive enumeration of every function, parameter, hook, and constant.
• Missing citations: Docs make claims without evidence. fp-docs generates verifiable code citations with file paths, symbol names, line ranges, and verbatim code excerpts.
• Stale API references: Function signatures change but reference tables don't. fp-docs extracts actual signatures from source and tracks provenance (PHPDoc, Verified, Authored).
• Undocumented data contracts: WordPress template components pass $locals arrays between files without formal contracts. fp-docs annotates source code with @locals PHPDoc blocks and generates contract tables.
• Branch mismatch: The docs repo and codebase repo can drift to different branches. fp-docs detects this on session start and synchronizes branches.
• No documentation lifecycle: Most codebases lack a systematic process from creation through maintenance to deprecation. fp-docs provides the full lifecycle: create, maintain, validate, deprecate.

---

Table of Contents

• Installation
• Quick Start
• Updating fp-docs
• Command Reference
• Common Workflows
• Architecture
• Development Guide
• Configuration Reference
• Troubleshooting
• Version Management

---

Installation

Marketplace Install (Production)

/plugin marketplace add tomkyser/fp-tools
/plugin install fp-docs@fp-tools

Local Development

claude --plugin-dir ~/cc-plugins/fp-docs

Path note: Point --plugin-dir at the fp-docs/ directory. This IS the plugin root. The parent directory (cc-plugins/) is the marketplace wrapper (fp-tools).

Default Permissions

The plugin auto-allows Read, Grep, and Glob. Write, Edit, and Bash operations will prompt for user approval per-session. Validation commands run without permission prompts; modification commands will ask.

---

Quick Start

1. Install the plugin using one of the methods above.

2. Run setup to verify your environment:

   /fp-docs:setup
   

   Setup checks plugin structure, detects the docs repo, verifies the codebase .gitignore includes the docs directory, and confirms branch sync status. It reports overall health as HEALTHY, DEGRADED, or BROKEN.

3. Sync branches if prompted:

   /fp-docs:sync
   

4. Try your first command -- run a quick audit to see the state of your docs:

   /fp-docs:audit --depth quick
   

5. Update docs after code changes:

   /fp-docs:auto-update
   

From here, the SessionStart hooks handle branch detection and plugin context injection automatically on every new session.

---

Updating fp-docs

Check for Updates

/fp-docs:update --check

This compares your installed version against the latest release on GitHub and reports whether an update is available.