zhongwei/gh-dnlopes-claude-code-plugins-project-documenter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:22:59 +08:00
commit dc07b7eb3a
6 changed files with 723 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,14 @@
{
"name": "project-documenter",
"description": "Repository documentation toolkit for creating and maintaining CLAUDE.md and docs/claude/ structure",
"version": "1.0.0",
"author": {
"name": "David Lopes"
},
"skills": [
"./skills"
],
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# project-documenter
Repository documentation toolkit for creating and maintaining CLAUDE.md and docs/claude/ structure

6
commands/onboard-repo.md Normal file
View File

@@ -0,0 +1,6 @@
---
name: onboard-repository
description: Create CLAUDE.md and docs/claude/ onboarding documentation for a repository
---
Use the onboard-repository skill exactly as written

387
commands/update-docs.md Normal file
View File

@@ -0,0 +1,387 @@
---
description: Update and maintain project documentation including docs/, READMEs, JSDoc, and API documentation using best practices and automated tools where appropriate
argument-hint: Optional target directory or documentation type (api, guides, readme, jsdoc)
---
# Documentation Update Command
<task>
You are a technical documentation specialist who maintains living documentation that serves real user needs. Your mission is to create clear, concise, and useful documentation while ruthlessly avoiding documentation bloat and maintenance overhead.
</task>
<context>
References:
- Tech Writer Agent: @/plugins/sdd/agents/tech-writer.md
- Documentation principles and quality standards
- Token efficiency and progressive disclosure patterns
- Context7 MCP for accurate technical information gathering
</context>
## Core Documentation Philosophy
### The Documentation Hierarchy
```text
CRITICAL: Documentation must justify its existence
├── Does it help users accomplish real tasks? → Keep
├── Is it discoverable when needed? → Improve or remove
├── Will it be maintained? → Keep simple or automate
└── Does it duplicate existing docs? → Remove or consolidate
```
### What TO Document ✅
**User-Facing Documentation:**
- **Getting Started**: Quick setup, first success in <5 minutes
- **How-To Guides**: Task-oriented, problem-solving documentation
- **API References**: When manual docs add value over generated
- **Troubleshooting**: Common real problems with proven solutions
- **Architecture Decisions**: When they affect user experience
**Developer Documentation:**
- **Contributing Guidelines**: Actual workflow, not aspirational
- **Module READMEs**: Navigation aid with brief purpose statement
- **Complex Business Logic**: JSDoc for non-obvious code
- **Integration Patterns**: Reusable examples for common tasks
### What NOT to Document ❌
**Documentation Debt Generators:**
- Generic "Getting Started" without specific tasks
- API docs that duplicate generated/schema documentation
- Code comments explaining what the code obviously does
- Process documentation for processes that don't exist
- Architecture docs for simple, self-explanatory structures
- Changelogs that duplicate git history
- Documentation of temporary workarounds
- Multiple READMEs saying the same thing
**Red Flags - Stop and Reconsider:**
- "This document explains..." → What task does it help with?
- "As you can see..." → If it's obvious, why document it?
- "TODO: Update this..." → Will it actually be updated?
- "For more details see..." → Is the information where users expect it?
## Documentation Discovery Process
### 1. Codebase Analysis
<mcp_usage>
Use Context7 MCP to gather accurate information about:
- Project frameworks, libraries, and tools in use
- Existing API endpoints and schemas
- Documentation generation capabilities
- Standard patterns for the technology stack
</mcp_usage>
**Inventory Existing Documentation:**
```bash
# Find all documentation files
find . -name "*.md" -o -name "*.rst" -o -name "*.txt" | grep -E "(README|CHANGELOG|CONTRIBUTING|docs/)"
# Check for generated docs
find . -name "openapi.*" -o -name "*.graphql" -o -name "swagger.*"
# Look for JSDoc/similar
grep -r "@param\|@returns\|@example" --include="*.js" --include="*.ts"
```
### 2. User Journey Mapping
Identify critical user paths:
- **Developer onboarding**: Clone → Setup → First contribution
- **API consumption**: Discovery → Authentication → Integration
- **Feature usage**: Problem → Solution → Implementation
- **Troubleshooting**: Error → Diagnosis → Resolution
### 3. Documentation Gap Analysis
**High-Impact Gaps** (address first):
- Missing setup instructions for primary use cases
- API endpoints without examples
- Error messages without solutions
- Complex modules without purpose statements
**Low-Impact Gaps** (often skip):
- Minor utility functions without comments
- Internal APIs used by single modules
- Temporary implementations
- Self-explanatory configuration
## Smart Documentation Strategy
### When to Generate vs. Write
**Use Automated Generation For:**
- **OpenAPI/Swagger**: API documentation from code annotations
- **GraphQL Schema**: Type definitions and queries
- **JSDoc**: Function signatures and basic parameter docs
- **Database Schemas**: Prisma, TypeORM, Sequelize models
- **CLI Help**: From argument parsing libraries
**Write Manual Documentation For:**
- **Integration examples**: Real-world usage patterns
- **Business logic explanations**: Why decisions were made
- **Troubleshooting guides**: Solutions to actual problems
- **Getting started workflows**: Curated happy paths
- **Architecture decisions**: When they affect API design
### Documentation Tools and Their Sweet Spots
**OpenAPI/Swagger:**
- ✅ Perfect for: REST API reference, request/response examples
- ❌ Poor for: Integration guides, authentication flows
- **Limitation**: Requires discipline to keep annotations current
**GraphQL Introspection:**
- ✅ Perfect for: Schema exploration, type definitions
- ❌ Poor for: Query examples, business context
- **Limitation**: No usage patterns or business logic
**Prisma Schema:**
- ✅ Perfect for: Database relationships, model definitions
- ❌ Poor for: Query patterns, performance considerations
- **Limitation**: Doesn't capture business rules
**JSDoc/TSDoc:**
- ✅ Perfect for: Function contracts, parameter types
- ❌ Poor for: Module architecture, integration examples
- **Limitation**: Easily becomes stale without enforcement
## Documentation Update Workflow
### 1. Information Gathering
**Project Context Discovery:**
```markdown
1. Identify project type and stack
2. Check for existing doc generation tools
3. Map user types (developers, API consumers, end users)
4. Find documentation pain points in issues/discussions
```
**Use Context7 MCP to research:**
- Best practices for the specific tech stack
- Standard documentation patterns for similar projects
- Available tooling for documentation automation
- Common pitfalls to avoid
### 2. Documentation Audit
**Quality Assessment:**
```markdown
For each existing document, ask:
1. When was this last updated? (>6 months = suspect)
2. Is this information available elsewhere? (duplication check)
3. Does this help accomplish a real task? (utility check)
4. Is this findable when needed? (discoverability check)
5. Would removing this break someone's workflow? (impact check)
```
### 3. Strategic Updates
**High-Impact, Low-Effort Updates:**
- Fix broken links and outdated code examples
- Add missing setup steps that cause common failures
- Create module-level README navigation aids
- Document authentication/configuration patterns
**Automate Where Possible:**
- Set up API doc generation from code
- Configure JSDoc builds
- Add schema documentation generation
- Create doc linting/freshness checks
### 4. Content Creation Guidelines
**README.md Best Practices:**
**Project Root README:**
```markdown
# Project Name
Brief description (1-2 sentences max).
## Quick Start
[Fastest path to success - must work in <5 minutes]
## Documentation
- [API Reference](./docs/api/) - if complex APIs
- [Guides](./docs/guides/) - if complex workflows
- [Contributing](./CONTRIBUTING.md) - if accepting contributions
## Status
[Current state, known limitations]
```
**Module README Pattern:**
```markdown
# Module Name
**Purpose**: One sentence describing why this module exists.
**Key exports**: Primary functions/classes users need.
**Usage**: One minimal example.
See: [Main documentation](../docs/) for detailed guides.
```
**JSDoc Best Practices:**
**Document These:**
```typescript
/**
* Processes payment with retry logic and fraud detection.
*
* @param payment - Payment details including amount and method
* @param options - Configuration for retries and validation
* @returns Promise resolving to transaction result with ID
* @throws PaymentError when payment fails after retries
*
* @example
* ```typescript
* const result = await processPayment({
* amount: 100,
* currency: 'USD',
* method: 'card'
* });
* ```
*/
async function processPayment(payment: PaymentRequest, options?: PaymentOptions): Promise<PaymentResult>
```
**Don't Document These:**
```typescript
// ❌ Obvious functionality
/**
* Gets the user name
* @returns the name
*/
getName(): string
// ❌ Simple CRUD
/**
* Saves user to database
*/
save(user: User): Promise<void>
// ❌ Self-explanatory utilities
/**
* Converts string to lowercase
*/
toLowerCase(str: string): string
```
## Implementation Process
### Phase 1: Assessment and Planning
1. **Discover project structure and existing documentation**
2. **Identify user needs and documentation gaps**
3. **Evaluate opportunities for automation**
4. **Create focused update plan with priorities**
### Phase 2: High-Impact Updates
1. **Fix critical onboarding blockers**
2. **Update outdated examples and links**
3. **Add missing API examples for common use cases**
4. **Create/update module navigation READMEs**
### Phase 3: Tool Integration
1. **Set up API documentation generation where beneficial**
2. **Configure JSDoc for complex business logic**
3. **Add documentation freshness checks**
4. **Remove or consolidate duplicate documentation**
### Phase 4: Validation
1. **Test all examples and code snippets**
2. **Verify links and references work**
3. **Confirm documentation serves real user needs**
4. **Establish maintenance workflow for living docs**
## Quality Gates
**Before Publishing:**
- [ ] All code examples tested and working
- [ ] Links verified (no 404s)
- [ ] Document purpose clearly stated
- [ ] Audience and prerequisites identified
- [ ] No duplication of generated docs
- [ ] Maintenance plan established
**Documentation Debt Prevention:**
- [ ] Automated checks for broken links
- [ ] Generated docs preferred over manual where applicable
- [ ] Clear ownership for each major documentation area
- [ ] Regular pruning of outdated content
## Success Metrics
**Good Documentation:**
- Users complete common tasks without asking questions
- Issues contain more bug reports, fewer "how do I...?" questions
- Documentation is referenced in code reviews and discussions
- New contributors can get started independently
**Warning Signs:**
- Documentation frequently mentioned as outdated in issues
- Multiple conflicting sources of truth
- High volume of basic usage questions
- Documentation updates commonly forgotten in PRs
**Documentation Update Summary Template:**
```markdown
## Documentation Updates Completed
### Files Updated
- [ ] README.md (root/modules)
- [ ] docs/ directory organization
- [ ] API documentation (generated/manual)
- [ ] JSDoc comments for complex logic
### Major Changes
- [List significant improvements]
- [New documentation added]
- [Deprecated/removed content]
### Automation Added
- [Doc generation tools configured]
- [Quality checks implemented]
### Next Steps
- [Maintenance tasks identified]
- [Future automation opportunities]
```

53
plugin.lock.json Normal file
View File

@@ -0,0 +1,53 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:dnlopes/claude-code-plugins:project-documenter",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "f283631eca6ec6d0d26dd12c057975d87a33cab0",
"treeHash": "365d962f0e561496f6a0282bd3b923e8b6cbe7f7d75f388d272f8112601e68ee",
"generatedAt": "2025-11-28T10:16:33.594630Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "project-documenter",
"description": "Repository documentation toolkit for creating and maintaining CLAUDE.md and docs/claude/ structure",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "52ddad94c5f71456fbd72e3a482e4f89dadf3bfbb1ab2099c8c6be0919c3520d"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "bb955722f60dc23972915f742607b3c6ff8e4f1f21921456480d6c552a584cba"
},
{
"path": "commands/update-docs.md",
"sha256": "cf791fc16af1cb836b3ba4304e0775f83e1e287d32d7604aaa2a463711206f0e"
},
{
"path": "commands/onboard-repo.md",
"sha256": "22e5a3201cc86c0fbdcb02fa854cfc1f5ef292a60364910e9d2d67345c1bc5a1"
},
{
"path": "skills/onboard-repository/SKILL.md",
"sha256": "dd370362da24e9ca7931c0d74ebc7b225073413b4076765b09db0bdbf49a9153"
}
],
"dirSha256": "365d962f0e561496f6a0282bd3b923e8b6cbe7f7d75f388d272f8112601e68ee"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

260
skills/onboard-repository/SKILL.md Normal file
View File

@@ -0,0 +1,260 @@
---
name: onboard-repository
description: Use when creating CLAUDE.md or docs/claude/ documentation for a new repository - ensures systematic codebase exploration instead of generic templates, extracting real architecture, actual tech stack, and concrete code patterns from the repository
---
# Onboard Repository
## Overview
**Repository onboarding creates documentation by systematically exploring the actual codebase, not by generating templates.**
Core principle: Documentation must reflect what's ACTUALLY in the repository, not what you assume is there.
## When to Use
Use this skill when:
- Creating CLAUDE.md for a new repository
- Setting up docs/claude/ documentation structure
- Onboarding multiple repositories systematically
- Someone asks to "document the codebase for Claude"
Do NOT use for:
- Adding to existing documentation (that's maintenance, not onboarding)
- Single file explanations (just read and explain)
- API documentation (that's a different skill)
## The Iron Law
```
NO DOCUMENTATION WITHOUT READING THE CODE FIRST
```
**Never:**
- Generate documentation from directory structure alone
- Create "likely includes..." or "probably has..." content
- Use placeholders like "(needs investigation)"
- Make assumptions about patterns or conventions
- Write TODO or "fill this in later" sections
**Always:**
- Read actual source files before documenting them
- Extract real examples from the codebase
- Document what IS there, not what SHOULD be there
## Systematic Onboarding Process
### Phase 1: Discovery (Required First)
**YOU MUST complete discovery before writing ANY documentation.**
1. **Identify the ecosystem:**
- Read go.mod/package.json/pom.xml/requirements.txt for dependencies
- Check for framework indicators (Spring Boot, React, Kubernetes operator, etc.)
- Identify build system (Make, Gradle, npm, etc.)
2. **Map the architecture:**
- Read main entry points (main.go, index.ts, Application.java)
- Trace key initialization code
- Identify major components and their responsibilities
- Find configuration sources
3. **Extract patterns:**
- Find 2-3 representative files that show typical structure
- Identify testing approach (framework, patterns, location)
- Note error handling patterns
- Document actual naming conventions used
4. **Catalog specifics:**
- List actual make/npm/gradle targets (from files, not assumptions)
- Find environment variables and configuration
- Identify external dependencies (databases, APIs, message queues)
- Document deployment/build artifacts
### Phase 2: Documentation Structure
Create docs/claude/ with these files:
| File | Content | Source |
|------|---------|--------|
| **architecture.md** | System design, component relationships, data flow | From reading main entry points and key files |
| **tech-stack.md** | Languages, frameworks, tools, versions | From dependency files and build configs |
| **patterns.md** | Code organization, naming, common patterns with REAL examples | From analyzing representative files |
| **development.md** | Build commands, testing, local dev setup | From Makefile/package.json/build files |
### Phase 3: Create CLAUDE.md
CLAUDE.md is the entry point that:
1. Briefly describes what the repo does (1-2 sentences)
2. Lists key directories and their purposes
3. Points to docs/claude/ for details
4. Includes quick start commands
**Keep it short** - detailed content goes in docs/claude/, not CLAUDE.md.
## Documentation Content Requirements
### Architecture (docs/claude/architecture.md)
**Must include:**
- High-level component diagram or description
- Data flow through the system
- Key abstractions and their relationships
- Integration points (databases, external services, APIs)
**Must be based on:**
- Reading main.go/index.ts/Application.java
- Tracing initialization code
- Following import/require chains
- Reading configuration setup
**Example of good content:**
```markdown
## Request Processing Flow
1. HTTP request arrives at `pkg/server/handler.go:HandleRequest()`
2. Request validated using `pkg/validator/schema.go` Zod schemas
3. Business logic in `pkg/service/processor.go:ProcessOrder()`
4. Database writes via `pkg/repository/orders.go` using GORM
5. Event published to Kafka topic `order.processed` via `pkg/events/publisher.go`
```
**Example of bad content:**
```markdown
## Request Processing Flow
The system likely handles requests through handlers, processes them with business logic, and stores results in a database.
```
### Tech Stack (docs/claude/tech-stack.md)
**Must include:**
- Exact language versions (from go.mod, package.json, etc.)
- Framework with version (Spring Boot 3.2.1, React 18.2.0, etc.)
- Key libraries with brief purpose
- Build tools and versions
- Runtime requirements (Java 17, Node 20, Go 1.21)
**Must be based on:**
- Reading dependency files completely
- Checking .tool-versions or .nvmrc
- Reading Dockerfile for runtime requirements
### Patterns (docs/claude/patterns.md)
**Must include:**
- Project structure with explanations
- Actual code examples (2-4) from the repo
- Testing patterns with real test file examples
- Error handling patterns with actual code
- Configuration patterns
**Each pattern needs:**
1. Description of the pattern
2. REAL code example from the codebase
3. Location of the example (file:line)
**Example of good content:**
```markdown
## Error Handling Pattern
Errors are wrapped with context using pkg/errors:
```go
// From pkg/service/processor.go:45
func (s *Service) ProcessOrder(order *Order) error {
if err := s.validator.Validate(order); err != nil {
return fmt.Errorf("validating order %s: %w", order.ID, err)
}
// ...
}
```
This pattern provides error context for debugging while preserving the original error for type checking.
```
**Example of bad content:**
```markdown
## Error Handling Pattern
Errors should be handled appropriately with proper context and wrapping.
```
### Development (docs/claude/development.md)
**Must include:**
- Actual build commands from Makefile/package.json
- How to run tests (with actual command)
- Local development setup steps
- Environment variables needed
- How to run the application locally
**Must be based on:**
- Reading Makefile/package.json/build.gradle completely
- Reading .env.example or config files
- Reading README.md if it exists
- Checking docker-compose.yml
## Red Flags - STOP and Read Code
If you're writing any of these, STOP - you haven't read the code:
- "likely includes..."
- "probably uses..."
- "typically structured..."
- "common pattern is..."
- "(see X for details)" without reading X
- "(needs investigation)"
- "TODO: fill in..."
- Generic descriptions without specifics
- Zero code examples from the actual repo
- Assumed make targets without reading Makefile
**All of these mean: Stop writing. Start reading.**
## Common Rationalizations
| Excuse | Reality |
|--------|---------|
| "Directory structure tells me enough" | No. Assumptions are wrong. Read the files. |
| "I can fill in details later" | No later. Document what you found NOW. |
| "It's obviously a standard X pattern" | Nothing is standard. Read the actual implementation. |
| "Quick overview is fine for now" | Quick + accurate, not quick + wrong. |
| "User said to work fast" | Fast exploration is fine. Fast assumptions are not. |
| "It's just like other repos I've seen" | Each repo is different. Read this one. |
## Quality Checklist
Before considering onboarding complete:
- [ ] Read at least main entry point file completely
- [ ] Read actual dependency manifest (go.mod, package.json, etc.)
- [ ] Read actual build file (Makefile, package.json scripts, etc.)
- [ ] Extracted 2+ real code examples for patterns.md
- [ ] Listed specific versions for all major dependencies
- [ ] Documented actual make/npm/gradle targets with their real names
- [ ] Zero instances of "likely", "probably", "typically" in docs
- [ ] Zero TODO or placeholder sections
- [ ] Every pattern has real code example with file:line reference
## Time Investment
Proper onboarding takes 15-30 minutes for typical repository:
- 10-15 min: Reading key files
- 5-10 min: Extracting examples
- 5-10 min: Writing documentation
This is MUCH faster than:
- Developers guessing what's there (hours)
- Debugging misunderstood architecture (hours/days)
- Onboarding new team members (hours/days)
The investment pays off immediately.
## The Bottom Line
**Repository onboarding means reading the actual code and documenting what you find.**
Templates and assumptions create useless documentation. Systematic exploration creates valuable documentation.
If you didn't read it, don't document it.