lmiranda/wikijs-sdk-python
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
40c801f0532456ab406ba5d24f6920fcc5ec0f33
wikijs-sdk-python/CLAUDE.md
l3ocho 18a82711cb ready for try
2025-07-29 20:16:11 -04:00

16 KiB
Raw Blame History

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

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) ✅

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) ✅

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"
    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:              # ✅ COMPLETE
    Status: "COMPLETE"
    Completion: 100%
    Estimated_Time: "4 hours"
    Claude_Requests: "15-20"
    
  Task_1.4_Pages_API:                   # ✅ COMPLETE
    Status: "COMPLETE"
    Completion: 100%
    Estimated_Time: "6 hours"
    Claude_Requests: "25-30"
    
  Task_1.5_Testing:                     # ✅ COMPLETE
    Status: "COMPLETE"
    Completion: 100%
    Estimated_Time: "6 hours"
    Claude_Requests: "20-25"
    
  Task_1.6_Documentation:               # ✅ COMPLETE
    Status: "COMPLETE"
    Completion: 100%
    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) ⏳

Status: PLANNED
Completion: 0%
Target_Start: "After Phase 1 Complete"

Phase 3: Reliability & Performance (0% COMPLETE) ⏳

Status: PLANNED
Completion: 0%
Target_Start: "After Phase 2 Complete"

Phase 4: Advanced Features (0% COMPLETE) ⏳

Status: PLANNED
Completion: 0%
Target_Start: "After Phase 3 Complete"

🎯 CURRENT FOCUS: TASK 1.1 - PROJECT FOUNDATION

Task 1.1 Detailed Breakdown

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:

# 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:

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:

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

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:

# 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

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

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

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

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

# 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

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

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!

Reference in New Issue View Git Blame Copy Permalink