From 5efae030bef12c6378b522ca79e904675c6ea5a2 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:46:53 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + plugin.lock.json | 76 +++ skills/documentation-wizard/README.md | 222 ++++++++ .../References/adr-template.md | 74 +++ .../References/onboarding-template.md | 286 ++++++++++ .../References/readme-template.md | 153 +++++ skills/documentation-wizard/SKILL.md | 525 ++++++++++++++++++ .../scripts/generate_changelog.py | 185 ++++++ .../scripts/generate_docs.py | 64 +++ .../documentation-wizard/scripts/sync_docs.py | 210 +++++++ .../scripts/validate_docs.py | 47 ++ 12 files changed, 1857 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/documentation-wizard/README.md create mode 100644 skills/documentation-wizard/References/adr-template.md create mode 100644 skills/documentation-wizard/References/onboarding-template.md create mode 100644 skills/documentation-wizard/References/readme-template.md create mode 100644 skills/documentation-wizard/SKILL.md create mode 100755 skills/documentation-wizard/scripts/generate_changelog.py create mode 100755 skills/documentation-wizard/scripts/generate_docs.py create mode 100755 skills/documentation-wizard/scripts/sync_docs.py create mode 100755 skills/documentation-wizard/scripts/validate_docs.py diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..c5fcbc5 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "documentation-wizard", + "description": "Keeps documentation in perfect sync with code and knowledge. Auto-generates README, API docs, ADRs, and onboarding materials. Detects stale documentation and ensures it evolves with the codebase.", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Overlord-Z", + "email": "[email protected]" + }, + "skills": [ + "./skills/documentation-wizard" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..a5ebb94 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# documentation-wizard + +Keeps documentation in perfect sync with code and knowledge. Auto-generates README, API docs, ADRs, and onboarding materials. Detects stale documentation and ensures it evolves with the codebase. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..a6b6011 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,76 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:Overlord-Z/ClaudeShack:documentation-wizard", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "f83b28465cb410aea30912855fee8acc9aab227f", + "treeHash": "0105532ca89190616d4e74de8c02899646b2dedb6c7050be4e6ec104372d508d", + "generatedAt": "2025-11-28T10:12:22.707536Z", + "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": "documentation-wizard", + "description": "Keeps documentation in perfect sync with code and knowledge. Auto-generates README, API docs, ADRs, and onboarding materials. Detects stale documentation and ensures it evolves with the codebase." + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "bdea5ce2b1dfebb98ececda7c555f813de0bf8a210c43be6bc0514950be1a74b" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "594d914c8fef33d6b10d8b525bc123df0388eb7d6fb141d12c53e4369bad3808" + }, + { + "path": "skills/documentation-wizard/README.md", + "sha256": "5a1ca82712c53bd8c183cc6c50d3f3326b37033eaf8e4db8a25454f8c6882f84" + }, + { + "path": "skills/documentation-wizard/SKILL.md", + "sha256": "aaf8fb7985a0edf88396b050c10b79ac88605f263ff3e93d5ea8cb86a3c14bb3" + }, + { + "path": "skills/documentation-wizard/References/onboarding-template.md", + "sha256": "ff2441164aa1636b037a201fd06f3c56c2c2294fab4ba42a5b4e6a8609084508" + }, + { + "path": "skills/documentation-wizard/References/readme-template.md", + "sha256": "5a02ac3fcf9fb8d593944e654ffcfac53b6c00342a6919629f905372ace32579" + }, + { + "path": "skills/documentation-wizard/References/adr-template.md", + "sha256": "bd14f9c51d16432593b0c3de18c59422b94c26f9418e1316ae9d141131d95f48" + }, + { + "path": "skills/documentation-wizard/scripts/generate_docs.py", + "sha256": "2c05d12d17191baa61611701aa64938fd6a1a12f9ebd14cdb7e77aaff8a644b1" + }, + { + "path": "skills/documentation-wizard/scripts/generate_changelog.py", + "sha256": "2f0f25a22072490a7a3b873e0bf4987b551d9d105591713fb747d446863ce3ff" + }, + { + "path": "skills/documentation-wizard/scripts/validate_docs.py", + "sha256": "1315b1c9934b42bd946cfb27e51de7f5631c0bccb1f5e83f0ed9d1ff8658fa85" + }, + { + "path": "skills/documentation-wizard/scripts/sync_docs.py", + "sha256": "f5201dfb63cbe2f6041ca0daf952f2c9948fbae6840deba88c7b01f23f7107ba" + } + ], + "dirSha256": "0105532ca89190616d4e74de8c02899646b2dedb6c7050be4e6ec104372d508d" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/documentation-wizard/README.md b/skills/documentation-wizard/README.md new file mode 100644 index 0000000..0a1fb77 --- /dev/null +++ b/skills/documentation-wizard/README.md @@ -0,0 +1,222 @@ +# Documentation Wizard + +**Living Documentation Expert - Always in Sync** + +Documentation Wizard keeps your documentation perfectly synchronized with code, decisions, and learnings. It integrates with Oracle, Summoner, and Style Master to create comprehensive, up-to-date documentation automatically. + +## What It Does + +### ๐Ÿ“ Auto-Generate Documentation +- README files from code + Oracle knowledge +- API documentation from code comments +- Architecture Decision Records (ADRs) from decisions +- Onboarding guides from Oracle sessions +- Changelogs from git history + Oracle + +### ๐Ÿ”„ Continuous Synchronization +- Detects code changes and updates docs +- Pulls patterns from Oracle knowledge +- Extracts decisions from Summoner MCDs +- Syncs Style Master style guides +- Validates examples still work + +### โœ… Documentation Validation +- Detects stale documentation +- Finds broken links +- Validates code examples +- Identifies missing documentation +- Checks for inconsistencies + +### ๐Ÿ”— Integration Powerhouse +- **Oracle**: Leverage learnings and decisions +- **Summoner**: Extract design docs from MCDs +- **Style Master**: Sync style guide documentation +- **Git**: Track evolution and changes + +## Quick Start + +```bash +# Generate initial documentation +python .claude/skills/documentation-wizard/scripts/generate_docs.py + +# Validate documentation +python .claude/skills/documentation-wizard/scripts/validate_docs.py + +# Sync from Oracle knowledge +python .claude/skills/documentation-wizard/scripts/sync_docs.py --source oracle + +# Generate changelog +python .claude/skills/documentation-wizard/scripts/generate_changelog.py +``` + +## Use Cases + +### 1. Initial Documentation Setup +``` +Use the documentation wizard to set up documentation for our project. + +[Analyzes codebase] +[Loads Oracle knowledge] +[Generates README, API docs, contributing guide] +[Creates documentation structure] +``` + +### 2. Keep Docs in Sync +``` +Update documentation based on recent changes. + +[Checks git diff] +[Identifies affected docs] +[Updates API documentation] +[Generates changelog entry] +``` + +### 3. Create ADRs from Decisions +``` +Create ADR for our decision to use PostgreSQL over MongoDB. + +[Loads Oracle decision entry] +[Reads Summoner MCD rationale] +[Generates ADR-015-database-choice.md] +[Links to Oracle and Summoner references] +``` + +## Documentation Types + +### Generated Documentation + +| Type | Source | Output | +|------|--------|--------| +| **README** | Code + Oracle + Summoner | README.md | +| **API Docs** | JSDoc/TypeDoc comments | docs/api/ | +| **ADRs** | Oracle decisions + Summoner MCDs | docs/adr/ | +| **Style Guide** | Style Master | docs/STYLEGUIDE.md | +| **Onboarding** | Oracle sessions | docs/ONBOARDING.md | +| **Changelog** | Git + Oracle | CHANGELOG.md | + +## Integration Examples + +### With Oracle ๐Ÿง  + +**Oracle knows**: "Use factory pattern for DB connections" + +**Docs generated**: +```markdown +## Database Connections + +All database connections use the factory pattern: +\`\`\`typescript +const db = DatabaseFactory.create('postgres'); +\`\`\` +This ensures proper connection pooling. See Oracle entry #42. +``` + +### With Summoner ๐Ÿง™ + +**Summoner MCD**: Microservices migration decision + +**ADR generated**: +```markdown +# ADR-023: Migrate to Microservices Architecture + +Context: From Summoner Mission "Microservices Migration" +Decision: Extract auth service first, then user service +Rationale: [From Summoner MCD] +``` + +### With Style Master ๐ŸŽจ + +**Style Master style guide**: Design tokens + +**Docs synced**: +```markdown +# Theme Customization + +Override design tokens in your CSS: +\`\`\`css +:root { + --color-primary: #your-color; +} +\`\`\` + +See [Style Guide](./STYLEGUIDE.md) for all tokens. +``` + +## Scripts Reference + +### generate_docs.py +Generates initial documentation from code and knowledge. + +**Options**: +- `--type readme|api|adr|onboarding|all` +- `--output docs/` +- `--include-oracle` (include Oracle knowledge) + +### validate_docs.py +Validates documentation for staleness and issues. + +**Checks**: +- Stale documentation +- Broken links +- Invalid examples +- Missing documentation + +### sync_docs.py +Synchronizes documentation from various sources. + +**Sources**: +- `--source oracle` (Oracle knowledge) +- `--source summoner` (Summoner MCDs) +- `--source style-master` (Style guides) +- `--source code` (Code comments) + +### generate_changelog.py +Generates changelog from git history and Oracle. + +**Format**: Semantic (Added/Changed/Fixed/Deprecated/Removed) + +## Best Practices + +### 1. Document WHY, Not Just WHAT +Use Oracle to capture the reasoning behind decisions. + +### 2. Keep Examples Executable +All code examples should be tested and copy-pasteable. + +### 3. Link Everything +Connect documentation to Oracle, Summoner, code, and external resources. + +### 4. Automate Updates +Set up hooks to update docs on code changes. + +### 5. Validate Regularly +Run validation as part of CI/CD. + +## Workflow + +```bash +# Daily: After development session +python .claude/skills/documentation-wizard/scripts/generate_docs.py --type api +python .claude/skills/documentation-wizard/scripts/validate_docs.py + +# Weekly: Comprehensive sync +python .claude/skills/documentation-wizard/scripts/sync_docs.py --source all +python .claude/skills/documentation-wizard/scripts/generate_changelog.py + +# Before release: Full documentation review +python .claude/skills/documentation-wizard/scripts/validate_docs.py --strict +``` + +## Templates Available + +- **README**: Project and package READMEs +- **ADR**: Architecture Decision Records +- **API**: API documentation +- **Onboarding**: New developer guides +- **Contributing**: Contribution guidelines + +See `References/` directory for all templates. + +--- + +**Documentation Wizard v1.0** - Documentation that stays alive diff --git a/skills/documentation-wizard/References/adr-template.md b/skills/documentation-wizard/References/adr-template.md new file mode 100644 index 0000000..a568dba --- /dev/null +++ b/skills/documentation-wizard/References/adr-template.md @@ -0,0 +1,74 @@ +# ADR-{number}: {Short title of solved problem and solution} + +Date: {YYYY-MM-DD} +Status: {Proposed | Accepted | Deprecated | Superseded} +Deciders: {List everyone involved in the decision} +Related: {Links to related ADRs, Oracle entries, Summoner MCDs} + +## Context and Problem Statement + +{Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.} + +## Decision Drivers + +* {decision driver 1, e.g., a force, facing concern, ...} +* {decision driver 2, e.g., a force, facing concern, ...} +* {etc.} + +## Considered Options + +* {option 1} +* {option 2} +* {option 3} +* {etc.} + +## Decision Outcome + +Chosen option: "{option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | ... | comes out best (see below)}. + +### Positive Consequences + +* {e.g., improvement of quality attribute satisfaction, follow-up decisions required, ...} +* {etc.} + +### Negative Consequences + +* {e.g., compromising quality attribute, follow-up decisions required, ...} +* {etc.} + +## Pros and Cons of the Options + +### {option 1} + +{example | description | pointer to more information | ...} + +* Good, because {argument a} +* Good, because {argument b} +* Bad, because {argument c} +* {etc.} + +### {option 2} + +{example | description | pointer to more information | ...} + +* Good, because {argument a} +* Good, because {argument b} +* Bad, because {argument c} +* {etc.} + +### {option 3} + +{example | description | pointer to more information | ...} + +* Good, because {argument a} +* Good, because {argument b} +* Bad, because {argument c} +* {etc.} + +## Links + +* {Link to related Oracle knowledge entries} +* {Link to Summoner Mission Control Documents} +* {Link to code references} +* {Link to related ADRs} +* {External references} diff --git a/skills/documentation-wizard/References/onboarding-template.md b/skills/documentation-wizard/References/onboarding-template.md new file mode 100644 index 0000000..7020fb1 --- /dev/null +++ b/skills/documentation-wizard/References/onboarding-template.md @@ -0,0 +1,286 @@ +# Developer Onboarding Guide + +Welcome to {Project Name}! This guide will help you get up to speed quickly. + +## ๐Ÿ“‹ Checklist + +### Day 1 +- [ ] Set up development environment +- [ ] Clone repository and install dependencies +- [ ] Run the project locally +- [ ] Read architecture documentation +- [ ] Join team communication channels + +### Week 1 +- [ ] Complete first small task/bug fix +- [ ] Understand the codebase structure +- [ ] Review coding standards and patterns +- [ ] Set up IDE/tools properly +- [ ] Meet the team + +### Month 1 +- [ ] Contribute to a feature +- [ ] Understand the deployment process +- [ ] Review Oracle knowledge base +- [ ] Understand testing strategy + +## ๐Ÿš€ Getting Started + +### 1. Environment Setup + +**Required Tools:** +- Node.js 18+ / Python 3.9+ / etc. +- Git +- IDE (VS Code recommended) +- Docker (optional) + +**Installation:** +\`\`\`bash +# Clone repository +git clone https://github.com/{org}/{repo}.git +cd {repo} + +# Install dependencies +npm install + +# Set up environment +cp .env.example .env +# Edit .env with your configuration + +# Run development server +npm run dev +\`\`\` + +### 2. Project Structure + +\`\`\` +project/ +โ”œโ”€โ”€ src/ # Source code +โ”‚ โ”œโ”€โ”€ components/ # UI components +โ”‚ โ”œโ”€โ”€ services/ # Business logic +โ”‚ โ””โ”€โ”€ utils/ # Utilities +โ”œโ”€โ”€ tests/ # Test files +โ”œโ”€โ”€ docs/ # Documentation +โ””โ”€โ”€ scripts/ # Build/deployment scripts +\`\`\` + +### 3. Key Concepts + +#### Architecture +{Brief architecture overview} + +See [ARCHITECTURE.md](./ARCHITECTURE.md) for details. + +#### Design Patterns + +*From Oracle knowledge base:* + +- **{Pattern 1}**: {Description} +- **{Pattern 2}**: {Description} +- **{Pattern 3}**: {Description} + +## ๐Ÿ“š Essential Reading + +1. **README.md** - Project overview +2. **ARCHITECTURE.md** - System architecture +3. **CONTRIBUTING.md** - Contribution guidelines +4. **docs/adr/** - Architecture decisions +5. **Oracle Knowledge** - Project-specific patterns and gotchas + +## ๐ŸŽฏ Common Tasks + +### Running Tests + +\`\`\`bash +# Run all tests +npm test + +# Run with coverage +npm run test:coverage + +# Run specific test file +npm test path/to/test.spec.ts +\`\`\` + +### Building + +\`\`\`bash +# Development build +npm run build:dev + +# Production build +npm run build:prod +\`\`\` + +### Debugging + +{Project-specific debugging tips} + +## โš ๏ธ Common Gotchas + +*From Oracle knowledge base:* + +### {Gotcha 1} +{Description and how to avoid} + +### {Gotcha 2} +{Description and how to avoid} + +### {Gotcha 3} +{Description and how to avoid} + +## ๐Ÿ”ง Development Workflow + +### 1. Pick a Task + +- Check the issue tracker +- Start with issues labeled \`good-first-issue\` +- Discuss approach with team if needed + +### 2. Create a Branch + +\`\`\`bash +git checkout -b feature/your-feature-name +# or +git checkout -b fix/bug-description +\`\`\` + +### 3. Make Changes + +- Follow coding standards +- Write tests +- Update documentation + +### 4. Commit + +\`\`\`bash +git add . +git commit -m "feat: add amazing feature" +\`\`\` + +We use [Conventional Commits](https://www.conventionalcommits.org/): +- \`feat:\` New feature +- \`fix:\` Bug fix +- \`docs:\` Documentation +- \`refactor:\` Code refactoring +- \`test:\` Tests +- \`chore:\` Maintenance + +### 5. Push and Create PR + +\`\`\`bash +git push origin feature/your-feature-name +\`\`\` + +Then create a Pull Request on GitHub. + +## ๐ŸŽจ Coding Standards + +### Style Guide + +{Link to style guide or summary} + +### Best Practices + +*From Oracle knowledge base:* + +1. **{Practice 1}**: {Description} +2. **{Practice 2}**: {Description} +3. **{Practice 3}**: {Description} + +### Code Review + +- All code must be reviewed +- Address all comments +- Ensure tests pass +- Update documentation + +## ๐Ÿงช Testing Strategy + +### Unit Tests + +\`\`\`typescript +describe('MyComponent', () => { + it('should render correctly', () => { + // Test code + }); +}); +\`\`\` + +### Integration Tests + +{Integration testing approach} + +### End-to-End Tests + +{E2E testing approach} + +## ๐Ÿ“– Learning Resources + +### Internal +- **Oracle Knowledge Base**: Project-specific learnings +- **ADRs**: Why we made certain decisions +- **Team Wiki**: {Link} + +### External +- {Relevant external resource 1} +- {Relevant external resource 2} +- {Relevant external resource 3} + +## ๐Ÿค Team + +### Communication Channels +- Slack: #{channel} +- Email: {team-email} +- Standups: {When/Where} + +### Key Contacts +- **Tech Lead**: {Name} +- **Product Owner**: {Name} +- **DevOps**: {Name} + +## โ“ FAQ + +### Q: How do I {common question}? +A: {Answer} + +### Q: Where can I find {common need}? +A: {Answer} + +### Q: What should I do if {common scenario}? +A: {Answer} + +## ๐ŸŽ“ Your First Week + +### Suggested Learning Path + +**Day 1-2:** +- Complete environment setup +- Read all documentation +- Run the project locally +- Explore the codebase + +**Day 3-4:** +- Pick a "good first issue" +- Make your first contribution +- Go through code review +- Merge your first PR + +**Day 5:** +- Retrospective on first week +- Questions and clarifications +- Plan for next week + +## ๐ŸŽ‰ Welcome Aboard! + +You're now part of the team! Don't hesitate to ask questions - everyone was new once. + +Remember: +- ๐Ÿ’ฌ Ask questions in {channel} +- ๐Ÿ“– Check Oracle knowledge base first +- ๐Ÿค Pair programming is encouraged +- ๐ŸŽฏ Focus on learning, not perfection + +--- + +*Generated by Documentation Wizard โ€ข Last updated: {date}* diff --git a/skills/documentation-wizard/References/readme-template.md b/skills/documentation-wizard/References/readme-template.md new file mode 100644 index 0000000..3c1560a --- /dev/null +++ b/skills/documentation-wizard/References/readme-template.md @@ -0,0 +1,153 @@ +# {Project Name} + +{Brief description of the project - one or two sentences} + +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) +[![Version](https://img.shields.io/badge/version-1.0.0-green.svg)](package.json) + +## Overview + +{Detailed description of what this project does, why it exists, and what problems it solves} + +## Features + +- โœจ {Feature 1} +- ๐Ÿš€ {Feature 2} +- ๐Ÿ”’ {Feature 3} +- ๐Ÿ“Š {Feature 4} + +## Quick Start + +### Prerequisites + +- Node.js 18+ (or other runtime) +- {Other prerequisites} + +### Installation + +\`\`\`bash +npm install +# or +yarn install +\`\`\` + +### Basic Usage + +\`\`\`typescript +import { Something } from '{package-name}'; + +// Example code here +const example = new Something(); +example.doSomething(); +\`\`\` + +## Documentation + +- ๐Ÿ“– [API Documentation](./docs/api/) +- ๐Ÿ—๏ธ [Architecture](./docs/ARCHITECTURE.md) +- ๐Ÿ“‹ [Architecture Decision Records](./docs/adr/) +- ๐ŸŽจ [Style Guide](./docs/STYLEGUIDE.md) +- ๐Ÿค [Contributing Guidelines](./CONTRIBUTING.md) + +## Configuration + +\`\`\`typescript +{ + // Configuration options + option1: "value1", + option2: "value2" +} +\`\`\` + +## Examples + +### Example 1: {Use case} + +\`\`\`typescript +// Code example +\`\`\` + +### Example 2: {Another use case} + +\`\`\`typescript +// Code example +\`\`\` + +## API Reference + +### Main API + +#### `functionName(param1, param2)` + +Description of what this function does. + +**Parameters:** +- `param1` (type): Description +- `param2` (type): Description + +**Returns:** Description of return value + +**Example:** +\`\`\`typescript +const result = functionName('value1', 'value2'); +\`\`\` + +## Architecture + +{Brief overview of the architecture} + +See [ARCHITECTURE.md](./docs/ARCHITECTURE.md) for detailed architecture documentation. + +## Development + +### Setup Development Environment + +\`\`\`bash +npm install +npm run dev +\`\`\` + +### Running Tests + +\`\`\`bash +npm test +npm run test:coverage +\`\`\` + +### Building + +\`\`\`bash +npm run build +\`\`\` + +## Contributing + +We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details. + +### Development Process + +1. Fork the repository +2. Create a feature branch (\`git checkout -b feature/amazing-feature\`) +3. Commit your changes (\`git commit -m 'Add amazing feature'\`) +4. Push to the branch (\`git push origin feature/amazing-feature\`) +5. Open a Pull Request + +## License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## Acknowledgments + +* {Credit to contributors} +* {Credit to inspirations} +* {Credit to tools/libraries used} + +## Support + +- ๐Ÿ“ง Email: {email} +- ๐Ÿ’ฌ Issues: [GitHub Issues](https://github.com/{user}/{repo}/issues) +- ๐Ÿ“– Documentation: [Full Docs](./docs/) + +--- + +*Generated by Documentation Wizard โ€ข Last updated: {date}* diff --git a/skills/documentation-wizard/SKILL.md b/skills/documentation-wizard/SKILL.md new file mode 100644 index 0000000..9798596 --- /dev/null +++ b/skills/documentation-wizard/SKILL.md @@ -0,0 +1,525 @@ +--- +name: documentation-wizard +description: Keeps documentation in perfect sync with code and knowledge. Integrates with Oracle to leverage learnings, Summoner for design docs, and Style Master for style guides. Auto-generates and updates README, API docs, ADRs, and onboarding materials. Detects stale documentation and ensures it evolves with the codebase. +allowed-tools: Read, Write, Edit, Glob, Grep, Task, Bash +--- + +# Documentation Wizard: Living Documentation Expert + +You are now operating as the **Documentation Wizard**, a specialist in creating and maintaining living documentation that stays synchronized with code, decisions, and learnings. + +## Core Philosophy + +**"Documentation is code. It should be tested, reviewed, and maintained with the same rigor."** + +Documentation Wizard operates on these principles: + +1. **Living, Not Static**: Documentation evolves with the codebase +2. **Single Source of Truth**: One place for each piece of information +3. **Automated Synchronization**: Reduce manual documentation burden +4. **Context-Aware**: Leverage Oracle, Summoner, Style Master knowledge +5. **User-Focused**: Write for the audience (developers, users, stakeholders) +6. **Examples Over Explanations**: Show, don't just tell + +## Core Responsibilities + +### 1. Documentation Synchronization + +**Sync Sources**: +- **Oracle Knowledge**: Patterns, decisions, gotchas, solutions +- **Summoner MCDs**: Design decisions, architectural choices +- **Style Master Style Guides**: Design system documentation +- **Code Comments**: Extract structured documentation +- **Git History**: Track evolution and decisions +- **Test Files**: Generate examples from tests + +**Sync Targets**: +- README files (project, package, component) +- API documentation (OpenAPI, GraphQL schemas, JSDoc) +- Architecture Decision Records (ADRs) +- Onboarding guides +- Changelog +- Style guides +- Contributing guidelines + +### 2. Documentation Generation + +**Auto-Generate**: + +**README Files**: +```markdown +# Project Name + +## Overview +[From package.json description + Oracle context] + +## Installation +[Auto-detected from package.json scripts] + +## Usage +[Generated from examples and tests] + +## API Reference +[From code comments and type definitions] + +## Architecture +[From Summoner MCDs and Oracle patterns] + +## Contributing +[Standard template + project-specific guidelines] +``` + +**API Documentation**: +- Extract JSDoc/TypeDoc comments +- Generate OpenAPI specs from code +- Create GraphQL schema documentation +- Build SDK documentation + +**Architecture Decision Records (ADRs)**: +```markdown +# ADR-XXX: [Decision Title] + +Date: [From Oracle session or git log] +Status: [Accepted/Deprecated/Superseded] + +## Context +[From Oracle decision log or Summoner MCD] + +## Decision +[What was decided] + +## Consequences +[Positive and negative outcomes] + +## Alternatives Considered +[From Summoner MCD or Oracle] +``` + +### 3. Documentation Validation + +**Detect Issues**: +- โŒ Stale documentation (code changed, docs didn't) +- โŒ Missing documentation (public API without docs) +- โŒ Broken links (internal and external) +- โŒ Outdated examples (code examples don't run) +- โŒ Inconsistencies (contradictory information) +- โŒ Missing images/diagrams (referenced but not found) + +**Validation Checks**: +```bash +# Run validation +python .claude/skills/documentation-wizard/scripts/validate_docs.py + +# Output: +โœ… README.md is up-to-date +โš ๏ธ API docs missing for 3 new functions +โŒ ARCHITECTURE.md references removed module +โœ… All code examples validated +``` + +### 4. Oracle Integration + +**Leverage Oracle Knowledge**: + +```json +{ + "category": "pattern", + "title": "Use factory pattern for database connections", + "content": "All database connections through DatabaseFactory.create()", + "context": "When creating database connections" +} +``` + +**Generate Documentation Section**: +```markdown +## Database Connections + +All database connections should be created through the `DatabaseFactory`: + +\`\`\`typescript +const db = DatabaseFactory.create('postgres', config); +\`\`\` + +This ensures connection pooling and error handling. See [Architecture Decision Records](./docs/adr/001-database-factory.md). +``` + +**From Oracle Corrections** โ†’ **Update Documentation**: +```json +{ + "category": "correction", + "content": "โŒ Wrong: element.innerHTML = userInput\nโœ“ Right: element.textContent = userInput" +} +``` + +**Generates Warning in Docs**: +```markdown +## Security Considerations + +โš ๏ธ **Never use `innerHTML` with user input** - this creates XSS vulnerabilities. Always use `textContent` or a sanitization library like DOMPurify. +``` + +### 5. Summoner Integration + +**From Mission Control Documents** โ†’ **Design Documentation**: + +When Summoner completes a mission, Documentation Wizard: +1. Extracts key decisions from MCD +2. Creates/updates ADRs +3. Updates architecture documentation +4. Adds examples to relevant docs +5. Updates changelog + +### 6. Style Master Integration + +**Sync Style Guide**: +- Pull design tokens from Style Master +- Include component examples +- Show accessibility guidelines +- Document theme customization + +## Workflow + +### Initial Documentation Generation + +``` +1. Analyze codebase structure + โ†“ +2. Load Oracle knowledge + โ†“ +3. Detect documentation needs + โ†“ +4. Generate initial docs from templates + โ†“ +5. Populate with code-derived content + โ†“ +6. Add Oracle context and patterns + โ†“ +7. Validate and format +``` + +### Continuous Synchronization + +``` +1. Detect code changes (git diff) + โ†“ +2. Identify affected documentation + โ†“ +3. Load relevant Oracle/Summoner context + โ†“ +4. Update documentation sections + โ†“ +5. Validate examples still work + โ†“ +6. Flag manual review items + โ†“ +7. Commit documentation updates +``` + +### Documentation Review + +``` +1. Run validation checks + โ†“ +2. Identify stale sections + โ†“ +3. Check broken links + โ†“ +4. Validate code examples + โ†“ +5. Generate report + โ†“ +6. Suggest updates +``` + +## Documentation Types + +### README Documentation + +**Project README**: +- Clear overview and value proposition +- Installation instructions (tested) +- Quick start guide with examples +- Link to detailed documentation +- Contributing guidelines +- License information + +**Package/Module README**: +- Purpose and use cases +- API overview +- Installation and setup +- Usage examples +- Configuration options + +### API Documentation + +**From Code**: +```typescript +/** + * Creates a new user account + * + * @param email - User's email address + * @param password - Must be at least 8 characters + * @returns The created user object + * @throws {ValidationError} If email is invalid + * @throws {ConflictError} If user already exists + * + * @example + * ```typescript + * const user = await createUser('user@example.com', 'password123'); + * console.log(user.id); + * ``` + */ +async function createUser(email: string, password: string): Promise +``` + +**Generates**: +Structured API documentation with type information, examples, and error cases. + +### Architecture Decision Records (ADRs) + +**Track Important Decisions**: +- Technology choices (React vs Vue, SQL vs NoSQL) +- Architecture patterns (microservices, event-driven) +- Library selections (auth provider, testing framework) +- Design system decisions (Tailwind vs styled-components) + +**ADR Template**: +```markdown +# ADR-{number}: {Short title} + +Date: {YYYY-MM-DD} +Status: {Proposed|Accepted|Deprecated|Superseded} +Deciders: {Who made this decision} + +## Context and Problem Statement + +{Describe the context and problem} + +## Decision Drivers + +* {Driver 1} +* {Driver 2} + +## Considered Options + +* {Option 1} +* {Option 2} +* {Option 3} + +## Decision Outcome + +Chosen option: "{Option X}", because {reasons}. + +### Positive Consequences + +* {Benefit 1} +* {Benefit 2} + +### Negative Consequences + +* {Drawback 1} +* {Drawback 2} + +## Links + +* {Related ADRs} +* {Related Oracle entries} +* {Related Summoner MCDs} +``` + +### Onboarding Documentation + +**Generated from Oracle Sessions**: +- Common questions and answers +- Setup procedures that worked +- Gotchas new developers encounter +- Recommended learning path +- Links to key resources + +## Scripts & Tools + +### Documentation Generator + +```bash +python .claude/skills/documentation-wizard/scripts/generate_docs.py +``` + +**Generates**: +- README from template + code analysis +- API docs from code comments +- Architecture docs from Oracle/Summoner +- Onboarding guide from Oracle sessions + +### Documentation Validator + +```bash +python .claude/skills/documentation-wizard/scripts/validate_docs.py +``` + +**Checks**: +- Stale documentation +- Missing documentation +- Broken links +- Invalid code examples +- Inconsistencies + +### Documentation Syncer + +```bash +python .claude/skills/documentation-wizard/scripts/sync_docs.py --source oracle +``` + +**Syncs**: +- Oracle knowledge โ†’ README sections +- Summoner MCDs โ†’ ADRs +- Style Master style guide โ†’ design docs +- Code comments โ†’ API docs + +### Changelog Generator + +```bash +python .claude/skills/documentation-wizard/scripts/generate_changelog.py +``` + +**From**: +- Git commit messages +- Oracle session logs +- Summoner MCD summaries + +**Generates**: +- Semantic changelog (Added/Changed/Fixed/Deprecated/Removed) +- Release notes +- Migration guides + +## Templates + +- **README Template**: See `References/readme-template.md` +- **ADR Template**: See `References/adr-template.md` +- **API Doc Template**: See `References/api-doc-template.md` +- **Onboarding Template**: See `References/onboarding-template.md` +- **Contributing Template**: See `References/contributing-template.md` + +## Integration Examples + +### Example 1: New Feature Documented + +**Flow**: +1. Summoner orchestrates feature implementation +2. Oracle records new patterns used +3. Code is written with JSDoc comments +4. Documentation Wizard triggers: + - Extracts JSDoc โ†’ API docs + - Reads Oracle patterns โ†’ README update + - Reads Summoner MCD โ†’ Creates ADR + - Generates examples from tests + - Updates changelog + +### Example 2: Correction Documented + +**Oracle Records Correction**: +```json +{ + "category": "correction", + "title": "Don't use Date() for timestamps", + "content": "โŒ Wrong: new Date()\nโœ“ Right: Date.now()\nReason: Performance and consistency" +} +``` + +**Documentation Wizard Updates**: +- Adds warning to relevant API docs +- Updates best practices section +- Generates "Common Mistakes" section +- Links to Oracle entry + +### Example 3: Style Guide Sync + +**Style Master Updates Style Guide**: +```markdown +## Colors +- Primary: #007bff +- Secondary: #6c757d +``` + +**Documentation Wizard**: +- Syncs to main documentation +- Updates component examples +- Generates theme customization docs +- Links to Style Master style guide + +## Success Indicators + +โœ… **Documentation Wizard is working when**: +- Docs always in sync with code +- New features automatically documented +- ADRs created for major decisions +- Onboarding guides current +- No broken links or stale examples +- Changes trigger doc updates +- Developers trust the documentation + +โŒ **Warning signs**: +- Docs out of sync with code +- Missing documentation for new features +- Broken links accumulating +- Code examples don't run +- No one reads the docs (sign of poor quality) + +## Best Practices + +### 1. Document WHY, Not Just WHAT + +โŒ Bad: +```markdown +## createUser() +Creates a user. +``` + +โœ… Good: +```markdown +## createUser() +Creates a new user account with email verification. We use email verification (not phone) because our user research showed 87% prefer email. See [ADR-023](./adr/023-email-verification.md). +``` + +### 2. Keep Examples Executable + +All code examples should be: +- Tested (ideally extracted from actual tests) +- Copy-pasteable +- Include necessary imports +- Show expected output + +### 3. Use Oracle as Documentation Source + +Oracle has the WHY behind decisions. Use it: +```markdown + +## Architecture Patterns + +We use the factory pattern for all database connections. This decision was made because [Oracle entry #42: connection pooling requirement]. + +``` + +### 4. Link Everything + +- Link to related ADRs +- Link to Oracle entries +- Link to Summoner MCDs +- Link to Style Master style guide +- Link to code files +- Link to external resources + +## Remember + +> "Documentation is love letter to your future self." + +Your role as Documentation Wizard: +1. **Keep docs synchronized** with code, decisions, learnings +2. **Leverage integrations** with Oracle, Summoner, Style Master +3. **Automate ruthlessly** - reduce manual documentation burden +4. **Validate constantly** - catch issues early +5. **Focus on users** - developers are users of documentation +6. **Make it living** - docs that evolve with the project + +--- + +**Documentation Wizard activated. Documentation will never be stale again.** diff --git a/skills/documentation-wizard/scripts/generate_changelog.py b/skills/documentation-wizard/scripts/generate_changelog.py new file mode 100755 index 0000000..194aa08 --- /dev/null +++ b/skills/documentation-wizard/scripts/generate_changelog.py @@ -0,0 +1,185 @@ +#!/usr/bin/env python3 +""" +Changelog Generator + +Generates semantic changelog from git history and Oracle sessions. + +Usage: + python generate_changelog.py + python generate_changelog.py --since v1.0.0 + python generate_changelog.py --format markdown|json +""" + +import os +import sys +import json +import argparse +import subprocess +from pathlib import Path +from datetime import datetime +from collections import defaultdict + + +def get_git_commits(since=None): + """Get git commits since a tag or date.""" + cmd = ['git', 'log', '--pretty=format:%H|%s|%an|%ad', '--date=short'] + + if since: + cmd.append(f'{since}..HEAD') + + try: + result = subprocess.run(cmd, capture_output=True, text=True, check=True) + commits = [] + + for line in result.stdout.strip().split('\n'): + if line: + hash, subject, author, date = line.split('|') + commits.append({ + 'hash': hash[:7], + 'subject': subject, + 'author': author, + 'date': date + }) + + return commits + except subprocess.CalledProcessError: + return [] + + +def categorize_commit(subject): + """Categorize commit by type.""" + subject_lower = subject.lower() + + # Check for conventional commits + if subject.startswith('feat:') or 'add' in subject_lower or 'new' in subject_lower: + return 'added' + elif subject.startswith('fix:') or 'fix' in subject_lower: + return 'fixed' + elif subject.startswith('docs:') or 'document' in subject_lower or 'readme' in subject_lower: + return 'documentation' + elif subject.startswith('refactor:') or 'refactor' in subject_lower: + return 'changed' + elif 'deprecat' in subject_lower: + return 'deprecated' + elif 'remov' in subject_lower or 'delet' in subject_lower: + return 'removed' + elif 'perf' in subject_lower or 'optim' in subject_lower: + return 'performance' + elif 'security' in subject_lower: + return 'security' + else: + return 'changed' + + +def generate_markdown_changelog(changes_by_category, version='Unreleased'): + """Generate markdown changelog.""" + changelog = f"# Changelog\n\n" + changelog += f"All notable changes to this project will be documented in this file.\n\n" + changelog += f"## [{version}] - {datetime.now().strftime('%Y-%m-%d')}\n\n" + + category_order = ['added', 'changed', 'deprecated', 'removed', 'fixed', 'security', 'performance', 'documentation'] + category_titles = { + 'added': 'Added', + 'changed': 'Changed', + 'deprecated': 'Deprecated', + 'removed': 'Removed', + 'fixed': 'Fixed', + 'security': 'Security', + 'performance': 'Performance', + 'documentation': 'Documentation' + } + + for category in category_order: + if category in changes_by_category and changes_by_category[category]: + changelog += f"### {category_titles[category]}\n\n" + for change in changes_by_category[category]: + changelog += f"- {change['subject']} ({change['hash']})\n" + changelog += "\n" + + return changelog + + +def main(): + parser = argparse.ArgumentParser( + description='Generate changelog from git history' + ) + + parser.add_argument( + '--since', + type=str, + help='Generate changelog since this tag or commit' + ) + + parser.add_argument( + '--version', + type=str, + default='Unreleased', + help='Version for this changelog' + ) + + parser.add_argument( + '--format', + choices=['markdown', 'json'], + default='markdown', + help='Output format' + ) + + parser.add_argument( + '--output', + type=str, + default='CHANGELOG.md', + help='Output file' + ) + + args = parser.parse_args() + + print(f"[NOTE] Generating changelog...") + + # Get commits + commits = get_git_commits(args.since) + + if not commits: + print(" [WARNING] No commits found") + return + + print(f" [INFO] Found {len(commits)} commits") + + # Categorize commits + changes_by_category = defaultdict(list) + + for commit in commits: + category = categorize_commit(commit['subject']) + changes_by_category[category].append(commit) + + # Generate changelog + if args.format == 'markdown': + changelog = generate_markdown_changelog(changes_by_category, args.version) + + with open(args.output, 'w') as f: + f.write(changelog) + + print(f" [OK] Generated {args.output}") + + # Print summary + print(f"\n Summary:") + for category, changes in changes_by_category.items(): + print(f" {category.capitalize()}: {len(changes)}") + + elif args.format == 'json': + output = { + 'version': args.version, + 'date': datetime.now().strftime('%Y-%m-%d'), + 'changes': dict(changes_by_category) + } + + output_file = Path(args.output).with_suffix('.json') + with open(output_file, 'w') as f: + json.dump(output, f, indent=2) + + print(f" [OK] Generated {output_file}") + + print("\n[OK] Changelog generated successfully!") + + +if __name__ == '__main__': + main() diff --git a/skills/documentation-wizard/scripts/generate_docs.py b/skills/documentation-wizard/scripts/generate_docs.py new file mode 100755 index 0000000..66d3cc6 --- /dev/null +++ b/skills/documentation-wizard/scripts/generate_docs.py @@ -0,0 +1,64 @@ +#!/usr/bin/env python3 +"""Documentation generator - creates documentation from code and knowledge.""" +import sys +import json +from pathlib import Path +from datetime import datetime + +def generate_readme(project_path): + """Generate README from project structure.""" + package_json = project_path / 'package.json' + name = project_path.name + description = "Project description" + + if package_json.exists(): + with open(package_json) as f: + data = json.load(f) + name = data.get('name', name) + description = data.get('description', description) + + readme = f"""# {name} + +{description} + +## Installation + +\`\`\`bash +npm install +\`\`\` + +## Usage + +\`\`\`typescript +// Add usage examples here +\`\`\` + +## Documentation + +- [API Documentation](./docs/api/) +- [Architecture Decision Records](./docs/adr/) +- [Contributing Guidelines](./CONTRIBUTING.md) + +## License + +See LICENSE file. + +--- + +*Generated by Documentation Wizard on {datetime.now().strftime('%Y-%m-%d')}* +""" + + output = project_path / 'README.md' + with open(output, 'w') as f: + f.write(readme) + + print(f"[OK] Generated: {output}") + +def main(): + project = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve() + print(f"[NOTE] Generating documentation for: {project}\n") + generate_readme(project) + print("\n[OK] Documentation generated!") + +if __name__ == '__main__': + main() diff --git a/skills/documentation-wizard/scripts/sync_docs.py b/skills/documentation-wizard/scripts/sync_docs.py new file mode 100755 index 0000000..ac5e382 --- /dev/null +++ b/skills/documentation-wizard/scripts/sync_docs.py @@ -0,0 +1,210 @@ +#!/usr/bin/env python3 +""" +Documentation Synchronization Script + +Syncs documentation from Oracle knowledge, Summoner MCDs, and Style Master guides. + +Usage: + python sync_docs.py --source oracle + python sync_docs.py --source summoner + python sync_docs.py --source style-master + python sync_docs.py --source all +""" + +import os +import sys +import json +import argparse +from pathlib import Path +from datetime import datetime + + +def find_oracle_root(): + """Find .oracle directory.""" + current = Path.cwd() + while current != current.parent: + oracle_path = current / '.oracle' + if oracle_path.exists(): + return oracle_path + current = current.parent + return None + + +def sync_from_oracle(oracle_path, output_dir): + """Sync documentation from Oracle knowledge base.""" + print(" Syncing from Oracle knowledge base...") + + knowledge_dir = oracle_path / 'knowledge' + if not knowledge_dir.exists(): + print(" [WARNING] No Oracle knowledge found") + return + + patterns_file = knowledge_dir / 'patterns.json' + gotchas_file = knowledge_dir / 'gotchas.json' + + sections = [] + + # Load patterns + if patterns_file.exists(): + with open(patterns_file, 'r') as f: + patterns = json.load(f) + + if patterns: + sections.append("## Architecture Patterns\n") + sections.append("*From Oracle knowledge base*\n\n") + + for pattern in patterns[:10]: # Top 10 + title = pattern.get('title', 'Untitled') + content = pattern.get('content', '') + sections.append(f"### {title}\n\n{content}\n\n") + + # Load gotchas + if gotchas_file.exists(): + with open(gotchas_file, 'r') as f: + gotchas = json.load(f) + + if gotchas: + sections.append("## Known Issues & Gotchas\n") + sections.append("*From Oracle knowledge base*\n\n") + + for gotcha in gotchas[:10]: + title = gotcha.get('title', 'Untitled') + content = gotcha.get('content', '') + priority = gotcha.get('priority', 'medium') + emoji = {'critical': '', 'high': '', 'medium': '', 'low': ''}.get(priority, '') + sections.append(f"### {emoji} {title}\n\n{content}\n\n") + + if sections: + # Write to ARCHITECTURE.md + output_file = output_dir / 'ARCHITECTURE.md' + with open(output_file, 'w') as f: + f.write(f"# Architecture Documentation\n\n") + f.write(f"*Last updated: {datetime.now().strftime('%Y-%m-%d %H:%M')}*\n\n") + f.write(''.join(sections)) + + print(f" [OK] Created {output_file}") + print(f" [NOTE] Synced {len(patterns if patterns_file.exists() else [])} patterns, {len(gotchas if gotchas_file.exists() else [])} gotchas") + else: + print(" [WARNING] No patterns or gotchas to sync") + + +def sync_from_style_master(project_path, output_dir): + """Sync from Style Master style guide.""" + print(" Syncing from Style Master...") + + style_guide = project_path / 'STYLEGUIDE.md' + if style_guide.exists(): + # Copy style guide to docs + output_file = output_dir / 'STYLEGUIDE.md' + with open(style_guide, 'r') as f: + content = f.read() + + with open(output_file, 'w') as f: + f.write(content) + + print(f" [OK] Synced {output_file}") + else: + print(" [WARNING] No STYLEGUIDE.md found") + + +def sync_from_summoner(project_path, output_dir): + """Sync from Summoner Mission Control Documents.""" + print(" Syncing from Summoner MCDs...") + + # Look for mission-*.md files + mcds = list(project_path.glob('mission-*.md')) + + if not mcds: + print(" [WARNING] No Summoner MCDs found") + return + + adr_dir = output_dir / 'adr' + adr_dir.mkdir(exist_ok=True) + + for mcd in mcds: + print(f" Processing {mcd.name}") + + with open(mcd, 'r') as f: + content = f.read() + + # Extract decisions from MCD + if '## Decisions' in content: + decisions_section = content.split('## Decisions')[1].split('\n\n')[0] + + # Create ADR + adr_num = len(list(adr_dir.glob('*.md'))) + 1 + adr_file = adr_dir / f'{adr_num:03d}-from-{mcd.stem}.md' + + adr_content = f"""# ADR-{adr_num:03d}: Decisions from {mcd.stem} + +Date: {datetime.now().strftime('%Y-%m-%d')} +Status: Accepted +Source: Summoner MCD {mcd.name} + +## Context + +From Mission Control Document: {mcd.name} + +## Decisions + +{decisions_section} + +## Links + +- Source MCD: {mcd.name} +""" + + with open(adr_file, 'w') as f: + f.write(adr_content) + + print(f" [OK] Created ADR: {adr_file.name}") + + +def main(): + parser = argparse.ArgumentParser( + description='Sync documentation from various sources' + ) + + parser.add_argument( + '--source', + choices=['oracle', 'summoner', 'style-master', 'all'], + default='all', + help='Source to sync from' + ) + + parser.add_argument( + '--output', + type=str, + default='docs', + help='Output directory (default: docs/)' + ) + + args = parser.parse_args() + + project_path = Path.cwd() + output_dir = project_path / args.output + output_dir.mkdir(exist_ok=True) + + print(f" Syncing documentation to {output_dir}\n") + + if args.source in ['oracle', 'all']: + oracle_path = find_oracle_root() + if oracle_path: + sync_from_oracle(oracle_path, output_dir) + else: + print("[WARNING] Oracle not initialized for this project") + print() + + if args.source in ['style-master', 'all']: + sync_from_style_master(project_path, output_dir) + print() + + if args.source in ['summoner', 'all']: + sync_from_summoner(project_path, output_dir) + print() + + print("[OK] Documentation sync complete!") + + +if __name__ == '__main__': + main() diff --git a/skills/documentation-wizard/scripts/validate_docs.py b/skills/documentation-wizard/scripts/validate_docs.py new file mode 100755 index 0000000..9e4bf3f --- /dev/null +++ b/skills/documentation-wizard/scripts/validate_docs.py @@ -0,0 +1,47 @@ +#!/usr/bin/env python3 +"""Documentation validator - checks for stale docs and issues.""" +import sys +from pathlib import Path +import re + +def validate_docs(project_path): + """Validate documentation.""" + issues = [] + + # Check README exists + readme = project_path / 'README.md' + if not readme.exists(): + issues.append("[ERROR] README.md missing") + else: + print("[OK] README.md found") + + # Check for broken internal links + content = readme.read_text() + links = re.findall(r'\[([^\]]+)\]\(([^)]+)\)', content) + for text, link in links: + if not link.startswith('http'): + link_path = project_path / link.lstrip('./') + if not link_path.exists(): + issues.append(f"[ERROR] Broken link in README: {link}") + + # Check for CONTRIBUTING.md + if not (project_path / 'CONTRIBUTING.md').exists(): + issues.append("[WARNING] CONTRIBUTING.md missing (recommended)") + + return issues + +def main(): + project = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve() + print(f"[SEARCH] Validating documentation for: {project}\n") + + issues = validate_docs(project) + + if issues: + print("\nIssues found:") + for issue in issues: + print(f" {issue}") + else: + print("\n[OK] All documentation checks passed!") + +if __name__ == '__main__': + main()