Every card is one Spec moving through human gates.
SpecDeck borrows the recognizability of a board, but the columns represent where a human decision is needed, not every internal agent state.
Clarify a product idea before any agent starts changing code.
Review Goal, Acceptance, and Checks before the Builder begins.
Inspect Checks and Evidence from the completed agent run.
Freeze the Spec as the contract for what shipped.
Async agents move the bottleneck from typing code to reviewing work.
When several agents run in parallel, terminal output and PR diffs are too low-level for the human coordination layer.
Terminal agents are hard to see
They can execute, but they do not give a clear control surface for watching many parallel workstreams.
IDE agents stay synchronous
They work well at file level, but still assume one developer steering one active editing session.
Kanban tracks status, not trust
A board can show where work is, but it does not explain whether the result is proven enough to approve.
Read the Checks, not the code.
Each Spec carries its Checks and the Evidence behind them. A passing Check with no Evidence never counts as green.
- Evidence is required: tests, logs, screenshots, or video.
- An independent Checker verifies the work, never the Builder.
- Deterministic checks run first; model judging happens last.
Shopping cart calculation
The user reviews the outcome at the Check and Evidence layer.
Tax is applied based on region
Evidence: unit tests passed, 12 of 12.
Discount codes are validated
Missing Evidence: no end-to-end trace attached.
Four columns, left to right.
Backlog and Plan shape intent before code. Review is where finished work waits for approval. Done freezes the Spec as the contract.
- Backlog01
Ideas wait here before Planner turns them into a Spec.
- Plan02
Review what is about to be built: Goal, Acceptance, and Checks.
- Review03
Approve completed work at the Check and Evidence layer.
You review here - Done04
The accepted Spec is frozen as the shipped contract.
Planner, Builder, Checker.
The agent relay separates intent creation, code execution, and verification so the same actor does not grade its own work.
- Planner
Turns intent into a Spec: Goal, Acceptance, and Checks.
- Builder
Executes one Spec in isolation. One agent per unit of work.
- Checker
An independent model verifies the Evidence. It never grades its own work.
A three-tier topology keeps agents behind a gateway.
The web app speaks to a FastAPI gateway over REST and SSE. The gateway coordinates a separate LangGraph Agent Server and owns secrets, persistence, and realtime fan-out.
Web deck
Next.js renders board, project context, Spec detail, Checks, Evidence, and diff views.
FastAPI gateway
REST commands and SSE streams pass through the gateway so clients never talk directly to the agent server.
Agent server
Planner, Builder, and Checker run as LangGraph workflows behind a structured event contract.
Persistence and realtime
Postgres stores app state while Redis pub/sub fans Builder and Checker events back to the board.
The design makes review cheap by narrowing what it tries to solve.
SpecDeck is not an IDE replacement. It is a coordination layer for deciding what agents should do and whether their output is proven.
- 01
Review at intent level
Control kept
Optimized for approving Goals, Acceptance, Checks, and Evidence quickly.
Cost accepted
Developers still need a diff escape hatch for risky changes and final spot checks.
- 02
Independent Checker
Control kept
Optimized for avoiding the Builder validating its own blind spots.
Cost accepted
Adds latency, model cost, and another event stream to operate.
- 03
Single-user coordination first
Control kept
Optimized for one operator running many agents without collaboration overhead.
Cost accepted
Multi-user review, canvas workflows, and full IDE replacement are deliberate non-goals for this stage.
Concept validated through a scaffolded, mock-driven deck.
The repo has architecture decisions, a self-host skeleton, and a product-shaped frontend. Real Planner, Builder, and Checker logic is still the next milestone.
Product UI is tangible
Landing, workspace, board/list views, grouped swimlanes, filters, project context, Spec detail, Checks, Evidence, and Diff are present as mock-driven flows.
Stack skeleton runs locally
The repo includes web, gateway, agent package boundaries, Postgres, Redis, and docker-compose wiring.
Next milestone is real orchestration
The open work is wiring Planner, Builder, and Checker execution to live workspace state and evidence capture.
Self-host the whole deck.
SpecDeck is designed to run in the owner's environment, with model keys and project workspaces kept behind the backend boundary.
- Postgres, Redis, gateway, agents, and web are composed together.
- Model keys stay server-side; the frontend gets events, not secrets.
- The repository remains the system of record for Specs, context, and implementation.