janpeter/Scrum4Me
0
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
Scrum4Me/docs/manual/index.md
Janpeter Visser bd7478861b
PBI-58: Developer manual + in-app /manual page (#148) 
* 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>

* chore(PBI-58): add markdown rendering deps + manual:build script

Adds mermaid, rehype-slug, rehype-autolink-headings for the in-app
/manual page. Wires manual:build into prebuild so production builds
always regenerate the chapter TOC.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(PBI-58): codegen script for in-app manual TOC

scripts/build-manual.mjs walks docs/manual/, parses YAML front-matter,
strips it from the body, and emits lib/manual.generated.ts with a typed
ManualEntry[] containing slug, title, description, filePath, and the
embedded markdown body. Pure Node 20, mirrors generate-docs-index.mjs.

Inlining the markdown at build time keeps runtime serverless functions
free of filesystem reads, which avoids whole-project NFT tracing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(PBI-58): /manual route renders developer manual chapters in-app

Catch-all route at app/(app)/manual/[[...slug]]/page.tsx with
generateStaticParams covering every TOC entry. Server-side
MarkdownView uses react-markdown with remark-gfm, rehype-slug, and
rehype-autolink-headings; mermaid code blocks are routed to a
client-only MermaidBlock that dynamic-imports mermaid on mount.

ManualSidebar (client) reads the typed TOC and highlights the active
chapter via usePathname.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(PBI-58): add Manual link to main nav bar

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-07 18:00:10 +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