# StarPunk V1 Project Plan

## Overview

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](implementation-plan.md) (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](quick-reference.md)
**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](feature-scope.md)
**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
1. Read **Implementation Plan** completely
2. Review **Feature Scope** to understand boundaries
3. Bookmark **Quick Reference** for daily use

### During Development
1. Follow **Implementation Plan** phase by phase
2. Check off tasks as completed
3. Reference **Quick Reference** for commands and lookups
4. Consult **Feature Scope** when scope questions arise

### For Daily Work
1. **Quick Reference** is your daily companion
2. **Implementation Plan** for detailed task guidance
3. **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
1. **Work in phases** - Complete Phase 1 before Phase 2
2. **Test as you go** - Write tests alongside features
3. **Document continuously** - Update docs as you implement
4. **Commit frequently** - Small, focused commits
5. **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 Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
- [Technology Stack](/home/phil/Projects/starpunk/docs/architecture/technology-stack.md)
- [Project Structure](/home/phil/Projects/starpunk/docs/design/project-structure.md)
- [Python Coding Standards](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)

### Architecture Decision Records (ADRs)
- [ADR-001: Python Web Framework](/home/phil/Projects/starpunk/docs/decisions/ADR-001-python-web-framework.md)
- [ADR-002: Flask Extensions](/home/phil/Projects/starpunk/docs/decisions/ADR-002-flask-extensions.md)
- [ADR-003: Frontend Technology](/home/phil/Projects/starpunk/docs/decisions/ADR-003-frontend-technology.md)
- [ADR-004: File-Based Storage](/home/phil/Projects/starpunk/docs/decisions/ADR-004-file-based-note-storage.md)
- [ADR-005: IndieLogin Authentication](/home/phil/Projects/starpunk/docs/decisions/ADR-005-indielogin-authentication.md)
- [ADR-006: Python Virtual Environment](/home/phil/Projects/starpunk/docs/decisions/ADR-006-python-virtual-environment-uv.md)

### External Standards
- [Micropub Specification](https://micropub.spec.indieweb.org/)
- [IndieAuth Specification](https://indieauth.spec.indieweb.org/)
- [Microformats2](http://microformats.org/wiki/microformats2)
- [RSS 2.0 Specification](https://www.rssboard.org/rss-specification)
- [IndieLogin API](https://indielogin.com/api)

---

## 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
1. Update relevant document(s)
2. Add "Last Updated" date
3. Commit changes with descriptive message
4. 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?**

1. **Read** [Implementation Plan](implementation-plan.md) completely
2. **Review** [Feature Scope](feature-scope.md) to understand boundaries
3. **Bookmark** [Quick Reference](quick-reference.md) for daily use
4. **Start with Phase 1** - Core utilities and models
5. **Work methodically** through each phase
6. **Test continuously** - don't defer testing
7. **Document as you go** - update docs with implementation
8. **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:

1. Review the relevant document first
2. Check ADRs for architectural decisions
3. Consult external specs for standards questions
4. 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