I know because I tried. I called 311 to report a cracked sidewalk near my neighbourhood. Fifteen minutes on hold. Then I described the location verbally to an operator who typed it into a form I couldn’t see. No photo. No GPS coordinates. No confirmation it went to the right department. I hung up and thought: that’s the last time I’m doing this.

I tried the city’s online reporting tool. Six minutes to fill out forms, describe the location in text, select from dropdowns that didn’t quite match my issue, and upload a photo through a clunky interface. Six minutes for a pothole.

Most people won’t spend six minutes. Most people won’t spend one minute. So the pothole stays. The graffiti stays. The broken streetlight stays. Not because nobody cares. Because the process punishes you for caring.

This is why I built SolveTO.

The math behind the problem

Toronto received 6,839 pothole reports in February 2026 alone. A fivefold increase from last year. The city repaired 257,000 potholes in 2025. The scale is massive.

But here’s the number that matters: each 311 phone report costs the city $12 to $15 in call center staff time. That’s operator wages, phone infrastructure, data entry, and ticket routing. Multiply that by hundreds of thousands of calls per year.

In the UK, Buckinghamshire Council measured the exact same problem. Email-based reports cost them $12.50 each. When they switched to FixMyStreet, an online civic reporting platform, that dropped to $0.15. The City of Melbourne in Australia saw a 17% improvement in citizen satisfaction scores after adopting Snap Send Solve, a similar platform.

These aren’t hypothetical gains. Cities worldwide are replacing phone-based reporting with digital platforms and seeing real results. Toronto is behind.

What I built

SolveTO is a free civic reporting platform for Toronto. It’s been live since early February 2026, covering all 25 wards. It costs the city nothing.

Here’s how it works.

You open solveto.ca on your phone or desktop, take a photo of the issue and submit it. That’s it. AI identifies what it is, pothole, graffiti, broken streetlight, illegal dumping, one of 24 categories. It rates the severity. It writes a structured report. GPS pins your exact location and maps it to the correct ward and postal code. The report goes to 311@toronto.ca and your ward councillor simultaneously.

Thirty seconds. No phone tree. No forms. No hold music. It’s that simple.

The report appears on a public live map that anyone can see. Other residents can verify the issue exists. When it’s fixed, anyone can submit a resolution photo. Everything is tracked, transparent, and public.

What the live map shows you

The homepage is a full-screen interactive map of Toronto with every report plotted in real time. It refreshes every five minutes.

You can filter by any of the 24 issue categories, each showing a live count. Filter by time: last 24 hours, 48 hours, 7 days, 30 days. Filter by ward, click any of the 25 wards to see its boundary drawn on the map and all data filtered to that ward. Toggle between open and closed reports, each showing how many exist.

Every filter combination is encoded in the URL. So you can bookmark “all open potholes in Ward 11 from the last 7 days” and share that link with your councillor. The charts update live as you filter. The sidebar updates. The counts update. Everything is connected.

This isn’t a static dashboard. It’s a live accountability tool.

What councillors and the city get

For councillors, SolveTO provides something that doesn’t exist today: a real-time view of what’s broken in their ward.

Ward report cards show total reports, open vs resolved, resolution rate, average response time, and top issue types. There’s a downloadable PDF for council meetings and budget requests. Councillor effectiveness is publicly visible, ranked by responsiveness and resolution rate.

For city operations, every report arrives structured and categorized. AI identifies the responsible department, Transportation, Parks, Solid Waste, Toronto Hydro, Municipal Licensing, or Parking, so reports can be triaged instantly. Reports include photos, GPS coordinates, severity ratings, and safety risk flags. No phone call. No manual data entry.

Duplicate detection clusters reports at the same location within 50 metres. If three people report the same pothole, the city sees one cluster, not three separate work orders.

The features that matter

Camera-first reporting. Take a photo and AI from anthropic handles the rest. No typing required unless you want to add description. Works on any phone with a browser. No app to download.

24 issue categories. Potholes, graffiti, illegal dumping, illegal signage, streetlights, tree issues, snow and ice, sidewalk damage, abandoned vehicles, parking violations, and 15 more. AI picks the right one.

Face redaction. AI automatically detects and blurs faces in photos before they’re stored or delivered. Bystander privacy is protected by default, not as an afterthought.

Duplicate detection. If someone already reported the same issue within 50 metres in the last 30 days, you’ll see it before submitting. This prevents redundant 311 tickets and helps prioritize repeat complaints.

Community verification. Neighbours can confirm a report: “confirmed,” “still here,” or “fixed.” Democratic validation, not just individual complaints.

Outside-Toronto alerts. If your GPS falls outside city limits, you’re warned before submitting. No wasted reports.

Public analytics. Open at solveto.ca/analytics. KPIs, resolution rates, response times, SLA compliance. Ward leaderboards. Councillor effectiveness scores. All public.

Works everywhere. Desktop and mobile. Add it to your home screen and it works like a native app. No app store needed. Works offline too, your report saves locally and syncs when you’re back online.

What’s next

SolveTO is live and serving Toronto residents today. Anyone can report an issue right now and it reaches 311 and their ward councillor for FREE. That works. But it’s only half the picture.

Platforms like FixMyStreet Pro in the UK and Snap Send Solve in Australia started the same way: citizens reporting, cities receiving. Then cities partnered with them. FixMyStreet Pro now serves 30+ UK councils. Snap Send Solve processes reports for 850+ organizations across Australia and New Zealand. Both operate as city partners, not volunteers. The city contracts the platform, gets direct integration with its internal systems, and the reporting pipeline becomes part of city operations.

That’s the model. SolveTO works on its own, but without city partnership it hits a ceiling. Reports go to 311 by email. We can’t connect directly to the city’s work order systems. We can’t close the loop and tell residents when their pothole is actually fixed. We can’t route reports straight into departmental queues. The platform is ready for all of that. The city just has to say yes.

If you’re a resident, use it. Report what’s broken. The more reports that land on city desks through SolveTO, the harder it becomes to ignore.

If you’re in city operations or on council, let’s talk. This isn’t a side project. It’s infrastructure that already works, built to integrate with yours.

solveto.ca — thirty seconds, that’s all it takes.

By the numbers

If you live in Toronto, use SolveTO. Report what you see. Report it again when it’s not fixed. Share it with your neighbours. Tell your councillor it exists. Bring it up at community meetings. The more residents who report, the more data the city can’t ignore.

If you work for the City of Toronto or any other Canadian city, SolveTO is ready to integrate with your systems today. I’m open for business. Get in touch.

I read that and thought: we launched this three weeks ago. SolveTO is a free platform where anyone in Toronto can photograph a civic issue — pothole, broken sidewalk, graffiti, damaged infrastructure — and AI handles the rest.

What SolveTO does right now

SolveTO is a free platform where anyone in Toronto can photograph a civic issue — pothole, broken sidewalk, graffiti, damaged infrastructure — and AI handles the rest.

Here’s the flow:

1. Snap a photo. The app captures your location automatically.
2. AI analyzes it. Within seconds, it classifies the issue type, assesses severity, and generates a structured report.
3. Auto-routed. The report goes to 311 and the ward councillor’s office. No phone trees. No 45-minute hold times.
4. Public accountability. Every report is public. Resolution rates are tracked per ward. Councillor performance is visible to everyone.

It’s been live since early February. We have reports filed across Toronto and every one of the 25 wards is covered.

The numbers that matter

The Sun article cited 6,839 pothole reports in February alone — a fivefold increase from last year. The city repaired 257,000 potholes in 2025. The scale is massive and growing.

The bottleneck isn’t repair crews. It’s reporting. Calling 311, waiting on hold, describing the location, hoping someone logs it correctly. That’s the part AI can eliminate today. I tried the city online solution and it was a nightmare. I had to describe the location, take a photo, and fill out several forms. It took me 6 minutes to report a pothole.

SolveTO already eliminates it. A photo and 10 seconds is all it takes.

What makes this different from 311

311 is reactive. You call, you wait, you describe. Someone logs it. Maybe it gets routed correctly.

SolveTO is proactive. Computer vision identifies the issue. GPS pins the location. The report is structured, categorized, and delivered before you’ve put your phone back in your pocket.

We also added community verification — neighbours can confirm an issue exists, which helps the city prioritize. And duplicate detection clusters reports at the same location so crews aren’t dispatched twice.

The real problem isn’t technology

Councillor Ainslie is right that AI can help. But the hard part isn’t building the tech. The hard part is getting citizens to use it and trust it.

That’s why SolveTO is designed as a public accountability tool, not just a reporting tool. Every report is visible. Every ward’s resolution rate is public. Councillors can’t quietly ignore reports when their constituents can see the scoreboard.

What’s next

I’m reaching out to Councillor Ainslie’s office directly. If the city wants AI-powered pothole reporting, it exists. It’s free. It works today.

If you’re in Toronto and you see a pothole, try it: solveto.ca

The contractor is on a roof three towns over. Phone is in the truck. He won’t see the notification until 5pm when he’s driving home. Or busy working and doesn’t check his phone until end of the day. By then the homeowner has submitted the same request to two other contractors. One of them replied in four minutes. They’re already booked for a Thursday walkthrough.

This happens every single day.

The numbers are brutal

Harvard Business Review and InsideSales.com studied 2.24 million leads across industries. What they found:

Responding within 5 minutes makes you 21 times more likely to qualify a lead than waiting 30 minutes. Wait an hour and you’re already 60 times less likely to convert than if you’d responded in the first five minutes. Wait 24 hours and it’s basically over.

And the construction industry? The average response time is 42 to 47 hours.

Let that sink in. Almost two full days to respond to someone who is ready to spend money right now.

Here’s the rest of the picture. 78% of customers buy from whoever responds first. Not whoever has the best reviews. Not whoever has the lowest price. Whoever picks up the phone first. And 85% of customers won’t even leave a voicemail. They just call the next contractor on the list.

For a remodeling contractor running a decent lead pipeline, slow follow-up costs over $50,000 a year in lost jobs. That’s not a guess. Work backward from average job values, lead volume, and conversion drops at each delay interval. The money is disappearing while the phone sits in the truck.

Only 4.7% of companies across all industries respond to leads within 5 minutes. In contracting, that number is even lower.

Why the usual fixes don’t work

The typical advice is “set up an autoresponder” or “get a CRM.” Neither solves the real problem.

Autoresponders send something like “Thanks for reaching out! We’ll get back to you within 24 hours.” Boring. No values and no personality. The customer reads that and thinks “so you’re slow, got it” and keeps calling other contractors. A generic auto-reply doesn’t qualify the lead, doesn’t answer their question, and doesn’t make them feel like someone is actually paying attention.

CRMs are worse. They assume the contractor is going to sit down at a laptop, log into a dashboard, and manage a sales pipeline. Contractors are not at laptops. They’re on ladders. They’re under houses. They’re covered in drywall dust. The problem with speed-to-lead(STL) systems in contracting isn’t that people don’t know it matters. Everyone knows fast response wins jobs. The problem is access. The contractor physically cannot get to the tools that are supposed to help them.

What I built

I spent a weekend building a system focused on one thing: meet contractors where they already are. Their phone. Specifically, Telegram.

Here’s what happens when a lead comes in.

A homeowner fills out a simple contact form. Within seconds, the contractor gets a Telegram notification on their phone with the lead details. Name, phone number, email, what service they need, how urgent it is, and their message. Everything they need to decide if this is worth pursuing.

At the same time, AI sends the customer an intelligent email response immediately. Not a generic “thanks for reaching out.” An actual response that acknowledges their specific request, asks a relevant follow-up question, and makes them feel like someone is paying attention. The customer gets a real reply in their inbox instead of waiting in a void.

The contractor, still on the roof, glances at their phone. They see the lead summary and the urgency level. Emergency leads get flagged hard so nothing critical gets missed. They know exactly what this lead needs and can decide on next steps right from Telegram. No app to open. No dashboard to log into.

From Telegram, they can:

• Type /leads to see all waiting leads
• Type /done to mark a lead as contacted
• Type /book to schedule an appointment
• Type /close to mark a job as won
• Type /stats to see today’s numbers

Additionally, every morning they get a briefing with overnight leads, today’s scheduled jobs, and an AI-generated summary of what needs attention. If a lead has been sitting for two hours without contact, the system sends a follow-up reminder automatically.

The entire workflow lives inside an app they already have on their phone. Zero friction.

Before and after

Before STL Agent: A lead comes in at 2pm. The contractor doesn’t see it until 5pm. They make a mental note to call back tomorrow. Tomorrow they forget. The customer hired someone else two days ago. The contractor never even knew they lost the job.

After STL Agent: A lead comes in at 2pm. AI emails the customer within seconds with an intelligent qualifying response. The contractor gets a Telegram ping moments later with the lead details and urgency level. They glance at the summary between tasks, see the customer needs a kitchen reno, and call them back on their next break. The customer, who was about to call another contractor, already has a thoughtful email in their inbox. The contractor books the walkthrough that evening.

The gap between those two scenarios is tens of thousands of dollars a year.

What’s coming next

The current system handles web leads through Telegram. That’s the foundation. What’s coming:

AI phone calls. When a lead calls and the contractor can’t answer, AI picks up, has a natural conversation, qualifies the project, and books the appointment. The contractor gets a transcript and summary on Telegram.

Outbound SMS. Automated text follow-ups to leads who haven’t responded, timed based on engagement patterns.

Voice transcription. Every voicemail and call automatically transcribed, summarized, and delivered to Telegram.

The goal is simple. No lead should ever have to wait.

How it’s built

Built with Rapidfy. AI agent build Rails applications in seconds. Claude powers the AI responses and lead qualification. Telegram Bot API delivers notifications and receives commands. The whole thing runs on a single server with SQLite. It’s deliberately simple because reliability matters more than architecture when someone’s livelihood depends on it.

Take a look

If you’re a contractor losing leads to slow follow-up, or you work with contractors and see this problem every day, take a look at STL Agent. It’s live and working.

The math is straightforward. If faster response wins more jobs, and the barrier to faster response is access, then the fix is meeting contractors where they already are. Everything else is noise.

STL Agent Dashboard

Telegram Notification

Telegram Morning Briefing

After model overhead, system prompts, tool definitions, autocompact buffer, memory files, SKILL files, and accumulated conversation history, you might have half that for actual reasoning. Add an MCP server or two and you’re down to a third.

Many developers building with agents never measure this. They add tools, extend prompts, wire up MCP servers, and wonder why the agent starts forgetting instructions halfway through a task. The answer is always the same, you’re taxing your agent’s brain and not tracking the bill.

Where tokens actually go

Here’s a rough breakdown from my agent system:

A 200k context window with two MCP servers and a detailed prompt might leave 100-120k for actual work. That sounds like a lot. Then the agent hits iteration 8 and the conversation history has consumed another 60k.

I measured this by accident. My agent was performing well for 4-5 iterations, then quality would drop sharply. Features that should have taken one iteration started taking three. The agent would forget constraints from its instructions and start writing code that violated my coding standards.

The problem wasn’t the model. The problem was that by iteration 6, there wasn’t enough room left in the context window for the model to hold the instructions and reason about the code and remember what it had already done.

The MCP tax

MCP servers are the biggest hidden cost in agent architectures. Each server adds three layers of overhead:

Tool definitions. Every tool the server exposes gets serialized as a JSON schema in the context. A server with 10 tools might add 3,000-5,000 tokens just for the definitions. Before you ever call a tool.

Protocol overhead. Handshake, capability negotiation, connection state. Small per-call, but it adds up across dozens of tool invocations per iteration.

Response data. This is the killer. Tool outputs go directly into the context window. For most tools, responses are small (a file listing, a search result). For Puppeteer, a single screenshot costs roughly 3,000 to 6,000 tokens, depending on page size.

What MCP Puppeteer actually costs

I ran this experiment. One verification check, “are the routes healthy?”, in two formats.

MCP Puppeteer (inside the agent loop):

Agent: [tool_call] puppeteer_navigate { url: "http://localhost:3000/" }
Server: { status: "navigated", title: "Rapidfy" }
Agent: [tool_call] puppeteer_screenshot {}
Server: { screenshot: "data:image/png;base64,iVBORw0KGgoAAAA..." }
         ^^^ 3,000-6,000 tokens for ONE screenshot
Agent: "The page looks correct, I can see the header and navigation..."

Repeat for 5-10 routes per iteration. Total: 15,000-60,000 tokens per verification pass, plus the MCP overhead that’s always there whether you call a tool or not.

Text summary (outside the agent loop):

## Route Verification (14:23:13)
10 passed, 0 failed (of 10 routes)
OK   / -- 200 (49750B)
OK   /apps -- 200 (12637B)
...

Total: ~200 tokens. Same signal. The agent knows all routes are healthy. It doesn’t need to see the pages to know they render.

That’s a 75-300x difference for the same information.

The one-window-one-goal principle

Geoffrey Huntley’s harness philosophy can be summarized in one line:

One window, one goal. Reset between iterations.

This means:

• Each agent invocation gets a fresh context window
• The agent does ONE thing (implement one feature, fix one bug)
• All state lives on disk (files, git), not in conversation history
• Tools are minimal: code editing and shell access, nothing more

My harness implements this literally. Each iteration is a fresh invocation:

OUTPUT=$(build_prompt | claude -p --dangerously-skip-permissions 2>&1 \
         | tee "$LOG" || echo "ERROR")

The prompt is piped in. The agent runs. Output is captured. The loop checks for progress and either continues (fresh invocation) or stops. No accumulated conversation history across iterations.

This is why the circuit breaker from Part 1 matters, each iteration starts clean, so the agent can’t spiral. And it’s why the progress file matters, since context resets between iterations, the agent needs something on disk to tell it where it left off.

The test-summary injection pattern

This is the single most impactful optimization in my harness. Instead of the agent running bin/rails test itself (which fills the context with 50-100 lines of raw test output), the harness pre-computes the results and injects a compact summary.

build_prompt() {
    local prompt
    prompt=$(cat "$PROMPT_FILE")

    # Run tests OUTSIDE the agent, inject summary
    ./test-summary.sh > /dev/null 2>&1 || true
    if [ -f ".test-summary" ]; then
        prompt="${prompt}

## Current Test State (pre-computed, do not re-run unless you change code)
$(cat ".test-summary")"
    fi

    echo "$prompt"
}

The test-summary script extracts just the stats and failures from raw test output:

RAW=$(bin/rails test 2>&1) || true

# Extract summary line (e.g. "34 runs, 84 assertions, 0 failures")
STATS=$(echo "$RAW" | grep -E '^\d+ runs,' | tail -1)

# Extract failure lines only (compact)
FAILURES=$(echo "$RAW" | grep -E '(Failure|Error):$' -A 2 | head -30)

Full test output: 80 lines. Summary: 3-15 lines. That’s an 80-90% token reduction on test state, every single iteration.

The instruction that saves the most tokens:

## Orientation
- If a "Current Test State" section is appended below, use it to orient —
  don't re-run tests unless you change code
- Focus on failures listed in the summary first

Two lines. Without them, the agent re-runs the entire test suite on its own, wasting tokens on raw output that the harness already summarized. With them, the agent trusts the pre-computed results and only runs tests after making changes.

Over 15 iterations, this saves roughly 25,000-40,000 tokens. That’s the difference between an agent that finishes its task and one that starts forgetting its instructions on iteration 10.

What to keep inside vs outside the context

Here’s the framework I use:

Keep inside the context window

• Task definition: what to build, acceptance criteria, test commands
• Relevant code: files the agent needs to read and modify (on demand, not pre-loaded)
• Pre-computed state: test results, route health, as compact text
• Conventions: coding standards, commit format, project rules (short list)

Externalize

• Raw test output: run tests outside, inject a summary
• Route verification: check outside, inject pass/fail counts
• Screenshots: don’t. Use text-based checks instead
• Full file contents: let the agent read files on demand rather than front-loading everything

The general principle, if it can be computed outside the context window and summarized in under 20 lines of text, do it outside.

Practical strategies

1. Pre-compute everything you can. Test results, route checks, linting output. Run it in the harness, summarize it, inject it as text. The agent should consume results, not produce them.

2. Use compact formats. 10 passed, 0 failed beats a full test log. OK /apps -- 200 (12637B) beats a screenshot. Design your summaries for scanability.

3. Reset between iterations. Don’t accumulate conversation history across agent invocations. Each iteration starts with a fresh context window and a current state snapshot from disk.

4. Measure your overhead. Count the tokens in your system prompt, tool definitions, and injected context. If overhead exceeds around 40% of your context window, you’re leaving performance on the table.

5. Question every MCP server. For each MCP server in your agent’s config, ask: “Can this be replaced with a shell script that produces a text summary?” If yes, do it. The token savings compound across every iteration.

6. Tell the agent what not to do. “Do not re-run tests unless you change code” saves more tokens than any optimization technique. Agents are eager. They’ll redo work to be safe. Explicit instructions to trust pre-computed state prevent this.

The optimization that matters

The best agent optimization isn’t faster models or bigger context windows. It’s spending fewer tokens on overhead so more tokens go to actual thinking.

Every MCP server you add is a tax on your agent’s ability to reason about the problem. Every raw test log you inject is noise that pushes out signal. Every screenshot is thousands of tokens that could have been ten lines of text.

The agent that ships the best code isn’t the one with the most tools. It’s the one with the most tokens left for reasoning.

This concludes the series “Building agent harnesses that work.” Start from Part 1 — 7 Patterns for long-running agent harnesses or revisit Part 2 — Where verification actually belongs in agent harnesses.

The agent doesn’t know. It can’t see the page. It sees a status code and moves on.

This is the E2E verification gap, and there are two competing philosophies on how to close it.

The problem: HTTP 200 does not mean “correct”

A Rails controller test can pass while the actual rendered page is broken. Here’s why:

• Controller tests mock the request cycle. They don’t start a real server
• A route can return 200 with a Rails exception page in the body
• A missing partial renders an empty page but no 500 error
• A bad database query returns the layout with no content

I had exactly this situation. A route was returning HTTP 200, all tests passed, and the agent committed the feature as complete. When I opened the browser, the page said “We’re sorry, but something went wrong” inside a perfectly valid 200 response. Rails wraps some errors in a 200 because the error page itself renders successfully.

Unit tests tell you the code works. They don’t tell you the app works.

Anthropic’s recommendation: MCP Puppeteer

Anthropic’s guide recommends giving agents browser access via MCP (Model Context Protocol). Specifically, they recommend the Puppeteer MCP server, which lets the agent:

1. Navigate to a URL
2. Take a screenshot
3. Analyze the screenshot visually
4. Decide if the page looks correct

The appeal is clear, the agent can see what it built. Broken page? The screenshot shows it. Any missing content, it’s visible in the image.

I wired this into my harness as an opt-in flag:

CLAUDE_MCP_FLAGS=""
if [[ "${MCP_PUPPETEER:-}" == "true" ]]; then
    CLAUDE_MCP_FLAGS="--mcp-server puppeteer"
fi

I keep it off by default. Here’s why.

Geoffrey Huntley’s counterpoint: verification outside the loop

Geoffrey Huntley, creator of the Ralph loop, takes a different position. When asked why he doesn’t use MCP Puppeteer for visual verification, his answer was one word: Bombadil.

His argument has three parts.

1. Context window cost. MCP servers consume tokens just by being loaded, tool definitions, schemas, protocol overhead. Puppeteer adds base64 screenshot data on top of that. Huntley found that MCP servers can drop usable context from ~176k to ~120k tokens. That’s 30% of the agent’s reasoning capacity gone before it writes a line of code. (I break down the full token budget in Part 3.)

2. Role confusion. An agent that codes and visually inspects is doing two jobs in one context window. It’s like having a developer also be the QA tester. Same screen, same time, half their desk taken up by QA tools.

3. Separation of concerns. Verification should be a gate after the agent runs, not a tool inside the agent’s loop. The agent codes. Something else verifies.

My experience with MCP Puppeteer

I tried it. Here’s what happened.

Each screenshot costs roughly 3,000 to 6,000 tokens depending on page size. Over multiple iterations of verifying key routes, this adds up fast, especially before you count the MCP overhead itself, tool schemas, protocol definitions, capability negotiation. Every MCP server you load eats context just by existing, whether you call its tools or not. (Part 3 has the full token math.)

By iteration 5, the agent started forgetting parts of its instructions. By iteration 8, it was re-implementing features it had already built. The context window was so full of screenshot data that the actual task instructions were getting pushed out.

I turned it off and the agent immediately got better. Not because the model improved. Because it had room to think again. Dont use MCP, it eats your context window.

The fundamental problem

Asking the agent to verify its own work is like asking an author to proofread their own book. They see what they intended to write, not what’s actually on the page.

What I actually built

Bombadil (the tool Huntley points to) is the right direction but not ready for me yet. It’s v0.2.1, Linux-only binaries, pre-1.0 API. So I built a pragmatic middle ground, a route verification script that follows Huntley’s philosophy, external, zero context cost.

Step 1: Discover routes programmatically.

Not by parsing rake routes text output, which breaks when column alignment changes between Rails versions, but by querying the Rails router directly:

ROUTES=$(bin/rails runner "
  Rails.application.routes.routes.select { |r|
    r.verb.to_s.include?('GET')
  }.map { |r|
    r.path.spec.to_s.gsub('(.:format)', '')
  }.reject { |p|
    p.include?(':') || p == '/up' || p.start_with?('/rails/')
  }.uniq.sort.each { |p| puts p }
" 2>/dev/null)

Step 2: Start a real server, hit every route.

PORT=$((RANDOM % 1000 + 9000))
bin/rails server -p "$PORT" > /dev/null 2>&1 &
SERVER_PID=$!

# Wait for boot
for _ in $(seq 1 30); do
    curl -sf "http://localhost:$PORT/up" >/dev/null 2>&1 && break
    sleep 0.5
done

Step 3: Check invariants, not screenshots.

This is the key difference from MCP Puppeteer. Instead of asking “does this page look right?”, the script checks a few rules that all working pages must satisfy:

for route in $ROUTES; do
    STATUS=$(curl -s -o /tmp/body -w '%{http_code}' \
             --max-time 5 "http://localhost:$PORT$route")
    BODY_SIZE=$(wc -c < /tmp/body | tr -d ' ')

    if [ "$STATUS" = "200" ]; then
        # Property: 200 responses must not contain error page content
        if grep -qiE "(Internal Server Error|something went wrong)" /tmp/body; then
            echo "FAIL $route -- 200 but error page content"
        # Property: 200 responses must have substantial content
        elif [ "$BODY_SIZE" -lt 100 ]; then
            echo "FAIL $route -- 200 but body too small (${BODY_SIZE}B)"
        else
            echo "OK   $route -- 200 (${BODY_SIZE}B)"
        fi
    elif [[ "$STATUS" =~ ^(301|302)$ ]]; then
        # Redirects are expected for auth-gated routes
        echo "OK   $route -- $STATUS (redirect)"
    else
        echo "FAIL $route -- HTTP $STATUS"
    fi
done

The invariants are simple:

• HTTP status must be 200, 301, or 302
• 200 responses must not contain error page strings
• 200 responses must have a body larger than 100 bytes
• Anything else is a failure

These catch the catastrophic failures, the ones where the agent thinks everything is fine but the app is broken.

How it integrates into the harness

The verification runs after the agent commits, not during the agent’s work. The agent never sees the verification tool. It sees the results, pre-computed and injected as text on the next iteration:

# Post-commit route verification (non-blocking warning)
if [ -x "./verify-routes.sh" ]; then
    ./verify-routes.sh 2>/dev/null || \
        echo "WARNING: route verification failed"
fi

The results get injected into the next iteration’s prompt:

## Route Verification (02:08:13)
10 passed, 0 failed (of 10 routes)

OK   / -- 200 (49750B)
OK   /apps -- 200 (12637B)
OK   /users/cancel -- 302 (redirect)
OK   /users/sign_in -- 200 (14404B)
OK   /users/sign_up -- 200 (14980B)

Ten lines. About 200 tokens. The agent sees route health the same way it sees test results, pre-computed facts, not a tool to invoke. Compare that to thousands of tokens for a single MCP screenshot.

The gotchas I hit building this

Puma 7 removed the -d (daemonize) flag. I had to background the process with & and manage the PID manually.

bin/rails server refuses to start if tmp/pids/server.pid exists. If a previous run crashed without cleanup, the next run fails silently. I use a separate PID file path: -P tmp/pids/verify.pid.

Turbo’s *_historical_location routes return 13-14 byte bodies. These are redirect stubs by design, not errors. I filter them out to avoid false positives.

Auth-gated routes return 302, not 401. Devise redirects to sign-in instead of returning unauthorized. Expected behavior, not failures. The script counts 302 as a pass.

The principle

Separation of concerns applies to agents too:

• The coding agent codes.
• A separate tool verifies.
• The harness orchestrates both.

Putting coding and verification in one context window is like asking a developer to write code and manually test it on a split screen. Half their monitor taken up by browser devtools. They can do it. But they’ll do both jobs worse than if they focused on one.

Next: Part 3 — Context window economics for AI agents

This harness decides what the agent sees, when it stops, what gets committed, and how failures are caught. It’s like the “controller” in a Rails application. Get it wrong and your agent writes code that looks correct but breaks everything because it was built on wrong assumptions.

I build Rapidfy, an agentic system that generates full Rails applications from a spec. The agent (an LLM with tools) writes the code. The harness (a bash loop) orchestrates: prepare the prompt, invoke the agent, check if progress was made, loop or stop.

Anthropic published a guide called “Effective Harnesses for Long-Running Agents” that distills this into 7 key patterns. I applied them to my harness and found that the first four are easy, most developers nail them naturally. The last three are where agents quietly fail. Here’s what each pattern looks like in practice, and what goes wrong when you skip them.

Pattern 1: Feature checklist (JSON)

The pattern: Give the agent a machine-readable list of what to build, with pass/fail tracking.

My harness reads a JSON spec file with structured acceptance criteria. Each feature has a test command and a passes field:

{
  "features": [
    {
      "id": "FEAT-001",
      "title": "User authentication",
      "criteria": [
        {
          "description": "User can sign up with email/password",
          "test": "bin/rails test test/integration/signup_test.rb",
          "passes": false
        }
      ]
    }
  ]
}

The test field is what makes this work. Without it, the agent decides on its own whether a feature is done, and agents are optimistic. They’ll mark a feature complete because the code compiles, not because it actually works. With an explicit test command, the harness can verify: run this command, did it pass? Yes or no.

Without it the agent builds features in whatever order it feels like. It skips hard ones. It marks things “done” based on vibes. You end up with 8 features “completed” and 3 of them broken.

Pattern 2: Progress file

The pattern: Keep a persistent record of what’s done on disk, not in conversation history.

The harness maintains a markdown file with checkboxes. In each iteration the agent finds the first unchecked task and works on it and checks it off.

- [x] FEAT-001: User authentication
- [x] FEAT-002: Landing page with RUI components
- [ ] FEAT-003: Dashboard with stats cards    <-- next task
- [ ] FEAT-004: CRUD for deals

Every iteration starts with a fresh context window. The agent doesn’t remember what it did last time. Without a file on disk, it has no idea what’s been built and what hasn’t. It will re-implement features that already exist, or skip features it thinks it already did. That’s why the progress file is the agent’s memory between sessions. Cheap to implement, critical to have.

Pattern 3: One feature per session

The pattern: The agent does ONE thing per invocation, then exits.

The harness enforces this with a circuit breaker. After each invocation, it checks if the git HEAD changed (meaning the agent committed something). If three iterations pass with no commit, the harness exits:

if [[ "$(git rev-parse HEAD)" == "$BEFORE" ]]; then
    NO_CHANGE=$((NO_CHANGE + 1))
    echo "No commit ($NO_CHANGE/3)"
    (( NO_CHANGE >= 3 )) && { echo "Circuit breaker."; exit 1; }
else
    NO_CHANGE=0
fi

I learned this one the hard way. Without a circuit breaker, the agent once ran 12 iterations without committing anything. It kept editing the same file over and over, convinced each edit was progress. Each iteration cost tokens and time, producing nothing. Twelve iterations of an LLM spinning on the same problem is expensive and pointless.

The circuit breaker forces the agent to either ship something or stop trying. Three attempts is generous. If it can’t make progress in three tries, a human needs to look at it.

Pattern 4: Git as memory

The pattern: Each task = one commit. The git log becomes a readable history of what the agent built.

The harness checks git rev-parse HEAD before and after each invocation. If HEAD changed, a commit happened, which means progress. The commit messages follow a convention:

[FEAT-006] Dashboard CRM stats, seed data, 7 system tests
[FEAT-005] Activity model + controller + views, 21 tests
[FEAT-004] Deal model + controller + views, pipeline stages, 20 tests

Incrementally committing each task to Git isn’t just a log, it’s a safety net for when the agent breaks something. If the agent breaks something on iteration 8, you can git diff HEAD~1 to see exactly what changed. You can revert one commit without losing everything. Without per-task commits, you get one giant diff at the end and no way to isolate what broke what.

Those first four patterns are the easy ones. Most of us get them right because they’re just good engineering habits applied to automation. The next three are where it gets interesting.

Pattern 5: E2E testing

The pattern: Not just unit tests, does the app actually work when you open it in a browser.

A route returning HTTP 200 with a Rails error page in the body was a common failure mode for my agent. All unit tests passed. The agent marked the feature as done. But the page said “We’re sorry, but something went wrong”, wrapped in a valid 200 response that the agent never visually checked.

HTTP 200 does not mean “correct.” The gap between “tests pass” and “app works” is where agents silently fail. Closing that gap requires a manual verification step outside the agent’s loop that starts a real server, hits every route, and checks the responses for actual content, not just status codes.

I built a route verification script that does exactly this, and tried Anthropic’s MCP Puppeteer approach as an alternative. The tradeoffs between the two are more interesting than the script itself. Full implementation and comparison in Part 2.

Pattern 6: Startup health check

The pattern: Before starting new work, verify nothing is already broken.

Before each iteration, I run the full test suite, test it visually, and check the route health. I do manual verification because I want to catch failures that unit tests miss. And if any test fails, I stop immediately:

if [[ "$MODE" == "build" ]]; then
    HEALTH=$(bin/rails test 2>&1) || true
    if echo "$HEALTH" | grep -qE '[1-9][0-9]* (failures|errors)'; then
        echo "Health check failed. Fix failures before continuing."
        exit 1
    fi
    echo "Health check passed."
fi

Note the regex: [1-9][0-9]* (failures|errors). It matches “1 failures”, “3 errors”, “12 failures” — but not “0 failures”. That distinction matters. grep "failures" would match the success line too.

While building this harness, I hit a wall where iteration 4 introduced a subtle bug in a model validation. The tests for that specific model still passed, but it broke a different controller that depended on the validation behavior. Iterations 5, 6, and 7 kept building on top of the broken foundation. Each one added code that assumed the validation worked correctly. By the time I noticed — three iterations later — I had to revert three commits and redo the work. Three iterations of wasted LLM calls, wasted tokens, wasted time. This was a failure mode that could have been caught much sooner if I had run the full test suite before each iteration.

A single bin/rails test before each iteration would have caught it immediately. The cost: 15 seconds of test runtime. The savings: three wasted iterations.

Pattern 7: Prompt efficiency

The pattern: Minimize token overhead so the agent has more context for actual reasoning.

When building this harness, I learned that pre-computing what you can outside the LLM call, then injecting compact summaries into the prompt is the most impactful pattern. Test results, route health, linting output — anything that can be summarized in a few lines of text shouldn’t be produced by the agent itself. Raw test output is 50-100 lines. A summary is 3-15 lines. That difference compounds across every iteration.

This turned out to be the least obvious pattern but the most impactful. Full implementation and token math in Part 3.

What I learned

The first four patterns (checklist, progress file, one-feature-per-session, git as memory) are table stakes. You need them, but they’re not what makes or breaks your agent. They’re just good habits.

The last three are where the real value is. Startup health check catches regressions before they compound — five lines of bash that save entire iterations of wasted work. E2E verification catches the failures that unit tests miss. Prompt efficiency determines how long your agent stays useful before it starts forgetting its instructions.

The easy patterns give you a working agent. The hard patterns give you a reliable one. Parts 2 and 3 dig into the two hardest: verification and context economics.

Next: Part 2 — Where verification actually belongs in agent harnesses

It started with a button. Literally one button component.

Today it’s 32 components. Forms, steppers, tables, modals, navigation, dropdowns. All built with Rails 8, Turbo, and StimulusJS. No external JavaScript libraries. No outside frontend. They work with your Rails forms out of the box because they were built for Rails forms. https://rapidrails.cc/docs/

I’m using them in production right now, which is really good. But something kept bugging me. A new idea!

Every week I see tools like v0 and Lovable letting developers describe what they want and get a working app back in seconds. Type a prompt, get a React app. It’s impressive. But if you’re a Rails developer, you get nothing. None of these tools generate Rails native code. None of them know about Turbo or Stimulus or Rails form or ViewComponents. You’re on your own.

That felt wrong. Rails developers deserve the same thing.

So I asked myself a question. I already have 32 components that follow Rails conventions. What if an AI agent already knows how those components work, how they connect, and how Rails 8 expects things to be structured? What would happen if I pointed an agent at all of that and said “build me a blog”?

I tried it. And it worked.

Let me tell you what happens right now when you give Rapidfy a clear prompt.

You say “build me a blog with authors, posts, and comments.” Rapidfy creates the models. Generates the migrations. Runs them. Builds the views using RapidRails UI components. Makes two commits. The whole thing takes about 10 seconds and ready for testing. Ten seconds. That’s faster than running “rails new”.

You get a working Rails 8 application with real UI, real database tables, and real components. Not a prototype. Not a wireframe. A working app.

And everything it builds is Rails native. Turbo for page updates. Stimulus for interactivity. ViewComponents for the UI. No React anywhere. No npm install anything. Just Rails the way Rails is meant to be.

Why does this work?

It works because Rails is predictable. Convention over configuration means there are clear patterns for where things go and how they connect. Models go here. Views go there. Routes follow this pattern. Forms work this way. But Rails alone isn’t enough. The agent also needs to understand the UI layer. That’s where RapidRails UI makes the difference. Every component follows a clear, consistent structure. A button works like a button. A stepper works like a stepper. The naming is predictable. The options are documented. The patterns repeat. An agent doesn’t have to guess how to use a modal or figure out five different ways to build a form.

And the documentation wasn’t built just for humans. It was built with AI agents in mind from the start. Every component has clear inputs, expected outputs, and usage examples that an agent can read and act on immediately. No ambiguity. No “it depends.” Just structure an agent can follow.

That predictability is exactly what AI agents need. When the framework is consistent and the components follow conventions, the agent makes fewer mistakes. React has a thousand ways to do everything. Rails has one good way. RapidRails UI makes sure the frontend follows that same philosophy. That’s the advantage. The whole stack speaks the same language.

I’m not saying this is perfect. It’s not. Right now it needs a clear, specific prompt to do its best work. Complex apps with unusual requirements will trip it up. Edge cases exist. But it’s a start. And it’s a start that already works faster than most developers expect.

My goal is simple. I want Rapidfy to be for Rails what v0 is for React. You describe what you want. You get a working Rails app back. Built with Rails, for Rails.

I’m getting there.

If you want to see what 32 Rails native components look like, start here rapidrails.cc/docs/ And if you want to follow along as Rapidfy gets better, I’ll be sharing demos and progress right here.

Meet Rapidfy 🚀

I came across this registration form from StockLive, an online livestock auction platform. You’ve probably seen forms like this in every industry. The goal is simple, get the user’s information and get them on board quickly.

It’s a single page. Eighteen fields. All visible at once. One big “Create Bidder Registration” button at the bottom.

You can see the form makes a few assumptions about the person filling it out: Their internet connection is stable and nothing will be lost if the page reloads. They’ll know exactly what every field means. They won’t mind scrolling through all 18 fields to find the one they missed. They have the patience to fill everything out in one sitting. And if something goes wrong with validation, they’ll happily start over again. Sound right?

On the contrary, every one of these assumptions is wrong. I tried registering. It took me almost 5 minutes. Five minutes for a registration form, that’s 300 seconds of friction between a potential bidder and their first auction. Most of that time wasn’t spent typing. It was spent dealing with phone number formatting, address validation, misleading dropdown list and postal code errors. One mistake and the form reset. Eventually I gave up trying to enter real data and just copied the placeholder values to get through. Tada.

If I a developer who builds forms for a living nearly abandoned this form, what happens to a cattle farmer in regional Australia who just wants to bid on livestock?

What’s actually going wrong. This isn’t about bad intentions. The team that built this form was trying to collect necessary information. But presenting it this way creates real problems for the people using it. The form has eighteen fields on a single screen that overwhelms people. The moment someone sees that wall of inputs, their first instinct is to close the tab, not fill it out. Researchers call this cognitive overload. I call it losing customers before they start. There’s no indication of progress or how far along you are or how much is left. Without that, every field feels like it might be followed by ten more. Uncertainty kills motivation. Sale selection sits next to personal details. Business information is mixed with agent contacts. PIC numbers live alongside email addresses. When everything is presented the same way, nothing stands out and nothing guides the user through. When you fill out 18 fields, hit submit, and then discover three things are wrong, what then!!. Now you’re scrolling back up, hunting for red text, fixing things you thought were fine. Each error-submit cycle increases the chance someone walks away becasue errors arrive too late. Life interrupts. Phones ring. Browsers crash. If you lose your progress on a long form, you’re probably not starting over. No. You’re finding another way or another platform.

The second -small- image shows the same registration, rebuilt with RapidRails UI’s Steps component. Same information collected. Same fields. Completely different experience. Instead of 18 fields on one page, the form is broken into six clear steps: Sale, Personal, Address, Business, Agent, and Review. A progress bar at the top shows exactly where you are. Each step shows only 2 to 4 fields. Just the fields that belong together. Personal details on one screen. Address on the next. Business information after that.

What changes for the user. Two or three fields at a time means the person filling out the form can actually think about what they’re entering. No scrolling and no scanning. Just answer what’s in front of you and move forward. This way users are focused instead of being overwhelm. The stepper at the top shows completed steps in green, the current step highlighted, and remaining steps ahead. This way people know exactly where they are. That certainty keeps them going. Made a mistake three steps back? Click that step and go straight there. No scrolling through a wall of fields. Just fix it and continue. And the data you already entered is waiting for you. Users have freedom to move around. Name and email belong together. Street address and postal code belong together. Trading agent and selling agent belong together. When information is grouped logically, it makes sense. When it’s all jumbled on one page, it doesn’t. The final step shows a summary of everything entered. Catch a typo in your ABN? Click back to the Business step, fix it and continue. This alone reduces support tickets from incorrect registrations. Progress is saved as you go. When browser crashes, phone rings, connection drops, come back and pick up where you left off because data survives interruptions.

This isn’t just about prettier forms only. It is crucial for businesses. It’s about what happens to your numbers. Forms with high field counts have abandonment rates above 60%. That’s a lot. Breaking them into steps with progress indicators typically cuts that in half, if not more. That’s not a design opinion, that’s measurable.

For StockLive specifically, every abandoned registration is a bidder who didn’t make it to the auction. A bidder who didn’t bid. Revenue that didn’t happen. Not because the product is bad, but because the door was too hard to open. And the fix isn’t complicated. It’s the same form, same data, and same validation. You’re just presenting it in a way that respects how people actually think and work.

Back to the original question, why this needs a component, not a hack? You could build a multi-step form from scratch. Wire up the JavaScript to show and hide sections. Track which step is active. Handle navigation between steps. Manage state. Build the progress indicator. Make it accessible. Test it across browsers.

Or you could use a component that already does all of that.

RapidRails UI’s Steps component handles the stepper navigation, progress tracking, step validation, free navigation between completed steps, and the review summary. It’s built with Rails Turbo, StimulusJS and no external JavaScript libraries and it works with your existing Rails forms. It’s accessible out of the box, first class citizen components.

One component that you drop it into your view and define your steps. Done. That’s what focused UI components are for. Not to impress other developers. To solve real problems for real users, consistently, without rebuilding the wheel every time.

→ See the full StockLive case study: rapidrails.cc/docs/stocklive → Steps component documentation: rapidrails.cc/docs/steps

However, they hesitated. Meetings got scheduled. Budgets got reviewed. Scopes changed a couple of time. And three weeks later, still no answer.

So, I tried something different with the next client. Same situation, clear work scope, same amount of expected work. This time I said: “5 hours minimum per quarter. Which is $1,000.” When I received a response a few hours later, I was surprised. They said yes!

Interestingly, the last client asked for 22 hours in the first quarter and paid $4,400. More than the first client would have paid!

What just happened!? I used to think that, my job was to accurately estimate what a client needed and quote that number upfront. After losing a few opportunities, it’s not.

That’s when I learned something new: the price is what they agree to, and the cost is what they actually spend. Why they looks and sound the same, they are different numbers. More importantly, the psychology around each is completely different.

When someone sees “$4,000 minimum,” they think, “that’s a big commitment. What if we don’t need that much work? What if it doesn’t work out? Let me check with finance.”

On the other hand, when someone sees “$1,000 minimum,” they think, “That’s reasonable. We can do this.” The first framing invites scrutiny. The second invites action.

Interestingly, the work doesn’t change. Still takes 20 hours. The support still costs the same per hour. The total invoice ends up being almost the same. What changes is how they feel saying yes the first time.

I used to resist this approach for a long time. It felt like I was underselling myself or playing games with pricing. However, that is not what is happening.

A low minimum is not a discount; it’s a door. The cost walks through later, naturally, once they already trust you and see the value of the work.

So when you are pricing your work, don’t anchor on what they’ll spend. Anchor on what they’ll agree to. The price gets you in. The cost is what happens once you’re there.

That escalated quickly.

Every week in 2025, experts said “AI is improving, get ready.” They undersold it. We’re not improving, we’re in free-fall acceleration. The kind where you check your phone for an hour and three new capabilities dropped while you weren’t looking.

Mid December 2025, I coordinate agents with specialized skills. They have objectives. They complete tasks. They work while I think about what’s next.

Who predicted solo developers or creators could do this in early 2025? Nobody. Not even the people building the tools. They all say, “we don’t know how AI works!” Which is both terrifying and hilarious.

And, the trade-off? Time. Learn one thing Monday, it’s ancient history by Friday. It’s like TikTok scrolling, except the algorithm is super-intelligence and nobody programmed a pause button. The Genie is out.

The train isn’t just moving, it’s breaking the speed limit. You’re either on it or watching from the platform. (Spoiler, the platform sells tickets to nowhere land.)

But here’s the beautiful part, that same insane speed means you can build things this year (2 weeks left!) that were science fiction or a dream early this year. You can help more people. Create more value. Ship products faster. Leave something behind.

Because if time flies, and AI flies faster, then builders who can keep up will build useful things -not slop- that seemed impossible.

So… what are you building while the train is moving?