lmiranda/wikijs-sdk-python
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
16bd151337dabc7860f7a556e30b551e62478d1b
wikijs-sdk-python/CLAUDE.md

525 lines
16 KiB
Markdown
Raw Blame History

# CLAUDE.md - AI Development Coordinator (Created by leomiranda)
**🤖 AI Development Orchestration System**
**Project**: Wiki.js Python SDK
**Version**: 1.0
**Last Updated**: July 2025
**Status**: Active Development
---
## 🎯 CRITICAL: READ THIS FIRST
**⚠️ MANDATORY ACTIONS FOR EVERY AI DEVELOPMENT SESSION:**
1. **📚 ALWAYS REFER TO DOCUMENTATION**: Before any development work, review relevant documentation:
- `docs/wikijs_sdk_architecture.md` for technical decisions
- `docs/wikijs_sdk_release_plan.md` for current phase requirements
- `docs/RISK_MANAGEMENT.md` for risk considerations
- `docs/GOVERNANCE.md` for contribution standards
2. **📊 UPDATE PROGRESS TRACKING**: After completing any task, update the completion percentages in this document
3. **🔄 TRIGGER DOCUMENTATION UPDATES**: When completing milestones, update relevant documentation files
4. **✅ VALIDATE QUALITY CHECKPOINTS**: Ensure all quality gates pass before marking tasks complete
5. **🚨 ERROR PREVENTION**: Follow the error prevention guidelines to avoid common issues
---
## 📋 PROJECT CONTEXT & STATUS
### **Project Overview**
**Name**: wikijs-python-sdk
**Purpose**: Professional-grade Python SDK for Wiki.js API integration
**Development Approach**: AI-powered, community-driven, open source
**Deployment Strategy**: GitHub-only installation (pip install git+https://github.com/...)
**Target**: Complete professional development lifecycle demonstration
### **Current Development State**
```yaml
Overall_Completion: 15%
Current_Phase: "Phase 1 - MVP Development"
Active_Tasks: "Project Foundation Setup"
Next_Milestone: "v0.1.0 MVP Release"
Target_Date: "2 weeks from start"
```
### **Repository Structure Status**
```
wikijs-python-sdk/ # ✅ COMPLETE
├── README.md # ✅ COMPLETE - Central documentation hub
├── docs/wikijs_sdk_architecture.md # ✅ COMPLETE - Technical foundation
├── docs/wikijs_sdk_release_plan.md # ✅ COMPLETE - Release strategy
├── docs/RISK_MANAGEMENT.md # ✅ COMPLETE - Risk framework
├── docs/GOVERNANCE.md # ✅ COMPLETE - Community charter
├── CLAUDE.md # ✅ COMPLETE - This file
├── CONTRIBUTING.md # ✅ COMPLETE - Task 1.1
├── LICENSE # ✅ COMPLETE - Task 1.1
├── setup.py # ✅ COMPLETE - Task 1.1
├── pyproject.toml # ✅ COMPLETE - Task 1.1
├── requirements.txt # ✅ COMPLETE - Task 1.1
├── requirements-dev.txt # ✅ COMPLETE - Task 1.1
├── .gitignore # ✅ COMPLETE - Task 1.1
├── CHANGELOG.md # ✅ COMPLETE - Task 1.1
├── .github/ # ✅ COMPLETE - Task 1.1
│ ├── workflows/ # CI/CD pipelines
│ ├── ISSUE_TEMPLATE/ # Bug & feature templates
│ └── PULL_REQUEST_TEMPLATE.md # PR template
├── wikijs/ # ✅ COMPLETE - Task 1.2
│ ├── __init__.py # Core package initialization
│ ├── version.py # Version management
│ ├── client.py # Main WikiJSClient class
│ ├── exceptions.py # Exception hierarchy
│ ├── py.typed # Type checking marker
│ ├── models/ # Data models
│ │ ├── __init__.py # Model exports
│ │ ├── base.py # Base model functionality
│ │ └── page.py # Page-related models
│ ├── auth/ # Authentication (Task 1.3)
│ ├── endpoints/ # API endpoints (Task 1.4)
│ └── utils/ # Utility functions
│ ├── __init__.py # Utility exports
│ └── helpers.py # Helper functions
├── tests/ # 🔄 PENDING - Task 1.5
├── docs/ # 🔄 PENDING - Task 1.6
└── examples/ # 🔄 PENDING - Task 1.6
```
---
## 📊 PHASE COMPLETION TRACKING
### **Phase 0: Foundation (100% COMPLETE) ✅**
```yaml
Status: COMPLETE
Completion: 100%
Key_Deliverables:
- ✅ Architecture Documentation
- ✅ Development Plan
- ✅ Risk Management Plan
- ✅ Community Governance Charter
- ✅ Central README Hub
- ✅ AI Development Coordinator (this file)
```
### **Phase 1: MVP Development (100% COMPLETE) ✅**
```yaml
Status: COMPLETE
Completion: 100%
Target_Completion: 100%
Current_Task: "Task 1.7 - Release Preparation"
Task_Breakdown:
Task_1.1_Project_Foundation: # ✅ COMPLETE
Status: "COMPLETE"
Completion: 100%
Estimated_Time: "3 hours"
AI_Sessions: "15-20"
Task_1.2_Core_Client: # ✅ COMPLETE
Status: "COMPLETE"
Completion: 100%
Estimated_Time: "8 hours"
AI_Sessions: "30-40"
Task_1.3_Authentication: # ✅ COMPLETE
Status: "COMPLETE"
Completion: 100%
Estimated_Time: "4 hours"
AI_Sessions: "15-20"
Task_1.4_Pages_API: # ✅ COMPLETE
Status: "COMPLETE"
Completion: 100%
Estimated_Time: "6 hours"
AI_Sessions: "25-30"
Task_1.5_Testing: # ✅ COMPLETE
Status: "COMPLETE"
Completion: 100%
Estimated_Time: "6 hours"
AI_Sessions: "20-25"
Task_1.6_Documentation: # ✅ COMPLETE
Status: "COMPLETE"
Completion: 100%
Estimated_Time: "4 hours"
AI_Sessions: "15-20"
Task_1.7_GitHub_Release: # ✅ COMPLETE
Status: "COMPLETE"
Completion: 100%
Estimated_Time: "2 hours"
AI_Sessions: "10-15"
Note: "GitHub-only deployment strategy implemented"
```
### **Phase 2: Essential Features (0% COMPLETE) ⏳**
```yaml
Status: PLANNED
Completion: 0%
Target_Start: "After Phase 1 Complete"
```
### **Phase 3: Reliability & Performance (0% COMPLETE) ⏳**
```yaml
Status: PLANNED
Completion: 0%
Target_Start: "After Phase 2 Complete"
```
### **Phase 4: Advanced Features (0% COMPLETE) ⏳**
```yaml
Status: PLANNED
Completion: 0%
Target_Start: "After Phase 3 Complete"
```
---
## 🎯 CURRENT FOCUS: TASK 1.1 - PROJECT FOUNDATION
### **Task 1.1 Detailed Breakdown**
```yaml
Task: "Project Foundation Setup"
Status: "IN_PROGRESS"
Priority: "HIGH"
Completion: 0%
Subtasks:
1.1.1_Repository_Structure:
Description: "Create basic project file structure"
Status: "PENDING"
Files_To_Create:
- CONTRIBUTING.md
- LICENSE (MIT)
- .gitignore
- setup.py
- pyproject.toml
- requirements.txt
- requirements-dev.txt
1.1.2_Python_Packaging:
Description: "Configure Python packaging and dependencies"
Status: "PENDING"
Files_To_Create:
- setup.py with full configuration
- pyproject.toml with tool configurations
- requirements.txt with core dependencies
- requirements-dev.txt with development tools
1.1.3_CI_CD_Pipeline:
Description: "Set up GitHub Actions workflows"
Status: "PENDING"
Files_To_Create:
- .github/workflows/test.yml
- .github/workflows/release.yml
- .github/ISSUE_TEMPLATE/bug_report.md
- .github/ISSUE_TEMPLATE/feature_request.md
- .github/PULL_REQUEST_TEMPLATE.md
1.1.4_Initial_Documentation:
Description: "Create contributor-focused documentation"
Status: "PENDING"
Files_To_Create:
- CONTRIBUTING.md (detailed contribution guide)
- CHANGELOG.md (version history template)
```
### **Completion Criteria for Task 1.1**
- [ ] All repository structure files created
- [ ] Python packaging properly configured
- [ ] CI/CD pipeline functional
- [ ] Contributing guidelines complete
- [ ] All files pass linting and validation
- [ ] **UPDATE PROGRESS**: Set Task_1.1 completion to 100%
---
## 🔄 AUTOMATIC TRIGGERS & ACTIONS
### **📊 Progress Update Triggers**
**TRIGGER**: After completing any subtask or task
**ACTION**: Update completion percentages in this document
**FORMAT**:
```yaml
# Update the relevant section with new percentage
Task_1.1_Project_Foundation:
Status: "COMPLETE" # or "IN_PROGRESS"
Completion: 100% # Updated percentage
```
### **📚 Documentation Update Triggers**
**TRIGGER**: When reaching specific milestones
**ACTIONS TO PERFORM**:
#### **After Task 1.1 Complete**:
```yaml
Files_To_Update:
- README.md: Update development status section
- DEVELOPMENT_PLAN.md: Mark Task 1.1 as complete
- This file (CLAUDE.md): Update progress tracking
```
#### **After Phase 1 Complete**:
```yaml
Files_To_Update:
- README.md: Update feature list and status badges
- CHANGELOG.md: Create v0.1.0 release notes
- DEVELOPMENT_PLAN.md: Mark Phase 1 complete
- ARCHITECTURE.md: Update implementation status
```
### **✅ Quality Checkpoint Triggers**
**TRIGGER**: Before marking any task complete
**MANDATORY CHECKS**:
- [ ] All code passes linting (black, flake8, mypy)
- [ ] All tests pass with >85% coverage
- [ ] Documentation is updated and accurate
- [ ] Security scan passes (bandit)
- [ ] No critical issues in code review
---
## 🚨 ERROR PREVENTION GUIDELINES
### **🔧 Development Environment Setup**
```yaml
Required_Python_Version: ">=3.8"
Required_Tools:
- git
- python (3.8+)
- pip
- pre-commit (for quality checks)
Setup_Commands:
- "python -m pip install --upgrade pip"
- "pip install -e '.[dev]'"
- "pre-commit install"
```
### **📂 File Creation Standards**
**ALWAYS FOLLOW THESE PATTERNS**:
#### **Python Files**:
```python
# Standard header for all Python files
"""Module docstring describing purpose and usage."""
import sys
from typing import Dict, List, Optional
# Local imports last
from .exceptions import WikiJSException
```
#### **Configuration Files**:
- Use consistent formatting (black, isort)
- Include comprehensive comments
- Follow established Python community standards
- Validate syntax before committing
#### **Documentation Files**:
- Use consistent markdown formatting
- Include complete examples
- Cross-reference related documentation
- Keep TOC updated
### **🔍 Common Error Prevention**
```yaml
Avoid_These_Mistakes:
- Creating files without proper headers
- Missing type hints in public APIs
- Incomplete error handling
- Missing tests for new functionality
- Outdated documentation
- Hardcoded values instead of configuration
- Missing docstrings for public methods
- Inconsistent code formatting
```
---
## 🎯 DEVELOPMENT SESSION GUIDANCE
### **Session Startup Checklist**
**EVERY SESSION MUST START WITH**:
1. [ ] Review current phase and task status from this document
2. [ ] Check completion percentages and identify next actions
3. [ ] Review relevant documentation (Architecture, Development Plan)
4. [ ] Confirm understanding of current task requirements
5. [ ] Identify potential risks from Risk Management Plan
### **Session Workflow**
```yaml
1. Context_Loading:
- Read current task details from this document
- Review architectural requirements
- Check quality standards from governance
2. Development_Work:
- Follow established patterns from architecture
- Implement according to development plan specifications
- Apply risk mitigation strategies
- Maintain quality standards
3. Session_Completion:
- Update progress tracking in this document
- Trigger documentation updates if milestone reached
- Validate quality checkpoints
- Prepare context for next session
```
### **Quality Validation Before Task Completion**
```yaml
Code_Quality:
- [ ] All code follows black formatting
- [ ] Type hints on all public APIs
- [ ] Docstrings on all public methods
- [ ] Error handling implemented
- [ ] No hardcoded values
Testing:
- [ ] Unit tests written for new functionality
- [ ] Integration tests updated
- [ ] All tests pass
- [ ] Coverage maintained >85%
Documentation:
- [ ] API documentation updated
- [ ] Examples provided
- [ ] README updated if needed
- [ ] Changelog updated
Security:
- [ ] No hardcoded secrets
- [ ] Input validation implemented
- [ ] Security scan passes
- [ ] Dependencies checked for vulnerabilities
```
---
## 📋 TASK REFERENCE GUIDE
### **Immediate Next Actions** (Task 1.1)
**PRIORITY ORDER**:
1. **Create Repository Structure** (setup.py, requirements.txt, .gitignore)
2. **Configure Python Packaging** (pyproject.toml, dependencies)
3. **Set Up CI/CD Pipeline** (GitHub Actions workflows)
4. **Create Contributing Guidelines** (CONTRIBUTING.md)
### **Task Dependencies**
```yaml
Task_1.1: No dependencies (can start immediately)
Task_1.2: Requires Task 1.1 complete (packaging setup needed)
Task_1.3: Requires Task 1.2 complete (core client foundation needed)
Task_1.4: Requires Task 1.3 complete (authentication needed for API calls)
Task_1.5: Requires Task 1.4 complete (functionality to test)
Task_1.6: Requires Task 1.5 complete (stable code to document)
Task_1.7: Requires Task 1.6 complete (documentation for release)
```
### **Resource Optimization**
```yaml
# Optimize AI usage by batching related work
Batch_1: "Repository setup + packaging configuration"
Batch_2: "Core client implementation + basic auth"
Batch_3: "API endpoints + error handling"
Batch_4: "Testing framework + initial tests"
Batch_5: "Documentation + examples"
Batch_6: "Release preparation + final validation"
```
---
## 🎯 SUCCESS CRITERIA & MILESTONES
### **Phase 1 Success Criteria**
```yaml
Functional_Requirements:
- [ ] Basic Wiki.js API integration working
- [ ] Pages CRUD operations functional
- [ ] Authentication system operational
- [ ] Error handling comprehensive
- [ ] Package installable via pip
Quality_Requirements:
- [ ] >85% test coverage achieved
- [ ] All quality gates passing
- [ ] Documentation complete and accurate
- [ ] Security scan passes
- [ ] Performance benchmarks established
Community_Requirements:
- [ ] Contributing guidelines clear
- [ ] Code of conduct established
- [ ] Issue templates configured
- [ ] Community communication channels active
```
### **Release Readiness Checklist**
```yaml
v0.1.0_Release_Criteria:
Technical:
- [ ] All Phase 1 tasks complete
- [ ] CI/CD pipeline operational
- [ ] Package builds successfully
- [ ] All tests pass
- [ ] Documentation comprehensive
Quality:
- [ ] Code review complete
- [ ] Security scan clean
- [ ] Performance benchmarks met
- [ ] User acceptance testing passed
Community:
- [ ] Release notes prepared
- [ ] Community notified
- [ ] PyPI package published
- [ ] GitHub release created
```
---
## 🔄 CONTINUOUS IMPROVEMENT
### **Learning & Adaptation**
This document evolves based on development experience:
**After Each Task**:
- Update completion tracking
- Refine time estimates based on actual effort
- Improve error prevention guidelines
- Enhance quality checkpoints
**After Each Phase**:
- Comprehensive retrospective
- Process optimization
- Documentation improvement
- Community feedback integration
### **Version History**
- **v1.0** (July 2025): Initial AI development coordinator
- Future versions will track improvements and lessons learned
---
## 🚀 READY FOR DEVELOPMENT
**CURRENT INSTRUCTION**: Phase 1 Complete - GitHub-Only Deployment Ready
**FOCUS**: Project is ready for GitHub-only installation and usage
**SUCCESS CRITERIA**: Users can install via `pip install git+https://github.com/...`
**DEPLOYMENT STRATEGY**: GitHub-only (no PyPI publishing required)
**REMEMBER**: Always refer to documentation, update progress, and maintain quality standards!
---
**🤖 AI Developer: You are ready to begin professional SDK development. Follow this coordinator for guidance, track progress diligently, and build something amazing!**
Reference in New Issue View Git Blame Copy Permalink