Sprintwise

Teams often start sprints with vague stories, and mid-sprint scope changes go unmeasured. Sprintwise scores every user story for readiness before planning, then measures how much the sprint changes after the team commits.

• Readiness check: nine fixed rules (C1–C9) give each story a score out of 100. Every point lost comes with a plain-English reason, one per missing thing. A story that isn't estimated, or is too big, can't be Ready. The score never uses AI.
• Scope tracking: lock the day-one sprint as a baseline and see scope added, removed, net change, churn and completion. A sprint built from the backlog records status and points changes as they're made; a sprint kept with Jira CSVs takes a fresh export as a snapshot. A burn-up chart shows scope against work done, day by day.

Paste a story, upload a CSV, or connect Jira Cloud to import, sync and send edits back. Light and dark themes. All sample data is invented.

Live: https://sprintwise.app · try the demo without signing in · watch the 3-minute demo video with voice-over on the home page.

Status

Version 2 is live (see the changelog). Version 1's phases, from the requirements doc:

Phase	Stories	State
1 · Foundations	F-1 CI, F-3 GitHub sign-in, F-4 projects	Done, live
2 · Readiness rules	R-1 paste a story, R-2 CSV import, R-3 sorted backlog, R-6 rule settings	Done, live
3 · AI layer	R-4 rewrites, R-5 test scenarios	Built and tested, switched off on the live site; moved to v2 (see below)
4 · Scope tracking	S-1 to S-4, S-6	Done, live
5 · Report and polish	S-5, F-2 demo, L-2 accessibility, F-5 privacy	Done: S-5 report, F-2 demo with a sample sprint, F-5 privacy and terms pages, L-2 accessibility (axe and keyboard tests)
6 · Launch	L-1, L-3	Done: README, screenshots, demo video and usage counts

Screenshots

All data shown is invented. The images follow your GitHub theme. Regenerate them with pnpm screenshots.

Backlog: every story scored, in your priority order (drag to reorder) or weakest first, with search, band and status filters, and changes to several stories at once.

Story: the score and a plain-English reason for every point lost.

Sprint: metrics against the locked baseline, and the dated change log.

Report: one printable A4 page.

Product decisions

The calls that shaped v1, with the reasoning in DECISIONS.md:

• CSV in v1, Jira in v2. Jira's sign-in and API setup is where side projects stall. CSV import proves both halves of the product with no integration risk.
• Rules set the score; AI never does. A rule-based score is the same for the same story every time, and every point lost has one reason you can explain.
• AI rewrites were built, tested, then switched off. Suggestions cost about two US cents each on the Claude API. For a free tool with no budget, I kept the code and tests and moved the live feature to v2, rather than pay ongoing costs or show a half-working button. Setting ANTHROPIC_API_KEY turns it on.
• An unestimated or oversized story can't be Ready. Under the first version of the rules, a story with no estimate scored 80 and passed. The fix caps the band rather than changing the score, so every point lost still has exactly one reason.
• The baseline can't be edited. If it could, every scope metric would be meaningless. A baseline locked by mistake can be undone until the first later snapshot is saved; after that, the only way to redo it is to delete the sprint.
• Built around a PO's week. Plan with the team's real velocity and a warning before committing unready stories; tag why scope changed; share the report with stakeholders by link; watch trends across sprints. All rule-based, no AI and no running costs.
• Rules v3: harder to fool. A story with the right shape but vague content ("As a user … so that I can see stuff", "Then it works") scored 95 under v2. v3 asks for a named user, more criteria for bigger stories, and more vague words. A rule that fails only because another did is folded into that one's reason, so seven failed checks on a bare story read as four things to fix.
• Team checks cap the band, not the score. A team's own Definition of Ready items are pass/fail. Adding points would break "100 points from nine rules", so a failed check keeps a story from being Ready instead, like an oversized story does.
• Changes are recorded as they happen. In a sprint built from the backlog, editing a story's status or points (from the backlog, the sprint page or the story) updates that day's automatic snapshot. One automatic snapshot per day keeps the change log readable, and editing back to the old value removes it. Snapshots saved by hand are never rewritten.
• No Jira? No CSV needed. Stories can be typed in and edited with a live score, and a sprint's baseline and snapshots can be picked straight from the backlog. CSV stays for teams that export from Jira.

Tech stack

• Next.js 16 (App Router) and TypeScript
• Tailwind CSS 4
• PostgreSQL through Prisma 7
• Better Auth with GitHub sign-in
• Claude API (Anthropic SDK) for optional AI suggestions, off unless a key is set
• Papa Parse and Zod for CSV parsing and validation
• Vitest, Playwright and axe for tests
• Vercel and GitHub Actions for hosting and CI

Why each choice was made is in DECISIONS.md.

Run it locally

You need Node 24 (nvm use), pnpm and Docker.

1. Install the dependencies:

   pnpm install
   

2. Create .env from the example:

   cp .env.example .env
   

   In .env, set BETTER_AUTH_SECRET to the output of openssl rand -base64 32.

3. Start Postgres and run the migrations:

   pnpm db:up
   pnpm db:migrate
   

4. Start the app:

   pnpm dev
   

Then open http://localhost:3000. The demo at /demo works without signing in.

GitHub sign-in

1. Create an OAuth app at https://github.com/settings/developers.
2. Set the callback URL to http://localhost:3000/api/auth/callback/github.
3. Put its client ID and secret into GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET in .env.

Jira connection (optional)

1. Create an OAuth 2.0 (3LO) app at https://developer.atlassian.com/console/myapps/.
2. Under Permissions, add the Jira API with read:jira-work, write:jira-work and read:jira-user, and the User identity API with read:me.
3. Under Authorization, set the callback URL to http://localhost:3000/api/auth/callback/atlassian (and the live site's equivalent).
4. Put its client ID and secret into ATLASSIAN_CLIENT_ID and ATLASSIAN_CLIENT_SECRET in .env.
5. To let people outside your own Atlassian account connect, turn on Distribution → Sharing in the console. It asks for a vendor name, a privacy policy URL (/privacy), and whether the app stores personal data: yes, Atlassian account IDs, reported through the personal data reporting API.

Atlassian requires apps that store account IDs to report them weekly. Vercel Cron calls /api/cron/atlassian-accounts daily (vercel.json); each ID is reported when its cycle is up, and a connection is deleted when Atlassian says its account was closed. A second cron, /api/cron/jira-sync, syncs each night the projects that have a sprint following the backlog. On Vercel, set CRON_SECRET (any long random string): both routes refuse every call without it, and Vercel Cron sends it.

Without these, the Jira parts of the app don't appear. End-to-end tests use a pretend Jira (JIRA_FAKE), so they never need a real one.

Tests

Command	What it covers
pnpm test	Unit tests: every scoring rule, the CSV parser, snapshot comparison and every metric, including the requirements doc's worked example
pnpm test:e2e	End-to-end tests against a production build: home page, demo, sign-in, projects, scoring, CSV import, access control, keyboard-only flows, and axe accessibility scans of every public page
pnpm lint and pnpm typecheck	Static checks

CI runs all of these on every push and pull request (.github/workflows/ci.yml).

Project layout

Path	Contents
src/lib/readiness	The rules engine: pure functions, no I/O
src/lib/csv	The frozen CSV template and parser
src/lib/sprint	Snapshot comparison and sprint metrics: pure functions
src/lib/server	Database client, auth, and the data access layer that checks ownership on every read and write
src/app	Pages and server actions; (marketing) holds the public site: home, product, demo, changelog, about and privacy
src/components/marketing	The home page's interactive parts: live scorer, feature tabs, video player, scroll reveals
src/demo	Invented sample data for demo mode, and the demo video's captions (video-lines.json), shared by the recorder and the home page transcript
e2e	Playwright tests

Launch kit

Document	Contents
Demo video script	A timed shot list; pnpm record-demo --voice records it from a local build with a voice-over (MP4, WebM)
DECISIONS.md	Every decision with its options and reasons

Usage counts (L-3): pnpm usage prints anonymous event counts by month: checks run, imports, reports and AI suggestions. Point it at production with DATABASE_URL="<Neon connection string>" pnpm usage. The events table holds only an event type and a time: no user ids and no story text.

Feedback and visit counts

"Send feedback" (footer and sidebar) opens a GitHub issue form. The live site counts page views with Vercel Web Analytics: no cookies, with ids, share tokens and query strings removed before sending (src/lib/analytics.ts).

Security

Report security problems privately through GitHub's vulnerability reporting, not in a public issue. SECURITY.md covers scope, response times and safe testing. The live site also serves /.well-known/security.txt.

Known limits

• Snapshots record what changed and on which day, not who changed it. The Jira connection reads issues, not their change history.
• Jira Cloud only (not Jira Data Center), up to 1,000 issues per search.
• One owner per project: teammates can read a shared backlog or report link, but can't edit.
• AI suggestions are built but switched off on the live site, to avoid running costs.

License

PolyForm Noncommercial 1.0.0. You may read, run and change the code for any noncommercial purpose, such as learning or personal use. Using it in a product or service you sell, or inside a business, needs permission. Copies taken before 19 October 2026 stay under the MIT license they came with.