Field note 01

The Golden Thread

A machine-readable thread that ties executive intent, implementation, and ground-truth into a living ledger.

HomesFlow is a real app. It was never the point.

It's a live test of one question: can an ordinary team keep AI-assisted development honest without slowing it to a crawl? Not "prompt-driven development," where governance is whatever you typed into the chat window last. Real governance, at AI speed.

For a CTO, the value isn't the methodology. It's control.

The base workflow is standard. We used Spec-Driven Development with GitHub's Spec Kit. We iteratively wrote a PRD, feature spec, plan and tasks, and code. We write the intent down before anyone, human or agent, implements it - and then we iterate through the stack as needed.

Standard isn't enough. A spec can exist and still drift. Tasks get marked done without proving which requirement they served. Tests pass without making clear which acceptance criterion they protect. AI is especially good at producing code that looks right without being justified by anything.

So we added one more layer: a machine-checkable thread. Every requirement in HomesFlow.prd.md gets a stable ID. That ID has to survive, visibly, through the spec, the tasks, the Swift code (@covers annotations), and the test names themselves (test_AC_SYNC_05...). A script, our Gate 2, checks the whole chain on every push. Reference an ID that doesn't exist, skip a Traces: field, or ship an acceptance criterion with no test and no tracked gap, and the build fails.

The current snapshot:

• 79 registry IDs in the PRD
• 50 acceptance criteria, 45 with tests
• 69 IDs referenced via @covers in code
• Gate 2 passing

Those numbers are the point. They're the difference between "we have documentation" and "the documentation governs the work."

Why this matters more with AI, not less: AI lowers the cost of writing code, and just as much, the cost of writing code that merely looks right. The Golden Thread forces the same four questions on every change: What requirement does this serve? Where's it implemented? What proves it? If proof is missing, is that gap visible or hidden?

It isn't perfect. Renaming the project from HomeFlow to HomesFlow touched the repo, Xcode targets, the bundle ID, Supabase, SonarCloud, CI paths, and docs. Gate 2 held the core traceability intact. Everything else still needed a manual pass.

For a CTO, the value isn't the methodology. It's control. AI-assisted delivery gets a governance surface without every change slowing to a crawl. Scope creep becomes visible. Untested acceptance criteria become visible. Drift between what was promised and what shipped gets much harder to hide.

GitHub's Spec Kit gives the workflow. The traceability gate turns that chain into something CI enforces, instead of something a slide deck asserts.

The receipts are in the repo: github.com/rdryfoos/HomesFlow. Or if you'd rather talk it through first: book some time.