Scrum4Me

From idea to visible results.

Scrum4Me turns product intent into a verifiable delivery pipeline. Ideas become plans, tasks, agent runs, tests, commits and pull requests, all within the standards and guidelines defined for each project.

Scrum4Me is a desktop-first fullstack web application for solo developers and small Scrum teams that manage multiple software projects in parallel. It combines lightweight Scrum planning with an agent-driven execution flow that stays traceable from the first idea to the final pull request.

What It Does

• Captures ideas and turns them into structured product work.
• Lets Claude challenge ideas through a Grill phase and generate implementation plans.
• Materializes approved plans into PBIs, stories and tasks.
• Supports product backlogs, active sprints, Sprint Board and Solo Panel workflows.
• Runs implementation jobs through a queue, MCP tool layer and Docker runner.
• Stores implementation logs, test results, questions, commits and PR links per story.
• Keeps source code, branches and pull requests in your own git provider.
• Provides REST endpoints and MCP tools for controlled integrations.

Platform Overview

Scrum4Me is not a single planning screen. It is a small platform with clear boundaries between planning, execution, tools, runtime and shared schema logic.

Component	Role	Responsibility
Scrum4Me	Planning app	Products, PBIs, stories, tasks, sprints, ideas, product docs, question channel and progress views
scrum4me-workers	Execution console	Job queue, worker registry, API tokens, job config, repo access and worker health
scrum4me-mcp	Tool and claim layer	Atomic job claiming, context loading, prompts, logs, status updates, questions and verification gates
scrum4me-docker	Headless runtime	Daemon loop, per-job worktree, Claude Code process and runtime logs
scrum4me-shared	Shared kernel	Canonical Prisma schema, status mappings, job config and realtime payload types
Forgejo / git provider	Source control	Repositories, branches, commits and pull requests

Postgres is the shared queue and metadata layer. Source code remains in git and in temporary worktrees created by the runner.

Delivery Workflow

1. A user captures or materializes work in Scrum4Me.
2. Product work is represented as a PBI, stories and tasks.
3. Clicking Execute creates a ClaudeJob in Postgres.
4. scrum4me-docker asks scrum4me-mcp for the next job.
5. scrum4me-mcp claims the job atomically and provides context, task plan, repo config, allowed tools and prompt.
6. The runner starts one Claude Code invocation for that exact job.
7. Claude writes implementation logs, test results, questions and status changes through MCP tools.
8. Verification, terminal status, commits and PR metadata are recorded back into Scrum4Me.
9. Scrum4Me and the workers app receive realtime updates through Postgres NOTIFY and SSE.

Core Product Areas

• Ideas - draft product intent before it becomes backlog work.
• Grill / Plan - asynchronous Claude jobs that challenge the idea and produce a structured YAML plan.
• Product Backlog - PBIs grouped by priority, with stories ordered inside each PBI.
• Sprint Board - one view for Product Backlog, Sprint Backlog and tasks.
• Solo Panel - personal Kanban board for claimed stories and tasks.
• Product Docs - architecture, plans, runbooks, specs, API docs and agent guidance.
• Question Channel - agents can ask blocking questions and continue after the user answers.
• Activity Log - implementation plan, test result and commit entries per story.

Architecture

• Next.js App Router for frontend, route handlers and server-side rendering.
• Server Components for data loading.
• Server Actions for UI mutations.
• Prisma ORM with PostgreSQL.
• iron-session for encrypted session cookies.
• Product access through owners and product_members.
• Postgres LISTEN/NOTIFY plus SSE for realtime updates.
• Vercel-compatible build and deployment.
• Shared schema and status contracts are generated from scrum4me-shared.

Tech Stack

• Next.js 16
• React 19
• TypeScript
• Prisma
• PostgreSQL / Neon
• Zustand
• dnd-kit
• Tailwind CSS
• shadcn/ui
• iron-session
• bcryptjs
• Vitest
• Vercel Analytics
• Sentry integration

Getting Started

Install dependencies:

npm ci

Create local environment variables:

cp .env.example .env.local

Fill at least:

• DATABASE_URL
• SESSION_SECRET

DIRECT_URL is optional for local development, but useful for migrations in cloud database environments.

Generate the local Prisma schema from scrum4me-shared, synchronize the database and generate Prisma Client:

bash scripts/gen-schema.sh
npx prisma db push
npx prisma generate

Seed test data when needed:

npm run seed

Start the development server:

npm run dev

The app runs at http://localhost:3000.

Scripts

npm run dev        # local development server
npm run lint       # ESLint
npm run typecheck  # TypeScript without emit
npm test           # Vitest test suite
npm run verify     # lint + typecheck + tests
npm run build      # production build

Verification

For normal development, run:

npm run verify
npm run build

For API smoke tests, start the app and use an API token:

bash scripts/test-api.sh

See scripts/README.md and docs/qa/api-test-plan.md for the API test setup.

Environment Variables

See .env.example for the full reference.

Variable	Required	Purpose
DATABASE_URL	Yes	PostgreSQL connection string for Prisma
DIRECT_URL	No	Direct database connection for migrations
SESSION_SECRET	Yes	At least 32 characters, used by iron-session
CRON_SECRET	Production	Bearer secret for /api/cron/* routes
NEXT_PUBLIC_VAPID_PUBLIC_KEY	No	VAPID public key for Web Push
VAPID_PRIVATE_KEY	No	VAPID private key for Web Push
VAPID_SUBJECT	No	Web Push contact URI
INTERNAL_PUSH_SECRET	No	Bearer secret for internal push routes
NEXT_PUBLIC_SENTRY_DSN	No	Sentry DSN; SDK is a no-op when omitted
SENTRY_ORG / SENTRY_PROJECT / SENTRY_AUTH_TOKEN	No	Source-map upload during build

API Overview

All protected API endpoints require:

Authorization: Bearer <token>

Implementation tokens are managed in the workers app at workers.jp-visser.nl/api-tokens.

Method	Endpoint	Purpose
GET	/api/health	Liveness check; ?db=1 also pings the database
GET	/api/products	Active products where the token user is owner or member
GET	/api/products/:id/next-story	Highest-priority open story from the active sprint
GET	/api/products/:id/claude-context	Bundled product, sprint, next story, tasks and open ideas for MCP
GET	/api/sprints/:id/tasks?limit=10	First sprint tasks in order
PATCH	/api/stories/:id/tasks/reorder	Reorder tasks; all IDs must belong to the story
POST	/api/stories/:id/log	Record implementation plan, test result or commit
PATCH	/api/tasks/:id	Update task status or implementation_plan
GET / POST	/api/ideas	Idea CRUD
GET / PATCH	/api/ideas/:id	Read or update one idea
GET	/api/jobs/:id/sub-tasks	Sprint task executions for a sprint implementation job
GET	/api/users/:id/avatar	Avatar for a specific user

Documentation

• CHANGELOG.md - release history.
• docs/INDEX.md - generated documentation index.
• docs/glossary.md - domain terms.
• docs/architecture/overview.md - architecture overview.
• docs/runbooks/mcp-integration.md - MCP integration runbook.
• docs/runbooks/worker-idempotency.md - worker idempotency rules.
• CLAUDE.md / AGENTS.md - agent instructions.

Related Repositories

• Scrum4Me - this planning app.
• scrum4me-workers - execution console for jobs, workers and tokens.
• scrum4me-mcp - MCP server and dev-flow tools.
• scrum4me-docker - headless runner for queued jobs.
• scrum4me-shared - shared schema and TypeScript contracts.

Commit Guidelines

Use small, focused commits:

• feat: for new behavior.
• fix: for bug fixes.
• docs: for documentation-only changes.
• chore: for tooling or configuration.
• refactor: for code improvements without behavior changes.

Keep one logical change per commit. Do not mix schema, UI, docs and tooling changes in the same commit unless they are required for one coherent feature.