Pedro Franceschin

Phase 01 · The Question

> build me an app that just works> make it good, you know what I mean> idk, figure it out

Agents will build whatever you ask for.

I ask questions first, until we both know what the software must do and what it must leave out.

Phase 02 · The Specification

I write down what you want until an agent can't misread it.

The spec names the goal, the acceptance criteria and what's out of scope. You read it, push back, and approve it before an agent writes a line.

Phases 03 to 06 all check against this file.

1
# Spec: Portfolio Tracker
2
 
3
## Goal
4
Show a user's balances across three chains in one screen.
5
 
6
## Acceptance Criteria
7
- Balances refresh without a page reload
8
- Wrong network shows an explicit state, never a silent zero
9
- Numbers round only for display, never for math
10
...
11
 
12
## Non-goals
13
- Trading
14
- Historical charts

Phase 03 · The Decomposition

I split the spec into tasks small enough for an agent to finish.

Each task gets a boundary and a definition of done. I set the order, so the agent doesn't guess what comes next.

SPEC
Data model
Chain RPC calls
Balance aggregation
Error & empty states
UI
Test plan

Phase 04 · The Agents at Work

The agents write the code, inside the boundaries the spec set.

Each commit points back to the spec section it implements, like §3.2 in this log.

agent@pipeline — build.sh
$ agent run --task data-model
→ writing src/lib/chains.ts
→ writing src/lib/balances.ts
$ agent run --task ui
→ writing src/components/PortfolioView.tsx
$ npm test
✓ 14 passed (0 failed)
$ git commit -m "feat: balance aggregation per spec §3.2"

Phase 05 · The Human in the Loop

I read every diff before it merges.

Agents drift outside the spec. Here an agent added a swap widget to a tracker that rules out trading, so I'm removing it.

balances.tsx
export function BalanceRow({ chain, amount }: Props) {
- if (isSwapEnabled) renderSwapWidget()
+ return <Row label={chain} value={formatUsd(amount)} />
}
Reviewer: swap logic falls under the “Trading” non-goal. Reverting.

Phase 06 · The Proof

I turn each acceptance criterion into a test.

wrong-network.test.ts and rounding.test.ts come straight from the spec. I ship when all six pass.

0/6acceptance criteria tested
chains.test.ts✓
balances.test.ts✓
PortfolioView.test.tsx✓
empty-state.test.ts✓
wrong-network.test.ts✓
rounding.test.ts✓
All checks passed

Phase 07 · The Product

One screen, three chains, as the spec asked.

I hold every line to the same spec and the same review, whether I wrote it or an agent did.

portfolio.app

Total balance

$12,480.32

Ethereum$8,214.10
Base$3,102.44
Arbitrum$1,163.78