Phil Skentelbery
e589f5bd6c
This commit resolves all documentation issues identified in the comprehensive review: CRITICAL FIXES: - Renumbered duplicate ADRs to eliminate conflicts: * ADR-022-migration-race-condition-fix → ADR-037 * ADR-022-syndication-formats → ADR-038 * ADR-023-microformats2-compliance → ADR-040 * ADR-027-versioning-strategy-for-authorization-removal → ADR-042 * ADR-030-CORRECTED-indieauth-endpoint-discovery → ADR-043 * ADR-031-endpoint-discovery-implementation → ADR-044 - Updated all cross-references to renumbered ADRs in: * docs/projectplan/ROADMAP.md * docs/reports/v1.0.0-rc.5-migration-race-condition-implementation.md * docs/reports/2025-11-24-endpoint-discovery-analysis.md * docs/decisions/ADR-043-CORRECTED-indieauth-endpoint-discovery.md * docs/decisions/ADR-044-endpoint-discovery-implementation.md - Updated README.md version from 1.0.0 to 1.1.0 - Tracked ADR-021-indieauth-provider-strategy.md in git DOCUMENTATION IMPROVEMENTS: - Created comprehensive INDEX.md files for all docs/ subdirectories: * docs/architecture/INDEX.md (28 documents indexed) * docs/decisions/INDEX.md (55 ADRs indexed with topical grouping) * docs/design/INDEX.md (phase plans and feature designs) * docs/standards/INDEX.md (9 standards with compliance checklist) * docs/reports/INDEX.md (57 implementation reports) * docs/deployment/INDEX.md (deployment guides) * docs/examples/INDEX.md (code samples and usage patterns) * docs/migration/INDEX.md (version migration guides) * docs/releases/INDEX.md (release documentation) * docs/reviews/INDEX.md (architectural reviews) * docs/security/INDEX.md (security documentation) - Updated CLAUDE.md with complete folder descriptions including: * docs/migration/ * docs/releases/ * docs/security/ VERIFICATION: - All ADR numbers now sequential and unique (50 total ADRs) - No duplicate ADR numbers remain - All cross-references updated and verified - Documentation structure consistent and well-organized These changes improve documentation discoverability, maintainability, and ensure proper version tracking. All index files follow consistent format with clear navigation guidance. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
108 lines
4.6 KiB
Markdown
108 lines
4.6 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/migration/`** - Migration guides for upgrading between versions and configuration changes
|
|
- **`docs/projectplan/`** - Project roadmaps, implementation plans, feature scope definitions
|
|
- **`docs/releases/`** - Release-specific documentation, release notes, version information
|
|
- **`docs/reports/`** - Implementation reports from developers (dated: YYYY-MM-DD-description.md)
|
|
- **`docs/reviews/`** - Architectural reviews, design critiques, retrospectives
|
|
- **`docs/security/`** - Security-related documentation, vulnerability analyses, best practices
|
|
- **`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.
|