Initial commit

.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "docs",
+  "description": "Commands for analysing project, writing and refining documentation.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Vlad Goncharov",
+    "email": "vlad.goncharov@neolab.finance"
+  },
+  "commands": [
+    "./commands"
+  ]
+}

README.md

@@ -0,0 +1,3 @@
+# docs
+
+Commands for analysing project, writing and refining documentation.

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,45 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:NeoLabHQ/context-engineering-kit:plugins/docs",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "ae5ed31d1ad8b632bc840fe56397fed0d6853d04",
+    "treeHash": "2f074f4151a71e9692fca6e823961de1e49a9ef25071b19363fa4827bbcd4686",
+    "generatedAt": "2025-11-28T10:12:11.842630Z",
+    "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": "docs",
+    "description": "Commands for analysing project, writing and refining documentation.",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "98ac0372fbc47272de8368b89cd22ed36308536f4b5e4473f0d4ea2c9653501c"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "88fad01824ca37387ca7a73a348a39e383bd92c3881fa0ec42cf91b6cf0a98fc"
+      },
+      {
+        "path": "commands/update-docs.md",
+        "sha256": "dc67e27464b9696276aef17f10eb3e73f404536c9264f091d257e0bb46136ab0"
+      }
+    ],
+    "dirSha256": "2f074f4151a71e9692fca6e823961de1e49a9ef25071b19363fa4827bbcd4686"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}