Initial commit
This commit is contained in:
Zhongwei Li
12
.claude-plugin/plugin.json
Normal file
12
.claude-plugin/plugin.json
Normal 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
3
README.md
Normal 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
76
plugin.lock.json
Normal 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
222
skills/documentation-wizard/README.md
Normal 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
74
skills/documentation-wizard/References/adr-template.md
Normal 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
286
skills/documentation-wizard/References/onboarding-template.md
Normal 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
153
skills/documentation-wizard/References/readme-template.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# {Project Name}
|
||||
|
||||
{Brief description of the project - one or two sentences}
|
||||
|
||||
[](LICENSE)
|
||||
[](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
525
skills/documentation-wizard/SKILL.md
Normal 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
185
skills/documentation-wizard/scripts/generate_changelog.py
Executable 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
64
skills/documentation-wizard/scripts/generate_docs.py
Executable 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
210
skills/documentation-wizard/scripts/sync_docs.py
Executable 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
47
skills/documentation-wizard/scripts/validate_docs.py
Executable 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()
|
||||
Reference in New Issue
Block a user