From dc07b7eb3af779f72ccc6bffcdc5b68dc4cff8fe Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:22:59 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 14 ++ README.md | 3 + commands/onboard-repo.md | 6 + commands/update-docs.md | 387 +++++++++++++++++++++++++++++ plugin.lock.json | 53 ++++ skills/onboard-repository/SKILL.md | 260 +++++++++++++++++++ 6 files changed, 723 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/onboard-repo.md create mode 100644 commands/update-docs.md create mode 100644 plugin.lock.json create mode 100644 skills/onboard-repository/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..cf1ca67 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -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" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..2f44d68 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# project-documenter + +Repository documentation toolkit for creating and maintaining CLAUDE.md and docs/claude/ structure diff --git a/commands/onboard-repo.md b/commands/onboard-repo.md new file mode 100644 index 0000000..b059361 --- /dev/null +++ b/commands/onboard-repo.md @@ -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 diff --git a/commands/update-docs.md b/commands/update-docs.md new file mode 100644 index 0000000..c87b57c --- /dev/null +++ b/commands/update-docs.md @@ -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 + + +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. + + + +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 + + +## 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 + + +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 + + +**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 +``` + +**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 + +// ❌ 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] +``` \ No newline at end of file diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..0b40357 --- /dev/null +++ b/plugin.lock.json @@ -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": [] + } +} \ No newline at end of file diff --git a/skills/onboard-repository/SKILL.md b/skills/onboard-repository/SKILL.md new file mode 100644 index 0000000..1f4c24d --- /dev/null +++ b/skills/onboard-repository/SKILL.md @@ -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.