fp-tools

fp-docs

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 19 commands, 9 specialized engines (including a universal orchestration engine that coordinates 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
• Command Reference
• Common Workflows
• Architecture
• Development Guide
• Configuration Reference
• Troubleshooting

---

Installation

Marketplace Install (Production)

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

Local Development

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

Important: Point --plugin-dir at plugins/fp-docs/, not the repo root. The repo root is the marketplace wrapper (fp-tools). The installable plugin lives at plugins/fp-docs/.

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.

---

Command Reference

Summary Table