From Scaffolding to Flight: Before the Training Wheels Come Off

From Scaffolding to Flight: Before the Training Wheels Come Off

June 5, 2025

“Are we limiting Piper’s potential with all these rigid enums and mappings?”

I asked Claude this when we started implementing workflow mappings. And yeah, we were. Intentionally. Like putting training wheels on a bike — not because the bike can’t balance, but because the rider needs to build confidence first.

The scaffolding question

Here’s what we built:

INTENT_TO_WORKFLOW_MAP = {
    "create_ticket": WorkflowType.CREATE_TICKET,
    "create_github_issue": WorkflowType.CREATE_TICKET,
    "analyze_document": WorkflowType.ANALYZE_FILE,
    # ... and so on
}

Rigid? Absolutely. Limiting? You bet. Necessary? You have to walk before you can run, or fly.

The alternative was to let AI figure out workflows from scratch. Which sounds great until you realize “figure out” often means “guess creatively.” And creative guessing in production is how you end up assigning tickets to people who left the company in 2019.

The Evolution Path We Mapped

Current state → Future state, explicitly planned:

1. Now: Fixed enums + rigid mappings (training wheels)
2. Next: AI determines workflow from intent + context
3. Later: AI composes workflows from task primitives
4. Eventually: AI creates new workflow types based on patterns

It’s not that we don’t trust AI. We just trust it to learn better with structure than without. Honestly, that’s pretty much how we learned things too, if you think back far enough, or just back to the last time you tried something new and had zero context for all the initial basic information.

PostgreSQL has opinions about your life choices

Of course, the moment we tried to persist these workflows, PostgreSQL reminded us that we hadn’t initialized the database.

role "piper" does not exist

Three hours of debugging later, we discovered:

• The init script was at scripts/init_db.py (who knew? obviously earlier versions of ourselves had known this — we put it there, but the continuity challenge continued to plague me, and still does to this day to some extent despite all the guardrails, belts, and suspenders I’ve adopted)
• Docker PostgreSQL and local PostgreSQL were fighting over port 5432 (to this day each new bot instance I work with wastes time guessing we’re on port 5432 when we moved PostgreSQL to 5433 to resolve this conflict and just have to rediscover that fact Memento-style every other day.
• The password in .env didn’t match what Docker expected (I think it was dev_changeme vs _dev_changeme_in_production but Claude never checks anything first without a reminder. Makes plausible guesses instead! Plus, I’m lazy and forget to proofread its suggestions most of the time.
• My soul had left my body somewhere around hour two

The beautiful moment when it worked

But then — success. Real workflows, persisting to a real database, with real IDs and timestamps.

{
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "create_ticket",
  "status": "running",
  "created_at": "2025-06-07T10:30:00Z"
}

You might think that looks like something that could only excite Mr. Spock, but you’d be wrong. This boring JSON represents architecture actually working. Domain models → Workflow creation → Database persistence → API response. The full stack, no mocks, no shortcuts.

When Structure Enables Freedom

Here’s what the scaffolding actually enabled:

• Predictable behavior while we test edge cases
• Clear upgrade path as Piper learns
• Debugging sanity when things go wrong
• User trust through consistency

The training wheels aren’t limiting Piper — they’re letting us build the rest of the bike while it stays upright. I don’t want to compare serious software projects to houses of cards, but you know how it’s hard to get the first few “walls” of the house to stand because they all have to lean on each other before you can build anything else on top of them? Well, it’s kind of like that.

Real GitHub issues in the real world

The payoff came June 7th. We created Issues #9–16 in the piper-morgan-platform repo. Real issues from natural language:

“Users want dark mode” → Issue #16 with:

• Proper classification
• Requirements
• Acceptance criteria
• Technical considerations
• Definition of done

Not templates. Not mad libs. Actual reasoning within our structured system.

The meta-architecture insight

Building scaffolding first seems backward until you realize: the scaffolding IS the architecture. Those enums aren’t limitations — they’re contracts. The rigid mappings aren’t constraints — they’re training data.

When we eventually remove them, Piper will have learned from thousands of correct mappings. It’s like teaching someone to play jazz by starting with scales. Boring? Maybe, if the novice wants to start “blowing” right away. Effective? Well, John Coltrane spent hours playing short pentatonic segments so that over time he could access any of those pathways without even thinking.

What this means for AI products

Every AI product faces this choice:

• Start flexible and hope it learns fast enough
• Start structured and gradually increase autonomy

We chose structure. Not because we’re control freaks (OK, maybe a little), but because we’ve already seen scary examples in the wild of what happens when AI systems learn from their own mistakes in production.

Those training wheels stay on (for now)

Those enums and mappings? They’re still there. Still working. Still keeping Piper from assigning tickets to ghosts or creating workflows that don’t exist.

But now we have:

• Working examples of correct behavior
• User feedback on what works
• Data on common patterns
• Confidence that the foundation is solid

When the training wheels come off — and they will — Piper will be ready to fly. Just not today. Today, we’re still building the wings.