AL+

RO EN

Email us

The AI coding agent workflow: the spec is the work

Copilot Workspace put the plan before the diff in 2024. Two years on, coding agents pay off where the spec and its review are treated as the engineering work.

. By . AI and agentic engineering

Citiți articolul în română

When GitHub opened the technical preview of Copilot Workspace on 29 April 2024, most of the attention went to the claim that you could go from an issue to a pull request in plain English. The more durable idea was the order of the screens. Workspace put a written specification and a plan in front of the developer before it wrote any code, and asked for them to be edited and accepted first.

Two and a half years on, that order is the part worth keeping. The teams that get real value from coding agents treat the written specification, and the review of it, as the engineering work. The generated code is the cheap part. A supplier who cannot show you who approved the plan before the agent started is not running a review process, whatever the pull request looks like at the end.

What Workspace actually proposed

GitHub's launch post (29 April 2024) described a task-centric flow that starts from a repository or an issue. Workspace then proposed "a step-by-step plan to solve the issue", made everything "from the plan to the code" editable, and ended with the familiar steps: file the pull request, run GitHub Actions and code scanning, ask colleagues for human review.

The GitHub Next team explained the structure in more detail in the Hacker News thread the same day. The spec had "current" bullet points, the agent's understanding of the system today, and "proposed" bullet points, what should be true after the change. The plan sat between the two. Each could be edited to correct the agent before it touched a file. The same comment made the point this article builds on: "A well-specified issue is as important to other humans as it is to AI. And 'well-specified' is not about 'more', it's about clarity."

What the first users found

The early reports were mixed, and the pattern in them matters more than the verdict. Austin Henley, who had worked with GitHub Next, wrote up a few days of use (29 April 2024). His summary: "The generated plan is usually good." The code was another matter. He reported that it was slow, that the generated code was "often buggy or has nothing to do with the specification", and that he would only use code from 2 of his 12 sessions.

Read that with hindsight and the plan was already the most reliable output of the system. The models of the time could often describe the right change and then fail to make it. The plan was where a human could add the most value for the least effort.

What survived

Workspace itself did not. GitHub Next concluded the technical preview on 30 May 2025 and pointed users to VS Code's agent mode and the new Copilot coding agent, saying plainly that these were "not a 1:1 match" for what Workspace did.

The coding agent announcement (19 May 2025) moved the starting point back to the issue: you assign an issue to Copilot, it works in the background and pushes to a draft pull request. The in-browser plan editor was gone, which makes the issue text the specification. The same post built the second gate into the defaults: the developer who asks the agent for a pull request cannot be the one who approves it, and Actions workflows do not run without approval. GitHub also stated where it expected the agent to do well: "low-to-medium complexity tasks in well-tested codebases".

By September 2025 GitHub was publishing Spec Kit (2 September 2025), an open source toolkit that splits the work into specify, plan, tasks and implement, with a checkpoint after each. Its diagnosis of failed agent work is that the problem is "our approach", not the agent's coding ability, and that agents behave like "literal-minded pair programmers".

Taken in order, these events suggest that the editable plan screen was a product experiment that ended, and the plan-before-code discipline moved into the issue, the repository and the team's process. That is where it belongs, because it is a decision about the work, not a feature of one tool.

Two distinct review questions

For consequential agent-written changes, I recommend separate plan and implementation checks. They answer different questions; the same lead can perform both if they are independent of the implementation and the requester.

Plan approval asks whether this is the right change. Does the spec describe the system as it is today? Does the proposed state match what the business needs? Are the edge cases named? The owner is whoever understands the domain and the system: often a technical lead, sometimes a product owner with an engineer beside them.

Pull request review asks whether the change is correct and safe. Does the code do what the approved spec says, and nothing else? Do the tests cover the new behaviour? Is anything touched that should not be? The owner is a reviewer who did not request the change. GitHub's default rule, where the requester cannot approve, encodes this.

Merging the two gates is the common failure. When the only review happens at the pull request, the reviewer has to reconstruct the intent from the diff. A weak issue such as "add discounts to checkout" then produces a confident pull request that compiles, passes the tests it wrote for itself, and implements one of several reasonable meanings of "discount". The review catches style problems and misses that the wrong thing was built. A clear issue names the rule (which customers, which products, whether discounts stack, what happens on refund) and what success looks like. Writing that is the engineering work. It is also the part a client can read.

The strongest objection

Henley's critique is the best case against spec-first agent work, and it still holds in part. He argued that the one-shot flow "skips all of the steps where I really dig into the code and build a mental model of how it works", and that the right design is iterative: express the task, refine the plan, choose changes, verify, repeat. On this view a large upfront spec is waterfall with a new name, and the understanding that makes a spec good only comes from working in the code.

He is right that the spec cannot be written in isolation or frozen. Spec Kit calls specifications "living" artifacts for the same reason. But iteration is an argument about how the spec gets written, not about whether it gets reviewed before code is generated. The cheap loop is to revise a paragraph. The expensive loop is to review a 600-line diff built on a misunderstanding.

Where this does not hold

Spec-first is the wrong tool in some places, and saying so is part of the argument.

  • Investigation. When you do not yet know why a bug happens, there is nothing to specify. The work is diagnosis, and an agent is a research assistant at best.
  • Throwaway prototypes. If the code exists to answer a design question and will be deleted, a formal spec costs more than it saves.
  • Codebases without tests. GitHub's own claim was for well-tested codebases. Without tests, the pull request gate has nothing mechanical to lean on, and an approved plan does not make an unverifiable change safe. Fix that first.
  • Small, obvious changes. A typo or a version bump does not need a plan review. The discipline scales with the cost of being wrong.

A test for anyone buying software built with agents

If a supplier tells you they use coding agents, ask to see one recent change from end to end: the issue or spec as approved, who approved it, the pull request it produced, who reviewed that, and which tests ran. Ask whether intent was checked before implementation and whether the code reviewer was independent of the implementation and the requester. The same lead may approve the plan and review the pull request; two different names alone do not establish independence. This is the practical form of a point we made earlier: AI-built software still needs an engineer who answers for it.

Copilot Workspace was right about the order of the screens. Agents have become far better at writing code since 2024, and that makes the spec and its review more important, because they are now the part that decides whether the code is worth anything.

Sources