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.