project-docs

project-docs

A Claude Code plugin for maintaining project documentation:

• README.md - What is this and how do I use it (setup, deploy, test)
• ARCHITECTURE.md - How is this designed and why (design, patterns, conventions)
• process-notes/ - Work history documenting decisions, dead ends, and progress. Each entry is a separate file named YYYY-MM-DDTHHMM-slug.md so writes stay atomic, grep works naturally, and reading recent entries is ls -t process-notes/ | head -3.
• A/B test docs - Structured documentation for experiments and tests

Installation

claude plugins add teresa-torres-plugins/project-docs

Commands

/project-docs:about

Show this README for help and usage information.

/project-docs:process-notes

Document current session progress as a new file in process-notes/. Creates a comprehensive entry capturing:

• What was accomplished with file references
• Key decisions with rationale and alternatives considered
• Dead ends: what didn't work, why, and what was done instead
• Technical details: files created/modified, dependencies, configs
• Next steps with context for the next session

Each invocation writes a new file named YYYY-MM-DDTHHMM-slug.md. Existing entry files are never modified — every write is a new, self-contained entry. If the project still has a legacy flat process-notes.md, this command will refuse to run and tell you to convert first (see below).

/project-docs:convert-flat-process-notes-to-dir

Migrate a project from the legacy single-file process-notes.md format to the per-entry process-notes/ folder format. Run this once per project when you see the new skill refusing to write, or whenever you want to adopt the folder format.

The skill:

• Splits the flat file on every ## heading
• Extracts a date from each heading when possible (handles [YYYY-MM-DD HH:MM], [YYYY-MM-DD], YYYY-MM-DD:, Session: YYYY-MM-DD, and fuzzy fallback for unusual formats)
• Writes each entry as a separate file in process-notes/
• Dated entries: YYYY-MM-DDTHHMM-slug.md
• Undated entries (phase-based or topic-based): NNNN-slug.md, ordinal-prefixed
• Renames the original to process-notes.md.archive as a safety net
• Verifies the conversion (entry count + byte count) before reporting success

/project-docs:readme

Update README.md to document what the project is and how to use it:

• Project overview and current status
• Project structure (file tree)
• Installation and dependencies
• Configuration (SSM parameters, environment variables)
• Deployment instructions
• Development workflows

/project-docs:architecture

Update ARCHITECTURE.md to document how the system is designed and why:

• System flow diagrams
• Data model (entities, attributes, indexes)
• API endpoint specs
• Workflow details (Step Functions, etc.)
• Infrastructure resources
• Patterns & conventions to follow when adding new code

/project-docs:ab-test <test-name> [file-path]

Document an A/B test interactively. Creates or updates a structured document capturing:

• Test date
• Hypothesis
• Control and treatment variants (name + description)
• Group assignment (how users are segmented into test/control)
• How success will be measured
• When results will be evaluated
• Results and conclusions (filled in when test completes)

Arguments:

• test-name (required): Name of the test
• file-path (optional): Where to save. Defaults to ./{test-name}.md

/project-docs:all-docs

Update all project documentation by running these commands sequentially:

1. /project-docs:process-notes
2. /project-docs:readme
3. /project-docs:architecture

/project-docs:code-review

Launch the code-reviewer agent to review all uncommitted changes. The agent checks:

• Consistency with ARCHITECTURE.md patterns
• Error handling coverage
• Test coverage (unit and integration)
• Security (secrets, least-privilege, input validation, logging hygiene, CORS, dependencies)
• Documentation (README, ARCHITECTURE.md, test.md, process-notes)

/project-docs:plan-review

Launch the plan-reviewer agent to review the most recent plan in .claude/plans/. The agent checks:

• Consistency with project architecture and patterns
• Potential duplicates in the codebase
• Unnecessary complexity that could be simplified

Skills

All commands have corresponding skills that Claude can invoke proactively: