docs: add initial README and OpenSpec proposal

Add comprehensive README.md documenting project purpose, architecture,
tech stack, and development workflow. Includes OpenSpec proposal
(add-initial-readme) with project documentation specification.

The README describes current state only (early development phase) and
serves as entry point for developers and AI assistants.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -0,0 +1,116 @@
+# Clubber
+
+A toolset for managing members of non-profit societies (Vereine) with AI-powered administration.
+
+## Overview
+
+Clubber provides a GraphQL API for member management combined with an MCP (Model Context Protocol) server that enables AI assistants to help with society administration tasks.
+
+**Current Status**: Early development - OpenSpec documentation and project structure in place.
+
+## Architecture
+
+The system consists of two main components:
+
+1. **GraphQL API** - Core backend for member data management
+   - Built with FastAPI and Strawberry GraphQL
+   - Database-agnostic design (SQLite for development, PostgreSQL for production)
+   - SQLAlchemy 2.0 ORM with async support
+
+2. **MCP Server** - AI assistant integration layer
+   - Connects to the GraphQL API
+   - Provides tools for AI agents to manage society operations
+   - Service account authentication
+
+## Tech Stack
+
+- **Python 3.11+** - Primary language
+- **uv** - Fast package and project manager
+- **FastAPI** - Async web framework
+- **Strawberry GraphQL** - Type-safe GraphQL with Python type hints
+- **SQLAlchemy 2.0** - Database ORM
+- **Alembic** - Database migrations
+
+## Project Structure
+
+```
+clubber/
+├── openspec/           # Specification-driven development
+│   ├── project.md      # Project conventions and context
+│   ├── specs/          # Current specifications
+│   └── changes/        # Change proposals
+├── CLAUDE.md           # AI assistant instructions
+└── README.md           # This file
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.11 or higher
+- [uv](https://github.com/astral-sh/uv) package manager
+
+### Setup
+
+```bash
+# Clone the repository
+git clone ssh://git@codeberg.org/gurix/clubber.git
+cd clubber
+
+# Install uv if not already installed
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Set up the project (when implemented)
+# uv venv
+# uv pip install -e .
+```
+
+## Development Workflow
+
+This project uses [OpenSpec](https://openspec.dev) for specification-driven development:
+
+1. **Review existing specs** in `openspec/specs/`
+2. **Create change proposals** in `openspec/changes/` before implementing features
+3. **Validate proposals** with `openspec validate --strict`
+4. **Implement changes** following the proposal
+5. **Archive completed changes** after deployment
+
+See `openspec/AGENTS.md` for detailed workflow instructions.
+
+### Working with Git Worktrees
+
+We use git worktrees for parallel development:
+
+```bash
+# Create a worktree for a feature branch
+git worktree add ../clubber-feature-name feature/feature-name
+
+# Work in the worktree
+cd ../clubber-feature-name
+
+# Remove worktree after merge
+git worktree remove ../clubber-feature-name
+```
+
+## Contributing
+
+1. Read `openspec/project.md` for project conventions
+2. For new features, create an OpenSpec proposal first
+3. Follow the coding style (Black, isort, ruff)
+4. Write tests for new functionality
+5. Use conventional commits (`feat:`, `fix:`, `docs:`, etc.)
+
+## License
+
+The MIT License
+
+## Contact
+
+Markus Graf - [info@markusgraf.ch](mailto:info@markusgraf.ch)
+
+## Acknowledgments
+
+Built with support from:
+- [Strawberry GraphQL](https://strawberry.rocks)
+- [FastAPI](https://fastapi.tiangolo.com)
+- [OpenSpec](https://openspec.dev)

openspec/changes/add-initial-readme/proposal.md

@@ -0,0 +1,16 @@
+# Add Initial README
+
+## Why
+The project currently has no README.md file. According to `openspec/project.md`, we maintain a README.md as the primary project documentation and entry point for developers and AI assistants. A README is essential for anyone discovering this repository on Codeberg.
+
+## What Changes
+- Add README.md to project root describing current state
+- Document the project's purpose and vision
+- Explain OpenSpec-based development workflow
+- Provide setup instructions for contributors
+- **Note**: README describes *current* state only, not planned features
+
+## Impact
+- Affected specs: project-documentation (new capability)
+- Affected code: None (documentation only)
+- No breaking changes

openspec/changes/add-initial-readme/specs/project-documentation/spec.md

@@ -0,0 +1,34 @@
+# Project Documentation Specification
+
+## ADDED Requirements
+
+### Requirement: README File
+The project root SHALL contain a README.md file that serves as the primary entry point for developers and AI assistants.
+
+#### Scenario: Repository discovery
+- **WHEN** a developer or AI assistant discovers the repository
+- **THEN** they can read README.md to understand project purpose and current state
+
+### Requirement: Current State Documentation
+The README.md SHALL accurately describe only the current implementation state, not planned features.
+
+#### Scenario: Accurate project status
+- **WHEN** reading the README.md
+- **THEN** it reflects what is actually implemented
+- **AND** does not promise or describe unimplemented features
+
+### Requirement: Getting Started Guide
+The README.md SHALL include instructions for contributors to get started with development.
+
+#### Scenario: New contributor onboarding
+- **WHEN** a new contributor wants to start developing
+- **THEN** README.md provides clear setup steps
+- **AND** explains the OpenSpec-based workflow
+
+### Requirement: OpenSpec Reference
+The README.md SHALL reference the OpenSpec documentation structure for detailed specifications.
+
+#### Scenario: Finding detailed specs
+- **WHEN** a developer needs detailed technical specifications
+- **THEN** README.md directs them to the `openspec/` directory
+- **AND** explains how to read and create proposals

openspec/changes/add-initial-readme/tasks.md

@@ -0,0 +1,13 @@
+# Implementation Tasks
+
+## 1. Documentation
+- [x] 1.1 Draft README.md content reflecting current project state
+- [x] 1.2 Include project overview and purpose
+- [x] 1.3 Document OpenSpec workflow for contributors
+- [x] 1.4 Add getting started section for contributors
+- [x] 1.5 Include license and contact information
+- [x] 1.6 Review README.md for accuracy against project.md
+
+## 2. Validation
+- [x] 2.1 Verify OpenSpec validation passes
+- [x] 2.2 Ensure README.md aligns with openspec/project.md conventions