This directory contains comprehensive planning documentation for StarPunk V1 implementation. These documents guide development from the current state (basic infrastructure) to a fully functional IndieWeb CMS.

Planning Documents

1. Implementation Plan (PRIMARY DOCUMENT)

Use this for: Detailed, step-by-step implementation guidance

The comprehensive implementation roadmap organized into 10 phases:

Phase 1-2: Foundation (utilities, models, notes management)
Phase 3-4: Authentication and web interface
Phase 5-6: RSS feeds and Micropub
Phase 7: Optional REST API
Phase 8: Testing and quality assurance
Phase 9: Documentation
Phase 10: Release preparation

Each phase includes:

Specific tasks with checkboxes
Dependencies clearly marked
Estimated effort in hours
References to relevant ADRs and docs
Acceptance criteria for each feature
Testing requirements

Start here for implementation work.

2. Quick Reference

Use this for: Fast lookups during development

A condensed reference guide containing:

Implementation order (strict dependency chain)
Module dependency diagram
Critical path items (what MUST be done)
Complete file checklist (35 files to create)
Test coverage requirements
Configuration checklist (required .env variables)
Common development commands
Key design decisions (quick ADR lookup)
Success criteria (how to know V1 is done)
Troubleshooting (common issues and fixes)

Use this when you need a quick answer without reading the full plan.

3. Feature Scope

Use this for: Scope decisions and feature prioritization

Definitive document on what's in/out of scope for V1:

IN SCOPE: Complete feature matrix with justifications
- Authentication & Authorization
- Notes Management
- Web Interface (Public & Admin)
- Micropub Support
- RSS Feed
- Data Management
- Security
- Testing
- Documentation
OUT OF SCOPE: What to defer to V2
- Multi-user support
- Tags and categories
- Media uploads
- Webmentions
- Advanced features
- (50+ features explicitly deferred)
Feature Justification Framework: How to evaluate new feature requests
Lines of Code Budget: Maximum complexity targets per module

Use this when someone asks "Should we add feature X?" or when tempted to add "just one more thing."

How to Use These Documents

For Initial Planning

Read Implementation Plan completely
Review Feature Scope to understand boundaries
Bookmark Quick Reference for daily use

During Development

Follow Implementation Plan phase by phase
Check off tasks as completed
Reference Quick Reference for commands and lookups
Consult Feature Scope when scope questions arise

For Daily Work

Quick Reference is your daily companion
Implementation Plan for detailed task guidance
Feature Scope for scope decisions

Current Project State

Completed (Setup Phase)

✓ Project structure created
✓ Virtual environment with uv
✓ Dependencies installed (6 core packages)
✓ Database schema defined and initialized
✓ Configuration management (config.py)
✓ Basic Flask app structure
✓ Documentation framework (ADRs, architecture)
✓ Git repository initialized

Ready to Implement

Phase 1: Core utilities and models
Phase 2: Notes management (CRUD)
Phase 3: Authentication (IndieLogin)
Phase 4: Web interface (templates + routes)
Phase 5: RSS feed generation
Phase 6: Micropub endpoint
Phase 7: Optional REST API
Phase 8: Testing and QA
Phase 9: Documentation
Phase 10: Release

Key Metrics

Estimated Effort

Total: 40-60 hours of focused development
Timeline: 3-4 weeks at 15-20 hours/week
Files to Create: ~35 files (code + tests + docs)
Lines of Code: ~2,500-3,700 total (app + tests)

Success Criteria

All features in scope implemented
Test coverage >80%
All validators pass (HTML, RSS, Microformats, Micropub)
Documentation complete
Deployable to production
Performance targets met (<300ms responses)

Development Workflow

Recommended Approach

Work in phases - Complete Phase 1 before Phase 2
Test as you go - Write tests alongside features
Document continuously - Update docs as you implement
Commit frequently - Small, focused commits
Run validators - Check standards compliance early and often

Phase Completion Checklist

Before moving to next phase, ensure:

All tasks in current phase completed
All tests for phase passing
Code formatted (black) and linted (flake8)
Documentation updated
Changes committed to git

Dependencies

Prerequisites

Python 3.11+
uv package manager
Git
Text editor
Web browser

External Services

IndieLogin.com (for authentication)
W3C validators (for testing)
Micropub.rocks (for testing)
IndieWebify.me (for testing)

Standards Compliance

StarPunk V1 must comply with:

Standard	Specification	Validation Tool
HTML5	W3C HTML5	validator.w3.org
RSS 2.0	RSS Board	validator.w3.org/feed
Microformats2	microformats.org	indiewebify.me
Micropub	micropub.spec.indieweb.org	micropub.rocks
IndieAuth	indieauth.spec.indieweb.org	Manual testing
OAuth 2.0	oauth.net/2	Via IndieLogin

All validators must pass before V1 release.

Reference Documentation

Project Documentation

Architecture Decision Records (ADRs)

External Standards

Questions and Support

Architecture Questions

Consult the Architect Agent (.claude/agents/architect.md) for:

Technology choices
Design patterns
Architectural decisions
Standards interpretation

Implementation Questions

Refer to:

Implementation Plan for detailed task guidance
ADRs for rationale behind decisions
Architecture docs for system design
External specs for standards details

Scope Questions

Check:

Feature Scope document for in/out of scope decisions
ADRs for architectural boundaries
Project philosophy: "When in doubt, leave it out"

Updates and Maintenance

These planning documents are living documents:

When to Update

After completing each phase (check off tasks)
When discovering new insights during implementation
When making scope decisions (add to Feature Scope)
When architectural changes occur (create new ADR)

How to Update

Update relevant document(s)
Add "Last Updated" date
Commit changes with descriptive message
Ensure consistency across all planning docs

Version History

2025-11-18: Initial V1 project plan created
- Created implementation-plan.md (10 phases, ~35 files)
- Created quick-reference.md (daily developer guide)
- Created feature-scope.md (in/out of scope)
- Created README.md (this file)

Getting Started

Ready to start implementing?

Read Implementation Plan completely
Review Feature Scope to understand boundaries
Bookmark Quick Reference for daily use
Start with Phase 1 - Core utilities and models
Work methodically through each phase
Test continuously - don't defer testing
Document as you go - update docs with implementation
Stay focused - resist scope creep, defer to V2

Good luck building StarPunk V1!

Remember: "Every line of code must justify its existence. When in doubt, leave it out."

Contact and Feedback

For questions, issues, or suggestions about these planning documents:

Review the relevant document first
Check ADRs for architectural decisions
Consult external specs for standards questions
Update documents with new insights

Project Philosophy: Simple, focused, standards-compliant. Build the minimal viable IndieWeb CMS. Ship V1. Then iterate.

Project Plan Created: 2025-11-18 Last Updated: 2025-11-18 Status: Ready for Implementation Next Step: Begin Phase 1 - Core Utilities and Models