Madhura68
e75bac9375
Adds a 7-file English-language manual targeted at new human contributors: index, overview, statuses & transitions (with mermaid state diagrams), git workflow, MCP integration, docker, and troubleshooting. The manual is the *map* — it cross-references existing runbooks/ADRs/architecture docs rather than duplicating their content. Regenerates docs/INDEX.md and validates with check-doc-links.mjs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
64 lines
4 KiB
Markdown
64 lines
4 KiB
Markdown
---
|
|
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
|