Phil Skentelbery
dca9604746
- Create ADR-029 for IndieAuth/Micropub integration strategy - Address all critical issues from developer review: - Add missing 'me' parameter to token endpoint - Clarify PKCE as optional extension - Define token security migration strategy - Add authorization_codes table schema - Define property mapping rules - Clarify two authentication flows - Simplify V1 scope per user decision: - Remove update/delete operations from V1 - Focus on create-only functionality - Reduce timeline from 8-10 to 6-8 days - Update project plan with post-V1 roadmap: - Phase 11: Update/delete operations (V1.1) - Phase 12: Media endpoint (V1.2) - Phase 13: Advanced IndieWeb features (V2.0) - Phase 14: Enhanced features (V2.0+) - Create token security migration documentation - Update ADR-028 for consistency with simplified scope BREAKING CHANGE: Token migration will invalidate all existing tokens for security
105 lines
4.4 KiB
Markdown
105 lines
4.4 KiB
Markdown
# Claude Agent Instructions
|
|
|
|
This file contains operational instructions for Claude agents working on this project.
|
|
|
|
## Python Environment
|
|
|
|
- We use **uv** for Python virtual environment management
|
|
- All Python commands must be run with `uv run` prefix
|
|
- Example: `uv run pytest`, `uv run flask run`
|
|
|
|
## Agent-Architect Protocol
|
|
|
|
When invoking the agent-architect, always remind it to:
|
|
|
|
1. Review documentation in docs/ before working on the task it is given
|
|
- docs/architecture, docs/decisions, docs/standards are of particular interest
|
|
|
|
2. Give it the map of the documentation folder as described in the "Understanding the docs/ Structure" section below
|
|
|
|
3. Search for authoritative documentation for any web standard it is implementing on https://www.w3.org/
|
|
|
|
4. If it is reviewing a developers implementation report and it is accepts the completed work it should go back and update the project plan to reflect the completed work
|
|
|
|
## Agent-Developer Protocol
|
|
|
|
When invoking the agent-developer, always remind it to:
|
|
|
|
1. **Document work in reports**
|
|
- Create implementation reports in `docs/reports/`
|
|
- Include date in filename: `YYYY-MM-DD-description.md`
|
|
|
|
2. **Update the changelog**
|
|
- Add entries to `CHANGELOG.md` for user-facing changes
|
|
- Follow existing format
|
|
|
|
3. **Version number management**
|
|
- Increment version numbers according to `docs/standards/versioning-strategy.md`
|
|
- Update version in `starpunk/__init__.py`
|
|
|
|
4. **Follow git protocol**
|
|
- Adhere to git branching strategy in `docs/standards/git-branching-strategy.md`
|
|
- Create feature branches for non-trivial changes
|
|
- Write clear commit messages
|
|
|
|
## Documentation Navigation
|
|
|
|
### Understanding the docs/ Structure
|
|
|
|
The `docs/` folder is organized by document type and purpose:
|
|
|
|
- **`docs/architecture/`** - System design overviews, component diagrams, architectural patterns
|
|
- **`docs/decisions/`** - Architecture Decision Records (ADRs), numbered sequentially (ADR-001, ADR-002, etc.)
|
|
- **`docs/deployment/`** - Deployment guides, infrastructure setup, operations documentation
|
|
- **`docs/design/`** - Detailed design documents, feature specifications, phase plans
|
|
- **`docs/examples/`** - Example implementations, code samples, usage patterns
|
|
- **`docs/projectplan/`** - Project roadmaps, implementation plans, feature scope definitions
|
|
- **`docs/reports/`** - Implementation reports from developers (dated: YYYY-MM-DD-description.md)
|
|
- **`docs/reviews/`** - Architectural reviews, design critiques, retrospectives
|
|
- **`docs/standards/`** - Coding standards, conventions, processes, workflows
|
|
|
|
### Where to Find Documentation
|
|
|
|
- **Before implementing a feature**: Check `docs/decisions/` for relevant ADRs and `docs/design/` for specifications
|
|
- **Understanding system architecture**: Start with `docs/architecture/overview.md`
|
|
- **Coding guidelines**: See `docs/standards/` for language-specific standards and best practices
|
|
- **Past implementation context**: Review `docs/reports/` for similar work (sorted by date)
|
|
- **Project roadmap and scope**: Refer to `docs/projectplan/`
|
|
|
|
### Where to Create New Documentation
|
|
|
|
**Create an ADR (`docs/decisions/`)** when:
|
|
- Making architectural decisions that affect system design
|
|
- Choosing between competing technical approaches
|
|
- Establishing patterns that others should follow
|
|
- Format: `ADR-NNN-brief-title.md` (find next number sequentially)
|
|
|
|
**Create a design doc (`docs/design/`)** when:
|
|
- Planning a complex feature implementation
|
|
- Detailing technical specifications
|
|
- Documenting multi-phase development plans
|
|
|
|
**Create an implementation report (`docs/reports/`)** when:
|
|
- Completing significant development work
|
|
- Documenting implementation details for architect review
|
|
- Format: `YYYY-MM-DD-brief-description.md`
|
|
|
|
**Update standards (`docs/standards/`)** when:
|
|
- Establishing new coding conventions
|
|
- Documenting processes or workflows
|
|
- Creating checklists or guidelines
|
|
|
|
### Key Documentation References
|
|
|
|
- **Architecture**: See `docs/architecture/overview.md`
|
|
- **Implementation Plan**: See `docs/projectplan/v1/implementation-plan.md`
|
|
- **Feature Scope**: See `docs/projectplan/v1/feature-scope.md`
|
|
- **Coding Standards**: See `docs/standards/python-coding-standards.md`
|
|
- **Testing**: See `docs/standards/testing-checklist.md`
|
|
|
|
## Project Philosophy
|
|
|
|
"Every line of code must justify its existence. When in doubt, leave it out."
|
|
|
|
Keep implementations minimal, standards-compliant, and maintainable.
|