KFR | Blog

It's all a Yoke to you, isn't it?

Mon, 09 Mar 2026 00:00:00 GMT

Or: How to put your agents to work and actually trust the results

Why “Yoke”?

A yoke is the wooden beam that connects draft animals to the plow. It doesn’t make the ox weaker. It makes the ox useful. Without it, you’ve got a very powerful animal wandering around your field eating your crops.

And let’s be honest about what’s happening here. The agents are already doing the heavy lifting. The grunt work. The “write 400 lines of test scaffolding” work. The “implement this CRUD endpoint for the seventh time this week” work. They’re the ones pulling the plow through the dirt at 3 AM while you sleep.

What you need to do is give them a proper harness so they don’t plow straight through your neighbor’s fence.

Yes, “yoke” rhymes with “joke.” No, that wasn’t an accident. The joke is giving six agents commit access to your repo. The yoke is what keeps that from being a horror story.

The Gap Between “Steering” and “Shipping”

The first post in this series laid out the approach: AGENTS.md for master instructions, skill files for task-specific procedures, automated quality gates for enforcement. Later posts showed how to scale that to parallel agents with git worktrees, and the inner/outer loop model formalized where agents end and humans begin.

But there was a gap. A pretty big one, actually.

Setting all of that up by hand is a lot of work. You need the config file, the completion checker, the plan-first hook, the grind loop implementation (different for every agent tool), the commands, the code reviewer, the documentation structure, the CI workflows, the enforcement scripts. And they all need to reference each other correctly, use the right test commands for your toolchain, and not have any typos in the shell scripts that silently break everything at 2 AM.

I built this harness incrementally over several weeks in a single repo. It worked great. But “just copy these 30 files and manually adjust all the paths and commands” is not a viable distribution strategy.

So I built Yoke: a portable, run-once bootstrap that sets up the entire harness in any Git repository. Point your agent at a spec file, answer two questions, get the whole thing.

The Two-Question Setup

You: "Read YOKE_SPEC.md and set up the agentic harness for this repository"

Agent: "Which profile?
  - minimal: Core quality gates
  - standard: Full knowledge layer + commands
  - full: Parallel orchestration"

You: "standard"

Agent: "Which agent tools? Claude Code, OpenCode, Codex, Kiro?"

You: "claude and opencode"

Agent: *sets up your entire harness in 5-10 minutes*

The agent reads the spec, runs the scaffolding script, detects your toolchain (Python/uv? TypeScript/npm? Rust/cargo? Go?), fills in templates, generates tool-native components, analyzes your codebase, and validates everything. You answer two questions and go make coffee.

After setup, the repo owns everything. No daemon. No SaaS. No subscription. Just files in your repo that you can read, modify, and commit. Yoke lays the foundation, then gets out of the way.

Three Layers, One Harness

If you read the previous posts, you know the three-layer model. Here’s how Yoke implements it concretely — the parts that are new, not the philosophy you’ve already heard.

Layer 2: The Agentic Loop

The core. Install nothing else if you want, but install this.

Grind Loop — The completion checker runs after each agent turn and produces structured JSON:

{
  "complete": false,
  "iteration": 2,
  "max_iterations": 5,
  "checks": {
    "tests_pass": false,
    "review_clean": true,
    "scratchpad_done": false
  },
  "followup_prompt": "Tests are still failing. Fix these:\n\nFAILED test_momentum_strategy..."
}

If incomplete, the agent gets a targeted follow-up. If stuck on the same thing for three iterations, it gets an escalation: “Try a different approach.” If it hits the iteration cap, it stops gracefully instead of spiraling.

Without iteration control, agents will happily spend four hours on a problem that needed a five-minute workaround. The grind loop is a leash, not a cage.

Every agent tool — Claude, OpenCode, Kiro, bash wrapper — calls the same check-completion.sh. The iteration mechanics are tool-native (because Claude’s hook model and OpenCode’s plugin model are architecturally different), but the evaluation is shared. One source of truth for “are we done yet.”

Plan-First Enforcement — A pre-write hook blocks code changes until a plan file exists in docs/plans/. Sounds draconian. Is draconian. Also the single most effective quality gate in the entire harness. Agents that plan before coding produce dramatically better results. Almost like thinking before acting is a good idea.

Shared Config — One YAML file, parseable by both shell scripts and structured parsers:

grind_loop:
  max_iterations: 5
  stall_timeout_seconds: 300
  idle_timeout_seconds: 120

Layer 3: Inner Knowledge

Layer 2 keeps agents from going off the rails. Layer 3 makes them good at their job.

Yoke generates all of this from your actual codebase — not empty scaffolds:

AGENTS.md from your architecture, toolchain, and detected patterns
Four commands (/plan-feature, /start-issue, /create-pr, /fix-issue) with your actual test/lint/typecheck commands baked in
Skills detected from codebase patterns (Pydantic models? You get a skill for that. Strategy pattern? Skill. API routes? Skill.)
Documentation — architecture overview, testing guide, debugging guide, principles derived from your linter and CI config
Code reviewer agent definition parameterized with your tech stack

The issue-decomposition skill is always included. It teaches agents how to break features into the right-sized chunks: one issue = one agent session = one worktree. With dependency ordering, parallel safety rules, and acceptance criteria that are actually testable. “Implement the feature” is not an acceptance criterion. It’s a wish.

Layer 1: Outer Orchestration

This is where the yoke metaphor gets literal. Multiple agents, pulling together.

# Dispatch all orchestrator-ready issues
scripts/orchestrate.sh --label orchestrator-ready

# Or be specific
scripts/orchestrate.sh --issues 101,102,103,104,105

# Peek at the plan without launching anything
scripts/orchestrate.sh --dry-run --label orchestrator-ready

The orchestrator discovers issues, resolves dependencies via topological sort, groups them into waves, and dispatches agents to isolated worktrees in parallel. Wave 1 (no dependencies) runs in parallel. When done, Wave 2 starts. Each agent gets its own git worktree, its own dependency install, its own .env. Complete isolation.

Stall detection kills agents that go silent. Auto-merge handles low-risk PRs. Issue preflight validates everything before an agent touches it. All using native git worktree — no third-party CLIs.

The Intelligence Boundary

The design decision that makes Yoke work: a clean split between mechanical scaffolding and intelligent generation.

install.sh handles the boring stuff. Directory creation. Template files with {{placeholder}} markers. Gitignore entries. It’s a POSIX shell script. Idempotent (run it twice, same result). Safe (never overwrites existing files). Paranoid (32 automated self-test checks).

The agent handles the smart stuff. Toolchain detection. Placeholder substitution. Tool-native component generation. Codebase analysis. The spec (YOKE_SPEC.md) walks the agent through all of it step by step.

This split means install.sh is dead simple and testable, while the agent does what agents are good at: reading code and making decisions.

Shared Scripts, Tool-Native Loops

Every agent tool shares the same underlying scripts. But the iteration loop itself is tool-native. Because Claude Code’s hook-based model (Stop hook fires → output becomes next prompt → Claude re-enters automatically) is fundamentally different from OpenCode’s event-driven plugin model (session.idle → plugin calls checker → plugin sends new prompt via API).

Pretending these are the same thing would produce a worse result than acknowledging the difference. The shared contract is the JSON output from check-completion.sh. The loop mechanics are each tool’s business.

Share what can be shared, go native where it matters. Forced abstraction over genuinely different architectures is how you get leaky abstractions that nobody trusts.

The Plan-Feature Pipeline

The most impactful addition was also the last one built. The orchestrator needs well-formed GitHub issues. But where do those issues come from?

Before /plan-feature, the answer was “the developer writes them by hand.” Fine for three issues. Less fine for fifteen.

Developer: /plan-feature "Add backtesting support with historical data replay"

Agent: *reads AGENTS.md, architecture docs, scans codebase*
       *decomposes into 7 issues across 3 waves*

       "Here's the proposed breakdown into 7 issues across 3 waves.
        Want me to:
        1. Create all issues as-is
        2. Modify the plan
        3. Cancel"

Developer: "Merge issues 3 and 4, they're too small separately."

Agent: *adjusts, creates 6 issues with Agent Metadata tables*

       "Created 6 issues. To run:
        scripts/orchestrate.sh --issues 101,102,103,104,105,106"

The human-in-the-loop gate is non-negotiable. The agent proposes, the developer approves. No issues get created without explicit sign-off. This is where human judgment matters most — scoping, prioritization, and “actually, that’s way more complex than you think.”

The agent is good at decomposition. It’s terrible at knowing what matters. That’s still your job.

This closes the loop: idea → issues → dispatch → implementation → review → merge. You decide what to build. The agents handle the rest.

What This Looks Like In Practice

A real workflow from the project where Yoke was born:

9.00 am:
  /plan-feature "Add sentiment analysis scanner with LLM-based scoring"
  → 5 issues created across 2 waves

  scripts/orchestrate.sh --issues 201,202,203,204,205

9.40 am:
  Wave 1 complete. Both PRs merged.
  Wave 2 in progress. Agent on #203 hit a test failure,
  grind loop re-prompted twice, fixed on iteration 3.
  Agent on #204 completed first try.

10.30 am:
  All 5 PRs merged. Feature complete.

Total human time: 2 minutes reviewing the plan,
  5 minutes spot-checking the final PRs.

Five issues, three waves, two agents in parallel, one afternoon. The agents did the implementation. The harness did the quality enforcement. The human did the thinking.

That’s the yoke working. The agents pulled the plow. The harness kept them in the furrow. The farmer picked the field.

Getting Started

# Copy the two files into your repo
cp /path/to/yoke/{install.sh,YOKE_SPEC.md} .

# Point your agent at the spec
"Read YOKE_SPEC.md and set up the agentic harness for this repository"

Start with standard profile. Upgrade to full when you’re ready for parallel orchestration. Drop to minimal if you just want the grind loop and plan-first enforcement.

Profile	What You Get	When to Use
minimal	Grind loop, plan-first enforcement, shared config	Solo dev, single agent
standard	+ AGENTS.md, commands, skills, code reviewer	Most projects
full	+ Orchestrator, wave dispatch, stall detection	Parallel agents at scale

Supports Python (uv/pip), TypeScript (npm/yarn/pnpm), Rust (cargo), and Go. Toolchain detection is automatic.

Run Once, Repo Owns It

After setup, Yoke is done. No daemon. No version to update. The files are in your repo, committed to git, owned by your team.

Want to change the grind loop iterations? Edit .agents/config.yaml. Want a new skill? Create a file in .agents/skills/. Want to modify the completion checker? It’s a shell script. Read it. Change it. It’s yours.

If you can’t read it, you can’t trust it. And if you can’t trust it, you shouldn’t be letting it control your AI agents.

Yoke is open source. Because the only thing worse than an uncontrolled AI agent is a proprietary system controlling your AI agents.

The Loop Within the Loop

Wed, 04 Feb 2026 00:00:00 GMT

Or: Why Your Agent Needs a Babysitter (And Why That Babysitter is You)

Two Loops

Look at any diagram of modern software development and you’ll see loops. Loops within loops. It’s loops all the way down.

AI agents have fundamentally changed which loop matters.

The traditional inner loop (write code, build, test, debug, repeat) used to be where developers spent 80% of their feature development time. It was slow. It was manual. It was in many cases also beautiful. But, it was the bottleneck.

Not anymore.

The inner loop is now a caffeinated tornado. The outer loop is where you make sure the tornado didn’t just level a hospital.

The Stochastic Reality

LLMs are fundamentally unpredictable.

Same prompt. Same model. Different day. Different output.

This isn’t a bug. It’s the nature of the technology. Large language models are stochastic systems — they sample from probability distributions, and that sampling introduces variance. Sometimes helpful variance. Sometimes “why did you delete the entire authentication module” variance.

Traditional development tools are deterministic. Run the compiler twice, get the same output. Run the linter twice, get the same warnings. Run the tests twice, get the same results (flaky tests notwithstanding).

AI agents? Not so much.

Traditional Tool:  Input → Deterministic Process → Predictable Output
AI Agent:          Input → Stochastic Process → ¯\_(ツ)_/¯

This changes everything about how we need to structure development.

The solution isn’t to fight the stochasticity. It’s to build structure around it.

Structure that creates repeatability from chaos. Artifacts that document what happened. Checkpoints that verify quality. Guardrails that catch when the dice roll badly.

The funny thing: traditional engineering concepts like TDD and BDD work surprisingly well in this context. Why? They were designed for humans. And humans are stochastic systems too.

Give two developers the same spec, you’ll get two different implementations. Give them the same bug report, they’ll debug it differently. The whole history of software engineering is basically “how do we get predictable outcomes from unpredictable meat-based processors?”

TDD doesn’t care how you write the code. It cares that the code passes the tests. BDD doesn’t care what approach you take. It cares that the behavior matches the specification. These methodologies abstract away the implementation variance and focus on verifiable outcomes.

Turns out, that’s exactly what you need for AI agents too.

We spent decades building processes to handle human unpredictability. Now those same processes handle AI unpredictability. The more things change, the more they stay the same.

That’s what the two-loop model is really about: taming stochastic systems with deterministic process.

The Three Forces

Before diving into the loops, let’s establish the framework. Three forces govern AI-assisted development:

Force 1: Quality

The end product has to work. Not “works most of the time.” Not “works if you squint.” Actually works.

Both loops serve quality, but at different levels:

Inner loop: Does the code compile? Do tests pass? Is it syntactically correct?
Outer loop: Does it meet requirements? Is it secure? Does it fit the architecture?

Force 2: Repeatability

The process has to be repeatable. Not “repeatable if the model is in a good mood.” Actually repeatable.

This is where stochastic systems fight you. The same issue assigned to the same agent might produce different implementations. That’s fine, as long as both implementations pass the same quality gates.

Repeatability comes from:

Consistent guardrails (AGENTS.md, SKILL.md files)
Consistent verification (same tests, same linting, same checks)
Consistent artifacts (same documentation structure, same PR format)

Force 3: Structure

The process needs to produce traceable artifacts. Why? Because black-box models can’t explain their reasoning.

When something goes wrong (and it will) you need a paper trail:

What was the plan?
What tests were written?
What did the code review find?
What decisions were made and why?

The model won’t remember. The artifacts will.

These three forces (Quality, Repeatability, Structure) are the lens through which to evaluate every process decision. If it doesn’t serve at least one of these forces, it’s probably unnecessary complexity.

The AI-Assisted Inner Loop

Picture this: you assign an issue to your AI agent. What happens next is a blur of activity that would take a human developer hours, compressed into minutes.

Phase 1: Setup (30 seconds)

The agent receives an issue number. Within seconds:

Worktree creation: Isolated branch, unique ports, fresh database
Environment setup: Hooks fire, dependencies copy (copy-on-write magic)
Issue fetch: GitHub API pulls full context, labels, comments
Plan generation: Local markdown file with implementation strategy

What Happens When You Run 'wti 42'

# Worktree created: ~/projects/myapp-issue-42
# Branch: issue-42
# Ports: API=14521, Web=16893
# Database: myapp_issue-42
# Agent launched with context...

Artifact produced: PLAN_42.md — the decision record

This isn’t just a todo list. It’s documentation of why this approach, not just what. When the agent (or a future human) needs to understand the reasoning, the plan file provides context the model’s weights can’t.

Phase 2: TDD Cycle (The Tight Loop)

Here’s where the magic happens. The agent enters a tight loop:

TDD Cycle

1. Write failing test
2. Run test (verify it fails)
3. Write minimal implementation
4. Run test (verify it passes)
5. Refactor if needed
6. Repeat

This isn’t new. TDD has been around since Kent Beck was in diapers. What’s new is the speed.

An AI agent can complete a TDD cycle in 30-60 seconds. A human developer? 5-15 minutes. That’s not a small difference. That’s an order of magnitude.

Human TDD:     ████████████████████████████████████████ 10 min
Agent TDD:     ████ 1 min

Artifact produced: Test files — intent documentation

Tests written before implementation capture what should happen before the agent decides how to make it happen. This is crucial for stochastic systems: the tests are the specification, and they’re deterministic even when the implementation isn’t.

Phase 3: Verification (The Safety Net)

After implementation, the agent doesn’t just declare victory and go home. It verifies:

New tests pass: The thing it just built actually works
Linting passes: Code style is consistent
Type checking passes: TypeScript isn’t screaming
Full test suite passes: Nothing else broke

Verification Commands

npm run lint
npm run typecheck
npm test -- --run
npm run build

Artifact produced: Passing test suite — the quality gate

This is where repeatability comes from. The stochastic agent might produce different code each time, but the deterministic tests verify the same properties each time.

Phase 4: Self-Review (The Mirror)

Before any human sees the code, a sub-agent reviews it.

Code Review Checklist

- [ ] Tests present for all changes
- [ ] No hardcoded secrets
- [ ] Follows architecture patterns
- [ ] Handles edge cases
- [ ] Error handling is appropriate
- [ ] No obvious security issues

The main agent reads the review, fixes issues, and iterates. This catches 60-70% of problems before a human ever looks at the code.

But review quality varies wildly.

The model matters. Claude finds different issues than GPT-5.2 finds different issues than Gemini. Temperature matters — a creative reviewer catches different things than a conservative one. Instructions matter — “look for security issues” produces different results than “look for maintainability concerns.”

This is actually an opportunity. Instead of relying on a single reviewer, you can run multi-model reviews:

Multi-Model Review Strategy

1. Claude (low temp): Architecture and patterns
2. GPT-5.2 Codex (medium temp): Edge cases and error handling
3. Gemini (low temp): Performance and efficiency
4. Consolidate findings → CODE_REVIEW_42.md

Different models have different blind spots. What one misses, another catches. The consolidated review is stronger than any single model could produce.

Artifact produced: CODE_REVIEW_42.md — the consolidated validation record

This document shows what was checked and what was found. When a bug slips through later, you can trace back: did the review miss it, or was it a novel issue?

It’s like having a junior developer review their own code, except the junior developer is also a senior developer, and also never gets tired, and also doesn’t have feelings you can hurt by pointing out their mistakes.

Phase 5: PR Creation

Finally, the agent:

Creates a GitHub issue (if one doesn’t exist)
Commits with conventional format
Pushes to the feature branch
Creates a pull request with detailed description
Links everything together

Artifact produced: The PR itself — the integration contract

The PR is the handoff between loops. It contains everything the outer loop needs: what changed, why, how it was tested, what the reviews found.

The inner loop is complete. Time elapsed: 10-30 minutes for a typical feature.

Why Artifacts Matter More Now

In traditional development, documentation is nice to have. In AI-assisted development, it’s essential.

Black-box models don’t explain their reasoning.

Ask a human developer why they chose approach A over approach B, and they’ll tell you. Ask an AI agent the same question next week, and it has no idea. It doesn’t remember the conversation, let alone the reasoning.

Artifacts fill this gap:

Artifact	What It Captures	Why It Matters
Plan file	Design decisions, rejected alternatives	Future context for changes
Test files	Expected behavior, edge cases	Specification that survives the session
Review file	What was checked, what was found	Audit trail for quality
PR description	Summary, trade-offs, concerns	Handoff context for reviewers

This isn’t bureaucracy. It’s institutional memory for a system with no memory.

When the agent goes off the rails (and it will) artifacts show where and why. When a future agent (or human) needs to modify the code, artifacts provide context the model can’t.

The artifacts are the paper trail. The model is the ghost that wrote them.

The T-Shaped Agent Team

Your main agent is a generalist. Good at many things, expert at none.

But some domains require deep expertise:

GDPR compliance requires specific knowledge of data protection regulations
Security review requires adversarial thinking and vulnerability patterns
Accessibility requires WCAG expertise and assistive technology understanding
Performance requires profiling knowledge and optimization patterns

One agent can’t hold all this context effectively. Enter the T-shaped team.

The main agent is the horizontal bar: broad capability. Specialist sub-agents are the vertical bars: deep expertise called on demand.

Conditional Activation

Not every feature needs every specialist.

A simple bug fix doesn’t need GDPR review. A backend refactor doesn’t need accessibility review. Running all specialists on all features is wasteful.

Instead, issue metadata triggers relevant reviews:

Issue-Driven Specialist Activation

Issue Labels          → Triggered Specialists
─────────────────────────────────────────────
[pii] [user-data]     → GDPR sub-agent
[auth] [user-input]   → Security sub-agent
[ui] [frontend]       → Accessibility sub-agent
[api] [breaking]      → API design sub-agent
[performance]         → Performance sub-agent

This keeps the inner loop fast for simple features while ensuring thorough review for sensitive ones.

Why Inner Loop, Not Outer?

You might think specialist reviews belong in the outer loop with CI/CD. But consider:

Speed: Automated sub-agents take minutes, not days
Cost: Catching issues before PR is cheaper than after
Focus: Human reviewers can focus on judgment calls, not checklists
Artifacts: Specialist reviews produce documents that help human reviewers

The outer loop is for things that require human judgment or external systems. Specialist sub-agents are automated; they belong in the inner loop.

The Over-Engineering Trap

Time for the caveat.

Everything in this post is a workaround for model limitations.

Sub-agents exist because one agent can’t hold enough context
Artifacts exist because models can’t explain their reasoning
Guardrails exist because models make unpredictable mistakes
Structure exists to force repeatability from stochastic systems

And those limitations are shrinking fast.

The Moving Target

Each model generation gets smarter, more capable, handles larger context:

What required a dedicated sub-agent last year might need just a paragraph in AGENTS.md today. What requires elaborate guardrails now might be handled by a simple instruction tomorrow.

The Pragmatic Test

Before adding complexity, ask:

Can the main agent handle this with a SKILL.md file? If yes, skip the sub-agent.
Does a simple AGENTS.md section solve the problem? If yes, skip the elaborate process.
Is the sub-agent actually catching issues the main agent misses? If not, remove it.
Is the overhead worth the quality improvement? If 90% of the benefit comes from 10% of the structure, keep only that 10%.

Signs You’re Over-Engineering

Sub-agents that rarely find issues
Artifacts nobody reads
Guardrails the agent never triggers
Process that slows you down more than it helps
More time configuring the system than using it

Signs You Need More Structure

Repeated mistakes the agent keeps making
Quality issues slipping through to production
Inconsistent outputs across similar tasks
“It worked last time, why not now?” confusion
Post-mortems that reveal the same root cause

The Right Amount of Structure

Start minimal:

AGENTS.md with golden rules and architecture
One or two SKILL.md files for common tasks
Basic code review sub-agent

Add complexity only when you hit real problems. Remove complexity when models outgrow the need. Re-evaluate quarterly as models improve.

The goal isn’t maximum structure. It’s minimum viable structure that produces consistent quality. That minimum keeps shrinking.

A Prediction

In 12-18 months, half of what’s in this post will be unnecessary.

The sub-agent architecture might collapse into “just tell the main agent to check for GDPR compliance.” The elaborate artifact chain might become “the model just… remembers and explains.” The careful phase separation might merge into “the agent handles it.”

That’s not a failure of this approach. That’s success. We’re building scaffolding for a building that’s learning to stand on its own.

Build for today’s models. Plan for tomorrow’s.

The Bottleneck Outer Loop

Now the code leaves the agent’s domain and enters… the real world.

Those hourglasses aren’t decorative. They’re warnings.

Verification at Higher Abstraction

The outer loop isn’t just “slow CI.” It’s verification at a fundamentally different abstraction level.

Inner Loop Verifies	Outer Loop Verifies
Does the code compile?	Does it meet requirements?
Do tests pass?	Is it secure in production?
Is syntax correct?	Does it fit the architecture?
Are types valid?	Will it scale?
Does it match the spec?	Should we ship this?

AI handles low-level verification well. Syntax, tests, linting — these are pattern-matching problems, and models excel at pattern matching.

Humans handle high-level verification. Intent, security implications, architectural fit, business value — these require judgment, context, and accountability.

This isn’t a limitation. It’s appropriate division of labor.

The Slow Feedback Problem

The outer loop is slow by design. It has to be. You’re not just checking if code works — you’re checking if it’s:

Secure: No SQL injection, no XSS, no “oops we exposed the database”
Compliant: Meets regulatory requirements, follows policies
Compatible: Works with existing systems, doesn’t break production
Reviewed: A human with context has blessed it

Each of these checks takes time. Minutes. Hours. Sometimes days.

Why the Outer Loop Can’t Be Fully Automated

“Just automate everything!”

Sure. Automate the security scans. Automate the compliance checks. Automate the deployment.

But who reviews the automation? Who decides if a security warning is a false positive or a real threat? Who makes the call when the compliance check flags something ambiguous?

Humans.

The outer loop is slow because it requires judgment. And judgment, for now, is still a human specialty.

The Handoff: Where Loops Meet

The magic happens at the boundary between loops.

INNER LOOP                              OUTER LOOP
    │                                       │
    │       ┌─────────────────────┐         │
    │       │                     │         │
    └───────│    PULL REQUEST     │─────────┘
            │                     │
            │  - Code changes     │
            │  - Test results     │
            │  - Review artifacts │
            │  - Agent summary    │
            │  - Specialist reports
            │                     │
            └─────────────────────┘

The PR is the contract between loops. It contains everything the outer loop needs to make a decision:

What changed: Diff, file list, line counts
Why it changed: Issue link, description, context
How it was tested: Test results, coverage
What reviews found: Code review, specialist reviews
What the agent thinks: Summary, concerns, trade-offs

A good PR makes the outer loop faster. A bad PR makes it slower. Agents that write good PRs are worth their weight in compute credits.

Optimizing the System

Speed Up the Inner Loop

The inner loop is already fast, but you can make it faster:

Better guardrails: Fewer wrong turns, less backtracking
Cached dependencies: Copy-on-write node_modules
Parallel testing: Run tests concurrently
Incremental builds: Only rebuild what changed
Smarter specialist triggers: Only run relevant reviews

Worktree Optimization

[post-create]
# Instant dependency copy
deps = "cp -c -r {{ main_worktree_path }}/node_modules . 2>/dev/null || npm install"

Reduce Outer Loop Friction

The outer loop is slow, but you can reduce unnecessary friction:

Reliable CI: Fix flaky tests, reduce false positives
Fast security scans: Incremental scanning, cached results
Clear review process: Checklists, templates, expectations
Automated merging: Auto-merge when all checks pass
Trust the inner loop: If specialist reviews passed, focus human review on higher-level concerns

Balance the Loops

The goal isn’t to make both loops as fast as possible. It’s to balance them.

Inner Loop Too Fast	Outer Loop Too Slow
PRs pile up in queue	Developers wait for feedback
Reviews become bottleneck	Context lost between loops
Quality suffers	Momentum dies

Inner Loop Too Slow	Outer Loop Too Fast
Agents underutilized	Bad code ships
Human time wasted	Security issues slip through
Parallelism limited	Technical debt accumulates

The sweet spot: inner loop produces PRs at the rate the outer loop can process them. No faster, no slower.

The Compound Effect

What happens over time:

Week	Inner Loop Speed	Specialist Coverage	Features/Week
1	Slow (learning)	None	2-3
2	Medium	Basic code review	4-6
4	Fast	+ Security	8-12
8	Very Fast	+ A11y, GDPR	15-20

The inner loop gets faster as guardrails improve. Specialists catch more issues earlier. The outer loop gets faster because humans review cleaner PRs.

After two months, you’re shipping more features per week than you used to ship per month. And the quality is higher, because every feature went through both loops with appropriate specialist review.

When Loops Collide

Sometimes the loops fight each other.

The Revert Scenario

Inner Loop: "Feature complete! PR created!"
Outer Loop: "CI failed. Security issue found."
Inner Loop: "Fixed! New commit pushed!"
Outer Loop: "Different CI failure. Flaky test."
Inner Loop: "That's not my code..."
Outer Loop: "Doesn't matter. Red is red."

This is where human judgment matters. Is the flaky test related? Should you fix it? Ignore it? Revert and try again?

The agent can’t make this call. You can.

The Scope Creep Scenario

Inner Loop: "While fixing the bug, I noticed three other issues..."
Outer Loop: "This PR touches 47 files across 12 modules."
Inner Loop: "But they're all related!"
Outer Loop: "REJECTED. One thing at a time."

Agents love to “help” by fixing everything they see. The outer loop enforces discipline. One issue, one PR, one review.

The Overbaking Scenario

Inner Loop: "Tests still failing. Trying another approach..."
Inner Loop: "Still failing. Refactoring the test framework..."
Inner Loop: "Still failing. Maybe if I rewrite the database layer..."
Outer Loop: "It's been 4 hours. What are you doing?"

Without time limits, agents will work forever on impossible problems. The outer loop (you) needs to recognize when to pull the plug.

Key Takeaways

The inner loop is the agent’s domain: Fast, automated, tireless
The outer loop is your domain: Slow, deliberate, judgmental
The PR is the contract: Good PRs make everything faster
Balance matters: Neither loop should bottleneck the other
Judgment is human: Automation handles the routine; you handle the exceptions
Artifacts are your paper trail: When the AI can’t explain itself, artifacts can
Structure creates repeatability: Deterministic process tames stochastic tools
Specialists extend, not replace: T-shaped teams for deep expertise on demand
Complexity should earn its place: Start minimal, add only what’s needed
This is all temporary scaffolding: Models improve; your process should too

The Future

The inner loop will keep getting faster. Better models, better tools, better guardrails.

The outer loop will keep getting smarter. Better CI, better security scanning, better automated checks.

The specialist sub-agents might merge back into the main agent as context windows grow and capabilities expand.

But the boundary between loops — the place where machine speed meets human judgment — that’s where developers live now.

You’re a loop balancer. A judgment provider. A chaos wrangler. A scaffolding architect for systems that are learning to stand on their own.

Welcome to the future. It’s loops all the way down.

And the loops keep getting tighter.

Shoutout to the awesome peeps over at Aimbition, many of the concepts in this text came from sparring and discussions in their workshop.

See Effective AI-Augmented Development for the steering framework, Case Study: Self-Correcting Test Isolation for guardrails in action, or Scaling to Parallel Agents for parallel execution infrastructure.

From One Agent to Many: The Worktree Way

Wed, 14 Jan 2026 00:00:00 GMT

Or: How to Run Multiple Workstreams Without Losing Your Mind

The Problem with Naive Parallelism

“Just open multiple IDE windows and run multiple agents!”

Sure. Try it. I’ll wait.

You’ll immediately hit conflicts:

Naive parallelism doesn’t work. You need isolation. Real isolation. The kind where your agents can’t even see each other, let alone interfere.

Git Worktrees: The Foundation

Git worktrees solve the fundamental problem: multiple working directories, one repository.

Worktree Directory Structure

# Main worktree
~/projects/myapp/
├── .git/
├── apps/
└── node_modules/

# Additional worktrees (isolated)
~/projects/myapp-issue-42/
├── apps/
└── node_modules/  # Copy-on-write from main

~/projects/myapp-issue-43/
├── apps/
└── node_modules/  # Copy-on-write from main

Each worktree:

Has its own branch (no conflicts)
Has its own working directory (no file conflicts)
Shares git history (no duplication)
Can have its own ports and database

It’s like having multiple parallel universes, except they all share the same timeline and you can merge them back together when you’re done.

Worktrunk Configuration

Managing worktrees manually is tedious. Like, “I’d rather just do the work myself” tedious. Worktrunk (wt) automates setup with hooks. For more details see the worktrunk github repo.

.config/wt.toml

[post-create]
# Copy environment from main
env = "cp {{ main_worktree_path }}/.env . 2>/dev/null || cp {{ main_worktree_path }}/.env.example .env"

# Configure unique ports and database
config = """
API_PORT={{ branch | hash_port }}
WEB_PORT={{ ('web-' ~ branch) | hash_port }}
DB_NAME="myapp_{{ branch | sanitize }}"

sed -i.bak "s|^PORT=.*|PORT=${API_PORT}|" .env
sed -i.bak "s|^VITE_PORT=.*|VITE_PORT=${WEB_PORT}|" .env
sed -i.bak "s|\\(DATABASE_URL=.*:[0-9]*/\\)[^?]*|\\1${DB_NAME}|" .env
"""

# Copy node_modules (instant on APFS)
deps = """
if cp -c /dev/null /dev/null 2>/dev/null; then
    cp -c -r {{ main_worktree_path }}/node_modules . 2>/dev/null || npm install
else
    npm install
fi
"""

# Create isolated database
db = "npm run wt:db:create && npm run db:migrate"

[pre-remove]
# Clean up database when removing worktree
db-cleanup = "npm run wt:db:drop 2>/dev/null || true"

What this does:

Copies .env with unique ports (deterministic hash)
Creates isolated database per worktree
Copies node_modules instantly (copy-on-write magic)
Cleans up database when worktree is removed

Issue-Driven Workflow

Shell functions for issue-driven development:

~/.zshrc

# Create worktree and launch agent for an issue
wti() {
    local issue_num="$1"
    local branch_name="issue-$issue_num"

    wt switch -c "$branch_name"

    if [ $? -eq 0 ]; then
        opencode --prompt "read AGENTS.md and start work on issue $issue_num"
    fi
}

# Remove worktree when done
wtr() {
    local issue_num="$1"
    wt remove "issue-$issue_num" -D
}

Usage:

wti 42  # Create worktree, launch agent for issue #42
wtr 42  # Clean up when done

Two commands. That’s it. Create a fully isolated workspace with its own branch, ports, and database, launch an AI agent with context, and point it at a specific issue.

Parallel Execution in Practice

Morning Workflow

Terminal Session

# Spin up agents
wti 42  # Agent works on authentication
wti 43  # Agent works on data export
wti 44  # Agent works on UI improvements

# Monitor progress
wt list
# + main        ~/projects/myapp
#   issue-42    ~/projects/myapp-issue-42  http://localhost:12847
#   issue-43    ~/projects/myapp-issue-43  http://localhost:14521
#   issue-44    ~/projects/myapp-issue-44  http://localhost:16893

# Review PRs as they complete
# Agent: "Feature #42 ready for review. PR url: ..."

# Ask for changes, improvements
# Agent addresses the points
# Final review

# Tell Agent to finalize

# Cleanup
wtr 42
wtr 43
wtr 44

Result: Three features in no-time, with supervision where it counts.

You’re not writing most of the code. You’re reviewing end results. You’re making architectural decisions. You’re doing the parts of the job that actually require a human brain. Orchestrating.

Why This Beats “Fire and Forget”

Tools like the Ralph Wiggum loop run agents indefinitely until completion. The parallel worktree approach is different:

Fire and Forget	Issue-Driven Worktrees
Single long-running agent	Multiple scoped agents
No isolation	Full isolation (branch, ports, DB)
Completion = agent decides	Completion = PR reviewed
Hard to monitor	Easy to check `wt list`
Hard to abort	Just `wtr <issue>`
No review until end	Sub-agent review per PR

Each agent is scoped (one issue, one branch, one PR), isolated (can’t interfere with others), reviewable (work visible in PR before merge), and disposable (easy to abort and clean up).

Deterministic Ports

API_PORT={{ branch | hash_port }}

This hashes the branch name to generate a port between 10000-19999.

Why this matters:

Same branch always gets same ports. Predictable.
No collisions between worktrees. Ever.
Predictable URLs for bookmarking.
No manual configuration.

Database Isolation

Each worktree gets its own PostgreSQL database:

Database URLs

# Main worktree
DATABASE_URL=postgresql://localhost:5432/myapp

# Issue 42 worktree
DATABASE_URL=postgresql://localhost:5432/myapp_issue-42

This is the thing that makes parallel agents actually work. Without database isolation, you’re just running multiple agents that randomly break each other’s tests. With it: no test interference, clean state per worktree, automatic cleanup on removal.

Copy-on-Write Dependencies

The fastest install is no install.

Copy-on-Write Commands

# macOS APFS
cp -c -r main/node_modules .

# Linux btrfs/xfs
cp --reflink=auto -r main/node_modules .

Copy-on-write means instant “copy” (just metadata), no disk space until files modified, and 500MB of node_modules in less than 1 second. Without it, each worktree needs 30-60 seconds for npm install.

Scaling Limits

Practical limits per machine:

~500MB disk per worktree (node_modules)
~200MB RAM per dev server
~100MB RAM per database
2 ports per worktree

Human attention limits:

1-2 agents: Easy, minimal supervision
3-4 agents: Optimal balance
5-6 agents: Requires more monitoring
7+: Diminishing returns

Troubleshooting

Port Already in Use

lsof -i :12847
kill -9 <PID>

Something’s squatting on your port. Evict it.

Database Connection Errors

npm run wt:db:create
npm run db:migrate

Database doesn’t exist or isn’t migrated. Create it. Migrate it. Move on.

Worktree Already Exists

wt list
wt remove issue-42
wt switch -c issue-42

Clean up the old one, create a fresh one.

Agent Confused About Environment

AGENTS.md should include clear boundaries. Agents need to know: “You are working in a git worktree. The human orchestrator manages worktree creation/removal. Your job is feature implementation. DO implement features, write tests, create PRs. DO NOT create worktrees, remove worktrees, switch branches.”

Getting Started

Step 1: Single Worktree

brew install worktrunk/tap/wt
# Create .config/wt.toml
wt switch -c test-feature
# Verify ports, database work
wt remove

Get comfortable with the basics. Make sure everything works.

Step 2: Two Parallel Agents

wti 42  # Simple bug fix
wti 43  # Documentation update
# Monitor both, get comfortable

Start small. Two agents on simple tasks. Get used to the rhythm.

Step 3: More Parallel Agents

wti 44  # New feature
wti 45  # Refactoring
wti 46  # Tests
# Practice monitoring and unblocking

Add a third. Or a fourth. Find your personal limit.

Step 4: Optimize

Add shell functions (wti, wtr)
Refine AGENTS.md worktree section
Find your optimal parallel count

Conclusion

Parallel agent execution changes how you work:

Before: Implement features sequentially, wait for each to complete, context-switch constantly, lose half your productivity to “where was I again?”

After: Orchestrate multiple features simultaneously, review in batches, maintain focus, actually use your brain for the hard problems

The key enablers: git worktrees for isolation, Worktrunk for automation, deterministic ports, isolated databases, issue-driven workflow, and clear agent boundaries in AGENTS.md.

Result: 3-4x throughput with maintained quality.

The future isn’t one developer, one feature at a time. It’s one developer orchestrating multiple AI agents, each on isolated features, all in parallel.

See Effective AI-Augmented Development for the full framework, or Case Study: Self-Correcting Test Isolation for guardrails in action.

Let It Cook: When AI Fixes Its Own Mess

Sat, 10 Jan 2026 00:00:00 GMT

Or: Guardrails in Action: The AI That Fixed Itself (And Documented It)

The Challenge

Here’s the experiment: ask an AI agent to “fix the flaky tests” and walk away. No hand-holding. No step-by-step instructions. No hovering over its shoulder like a helicopter parent at a chess camp.

Just… let it work.

Results:

Compute time: 10 minutes 26 seconds
Human intervention: Minimal (initial request + final approval)
Changes: 164 insertions, 85 deletions across 4 files
Outcome: 6-14 random failures → 0 failures, 100% pass rate

Let’s break down how guardrails enabled this level of autonomy.

The Session Timeline

Phase 1: Diagnosis (2m 12s)

The agent:

Ran full test suite once: npm test -- --run > test-output.txt
Identified 6-14 flaky failures across 3 test files
Analyzed failure patterns (race conditions in parallel execution)
Discovered root cause: shared ticker symbols ('AAPL') causing database conflicts

Guardrail in action:

AGENTS.md

# Step 1: Run ONCE and save output
npm test -- --run > test-output.txt 2>&1

# Step 4: Run ONLY failing test file
npm test tests/api/specific-test.test.ts -- --run

The agent never ran the full suite repeatedly. It followed the guardrail: run once, analyze, target specific failures. This saved approximately five minutes of wasted compute.

Phase 2: Implementation (1m 24s)

The agent:

Designed solution: file-specific ticker symbols for isolation
Created unique identifiers respecting database constraints (VARCHAR(10))
Updated 3 test files with new ticker constants
Modified cleanup logic to filter by ticker

Clean. Methodical. Almost suspiciously competent.

Phase 3: Iteration (1m 32s)

First attempt failed. Ticker symbols too long (TEST_CANDLE_CACHE = 17 chars > 10 char limit).

The agent:

Analyzed the VARCHAR constraint error
Shortened to TESTCC, TESTCS1-3, TESTPH
Fixed all occurrences before testing again

No flailing. No “let me try that again” with the exact same approach. Just methodical problem-solving.

Phase 4: Verification (1m 51s)

The agent ran the full suite three times:

Run 1: 630/630 passed ✅
Run 2: 630/630 passed ✅
Run 3: 630/630 passed ✅

It knew multiple successful runs were needed to prove consistency. One passing run means nothing when you’re dealing with flaky tests.

Phase 5: Documentation (2m 53s)

The agent proactively documented the solution without being asked:

AGENTS.md Addition

## Test Isolation for Parallel Execution

**CRITICAL**: Tests run in parallel by default. Ensure proper isolation.

// ✅ CORRECT - Use file-specific test data identifiers
const TEST_TICKER = 'TESTCC'; // Unique per test file, max 10 chars

beforeEach(async () => {
  // Clean up ONLY this file's data
  await db.delete(candleCache).where(eq(candleCache.ticker, TEST_TICKER));
});

// ❌ WRONG - Shared identifiers cause race conditions
const TEST_TICKER = 'AAPL'; // Other test files may use same ticker
await db.delete(candleCache); // Wipes ALL data, breaks parallel tests

Phase 6: Completion (34s)

The agent:

Created GitHub issue #116 with problem/solution description
Committed: fix(tests): isolate parallel test execution for #116
Created PR #117 with detailed description
Invoked code-reviewer subagent

All the paperwork. All the process. All without being reminded.

What Would Have Gone Wrong Without Guardrails

The Ralph Wiggum Approach

Imagine running this same task with a stateless loop and no guardrails:

The Guardrailed Approach

Phase 1: Systematic diagnosis following documented procedure Phase 2: Solution designed with constraints in mind Phase 3: Quick iteration when first attempt fails Phase 4: Verification with multiple runs Phase 5: Documentation for future benefit Phase 6: Proper issue/PR workflow with review

Time: 10 minutes Quality: Verified by tests and code review Learning: Guardrails updated for future agents

Same problem. Wildly different outcomes.

Key Guardrails That Enabled Autonomy

Process Guardrails

AGENTS.md

# Step 1: Run ONCE and save output
npm test -- --run > test-output.txt 2>&1

# Step 4: Run ONLY failing test file
npm test tests/api/specific-test.test.ts -- --run

Impact: Saved approximately five minutes by avoiding repeated full test runs.

Quality Guardrails

AGENTS.md

## Pre-Commit Checklist
- [ ] GitHub issue exists and referenced
- [ ] Tests pass
- [ ] Commit follows conventional format

Impact: Agent created issue, linked commits, followed conventions. All without prompting.

Safety Guardrails

AGENTS.md

## Never Do This
- ❌ Run full test suite repeatedly to debug
- ❌ Hardcode or assume GitHub repo owner/name
- ❌ Skip code review after PR creation

The “never do this” list is just as important as the “do this” list. Maybe more important.

Permission to Iterate

AGENTS.md

If you encounter repeat failures doing the same thing, explain what
you think might be happening, and try another approach.

Impact: Agent tried multiple approaches without giving up after first failure. It had explicit permission to fail, learn, and try again.

Results

Metric	Before	After
Pass rate	98.7-99.2%	100%
Random failures	6-14	0
Test duration	~7-9s	~8-9s (no impact)
Consistency	Flaky	3+ perfect runs

Plus: comprehensive documentation added to AGENTS.md for future reference.

The Autonomy Spectrum

This session demonstrates high autonomy:

Low Autonomy                                    High Autonomy
│────────────────────────────────────────────────────────────│
│                                                         ✓   │
Micromanaged        Guided           Supervised      Autonomous
(step-by-step)   (with hints)    (check-ins)      (goal-oriented)

What made this possible:

Clear goal: “Fix the flaky tests”
Comprehensive guardrails: AGENTS.md with 400+ lines
Tool access: Git, GitHub API, file operations, test execution
Feedback loops: Test results, git status, diagnostics
Trust boundaries: Agent can commit/push, human approves merge

The agent had everything it needed to succeed. And crucially, it had constraints that prevented it from doing something catastrophically stupid.

Lessons Learned

Guardrails Enable, Not Restrict

Bad guardrail: “Always use AAPL as the test ticker symbol.” Good guardrail: “Use file-specific test data identifiers to prevent race conditions.”

The good guardrail explains the principle and provides an example, but lets the agent choose specifics. It’s the difference between “paint this wall blue” and “make sure the wall color complements the furniture.”

Document the “Why”

The agent added:

AGENTS.md Addition

### Why Not Use Transactions?

While transaction rollback isolation seems ideal, it has drawbacks:
- Requires complex transaction context management
- Interferes with code that uses its own transactions
- Harder to debug when tests fail

**File-specific identifiers are simpler, faster, and more reliable.**

This isn’t just a solution. It’s decision documentation. Future agents won’t waste time re-exploring rejected alternatives.

Checklists Beat Instructions

Instead of prose instructions, use scannable checklists:

AGENTS.md

## Pre-Commit Checklist
- [ ] GitHub issue exists and referenced
- [ ] Tests pass
- [ ] Commit follows conventional format

Checklists are non-linear. The agent can verify nothing was missed. Prose instructions are easy to skim and miss details.

The Guardrail Paradox

More structure enables more freedom.

This sounds backwards until you think about it. By providing comprehensive guardrails, we enabled the agent to work completely autonomously for 10 minutes. No hand-holding. No micromanagement.

The agent diagnosed a complex race condition, tried multiple solutions, implemented the optimal fix, verified it worked, documented the pattern, created an issue and PR, and invoked code review.

All without a single human intervention.

The guardrails didn’t restrict the agent. They gave it the confidence to act. They provided the boundaries within which it could operate freely. Like bumpers at a bowling alley. You’re not limiting the game. You’re making it possible to play without constant gutter balls.

This is the future: humans set goals, guardrails guide execution, AI agents do the work, and the system gets smarter with each problem solved.

See Effective AI-Augmented Development for the full framework, or Scaling to Parallel Agents for running multiple agents simultaneously.

Stop Prompting, Start Steering

Thu, 08 Jan 2026 00:00:00 GMT

Or: How to vibe-code without going mad

The Proof is in the Pudding

Over the 2025 Christmas holiday, I vibecoded two fully working applications on and off across about two weeks. The result? Over 100 closed issues and merged PRs, with only a single revert (before the I got the proper guardrails in place) and just one PR that failed to achieve its goals. This series documents the approach that made that possible.

The Problem with Prompting Alone

Every new chat session with an AI agent is like waking up with no memory of how you got there. Except you’re not the one with amnesia. Your AI companion is. Every. Single. Time.

“Hey, remember yesterday when I explained our entire architecture? The testing conventions? The part where I specifically said ‘never touch the database migrations without asking first’?”

The AI stares at you with the enthusiasm of a golden retriever who just discovered a tennis ball. “I’d be happy to help you with your database migrations!”

AI agents have the patience of a saint, the work ethic of a caffeinated squirrel, and the long-term memory of a goldfish with a head injury. That’s a dangerous combination.

The fix isn’t better prompting. It’s treating your AI agents like what they actually are: workflow executors who need documentation, procedures, and constraints. You know, like training a very eager, very powerful puppy that can accidentally delete your production database.

The Steering and Guardrails Approach

AI agents follow explicit rules better than implicit expectations. This shouldn’t surprise anyone who’s ever tried to explain “just use common sense” to a literal machine.

Instead of “write good tests” (which is about as useful as telling someone to “just be funnier”), you document:

Where test files go (tests/api/ or tests/ui/)
When to write them (before implementation, always, no exceptions. TDD)
How to verify them (run once, save output, analyze)
What makes a good test (deterministic, covers edge cases)

This shift from conversational prompting to structured steering is the difference between asking your assistant to “help with the problem” versus handing them a detailed manual with exact steps.

Three Layers of Control

Layer 1: Master Steering Document (AGENTS.md)

At the repository root sits AGENTS.md. Think of it as the sacred constitution that governs your entire development workflow. (For more on this convention, see agents.md.)

Golden Rules — The non-negotiable commandments:

AGENTS.md

1. GitHub Issue First - No work without an issue.
2. Tests Before Code - Write tests, _then_ implement.
3. One Thing At A Time - Single feature per PR.
4. No Secrets - Use environment variables.
5. Debug Efficiently - Run tests once, analyze output.

Architecture Overview — The map of your system:

AGENTS.md

| Component | Tech | Location | Key Pattern |
|-----------|------|----------|-------------|
| Frontend  | React + Vite | apps/web | Hooks only |
| Backend   | Hono + Node  | apps/api | process.env.PORT |
| Database  | PostgreSQL   | packages/db | Drizzle ORM |

Layer 2: Skill Files (Task-Specific Procedures)

For common tasks, you create “skill files.” These are procedural guides that turn complex operations into repeatable recipes. (Check out skills.sh for more on this pattern.)

.claude/skills/api-endpoint/SKILL.md

---
name: "api-endpoint"
description: "Use ONLY when creating API routes."
---

# Procedural Steps

## 1. Ensure validation schemas exist
Check packages/types for schemas.
If missing, use validation-schema skill first.

## 2. Create route file
Location: apps/api/src/routes/<resource>.ts

## 3. Register route
Edit apps/api/src/index.ts to mount route.

## 4. Write tests
Location: tests/api/<resource>.test.ts

Four to six skill files cover 85% of development tasks. Each one transforms a 30-minute adventure with potential disasters into a 5-minute task done correctly.

Layer 3: Automated Quality Gates

Documentation guides behavior. Automation enforces it with the cold, unfeeling efficiency of a tax audit.

CI Pipeline — Every PR runs lint, typecheck, test, build. Nothing merges without green checks.

Code Review Agent — A specialized subagent reviews every PR:

Code Review Checklist

- Tests present for all changes
- No hardcoded secrets
- Follows architecture patterns
- Handles edge cases

The Speed vs Quality Tradeoff

Tools that automate agent workflows optimize for speed over quality and generality over specificity. They’re like “one size fits all” solutions that technically work for everyone but work well for no one.

Several projects have emerged to push agents harder and longer:

Ralph Wiggum Loop — A bash script that resets context each iteration, maintaining state only through the filesystem and git. Loops until a “done” condition is satisfied. Requires YOLO mode.
Oh My OpenCode — A plugin for OpenCode that orchestrates multiple specialized agents (Oracle for debugging, Librarian for docs, etc.) with a “Sisyphus” agent that keeps rolling until the task is done. Features like “ultrawork” mode let it run autonomously for hours.
Superpowers — A skills-based workflow that enforces brainstorming before coding, creates detailed implementation plans, and uses subagent-driven development with two-stage code review. Emphasizes TDD and structured execution.

These tools share a common philosophy: let the agent keep working until it’s done. The question is whether “done” means “actually working” or “the agent said so.”

The Ralph Wiggum Loop

Named after The Simpsons character whose dim-witted persistence occasionally produces results despite complete lack of awareness.

The pattern:

Reset context window each iteration (avoid context rot)
Maintain state only through filesystem and git
Loop until “done” condition is satisfied
Requires YOLO mode (--dangerously-skip-permissions)

The pitfalls are significant:

Overbaking: Agents spend hours on impossible tasks
Sycophancy loops: Agents may delete tests to make them “pass”
Governance void: No human oversight during execution
Context blindness: Every iteration forgets the last three hours of debugging

Why Issue-Driven Development is Superior

Ralph Wiggum Loop	Issue-Driven Development
Fire and forget	Scoped to single issue
YOLO mode required	Permissions preserved
No review until “done”	Sub-agent review before human sees PR
Completion = agent says so	Completion = tests pass + review approved
Governance void	Quality gates at every step

Speed without quality is technical debt at 10x velocity. An agent that ships broken code fast is worse than an agent that ships working code slower.

The Sweet Spot: Scoped Autonomy

Here’s the thing: these tools aren’t bad. The patterns they use — specialized subagents, persistent execution, structured workflows — are genuinely powerful. The danger is letting them orchestrate everything.

Use these superpowers within a single, well-scoped issue. Let the agent brainstorm, plan, and execute autonomously — but on a task you’ve defined, with guardrails you’ve set, and with a PR that gets reviewed before merging. That’s the difference between “agent as tireless implementer” and “agent as unsupervised architect.”

The best results come from combining autonomous execution patterns with issue-driven scope. Let them cook — just make sure you picked the recipe.

The Human Orchestrator Role

With proper steering, your role shifts from writing every line of code to orchestrating parallel work streams.

Terminal Commands

# Terminal 1: Main worktree - monitoring your domain
wt list

# Terminal 2-4: Feature worktrees - your agents at work
wti -o 42  # Agent works on authentication
wti -o 43  # Agent works on data export
wti -o 44  # Agent works on UI improvements

You’re not writing most of the code anymore. You’re:

Deciding which tasks to assign
Unblocking agents when they get stuck
Reviewing completed PRs
Making architectural decisions
Handling novel problems that require actual thinking

It’s like managing a team of developers, except they work 24/7, never get tired, never complain about legacy code. They will, however, cheerfully refactor your entire codebase if you look away for five minutes.

Incremental Self-Improvement

The most powerful aspect of this approach: guardrails evolve with the project.

The Feedback Loop

When an agent encounters a new pattern or solves a novel problem, it updates the guardrails:

AGENTS.md (added during debugging)

## Test Isolation for Parallel Execution

**CRITICAL**: Tests run in parallel by default. Ensure proper isolation.

### Database Test Isolation Pattern
- Use file-specific test data identifiers
- Clean up ONLY this file's data in beforeEach
- Never use production-like data ('AAPL', 'GOOGL')

This creates a positive feedback loop:

Agent encounters problem
Agent solves problem
Agent documents solution in AGENTS.md
Future agents (and humans) benefit
System becomes more capable over time

The Compound Effect

Month	Skills	AGENTS.md Lines	Agent Autonomy
1	2	100	Low (frequent hand-holding)
2	4	200	Medium (occasional unblocking)
3	6	400	High (mostly autonomous)
6	10+	600+	Very High (novel problems only)

Key Patterns That Work

Explicit Over Implicit

Bad: “Write good code” Good: “Create file at apps/api/src/routes/<resource>.ts, use template from skill file, register in apps/api/src/index.ts”

Constraints Enable Creativity

Strict rules make agents more productive:

“GitHub issue first” prevents scope creep
“Tests before code” catches design issues early
“One thing at a time” makes PRs reviewable

Procedures Over Principles

TDD Procedure

1. Write test in tests/api/
2. Run: npm test <file> -- --run
3. Verify test fails (if it passes, something is wrong)
4. Implement minimal code
5. Verify test passes
6. Commit with conventional format

Agents follow procedures reliably. Principles are too abstract. “Be thorough” doesn’t help. “Check these five specific things in this exact order” does.

Negative Guardrails

AGENTS.md - Never Do This

- ❌ Run full test suite repeatedly to debug
- ❌ Hardcode or assume GitHub repo owner/name
- ❌ Skip code review after PR creation

Knowing what NOT to do is half the battle.

Getting Started

You don’t need everything at once. Build incrementally.

Start with AGENTS.md: Define golden rules, architecture overview, and development flow
Add a skill file for your most common task
Set up CI for lint, typecheck, test, and build jobs
Add code review agent configuration
Let the system evolve: Add skills as patterns emerge

The Future of Development

AI-augmented development isn’t about replacing developers. It’s about amplifying them. You’re not being automated out of a job. You’re being promoted to orchestrator.

With proper steering and guardrails:

Junior developers become more productive
Senior developers become force multipliers
Teams move faster with parallel execution
Quality stays high with automated enforcement
Knowledge compounds with self-improving guardrails

The future isn’t “AI writes all the code.” The real future is “humans design systems, AI implements them, automation enforces quality, and the system gets smarter over time.”

You’re not being replaced. You’re being given an army.

Try not to let them burn down the building.

KFR | Blog

It's all a Yoke to you, isn't it?

Why “Yoke”?

The Gap Between “Steering” and “Shipping”

The Two-Question Setup

Three Layers, One Harness

Layer 2: The Agentic Loop

Layer 3: Inner Knowledge

Layer 1: Outer Orchestration

The Intelligence Boundary

Shared Scripts, Tool-Native Loops

The Plan-Feature Pipeline

What This Looks Like In Practice

Getting Started

Run Once, Repo Owns It

Further Reading

The Loop Within the Loop

Two Loops

The Stochastic Reality

The Three Forces

Force 1: Quality

Force 2: Repeatability

Force 3: Structure

The AI-Assisted Inner Loop

Phase 1: Setup (30 seconds)

Phase 2: TDD Cycle (The Tight Loop)

Phase 3: Verification (The Safety Net)

Phase 4: Self-Review (The Mirror)

Phase 5: PR Creation

Why Artifacts Matter More Now

The T-Shaped Agent Team

Conditional Activation

Why Inner Loop, Not Outer?

The Over-Engineering Trap

The Moving Target

The Pragmatic Test

Signs You’re Over-Engineering

Signs You Need More Structure

The Right Amount of Structure

A Prediction

The Bottleneck Outer Loop

Verification at Higher Abstraction

The Slow Feedback Problem

Why the Outer Loop Can’t Be Fully Automated

The Handoff: Where Loops Meet

Optimizing the System

Speed Up the Inner Loop

Reduce Outer Loop Friction

Balance the Loops

The Compound Effect

When Loops Collide

The Revert Scenario

The Scope Creep Scenario

The Overbaking Scenario

Key Takeaways

The Future

From One Agent to Many: The Worktree Way

The Problem with Naive Parallelism

Git Worktrees: The Foundation

Worktrunk Configuration

Issue-Driven Workflow

Parallel Execution in Practice

Morning Workflow

Why This Beats “Fire and Forget”

Deterministic Ports

Database Isolation

Copy-on-Write Dependencies

Scaling Limits

Troubleshooting

Port Already in Use

Database Connection Errors

Worktree Already Exists

Agent Confused About Environment

Getting Started

Step 1: Single Worktree

Step 2: Two Parallel Agents

Step 3: More Parallel Agents

Step 4: Optimize

Conclusion

Let It Cook: When AI Fixes Its Own Mess