Built With Spec4

The apps

Two apps share the planning_agent tier on purpose: Planning Agent fixes its plan up front, and ReAct Loop discovers it one observation at a time. Router is not a tier of its own: one classification call with structured output scores four paths the other apps already show — a hand-written evaluator, a single call, RAG's retriever, or search plus one generation call — and code, not the model, dispatches to the winner. Its catalog entry is chained_calls, recommendation and decision alike. The tier ladder is on the Agentifier page.

Every app runs on free models — OpenRouter and Groq, through one shared registry with one fallback chain — with per-visit run caps so a public demo can't spend the quota. The caps are stated on each app's page.

The eleven rounds

One line per round, from each vision.json's revision_history:

IMPLEMENTED is present in all eleven. Nine of the ten brownfield rounds open with an integration thread; v3 went straight to backend work. v8 and v10 skipped Designer and Agentifier, since nothing they planned had a new screen or a new model call; Deployer ran only when the deployment changed — v0, v1, v8, and the two rounds since, each updating the v8 plan for its delta. Run the agents a round needs.

Phases in v0–v4 run 7 to 14 instructions; the agentic-pattern rounds v5–v8 run 14 to 26; v9 and v10, planned under Spec4 2.x against a measured code review, are back to 6 to 14 across ten and eight phases.

The recommendation and the decision

Agentifier writes its recommendation and the developer's decision to the same file. From .spec4/v0/ai_catalog.json:

{
  "name": "rag_example_app",
  "tier_recommendation": "single_call",
  "tier_decision": "rag",
  "tier_decision_rationale": "The whole point of this example is to illustrate the use of RAG, so the retrieval pipeline is intentional despite the small dataset size."
}

The tool argued against the agent; the developer decided; the file records both. Every other product feature across v1–v9 shows recommendation and decision agreeing; the infrastructure entries — embedding_pipeline, vector_index, agent_loop_runtime, and the rest — carry no recommendation, because they're injected from the tier's pattern file rather than chosen.

Hand edits, reconciled

Between v0 and v1 the developer changed the code without Spec4, and the next round's CodeScanner read it. Three things entered the codebase that no v0 artifact mentions:

The v1 review's one recorded change risk is the free-tier model chains in model_registry.py rotting as providers retire slugs — a risk in code the plan never asked for, caught on the next scan. Rounds

Nine rounds later the reconciling is measured rather than read. v10's scan, under Spec4 2.11.1, found 67 files added and 12 modified since v9's plan and none removed, two symbols added to models.py, two load-bearing candidates entered and two left, no manifest changed, and one planned dependency no manifest declares — Playwright. The model's review then reconciled all ten v9 phases as evidence_found, recorded two divergences from the planned stack (both renames), and listed three areas edited outside any phase: the site metadata, the shared generation service, and the README, tooling, and manifests. The commit carried nothing back — carried: {env_vars: 0, dependencies: 0, api_surface: 0} — because the model had kept every untouched entry itself. v10's goal names those three unrecorded edits as something to write down; the excerpt is on the Artifacts page.

Deployment

The VPS runs the plan Deployer wrote in v8 and updated in v9 and v10, each for that round's delta — v10's records that the Router's unavailable state and Retry button ship in the same hashed bundle and change nothing in the edge. The v8 plan opens with instructions for the coding agent named for the round, then the whole system, one target at a time. The web client's block, from .spec4/v8/deployment-plan.md:

### `web_client`

- **Type:** on-premise (self-hosted VPS)
- **Provider:** netcup — VPS 500 G12 (2 vCore, 4 GB DDR5 ECC, 128 GB NVMe, always-on)
- **Service:** Caddy 2 serving static files from `/srv/bws4/frontend/dist`
- **Region:** netcup European datacenter (Nuremberg / Vienna / Amsterdam). Choose the one nearest your primary audience — this bears directly on `nfr_pages_appear_within_about_a_second`.
- **Transport:** HTTPS only. Automatic Let's Encrypt issuance and renewal by Caddy, automatic HTTP→HTTPS redirect.
- **CORS:** not applicable — serves the browser origin itself rather than consuming one.

Build: `npm ci && npm run build` executed **on the VPS** by `deploy/deploy.sh`, producing a hashed bundle with route-based lazy-loaded chunks per example app. Served with SPA history fallback.

The plan's Configuration Files section carries the Caddyfile, the systemd unit, deploy/deploy.sh, and a CLAUDE.md for the coding agent, complete. Its Roadmap records what was considered and not provisioned — CI, fail2ban, snapshots — so a later round can pick them up.

Cost

v0–v8 predate Spec4's usage recording, so there is no cost line for them. v9 and v10 carry one, from each round's usage.json — calls, tokens, and the cost LiteLLM computed, all on claude-sonnet-5-5 at medium effort:

About 70% of each round's input tokens were read from cache. v9's calls span October 1 to 16; v10's fit in a day. Spec4's own rounds carry a cost line on the front page, and SnarkCheck's round carries one with caching and all six agents.