Workflow Blueprint
Workflow Blueprint is an invite-gated Next.js App Router task-planning workspace — board-based tasks, subtasks, recurring work, notes, profile settings, Resend-backed transactional email, and a per-visitor demo sandbox — with a first-class agent-access layer: per-user scoped API tokens, a full read/write external REST API (/api/external/v1/*), and an in-repo MCP server (/api/external/v1/mcp) so a user's AI agents can run their own boards, tasks, and subtasks headlessly.
The live deployment is at https://www.workflowblueprint.io.
What this repo demonstrates
This repository is published as a showcase of a multi-agent development workflow with PR-level guardrails, not just as a working product. The artifacts of that workflow are checked in alongside the code:
- Strategic source of truth.
PROJECT.md defines the product's purpose, non-goals, and the resolved open questions (Q1–Q9) that act as durable Verifier rules. Any PR that violates these rules is an automatic reject.
- Tactical agent runbook.
AGENTS.md is the operational quickstart that Builder agents (OpenAI Codex) read before writing code, plus dev-environment gotchas.
- Walked-through case study.
CASE_STUDY.md traces a single PR (#13) end-to-end: the Builder prompt, the diff Codex returned, the Verifier rule it triggered (the Q6 scope-discipline rule), and how the rule itself was born from that PR.
- Machine-readable API contract with CI drift detection.
docs/openapi.yaml is generated from Zod schemas in src/lib/external-contract.ts; a CI test (tests/api/external/openapi.test.ts) fails any PR where the committed spec diverges from the schemas.
- Real CI gates, not vibes.
.github/workflows/ci.yml runs six parallel jobs (lint, audit, typecheck, build, test, smoke) on every PR, with a Postgres service container backing the integration and smoke suites.
- A sustained, self-correcting test-coverage push. Two campaigns, both run through the same Builder/Verifier loop one narrowly-scoped slice at a time. PRs
#159–#193 (35+ merges) took line coverage from 72% to 93%+; PRs #204–#233 (25 slices) then targeted the metric Codecov actually reports — which counts a partially-covered line as uncovered, and so read 84.91% where the test runner reported 93% — and closed all 684 outstanding records to reach 100%, with src/app/**, src/components/**, and src/lib/** all at zero. It's a useful trace of the workflow under sustained load. Prompts built on wrong assumptions were caught and corrected rather than forced — nearly every builder hard-stop traced to an advisor claim about whether a branch was reachable, which measurement then disproved in one direction or the other. Techniques were validated against disposable spikes before being prescribed. And because a coverage pragma is a permanent hole in the signal, each batch was held to an inverse check — strip the markers, re-run coverage, confirm exactly the claimed records reappear and nothing else — rather than to an argument.
The most informative entry points are PROJECT.md, the merged PR history (especially #7, #10, #13, and #14; the #106–#114 agent-access epic — per-user scoped auth → read/write endpoints → MCP capstone; and the #159–#193 and #204–#233 coverage campaigns for the workflow under sustained, repetitive load), and CASE_STUDY.md.
What I would do differently
A short, honest retrospective. Three things I would change if I were starting this repo over today:
- Write
PROJECT.md on day one, not at PR 5. The Builder/Verifier handoff was installed in #5 after several feature PRs had already merged. Several of those earlier PRs would have been smaller and more focused if the scope-discipline rule (Q6) had existed when they were prompted. Lesson: the strategic document should be the first commit, even when its contents are still rough.
- Adopt path-versioned external APIs from the first endpoint. The original API lived at
/api/external/daily-summary and /api/read-only/*. Migrating to /api/external/v1/* required PR 3 (consumer migration in another repo) and PR 4 (legacy alias removal) before the contract could be cleanly versioned. Starting with /v1/ from day one would have eliminated both PRs.
- Treat the Builder prompt as a reviewable artifact. Q6 ("out-of-scope changes must be declared in the PR body") only became enforceable after
#13 shipped a correct-but-unauthorized SQL rewrite. If the Builder prompt itself were checked into the PR description from the start, scope drift would be auditable from day one rather than caught reactively.
Stack
- Next.js 16 App Router and React 19
- Prisma 7 with PostgreSQL persistence (currently hosted on Supabase)
- Tailwind CSS 4 with custom blueprint design tokens
- Zod validation on all API payloads
- Signed HTTP-only session cookies with
jose
- Resend transactional email for welcome and password reset messages
Getting Started
npm install
npm run db:deploy
npm run db:seed
npm run dev
The dev server starts Next.js on 127.0.0.1. Run npm run db:deploy before the first deploy, and run npm run db:seed only when you want the demo account and starter boards in the configured database.
The seed command reads the demo account password from the required DEMO_USER_PASSWORD environment variable and refuses to run when NODE_ENV=production or VERCEL_ENV=production unless ALLOW_PRODUCTION_SEED=true is also set. Choose a unique value per environment and rotate it.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
