A Bigger Vision For Tug
tl;dr
I’m pivoting this project. Tug is now about creating an AI-assisted software construction system, thinking through and delivering the tools and techniques humans and coding assistants need to make better software together.
I started this Tug project to scratch an itch. I noticed that Claude Code would often struggle to do complex code refactoring, issuing long chains of grep, sed, and awk commands to change the text of my programs lexically rather than understanding how to change my code semantically.
So, I started making proper code refactoring tools to make available to the assistant, starting with python—a substantial project as I conceived of it. I began with a combination of Claude Code and Cursor, but soon started leaning more on Claude Code, extending it with skills and subagents to help me in my daily coding. I acted as the orchestrator, calling on these new tasks as I made and improved them. Eventually, I produced a workflow I liked well enough to produce work I was happy to commit. I wrote it up in How I Write Code With AI.
After I finished writing this post, I took a step back and looked at the 20-step process I included. I felt a mix of fascination and frustration. I was fascinated about how such a workflow had become possible. I was frustrated that I wasn’t working more directly on this new style of software construction.
So, I decided to do something about it. I kicked off a side project that I called “specks”1, to spend more time with that workflow, to think about it more deeply, and to see if I could turn it into an automated process orchestrated by AI agents.
I succeeded. What an interesting two weeks of work! Talk about fascination!
My planning and implementation loops are now fully under the control of two top-level orchestrator skills in Claude Code. Each of them call on a number of subagents (see below). I also added one additional step at the end to merge code after the implementation loop completes, since the implementation now happens on a git worktree. I also integrated beads to bolster the implementation infrastructure.
Now, my main workflow now has four steps rather than twenty. All focused around Claude Code.
- I chat with Claude Code to explore a new idea until I’m satisfied that it represents a piece of work I want to do.
- I run
/tugtool:plan, and reference the context. It makes a plan file. (Subagents:clarifier-agent→author-agent→critic-agent, with an author/critic revision loop; tugtool calls:tugtool initpre-hook.) - I run
/tugtool:implementwith the plan just created. It writes the code and sends me a PR. I review the PR. If I’m satisfied (and I usually am)… (Subagents:architect-agent→coder-agent→reviewer-agent→committer-agent→auditor-agent→integrator-agent; tugtool calls:tugtool worktree create --json.) - I run
/tugtool:mergeto pull that code onto my main branch. (Subagents: none; tugtool calls:tugtool merge --dry-run --json→ confirm →tugtool merge --json→tugtool doctor+tugtool worktree list.)
This side project accomplished two things:
- I made my workflow more efficient by taking a useful workflow and taught the AI to do it for me.2
- I changed my work from developing a code refactoring tool—solving a problem that I occasionally have—to one where I was improving my everyday workflow—solving a problem I have all the time.
This was just too fascinating to keep as a side project. It started to feel like it should be my main project.So, I’m now pivoting Tug to be a project about software construction. This new agent flow is now the core of the focus—at least for now. It’s also given me a whole new set of ideas for building a more full-featured experience—something that imagines a future of software construction beyond the age of IDEs like vscode and Xcode. I’ve already sketched out a roadmap, some exiciting new ideas for how this might fit together. I also made a comprehensive update to the sticky What is Tug always present in the header, to describe the new project concept.
I have more posts planned to share additional thoughts about new direction, but until then, here are the new agents that make up the core of this new workflow.
Agent Orchestration Loops
PLAN ORCHESTRATION LOOP
┌──────────────────────────────────────────┐
│ PLANNING PHASE BEGINS │
│ (produce a tugplan at .tugtool/tugplan) │
└────────────────────┬─────────────────────┘
│
▼
┌──────────────────────────────────────────┐
│ clarifier-agent (runs once) │
│ SPAWN → clarifier_id │
└────────────────────┬─────────────────────┘
│
▼
┌────────────┐
│ questions? │
└──┬─────┬───┘
yes │ │ no
▼ │
┌──────────────────┐ │
│ AskUserQuestion │ │
└────────┬─────────┘ │
└──────┬─────┘
│
┌─────────────────▼────────────────────────┐
│ author-agent │
│ Pass 0: SPAWN (FRESH) → author_id │◄─┐
│ Pass N: RESUME author_id │ │
└────────────────────┬─────────────────────┘ │
│ │
▼ │
┌──────────────────────────────────────────┐ │
│ critic-agent │ │ revision
│ Pass 0: SPAWN (FRESH) → critic_id │ │ loop
│ Pass N: RESUME critic_id │ │
└────────────────────┬─────────────────────┘ │
│ │
▼ │
┌────────────────┐ │
│ critic │ │
│recommendation? │ │
└──┬──────────┬──┘ │
APPROVE │ │ REVISE / REJECT │
│ └──────────────────┘
▼
┌──────────────────────────────────────────┐
│ PLANNING PHASE COMPLETE │
│ Plan ready at {plan_path} │
│ Next: /tugtool:implement {plan_path} │
└──────────────────────────────────────────┘IMPLEMENT ORCHESTRATION LOOP
┌──────────────────────────────────────────┐
│ tugtool worktree create <plan> --json │
└────────────────────┬─────────────────────┘
│
▼
┌────────────┐
│ succeeded? │
└──┬──────┬──┘
yes │ └ no ──► HALT WITH ERROR
│
▼
═══ STEP LOOP (each ready step) ═══
┌──────────────────────────────────────────┐
│ architect-agent │
│ Pass 0: SPAWN → architect_id │
│ Pass N: RESUME architect_id │
└────────────────────┬─────────────────────┘
│
▼
┌──────────────────────────────────────────┐
│ coder-agent │
│ Pass 0: SPAWN → coder_id │
│ Pass N: RESUME coder_id │
└────────────────────┬─────────────────────┘
│
▼
┌────────────┐
│ drift? │
└──┬──────┬──┘
none/ │ │ moderate/major
minor │ └──► AskUserQuestion
│ │
│◄──────────────┘
│
▼
┌──────────────────────────────────────────┐
│ reviewer-agent │◄──┐
│ Pass 0: SPAWN → reviewer_id │ │
│ Pass N: RESUME reviewer_id │ │
└────────────────────┬─────────────────────┘ │
│ │
▼ │ review
┌───────────────┐ │ retry
│ reviewer │ │
│recommendation?│ │
└──┬─────────┬──┘ │
APPROVE │ │ REVISE (max 3) │
│ └─► coder fix ───────┘
▼
┌──────────────────────────────────────────┐
│ committer-agent │
│ SPAWN/RESUME → commit + close bead │
└────────────────────┬─────────────────────┘
│
┌───────────────┐
│ more steps? │─ yes ─► back to architect
└───────┬───────┘
│ no
▼
═══ AUDITOR PHASE ═══
┌──────────────────────────────────────────┐
│ auditor-agent │◄─────────────┐
│ SPAWN/RESUME │ │
└────────────────────┬─────────────────────┘ │
│ │
▼ │ audit
┌───────────────┐ │ retry
│ auditor │ │
│recommendation?│ │
└──┬─────────┬──┘ │
PASS │ │ REVISE (max 3) │
│ └─► coder fix → committer ──────┘
▼
═══ INTEGRATOR PHASE ═══
┌──────────────────────────────────────────┐
│ integrator-agent │◄─────────────┐
│ SPAWN/RESUME → push, PR, CI │ │
└────────────────────┬─────────────────────┘ │
│ │
▼ │ CI
┌───────────────┐ │ retry
│ integrator │ │
│recommendation?│ │
└──┬─────────┬──┘ │
PASS │ │ REVISE (max 3) │
│ └─► coder fix → committer ──────┘
▼
┌──────────────────────────────────────────┐
│ IMPLEMENTATION COMPLETE │
│ Plan: {plan_path} PR: {pr_url} │
└──────────────────────────────────────────┘