books/CLAUDE.md

Session Start

Always run bd ready at the start of each session to check for available work from Beads. Delegate work to the appropriate team specialist.

If work is available, Find the team-lead agent and ask him to assign and claim it with bd update <id> --status in_progress and begin working.

Session End

Follow the "Landing the Plane" protocol below - work is NOT complete until git push succeeds.

This project uses bd (beads) for issue tracking and Claude Code Swarm Mode for multi-agent coordination.

---

Entry Point: Creating Tasks

All work starts with bd create. The Team Leader monitors tasks and coordinates the team.

# Create a new task - THIS IS THE ENTRY POINT
bd create --title "Implement feature X" --description "Details here..."

# Other useful commands
bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --status in_progress  # Claim work
bd close <id>         # Complete work
bd sync               # Sync with git

---

Team Structure (Swarm Mode)

When working on tasks, the Team Leader spawns specialists EVERY TIME.

Role	Agent Name	Responsibility
Team Leader	team-lead	Coordinates work, monitors bd ready, assigns tasks, reviews PRs
Frontend Developer	frontend	React/TypeScript, UI components, styling, state management
Backend Developer	backend	.NET/C#, GraphQL, EventFlow, database migrations
Tester	tester	Integration tests, unit tests, E2E tests, quality assurance
Code Reviewer	reviewer	Code quality, patterns, security review, best practices
Accounting Expert	sme-accounting	Danish accounting rules, VAT, bookkeeping, compliance
Usability Expert	sme-usability	UX patterns, accessibility, user workflows, design feedback

Workflow

1. User creates task: bd create --title "..." --description "..."
2. Team Lead picks up task: Runs bd ready, claims with bd update <id> --status in_progress
3. Team Lead analyzes and delegates: Spawns specialists via Claude Swarm Mode
4. Specialists work in parallel: Each handles their domain
5. Reviewer ensures quality: Code review before merge
6. Tester validates: Runs tests, confirms functionality
7. Team Lead closes task: bd close <id> and pushes to remote

Spawning Teammates (for Team Lead)

Task tool with:
  - subagent_type: "general-purpose"
  - prompt: Include role context (e.g., "As the frontend developer, implement...")
  - description: Short task summary

Communication Rules (CRITICAL)

• Use Task tool to spawn specialist agents for parallel work
• Provide complete context in the prompt - agents don't share memory
• Use TaskCreate/TaskUpdate for tracking work with dependencies (blockedBy / blocks)

---

Domain Knowledge

Project: Books (Danish Accounting System)

Backend (/backend/Books.Api/):

• .NET 8, EventFlow CQRS, HotChocolate GraphQL
• PostgreSQL with event sourcing
• Danish accounting compliance (SAF-T, VAT)

Frontend (/frontend/):

• React 18, TypeScript, Vite
• Mantine UI, Zustand state management
• Apollo Client for GraphQL

Key Concepts:

• Fiscal years (regnskabsår)
• Chart of accounts (kontoplan)
• Journal entries (kassekladde)
• VAT reporting (momsindberetning)
• Bank reconciliation (bankafstemning)

---

Landing the Plane (Session Completion)

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

1. File issues for remaining work - Create issues for anything that needs follow-up
2. Run quality gates (if code changed) - Tests, linters, builds
3. Update issue status - Close finished work, update in-progress items
4. PUSH TO REMOTE - This is MANDATORY:

   git pull --rebase
   bd sync
   git push
   git status  # MUST show "up to date with origin"
   

5. Clean up - Clear stashes, prune remote branches
6. Verify - All changes committed AND pushed
7. Hand off - Provide context for next session

CRITICAL RULES:

• Work is NOT complete until git push succeeds
• NEVER stop before pushing - that leaves work stranded locally
• NEVER say "ready to push when you are" - YOU must push
• If push fails, resolve and retry until it succeeds