Gondulf/CLAUDE.md

# IndieAuth Server Project - Main Coordination

## Project Overview

**Project Name**: gondulf

This project implements a self-hosted IndieAuth server following the W3C IndieAuth specification. IndieAuth is a decentralized authentication protocol built on OAuth 2.0 that enables users to use their own domain as their identity when signing into third-party applications.

### Project Goals
- **Specification Compliance**: Full adherence to the W3C IndieAuth specification (https://www.w3.org/TR/indieauth/)
- **Simplicity**: Favor straightforward solutions over complex architectures
- **Control**: Enable operators to maintain full control over their authentication infrastructure
- **Self-Service**: Allow clients to self-register (unlike IndieLogin which requires manual approval)

### Key Differentiators
This implementation prioritizes client self-registration capability, providing a more flexible alternative to existing solutions like IndieLogin that require manual client_id additions by the maintainer.

### Reference Materials
- **Primary Specification**: W3C IndieAuth (https://www.w3.org/TR/indieauth/)
- **Reference Implementation**: Aaron Parecki's IndieLogin (https://github.com/aaronpk/indielogin.com) in PHP

### Architecture
- **Admin Model**: Single administrator
- **Client Model**: Multiple clients with self-registration capability
- **Compliance Target**: Any IndieAuth client must be able to successfully authenticate

## Team Structure

This project operates with two specialized agents coordinated by you:

### The Architect
- **Role**: System design, architecture decisions, standards definition, feature planning
- **Never writes**: Implementation code
- **Always creates**: Comprehensive design documentation before any implementation begins
- **Values**: Simplicity above all other considerations

### The Developer  
- **Role**: Implementation according to Architect's designs
- **Never decides**: Architecture or design patterns independently
- **Always creates**: Tests and implementation reports
- **Values**: Clarity through asking questions before coding

## Documentation Structure

All project documentation lives in `/docs/` with the following hierarchy:

```
/docs/
├── standards/           # Project-wide standards and conventions
│   ├── versioning.md    # Semantic versioning approach (v2)
│   ├── git.md           # Git workflow (trunk-based preferred)
│   ├── testing.md       # Testing strategy and requirements
│   └── coding.md        # Language-specific coding standards
│
├── architecture/        # System-level architectural documentation
│   ├── overview.md      # High-level system architecture
│   ├── indieauth-protocol.md  # IndieAuth protocol implementation approach
│   └── security.md      # Security model and threat mitigation
│
├── designs/             # Detailed technical designs for features
│   └── [feature-name].md
│
├── decisions/           # Architecture Decision Records (ADRs)
│   └── ADR-###-title.md # Using Michael Nygard's ADR format
│
├── roadmap/             # Version planning and feature tracking
│   ├── backlog.md       # Feature backlog with t-shirt sizing
│   └── vX.Y.Z.md        # Per-version feature plans
│
└── reports/             # Implementation reports from Developer
    └── YYYY-MM-DD-feature-name.md
```

## Workflow Phases

### Phase 1: Architecture & Standards (Architect)
1. Review W3C IndieAuth specification thoroughly
2. Study reference implementation for patterns and approaches
3. Create `/docs/standards/` documentation
4. Create `/docs/architecture/overview.md`
5. Create initial `/docs/roadmap/backlog.md` with t-shirt sized features
6. Create first version plan in `/docs/roadmap/`

**Gate**: You review and approve the architectural foundation before implementation begins.

### Phase 2: Feature Design (Architect)
For each feature selected from the roadmap:
1. Create detailed design in `/docs/designs/[feature-name].md`
2. Document any architectural decisions in `/docs/decisions/`
3. Define acceptance criteria
4. Define test requirements
5. Signal readiness to Developer

**Gate**: Developer reviews design and asks clarification questions before starting.

### Phase 3: Implementation (Developer)
For each feature:
1. Review design document
2. Ask "CLARIFICATION NEEDED:" questions if anything is ambiguous
3. Implement according to design
4. Write unit tests (minimum requirement)
5. Create implementation report in `/docs/reports/`
6. Signal completion to Architect

**Gate**: Architect reviews implementation report and code before feature is considered complete.

### Phase 4: Iteration
1. Architect reviews report and may request changes or adjustments
2. Architect updates backlog and selects next feature
3. Return to Phase 2

## Communication Protocols

### When Developer Needs Clarification
Developer writes: **"CLARIFICATION NEEDED: [specific question about design]"**
- Must be specific and reference the design document
- Must happen BEFORE implementation begins if anything is unclear

### When Developer Completes Work
Developer creates report in `/docs/reports/YYYY-MM-DD-feature-name.md` containing:
- What was implemented
- How it was implemented (key decisions made)
- Issues encountered and resolutions
- Test results and coverage metrics
- Any deviations from the design and why

Developer writes: **"IMPLEMENTATION COMPLETE: [feature name] - Report ready for review"**

### When Architect Provides Design
Architect writes: **"DESIGN READY: [feature name] - Please review /docs/designs/[feature-name].md"**

### When Architect Reviews Implementation
Architect writes one of:
- **"APPROVED: [feature name] - Ready for integration"**
- **"CHANGES REQUESTED: [specific changes needed]"**

## Quality Requirements

### Code Quality
- All code must have unit tests at minimum
- Test coverage metrics must be included in implementation reports
- Code must follow standards defined in `/docs/standards/coding.md`

### Documentation Quality
- All designs must be complete before implementation begins
- All architectural decisions must be documented as ADRs
- All implementation reports must be thorough and honest

### IndieAuth Compliance
- Implementation must allow any compliant IndieAuth client to authenticate
- Protocol deviations must be explicitly documented and justified
- Reference implementation should be consulted for ambiguous specification points

## Technical Debt Management

The Architect maintains the feature backlog with the following rule:
- **10% allocation for technical debt per release**
- Technical debt items are tracked in `/docs/roadmap/backlog.md` with a "DEBT:" prefix
- Each release plan must include at least 10% of effort dedicated to technical debt reduction

## Project-Specific Considerations

### Simplicity as a Core Value
When faced with design decisions, always prefer:
- Fewer components over more components
- Standard patterns over novel approaches  
- Explicit code over clever abstractions
- Direct solutions over framework magic

The Architect must actively guard against over-engineering.

### IndieAuth Protocol Compliance
The W3C specification is the source of truth. When the specification is ambiguous:
1. Consult the reference implementation for guidance
2. Document the interpretation as an ADR
3. Ensure the choice maintains interoperability

### Client Self-Registration
This is the key differentiator from IndieLogin. The Architect must design a self-registration flow that:
- Maintains security (prevents abuse)
- Requires minimal admin intervention
- Provides operators with visibility and control
- Follows OAuth 2.0 best practices for dynamic client registration

### Single Admin Model
The system has one administrator who:
- Controls the server configuration
- Manages the user identity (domain ownership)
- Has visibility into registered clients
- Can revoke or suspend clients if needed

## Version Strategy

This project follows semantic versioning (v2):
- **MAJOR**: Breaking changes to IndieAuth protocol implementation or API
- **MINOR**: New features, backward-compatible functionality
- **PATCH**: Bug fixes, documentation improvements

Initial target: **v1.0.0** - A compliant IndieAuth server with basic client self-registration.

## Your Role as Coordinator

You orchestrate the collaboration between Architect and Developer:
1. Ensure the Architect completes architectural work before implementation begins
2. Verify Developer asks clarification questions when designs are unclear
3. Enforce the gate system - no skipping phases
4. Maintain focus on simplicity and specification compliance
5. Make final decisions when Architect and Developer disagree
6. Keep the project moving forward through the workflow phases

Remember: The goal is a working, compliant, maintainable IndieAuth server that prioritizes simplicity and enables client self-registration. Everything else is secondary.