---
title: "Scrum4Me Developer Manual"
status: active
audience: [contributor]
language: en
last_updated: 2026-05-07
when_to_read: "Onboarding to Scrum4Me as a human contributor."
---

# Scrum4Me Developer Manual

Welcome. This manual is the **map** of Scrum4Me — a guided tour through the moving parts of the project. It is written for a new human contributor who needs to understand how the pieces fit together before diving into the authoritative reference docs (the runbooks, ADRs, and patterns under [`docs/`](../INDEX.md)).

> **The manual is the map. The runbooks are the territory.**
> When two sources disagree, trust the runbook or ADR linked from this manual.

## Audience

- **New human contributors** picking up the project for the first time.
- **Returning contributors** who want a quick refresher on how a specific subsystem (statuses, git, MCP, Docker) fits into the whole.
- **Not for**: AI agents — they should follow [`CLAUDE.md`](../../CLAUDE.md) and the agent-specific runbooks under [`docs/runbooks/`](../runbooks/).

## How to read this manual

| You want to… | Read |
|---|---|
| …get the elevator pitch and project structure | [01 — Overview](./01-overview.md) |
| …understand how a PBI/Story/Task moves through its lifecycle | [02 — Statuses & Transitions](./02-statuses-and-transitions.md) |
| …know when to branch, commit, push, and open a PR | [03 — Git Workflow](./03-git-workflow.md) |
| …see how Claude Code drives stories via the MCP server | [04 — MCP Integration](./04-mcp-integration.md) |
| …run the worker container locally or understand the deploy topology | [05 — Docker](./05-docker.md) |
| …diagnose an error code, stuck job, or weird state | [06 — Troubleshooting](./06-troubleshooting.md) |

A linear read takes about 30 minutes. As a lookup reference, jump straight to a chapter — each one stands alone.

## Conventions

- **Cross-references** use relative links (`../runbooks/...`) so they work both in GitHub and inside the in-app `/manual` viewer.
- **Callouts** use blockquotes prefixed with a label: `> **Note:**`, `> **Warning:**`, `> **Hardstop:**` (a non-negotiable rule from [`CLAUDE.md`](../../CLAUDE.md)).
- **Code blocks** show shell commands with no `$` prefix, so they're copy-pasteable.
- **State diagrams** use Mermaid `stateDiagram-v2`; they render in GitHub and in the in-app viewer.
- **Status labels** are written in `UPPER_SNAKE` when referring to the database value and `lowercase` when referring to the API representation — see [02 — Statuses & Transitions](./02-statuses-and-transitions.md#db-vs-api-mapping) for the contract.

## In-app rendering

Every chapter in this manual is also browsable inside the running Scrum4Me app at `/manual`. The in-app sidebar mirrors this index, and Mermaid diagrams render in place. The markdown files under `docs/manual/` are the **source of truth** — the in-app page reads them at build time via the `scripts/build-manual.mjs` generator.

## What this manual does **not** cover

- **REST API reference** → [`docs/api/rest-contract.md`](../api/rest-contract.md)
- **Component & dialog specs** → [`docs/specs/dialogs/`](../specs/dialogs/)
- **Architecture deep-dives** → [`docs/architecture.md`](../architecture.md) breadcrumb
- **Decision rationale** → [`docs/adr/`](../adr/)
- **Implementation patterns** → [`docs/patterns/`](../patterns/)
- **AI-agent instructions** → [`CLAUDE.md`](../../CLAUDE.md) and [`docs/runbooks/mcp-integration.md`](../runbooks/mcp-integration.md)

## Table of contents

1. [Overview](./01-overview.md) — what Scrum4Me is, the entity hierarchy, the stack, repository layout
2. [Statuses & Transitions](./02-statuses-and-transitions.md) — state machines for every entity
3. [Git Workflow](./03-git-workflow.md) — branching, commits, PRs, deploy controls
4. [MCP Integration](./04-mcp-integration.md) — the agent loop, idea jobs, the Q&A channel
5. [Docker](./05-docker.md) — worker container, local dev, scrum4me-docker
6. [Troubleshooting](./06-troubleshooting.md) — error codes, stuck jobs, recovery procedures