Who guides the work

The first question in a software factory is who decides what it should build. This is what I call the direction flow: deciding what the factory should work on and giving it the go-ahead.

Organizations build software for two kinds of users: customers (external-facing products) and employees (internal-facing operational tools). Each of these has needs, constraints and priorities that are based on their jobs to be done. A model can inspect the repository and find defects and even recommend improvements based on what it has seen elsewhere, but it cannot decide that one customer segment matters more than another, the flow that will give the user "joy", that a legal risk is tolerable, or that a feature advances the company’s strategy. A factory that chooses its own work from whatever is easiest to detect will optimize aspects that its training data favors rather than the business around it. Any AI slop it introduces has a way of compounding, and you'll be left with a product or tool that no one can use.

A factory left to choose its own work can produce a large volume of software that it believes addresses pressing matters. But is it producing the most valuable software?

Structural work (tests, build systems, security, maintenance and shared components) is often what makes features possible, so both are useful. But the software doesn't yet quantify the impact of either, and there should be a way to. Ideally, a feature should drive evidence (e.g. dashboards) that its intended user can accomplish the task; later, adoption or customer outcomes can show whether it mattered. Structural work should also drive observable metrics: a test that rejects a known failure, a measured reduction in drift, a repaired exposure or a reliable deployment.

An insight here is that limiting every task to something a person has already noticed would waste one of the strongest properties of agentic engineering. Agents can scan for deviations from security best practices, compare implementations to fix inconsistencies, inspect repeated failures, find missing tests and identify patterns across repositories.¹² They can discover work that a team would otherwise postpone indefinitely.

Both people and agents should therefore be able to propose work, with evidence, and the team remains responsible for choosing the policies for what enters the plan.

Before anything is built, the factory needs to clarify the request and save enough detail to pick up the work later without waiting for you to sit in front of the machine and answer its questions. A raw operator request is rarely ready for implementation. “Add team accounts” leaves open the identity model, permissions, migration, billing behavior, invitation flow and dozens of failure cases. “Fix the security warning” may be trivial once you provide the image and the typo in it is self-evident, or it may require a database migration and compatibility work across several services. At worst it's a one-sentence idea; at best it states the problem, the outcome, the constraints and the evidence that would show it's done.

Before the factory builds anything, the person and the agent need to agree on what it should build. For example, a one-off request may be specific enough that it could be a surgical fix, but it may have ramifications (e.g. creating an inconsistent component). A longer specification doesn't necessarily mean clearer instructions for the agent. What matters is that they agree on the problem, the intended outcome, the constraints and the evidence that would show the change works, with enough detail for the factory to act on it.

A useful work item should contain:

• the problem and why it is worth solving;
• the users or systems affected;
• the desired behavior and explicit non-goals;
• constraints, including compatibility, privacy, security and operations;
• relevant architecture and design decisions;
• dependencies on other repositories or services;
• a definition of done expressed as observable outcomes;
• open questions and the person responsible for resolving them.

This is a form of spec-first development: save enough of the conversation that the intent survives the conversation.³ It does not require a blueprint that predicts the implementation or stays synchronized with every function. It creates a reviewable record of what was meant, next to the evidence of what was built.

Spec-driven tools tend to follow a sequence: write down what should be built, make a plan, divide it into tasks and implement them.⁴⁵⁶ Their central insight is sound. One thing to note is that the process can generate more Markdown than anyone reads. Often the intent specification includes specific code that needs to be changed along with the target code itself. A document written before implementation may be incomplete, and a detailed implementation plan may become false as soon as the agent learns something from the code. In many cases, coding agents still find new inconsistencies when they actually build, making them reconsider their original plan or roll back their proposal.

I would like these to be at the level that you'd have on the whiteboard if you were to have a discussion with a peer. The team and the agent work through enough detail to make the important structure visible. They agree on the user’s journey, the system boundaries, the important services and data, the risks and the conditions for done. They do not try to predict every line of implementation or every test to be written. Guidance remains. Once someone else could reasonably build from what is on the board, the agent can start.

This keeps two kinds of decision separate. Product and risk decisions should be settled early: who the user is, what behavior is wanted, what must not break, and whether a migration or other hard-to-reverse action is acceptable. Implementation decisions can remain open. Exact function boundaries, test arrangements and library calls are often better decided after the repository has been explored.

If a plan stays only in the session where it was discussed, an agent returning to the work later cannot reliably recover what was agreed. A reviewer may also struggle to compare what was built with what was requested. Later, an audit can show that the code changed, but not necessarily why someone gave the go-ahead.

Work can reach the factory from many sources. Accepting all of them is the easy half of the problem; choosing among them is the hard half, and it is where my factory fell short. In a conventional product organization, product managers translate customer and market signals into priorities. Engineering contributes reliability, scalability and maintenance work. Security teams raise vulnerabilities. Quality and operations teams contribute test, infrastructure and deployment work. Internal software may be directed by IT or operational leaders. In a small company, the same decisions may happen in a chat channel rather than a formal tracker.

The factory should accept work from all of these sources. Each work item should have an attribute that records the type or kind of source it came from. A customer request, a compliance obligation and a refactor may need approval from different people or policies, have different deadlines and require different evidence to justify the work.

The factory itself becomes another source. Dependency tools have identified upgrades for years, but an agent working inside a repository can go further. It can find a security flaw while implementing a feature, notice that several services have copied the same broken assumption, or discover that a shared component lacks an interaction state required by the design. Production diagnosis can connect an incident to a code path. Review can expose a recurring weakness in tests or architecture. These findings are valuable because they arise while the agent has unusually rich local context.

Finding a problem outside the current task doesn't mean the agent should immediately fix it. When an agent finds a problem outside its current task, it should record a new work item, attach the evidence and route it to the place that owns the decision. The owner may be a product manager, a security policy, a shared-service team or the maintainer of the local repository. The finding may become a local task, a message to another team or a rule broadcast across the fleet. It should not become an opportunistic edit to someone else’s code merely because the agent is capable of making it.

The rule in my factory is simple: agents may propose work; I determine whether it enters the plan. The data show that the first half of this rule works better than the second. The agents notice, file and often finish problems. But then every proposed item waits for me, whether it is important or not. That gate costs my attention but filters little: I approved most plans by default, and 85 percent of discovered items shipped. The factory does not yet have a strong enough step for ranking the resulting queue and holding some of it back, and that is the case for a prioritization step.

As discovery improves the bottleneck becomes more critical (or as Claude would like to call it 'load-bearing'). Builders do not become tired when the queue grows, but the people responsible for deciding what is worth building do. A limit on open items per repository would force an explicit choice.⁸⁹ A stricter policy could remove the least valuable items rather than allowing every plausible improvement to wait indefinitely. Either would make the cost of discovery visible at the point where the factory still has the option not to build.

Items that touch the same code should be planned together. Backlogs encourage work to be treated as independent but the code may be closely related. Several tasks may touch the same subsystem, require the same migration or need to ship together. Handling them in separate sessions repeatedly reloads the same context, produces conflicting edits and creates extra deployments.

My factory groups related work items into a goal. A goal is a deployable unit of intent: a coherent set of changes that can be planned, built and validated together. Before implementation, a planning skill questions me one prompt at a time until the purpose, boundaries and risks are clear.¹⁰ The resulting plan names the work items, their dependencies and the evidence required for each part of the definition of done (Diagram 2.1).

The plan does not prescribe every test. It says how success will be tested. “The migration preserves all existing memberships and can be rolled back” is a durable condition. “Write a test in this file using these three mocks” is an implementation guess that may be wrong before the repository has been explored.

Goals make the unit of planning the unit of shipping. Related changes can share context, review and deployment. Unfinished work also becomes easier to see: a goal is not complete because code was written; it is complete when its defined outcomes have been demonstrated.

A budget attached to a goal only means something when it counts what the plan counts. If the plan counts features or change sets, the budget should count features or change sets, not the commits used to save intermediate states. The next section asks what the person who marks an item ready actually does at that gate.

Putting a person at a decision point or gate does not by itself create control. The gate means whatever the person actually does there. For example, a person who over time accepts agent recommendations gets unknowingly trained to hit "yes" on every plan.

A bad line in a plan can produce hundreds of internally consistent lines of bad code.¹¹ It's easier to correct a bad plan before the agent builds on it than to fix the resulting code afterward. But requiring the same ceremony for every plan would recreate the permission-prompt problem at a higher level. If every small and reversible change demands close attention, attention becomes the bottleneck and eventually degrades into routine approval.¹²

There are two honest designs. One is to treat the ready mark as a quick authorization and rely primarily on checks after it. The other is to make it a substantive review for work that is large, sensitive or hard to reverse. In the absence of prioritization or impact analysis, the factory currently mixes the two in the same decision queue. The planning interview asks whether an item is a one-way door or materially impacts active customers, and the build stops before executing an item marked that way, but nothing requires a more careful reading at the moment the plan is approved. Much of the work still begins from a one-off instruction with no saved plan, so the clarifying happens inside the session instead, and that keeps me at the keyboard longer, answering the agent's questions. Longer interviews or more questions mean more potential for a human bottleneck.

The better answer is to name the decisions that require human judgment and make the system route those decisions deliberately. An update that changes a public contract, a data migration, a change to permissions, irreversible data loss or movement of money should not depend on whether the agent happened to ask a good question. Those properties should be recognizable in the plan and, where possible, in the change itself.

Discussions of agent trust often collapse into a personal question: do you read the code the agent writes? That is too narrow. Trust is the amount of consequence the system permits without human oversight. Let's look at how that works in my factory.

At one end of the field, people write scenarios and agents build until the scenarios pass; humans may review architecture but not individual lines.¹³ At the other end, a person reviews and merges every pull request.¹⁴ Both arrangements can be rational. The correct level depends on the quality of the checks, the reversibility of the change, the sensitivity of the system and the organization’s ability to observe production.

Permission prompts are a poor substitute for this design.¹⁵ An agent in this study stopped to ask roughly three times per working hour, while I refused 0.75 tool calls per hour. Neither rate fell during the 38 days measured, although incomplete logging means those figures should be treated cautiously (evidence). If an agent repeatedly presents a person with low-context questions, the person will approve most of them. Safety then depends on attention at precisely the moment the process has trained attention away.

It is better to put controls in layers: limit the files and network the agent can reach, make dangerous operations structurally unavailable, run deterministic checks, use independent review, and reserve human approval for decisions with material consequences.¹⁶¹⁷ With agentic engineering we can be more thoughtful about where that boundary is. A dependency's version number alone should not decide whether a person must review the upgrade. An agent can update interfaces from the documentation and verify behavior; changes that affect permissions, public contracts, data or other material consequences still need the deliberate judgment described above.

“Reviewed” is not a sufficient description of the control. A review has to say who or what performed it, what evidence it considered and whether it was independent of the builder. When agents do the reviewing, review may still catch mistakes, but the person stops learning what changed.¹⁸ That understanding has to come from somewhere else (a plan, a concise change summary or a consequence-based review) or it quietly disappears.

Across prompts, reviews and security findings (Chapter Five takes up the security checks), the same gap appears: the factory records that a control ran, but not who or what performed it or how independent it was, and that is what trust depends on.

Between an item becoming ready and its merge, the largest share of the time passed outside any session. Once a ready item begins, the build is usually short. A work item shipped in a median of one day, with 66 percent shipping within a day. The slow fifth became slower, however: the 80th percentile rose from 1.2 days in July to three days in September (evidence).

In a factory where agents do most of the building, the longest waits move toward the remaining human or externally triggered transitions. In mine, the largest of those was starting or resuming the session.

The factory needs a way to start authorized work without waiting for me to open a session. If a usage limit interrupts a goal, it should also be able to resume under the same authorization. Other software-factory designs use an external trigger to start work. That addresses a wait that faster code generation cannot reduce.¹⁹²⁰ Chapter Seven designs that trigger for my factory.

The direction flow I am building toward can now be stated more precisely; parts of it, such as routing and prioritization, don't exist in my factory yet. Signals may come from people, systems or agents. The factory converts them into work items with evidence. Operators would route each item to the person or policy capable of authorizing it. A prioritization step would choose which proposed items enter the plan and which remain deferred or are dropped. Related items become goals. A person and an agent clarify the intent, risks and definition of done. The factory is then authorized to execute within that boundary.

New information may change the method without stopping the work. Material changes in purpose, risk or scope return to the operator. Findings outside the boundary become proposals rather than opportunistic edits. Consequential changes receive controls appropriate to their reversibility, not the same generic approval as everything else. The record preserves the plan, the evidence, the actual reviewer and the source of discoveries.

This boundary prevents two opposite failures. The first is micromanagement, in which the agent requires a person to approve steps that the system could safely verify. The second is accidental strategy, in which the agent’s local judgment quietly becomes the organization’s priority.

The person guides the work by defining value and risk. The factory guides itself by selecting methods, checking progress and surfacing discoveries (Diagram 2.2). Neither role disappears. They become explicit.

The findings point to five changes, in order.

First, save the plan. Most work already traces to a decision, but too much of its intent lives only in the session where I typed it. Before implementation, the factory should create a lightweight work item that preserves the problem, outcome, constraints and evidence for completion. That way, an agent returning to the work later can see what was approved and why, and a reviewer can compare it with what was built.

Second, place a prioritization step between discovery and planning. Agents are good at noticing and filing work, and filed work is usually completed. The growing backlog shows why we also need to decide which of those items are worth doing. A limit on open work per repository would force selection; a stronger policy would periodically remove the least valuable proposals. The objective is to prevent whatever was easiest to notice from becoming the de facto roadmap.

Third, define what approval means. A routine, low-impact or reversible plan may need only a quick authorization followed by strong automated evidence. A one-way-door plan needs a careful read by someone who understands its consequences. It need not always be a critical change - it could be one that just needs buy-in. The system should record the distinction and make the latter gate real. It should also detect sensitive changes from the change itself, because a plan-based mark cannot protect work that never received a written plan.

Fourth, preserve provenance. Each discovered item should record what found it. Each review should record whether it was performed by a person, an independent agent or the builder operating under another identity. Each material scope change should point back to its authorization. Mistakes and decisions deserve their own fields in the log; before the factory introduced them, almost every entry described only what had been completed. In the seven days after the new categories appeared, agents recorded 379 mistakes and 38 decisions. If the factory is expected to learn from its own work, it has to ask for the evidence it wants to learn from.

Fifth, let authorized work start and resume without me. Human direction should determine what may happen, not provide the keystroke that awakens every session. A ready queue and a resumable goal would reduce the largest observed wait while preserving the same boundary of authority. As I like to tell my coding agent, "Let's F***ing go".

These changes do not remove the person from the flow. Instead of just saying that a person must be involved, they spell out which decisions need a person, what evidence must be kept and how much the factory can do on its own given the consequences.

The charts behind this chapter, including those the text does not discuss, are collected in the Evidence appendix at the end of the book.

Much of my work leaves no trace. Reading a plan produces no event, and ready marks carry a date rather than a timestamp, so the data cannot say how much attention a plan received before approval. The count of my approval gates is a floor: goals initiated in a session were not consistently linked to their work items, permission mode was not recorded, interruptions preserve a marker but not a reason, and approved tool calls were not logged.

Session logs cover late August to the 1st of October (38 days), plus one session in early August, so claims about pull-request time and session behavior describe only that window. The .plans folders record days, not hours, and edits to a plan leave no history. Lead time cannot be measured more finely than a day, and scope added by rewriting an existing item is invisible.

The feature-versus-structure analysis assigns a single label to each change set. The fall in feature share coincided with changes in planning and workflow, but the data do not establish that those changes caused it. The work mix also reflects my choice to study hardening and autonomy, alongside changes in repositories and models. Nor can repository history say how far a leaked credential reaches, what is open to the internet, or how quickly a revoked credential becomes unusable. Those questions require live-system evidence.

Most importantly, the data cannot yet tell whether accepting an agent’s recommendation after a quick read caused a later mistake. The recommendation, approval and correction records are not linked strongly enough to establish that chain. Recommendation uptake is therefore a measure of reliance, not a measure of justified trust.