l3ocho
11b6be87c8
✅ Task 1.1 - Project Foundation Setup: - Repository structure with Python packaging (setup.py, pyproject.toml) - Development dependencies and requirements - Contributing guidelines and MIT license - GitHub workflows for CI/CD (test.yml, release.yml) - Issue and PR templates for community contributions - Comprehensive project documentation ✅ Task 1.2 - Core Client Structure: - wikijs package with proper module organization - Core client class foundation in client.py - Exception hierarchy for error handling - Base model classes and page models - Type checking support (py.typed) - Utility modules and helper functions 📊 Progress: Phase 1 MVP Development now 40% complete 🎯 Next: Task 1.3 - Authentication System implementation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
523 lines
16 KiB
Markdown
523 lines
16 KiB
Markdown
# CLAUDE.md - AI Development Coordinator
|
|
|
|
**🤖 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 CLAUDE 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
|
|
**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 (0% COMPLETE) 🔄**
|
|
```yaml
|
|
Status: IN_PROGRESS
|
|
Completion: 40%
|
|
Target_Completion: 100%
|
|
Current_Task: "Task 1.3 - Authentication System"
|
|
|
|
Task_Breakdown:
|
|
Task_1.1_Project_Foundation: # ✅ COMPLETE
|
|
Status: "COMPLETE"
|
|
Completion: 100%
|
|
Estimated_Time: "3 hours"
|
|
Claude_Requests: "15-20"
|
|
|
|
Task_1.2_Core_Client: # ✅ COMPLETE
|
|
Status: "COMPLETE"
|
|
Completion: 100%
|
|
Estimated_Time: "8 hours"
|
|
Claude_Requests: "30-40"
|
|
|
|
Task_1.3_Authentication: # ⏳ PENDING
|
|
Status: "PENDING"
|
|
Completion: 0%
|
|
Estimated_Time: "4 hours"
|
|
Claude_Requests: "15-20"
|
|
|
|
Task_1.4_Pages_API: # ⏳ PENDING
|
|
Status: "PENDING"
|
|
Completion: 0%
|
|
Estimated_Time: "6 hours"
|
|
Claude_Requests: "25-30"
|
|
|
|
Task_1.5_Testing: # ⏳ PENDING
|
|
Status: "PENDING"
|
|
Completion: 0%
|
|
Estimated_Time: "6 hours"
|
|
Claude_Requests: "20-25"
|
|
|
|
Task_1.6_Documentation: # ⏳ PENDING
|
|
Status: "PENDING"
|
|
Completion: 0%
|
|
Estimated_Time: "4 hours"
|
|
Claude_Requests: "15-20"
|
|
|
|
Task_1.7_Release: # ⏳ PENDING
|
|
Status: "PENDING"
|
|
Completion: 0%
|
|
Estimated_Time: "2 hours"
|
|
Claude_Requests: "10-15"
|
|
```
|
|
|
|
### **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 Claude 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**: Begin Task 1.1 - Project Foundation Setup
|
|
|
|
**FOCUS**: Create repository structure, Python packaging, and CI/CD pipeline
|
|
|
|
**SUCCESS CRITERIA**: All foundational files created and validated
|
|
|
|
**NEXT SESSION TARGET**: Complete Task 1.1 and begin Task 1.2
|
|
|
|
**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!** |