janpeter/Scrum4Me
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Scrum4Me/docs/manual/index.md
Madhura68 e75bac9375 docs(PBI-58): add developer manual chapters under docs/manual/ 
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>
2026-05-07 17:37:43 +02:00

4 KiB
Raw Blame History

title status audience language last_updated when_to_read
Scrum4Me Developer Manual active
contributor
en 2026-05-07 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/).

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 and the agent-specific runbooks under docs/runbooks/.

How to read this manual

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

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).
  • 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 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

Table of contents

  1. Overview — what Scrum4Me is, the entity hierarchy, the stack, repository layout
  2. Statuses & Transitions — state machines for every entity
  3. Git Workflow — branching, commits, PRs, deploy controls
  4. MCP Integration — the agent loop, idea jobs, the Q&A channel
  5. Docker — worker container, local dev, scrum4me-docker
  6. Troubleshooting — error codes, stuck jobs, recovery procedures