Initial commit

.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"
+  ]
+}

README.md

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

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

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
+
+<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]
+```

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": []
+  }
+}

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.