A couple of months ago, I wrote about reducing token usage when working with coding agents. The central idea was that an agent should not have to re-understand an entire project every time it starts a task.

I still believe that. But I would frame it differently now.

The biggest token-saving idea in that article was not really a workflow. It was the map. I did not explain that well enough at the time.

I do not mean one giant MAP.md at the root of every project. I mean a small navigation system: a root map that identifies the major areas of a repository, then shorter maps inside those areas when they need another level of detail. Like zooming in and out on a geographic map, an agent can move from the project boundary to the subsystem it needs without treating every file as equally relevant.

Each MAP.md is deliberately short. It indexes the files and narrower areas below it, with one-line explanations of what they do. That makes navigation intentional: before searching blindly through a codebase, the agent has a useful path toward the code that matters. It also makes returning to an old project less expensive for humans. Flowmap is a project I built with this kind of map structure if you want a concrete example.

The workflow around it turned out to be about a different question:

How much do I need to understand about what the agent is doing?

That question changes from project to project. Sometimes I only care that a small tool works. Sometimes I am building something I expect to maintain for years and want to be able to explain every important architectural choice. Sometimes I am working with other people, and the work needs to remain legible even to someone who was not in the original agent conversation.

Those situations do not deserve the same process.

Three pressures, not one correct workflow #

I now think about agent-assisted development as a balance between three pressures: velocity, comprehension debt, and teamwork.

Velocity is straightforward. Agents are very good at helping us move from an idea to a working result. For a short-lived experiment, spending a day on documentation before asking an agent to write the first line of code can be the wrong trade-off. The point might be to learn whether the idea is useful, not to create a system that survives indefinitely.

Comprehension debt is the cost of moving faster than you understand. It is not always a mistake. You can choose to take it on deliberately. But it shows up later when you need to change a feature, investigate a failure, judge whether an agent’s proposal is safe, or remember why a strange piece of code exists.

With a coding agent, that debt can grow quietly. The code works, so the next prompt begins. The reasons behind a decision remain in a conversation that is no longer open. A later agent can read the code, but it cannot recover every rejected alternative or product constraint from the diff.

Teamwork adds another dimension. A choice that is acceptable knowledge debt for one developer becomes a coordination problem when a teammate has to review it, build on it, or take ownership of it. More people and more parallel work make durable intent more valuable.

None of these pressures always wins. The useful question is not, “What is the best agent workflow?” It is, “What does this project need me and the people around it to retain?”

When I just want the result #

Some projects are allowed to be fast and disposable.

Maybe I am building a small internal script, exploring a product idea, or making a personal tool whose value is entirely in the outcome. I want to describe the result, let the agent inspect the repository, then use its normal plan/build loop and iterate. I might keep a simple project instruction file and a map if the codebase starts growing. Otherwise, I do not need a planning ritual.

This is vibe coding in the useful sense of the phrase: I am guiding the work toward an outcome without requiring myself to own every implementation detail immediately.

There is nothing irresponsible about that. The mistake is pretending that the trade-off does not exist. If that tiny experiment becomes a product, I will eventually need to pay down some of the comprehension debt before I ask people to depend on it. The right answer at the beginning can still be to go fast.

When I need to understand the work #

Other projects ask something very different of me.

If I expect to maintain a system, make architectural decisions, or be accountable for its reliability, I want the agent to be fast and inspectable. Before implementation, I want to see what behavior is being changed, what is explicitly out of scope, what evidence will prove it works, and what risks the tests are meant to protect.

That creates an upfront cognitive load. Writing a task contract, reviewing a technical design, or reading a proposed test plan is slower than saying “build this.” But it creates a place where I can challenge assumptions while changes are still cheap. It also leaves behind something more useful than a completed chat: a clear explanation of what we intended to do and why.

This is where task planning, independent review, and maps earn their place. A task is a short-lived implementation contract grounded in the code as it exists today. A map helps the agent and me navigate the code that contract touches. A fresh reviewer can compare the result against the intent instead of asking only whether a diff feels reasonable.

The goal is not to make the agent more capable. A capable agent can often build a feature with very little ceremony. The goal is to keep my understanding proportional to the responsibility I have for the result.

When the work belongs to a team #

The shape changes again when other people need to participate.

I introduced the earlier version of this approach to teammates who were less familiar with agentic coding. That forced me to explain a distinction I had mostly made for myself: not every decision should be recorded at the same level or at the same time.

Some decisions have a long life. Product requirements and Technical Design Documents (TDDs) preserve direction that should guide several future pieces of work. They help a team agree on users, constraints, interfaces, and trade-offs before individual tasks appear.

Other decisions have a short life. A concrete task plan should be created close to implementation, because its file touchpoints and technical details can go stale as other work lands. For a larger initiative, it is often better to retain the outcome and a high-level sequence, then plan each child task just before it is built.

This matters even more with parallel work. A roadmap can say what outcomes matter and how they relate. A durable product requirement or TDD can explain why. A current task can translate that direction into the next change against the code that actually exists. Each artifact answers a different question, so none of them needs to become a giant permanent specification.

The benefit is not bureaucracy. It is that a teammate can inspect the work without reconstructing its purpose from a long agent transcript. Review becomes easier to trust, handoffs become less fragile, and people can decide how much autonomy they are comfortable giving an agent without losing the ability to steer it.

Why I stopped looking for the perfect workflow #

While exploring agent workflows, I read repositories with large, detailed READMEs and strong philosophies about how work should proceed. They often made sense on their own terms. But I kept feeling that they had already decided the answer to the question above.

They assumed a fixed amount of structure: a particular specification format, a particular order of planning, and a particular amount of ceremony before implementation. I did not want to bring that whole answer to every project.

I wanted a project to be able to start small—perhaps with only normal plan/build behavior and a map—and become more deliberate only when the work earns it. I wanted planning and review without requiring every project to keep an initiative hierarchy. I wanted durable product and technical documents when a team needed shared direction, without pretending a weekend experiment needed them too.

That is why I renamed the project I originally called GT Workflow to GT Weave.

“Workflow” suggested that the repository contained one prescribed path. It does not. GT Weave is a setup kit for shaping project-owned agent skills, instructions, maps, and planning artifacts around a project. The host agent remains responsible for inspecting, planning, implementing, and testing. GT Weave helps decide which pieces of context and structure should survive the conversation.

The name “weave” better reflects the job: combine only the threads that make the project easier to understand, steer, review, and continue.

Structure should earn its place #

There is a real cost to asking an agent to wait while we write documents. There is also a real cost to accumulating code and decisions that nobody can confidently explain.

The answer is not to always optimize for speed, and it is not to always optimize for documentation. It is to make the trade-off visible.

For one project, the honest answer may be: “I only need a result, and I am happy to accept the debt.” For another: “I need to understand and validate every important choice before the agent commits to it.” For a team: “We need enough shared context that work can outlive the person and conversation that started it.”

Start with the smallest amount of structure that makes that answer true. Add more only when it solves a problem you can name.

If that is the problem you are trying to solve, GT Weave is my reference implementation—not a process you have to adopt, but a set of ideas and optional capabilities to adapt to your own project.

For the earlier, narrower point about maps and agent context, read my post on reducing token usage.