Getting
airborne

Demystifying agentic engineering, so we can leave the "ground" and "take flight" on the AI Adoption Continuum. 

Every claim here is runnable — the repo builds a real app, unattended.

Same car. Different driver.

“AI hallucinates.”  “It can't do X.”  “We've seen it fail at other companies.”

Put an automatic-only driver in this car and they spin it into the wall...then tell you why it's undrivable. Put a pro in the same seat, and it's the fastest thing on Earth. Both are correct.

Every stage of this loop masquerades as good judgment; however it is really a signal of low proficiency + low agency.                                                                    Distrust is a status report on your scaffolding.

And the hallucination fear assumes the model is always guessing...it isn't. Hold that thought.

In a loop, most of the work is tool calls returning ground truth not the model free-associating. run-qa’s Playwright test actually ran; the model didn’t decide it passed.

How we work.

Everything true for every sprint: architecture, conventions, and the definition of done. One constraint forces quality —

What needs to get done, where we're at.

Three characters per line — that's your state machine. The checkbox ticks after each sprint. Stuck work marks [!] and stops.

What to build this turn.

One spec per sprint: acceptance criteria, technical approach, edge cases. This is where your engineering judgment lives.

Executes the spec for a single  feature / sprint. Then done.

The Builder is just a Claude Code session — no special framework, no persistent agent. Spun up fresh for one sprint, then thrown away. Its power is that nothing carries over.

Judgment moves up a rung — you approve plans instead of writing specs. That's the Jet step.

run.sh

#!/usr/bin/env bash
set -euo pipefail
MAX=4; n=0
# planted mode: DEMO_MODE=planted swaps in a buggy build
# (fixtures/index.sprint2-buggy.html) before Sprint 3 so QA goes RED

echo "THE LOOP — starting..."
cat roadmap.md

while grep -q '^- \[ \]' roadmap.md && (( n < MAX )); do
  n=$((n+1))
  echo "SPRINT $n — launching fresh session..."
  claude -p "$(cat prompt.md)" \
    --dangerously-skip-permissions \
    --model opus \
    || { echo "session error"; break; }
  cat roadmap.md
  if grep -q '^- \[!\]' roadmap.md; then
    echo "BLOCKED — human needed."; break
  fi
  echo "Sprint $n complete."
done

echo "DONE — $n sprint(s) attempted"
cat PROGRESS.md

CLAUDE.md

# Click Farm

## Identity & Mission
You maintain the Click Farm game. Done = the feature
works, QA is GREEN, nothing else broke.

## Map
One index.html (inline CSS + JS). State lives in
localStorage. Specs are in specs/.
State: localStorage key clickfarm = { score, farmhands }.
Stable ids: #score, #harvest, #hire, #farmhands, #cost.

## Conventions
Vanilla HTML/CSS/JS — no frameworks, no build step.
Mobile-first, system fonts, one accent color.

## Running it
Open index.html in a browser to play. run-qa to check.
No package manager.

## Guardrails
Never add dependencies or a build tool. Don't edit
other sprints' specs. Ask before changing the schema.

## Definition of Done
Not done until run-qa returns GREEN.
If RED, read it, fix it, re-run. Never ship on RED.

prompt.md

# Sprint Turn
Read roadmap.md and pick the first sprint marked [ ].
Read that sprint's spec and PROGRESS.md for context.

Build the feature per the spec.
Then run the run-qa skill until GREEN (max 3 attempts).

When GREEN:
- Mark the sprint [x] in roadmap.md.
- Append a handoff to PROGRESS.md: what you built,
  key decisions, gotchas, what the next sprint needs.

If you can't reach GREEN after 3 attempts:
- Mark the sprint [!] in roadmap.md, then stop.

Updating the status is your final action — never skip it.

roadmap.md

# Click Farm — Roadmap

- [ ] Sprint 1: Core clicker — harvest + persistent score    — specs/sprint-1.md
- [ ] Sprint 2: Farmhands — buy auto-harvesters             — specs/sprint-2.md
- [ ] Sprint 3: Scaling cost — price curve + spend guard    — specs/sprint-3.md
- [ ] Sprint 4: Polish — number formatting + click pulse    — specs/sprint-4.md

roadmap.md

PROGRESS.md

# Progress Log

specs/sprint-1.md

# Sprint 1: Core Clicker

## What to build
A big Harvest button. Clicking it adds 1 to the
score. Score persists across reloads.

## Acceptance Criteria
- Clicking #harvest increases #score by 1
- #score persists after a reload (localStorage)
- Score is a non-negative integer

## Technical Notes
- Single index.html, inline CSS + JS
- localStorage key "clickfarm" → { score, farmhands }
- Stable ids: #score, #harvest

specs/sprint-2.md

# Sprint 2: Farmhands (auto-harvest)

## What to build
A "Hire Farmhand" button (cost 10). Hiring deducts
10 and adds a farmhand. Each farmhand earns
+1 score/sec automatically.

## Acceptance Criteria
- #hire with score ≥ 10 deducts 10 and adds a #farmhands
- With ≥1 farmhand, #score rises ~1/sec on its own
- #cost shows the hire cost (10)

## Technical Notes
- New ids: #hire, #farmhands, #cost
- setInterval 1000ms; persist state on each tick

specs/sprint-3.md

# Sprint 3: Scaling Cost

## What to build
Farmhands get more expensive the more you own.
cost = floor(10 * 1.15 ^ farmhands). #cost
shows the NEXT price, updates after each hire.

## Acceptance Criteria
- #cost increases after each hire (per the formula)
- When score < cost, clicking #hire does nothing
  (score & farmhands unchanged)
- Score never goes negative; hiring at score == cost succeeds

## Technical Notes
- Integer math, Math.floor
- Guard lives in the acceptance test; the bug is
  planted via the fixture swap, not the spec

specs/sprint-4.md

# Sprint 4: Polish

## What to build
Number formatting + click feedback.

## Acceptance Criteria
- Score ≥ 1000 shows abbreviated (1.2K / 3.4M / 5.6B);
  below 1000 shows the integer
- Same formatting on #cost
- Underlying state stays an exact integer (display-only)
- #harvest pulses briefly on click

## Technical Notes
- Format on display only — never round the stored value

.claude/skills/run-qa/SKILL.md

---
name: run-qa
description: Full QA pass — lint, review, e2e.
  Returns one GREEN/RED verdict.
---

# run-qa
Run these in order. Each is a subagent; use its
returned message as the result.

1. Delegate to linter.
2. Delegate to code-reviewer.
3. Delegate to playwright-tester.

Verdict:
- Any lint error, any CRITICAL finding, or any
  failed spec → RED. List what failed.
- Otherwise → GREEN.

If RED: fix the issues, re-run from step 1.
Stop after 3 attempts; then report to the human.

.claude/agents/linter.md

---
name: linter
description: Validates HTML structure and JS errors.
tools: Read, Edit, Bash    model: haiku
---

Run validation on index.html:
1. Check HTML is well-formed (tags, nesting)
2. Run node --check on inline script content
3. Check for unclosed strings, missing semicolons,
   undefined variables

Auto-fix trivial violations (formatting, whitespace).
For judgment calls, leave it and report it.

Return "CLEAN" if no errors remain, else the list
of remaining errors with location.

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews changes for bugs and UX issues.
tools: Read, Grep, Glob    model: sonnet
---

Review index.html against the sprint spec.
Do not change any files.

Check for:
- Logic bugs (especially localStorage read/write)
- State issues (stale data, race conditions)
- UX problems (unaffordable hires, negative balances)
- Missing acceptance criteria

Return findings as:
- CRITICAL — bugs, data corruption, broken function
- WARN — likely problems, edge cases
- NIT  — style, naming
For each: the issue + a one-line fix. Else "CLEAN".

.claude/agents/playwright-tester.md

---
name: playwright-tester
description: Runs behavioral tests against the app.
tools: Read, Write, Bash    model: sonnet
---

Write and run a Playwright test for the sprint's
acceptance criteria.
1. Create test-farm.spec.js from the sprint spec
2. Open index.html via file:// or a local server
3. Test each acceptance criterion

Key scenarios for Sprint 3:
- Click → score increments
- Hire with enough score → cost deducted, +1 farmhand
- Hire when you can't afford it → blocked, no change
- Hire at score == cost → succeeds, score ≥ 0
- Score never goes below 0
- State persists across refresh

Return "GREEN" if all pass, else "RED" plus, per
failure: test name, failed assertion, actual result.