zhongwei/gh-overlord-z-claudeshack-documentation-wizard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:46:53 +08:00
commit 5efae030be
12 changed files with 1857 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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"
]
}

3
README.md Normal file
View File

@@ -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.

76
plugin.lock.json Normal file
View File

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

222
skills/documentation-wizard/README.md Normal file
View File

@@ -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

74
skills/documentation-wizard/References/adr-template.md Normal file
View File

@@ -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}

286
skills/documentation-wizard/References/onboarding-template.md Normal file
View File

@@ -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}*

153
skills/documentation-wizard/References/readme-template.md Normal file
View File

@@ -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}*

525
skills/documentation-wizard/SKILL.md Normal file
View File

@@ -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<User>
```
**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
<!-- AUTO-GENERATED FROM ORACLE -->
## Architecture Patterns
We use the factory pattern for all database connections. This decision was made because [Oracle entry #42: connection pooling requirement].
<!-- END AUTO-GENERATED -->
```
### 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.**

185
skills/documentation-wizard/scripts/generate_changelog.py Executable file
View File

@@ -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()

64
skills/documentation-wizard/scripts/generate_docs.py Executable file
View File

@@ -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()

210
skills/documentation-wizard/scripts/sync_docs.py Executable file
View File

@@ -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()

47
skills/documentation-wizard/scripts/validate_docs.py Executable file
View File

@@ -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()