Spec-Driven Agent Workflows: GitHub Spec Kit, gstack, and the New Handoff Layer

Spec-driven development is having another developer-tool moment.

GitHub's Spec Kit is now a huge public repo with a dedicated docs site, a specify CLI, slash commands, templates, extensions, presets, bundles, and integrations for more than 30 coding agents. Garry Tan's gstack is getting Hacker News attention for a more personal version of the same instinct: turn a Claude Code setup into named roles, slash commands, memory, issue handoff, review, QA, and shipping routines.

The overlap is more important than either project by itself.

Developers are discovering that the bottleneck in agentic coding is no longer "can the model write files?" It is "can the team preserve intent across planning, implementation, review, retry, and handoff?"

That is why the durable topic is not only GitHub Spec Kit or gstack. It is specs as the handoff layer for coding agents.

Last updated: July 17, 2026. Google Trends was checked for GitHub Spec Kit, spec driven development, AI coding agent, Claude Code, and gstack in the US over the past three months. Claude Code averaged 64.1, AI coding agent averaged 4.0, gstack averaged 0.6, spec driven development averaged 0.4, and GitHub Spec Kit averaged 0.1. That points to durable demand around Claude Code and AI coding agents, with exact tool names still behaving like launch chatter.

What Spec Kit Actually Adds#

Spec Kit is an open-source toolkit for spec-driven development. Its README frames the shift directly: specifications stop being disposable scaffolding and become executable inputs that generate implementation work.

The workflow is intentionally staged:

1. Create or update project principles with /speckit.constitution.
2. Define what to build with /speckit.specify.
3. Create a technical implementation plan with /speckit.plan.
4. Generate tasks with /speckit.tasks.
5. Execute with /speckit.implement.
6. Reconcile drift with /speckit.converge.

That structure matters because it turns a prompt into artifacts the next agent can inspect. The spec is not only a conversation turn. The plan is not only transient reasoning. The task list is not only a model's private outline.

This is the same design pressure behind Kiro's spec-driven IDE, but Spec Kit is more portable. It is not trying to replace your editor. It is trying to make the work legible to Copilot, Claude Code, Cursor, Codex CLI, Gemini CLI, Qwen Code, opencode, and other agent surfaces.

The useful pattern is not the exact command names. The useful pattern is phase separation.

Why gstack Hit The Same Nerve#

gstack comes from a different direction. It packages an opinionated Claude Code setup into roles and commands such as spec authoring, planning, review, QA, release management, docs, memory, and context save.

The Hacker News thread around Garry Tan's setup is useful because the reaction was not only "cool prompt pack." Developers were debating whether these systems are practical workflow infrastructure or influencer-shaped ceremony.

That skepticism is healthy.

A skill pack that only names roles can become theater. A spec workflow that only produces markdown can become paperwork. Neither helps if the agent still skips verification, loses context, or ships a diff nobody can review.

But the shared idea is sound: coding agents need externalized process.

That puts gstack in the same family as the broader skills wave we covered in Skills Are the New Agent Operating System and Why Skills Beat Prompts for Coding Agents. The good versions do not make the model magical. They make the boring workflow steps harder to skip.

The Real Unit Is The Handoff#

The important question is not "should I use Spec Kit or gstack?"

The better question is: what has to survive the handoff?

A serious agent workflow has many handoffs:

• user intent to first planning agent
• planning agent to implementation agent
• implementation agent to test runner
• test result to repair agent
• repair agent to reviewer
• reviewer to merge process
• merge process to deployment verification
• current session to tomorrow's session

If those handoffs live only inside one chat transcript, the workflow is fragile. If they live in durable specs, plans, task lists, logs, memory notes, issues, and PR receipts, the workflow can recover.

That is the connection to Long-Running Agents Need Harnesses, Not Hope. A harness is the runtime around the model. A spec is the contract the harness can carry from step to step.

Without the contract, a harness only knows that "the agent is working." With the contract, it can ask better questions:

• Did the implementation satisfy the original user story?
• Did the task list cover every requirement?
• Did the reviewer challenge the same acceptance criteria?
• Did the final PR include proof for the claims in the spec?
• Did a later agent change scope without recording why?

That is the difference between agent work that feels impressive and agent work that can be operated.

Specs Beat Prompt Threads For Review#

Prompt threads are terrible review artifacts.

They contain the user's goal, the model's reasoning, tool logs, failed attempts, corrections, and final claims in one long stream. The important pieces are mixed with noise. A reviewer has to reconstruct intent from the whole conversation.

Specs are better because they compress the review surface.

A good spec says:

• problem
• users
• non-goals
• requirements
• acceptance criteria
• constraints
• risks
• open questions
• verification plan

That gives reviewers something concrete to challenge before code exists. It also gives later agents a smaller, cleaner input than "read this 40,000 token chat and infer what mattered."

This is especially valuable when you run agent teams and subagents. Parallel agents are fast, but they amplify drift. A spec turns parallelism into coordinated work instead of five agents optimizing five interpretations of the same vague prompt.

The Failure Mode: Spec Cargo Culting#

There is a bad version of this trend.

It looks like:

• every task gets a huge spec
• the spec repeats obvious implementation details
• the agent writes requirements after it already knows the answer
• task lists are generated but never checked off against real tests
• markdown is treated as proof
• nobody deletes stale assumptions

That is not spec-driven development. That is documentation cosplay.

The fix is to make specs executable in the practical sense, not the marketing sense.

A spec should drive a check. If the spec says uploads must preserve EXIF metadata, there should be a test or manual verification step for EXIF metadata. If the spec says the page works on mobile, there should be a mobile screenshot or Playwright check. If the spec says the API is idempotent, there should be a retry demonstration.

This is why agent swarms need receipts. The spec names the promise. The receipt proves whether the promise held.

A Practical Spec Template For Coding Agents#

You do not need to adopt a full framework to get most of the value.

Start with a small project-local template:

# Feature Spec

## Goal
What user-visible outcome should exist when this is done?

## Non-goals
What should the agent avoid changing?

## User stories
- As a ...
- I want ...
- So that ...

## Acceptance criteria
- [ ] Observable behavior one
- [ ] Observable behavior two
- [ ] Failure state or edge case

## Constraints
- Files or modules in scope
- Design system rules
- API compatibility requirements
- Security or privacy boundaries

## Verification
- Command:
- Browser route:
- API probe:
- Screenshot:

## Handoff
- Branch or PR:
- Remaining risks:
- Follow-up tasks:

Then require the agent to update the checklist as it works. The goal is not perfect requirements engineering. The goal is to give the next agent and the human reviewer a stable object to inspect.

If a workflow keeps repeating, promote it into a skill. If a workflow crosses tools, put it in the harness. If a workflow is specific to one feature, keep it as a local spec.

That division keeps the system from turning into one giant prompt again.

When To Use Spec Kit#

Spec Kit is worth testing when:

• multiple agents or tools touch the same feature
• requirements are ambiguous
• review cost is high
• implementation spans more than one session
• you need traceable decisions
• you want a provider-neutral workflow across Copilot, Claude Code, Cursor, Codex, or opencode

It is probably too much for:

• one-file fixes
• quick experiments
• throwaway prototypes
• tasks where the acceptance criteria are already obvious

The strongest fit is not "I want AI to code faster." The strongest fit is "I need AI coding work to survive handoff."

When gstack Is The Better Reference#

gstack is useful as a reference when your real problem is role design.

Spec Kit is about the spec lifecycle. gstack is more about packaging an opinionated operating model: product thinking, engineering management, design review, QA, docs, release, memory, and context transfer.

Study it for the shape of reusable roles, not as a set of universal truths. Your team's designer checklist, QA routine, and release gate should be local. A YC founder's workflow can inspire yours, but it should not become your production policy by copy-paste.

The same warning applies to any public skill pack: inspect it like code, pin it if you depend on it, and keep project-specific behavior project-local.

The Takeaway#

Spec-driven agent workflows are not a return to waterfall.

They are a response to a specific agent failure mode: vague intent goes into a long-running system, many tools and subagents transform it, and nobody can later explain whether the final diff still matches the original goal.

GitHub Spec Kit, gstack, Kiro, and the wider skills ecosystem are all circling the same answer.

The future of coding agents is not just better code generation. It is better handoff artifacts.

When the spec, plan, tasks, checks, and receipts are durable, agents become easier to review, resume, parallelize, and trust. When they are not, every session starts as a fresh act of interpretation.

That is the part worth adopting now.

FAQ#

What is GitHub Spec Kit?#

GitHub Spec Kit is an open-source toolkit for spec-driven development. It provides a specify CLI, templates, slash commands, skills-mode support, extensions, presets, bundles, and integrations for many AI coding agents.

Is spec-driven development just waterfall?#

No. The useful version is lightweight and iterative. It creates enough durable intent for agents and humans to coordinate, then updates the spec as the work changes. The bad version becomes slow paperwork.

How is gstack different from Spec Kit?#

Spec Kit focuses on the spec lifecycle: constitution, specification, plan, tasks, implementation, and convergence. gstack is an opinionated Claude Code setup with roles and commands for product, engineering, design, QA, docs, memory, and shipping.

Should every AI coding task start with a spec?#

No. Use specs when handoff, ambiguity, review cost, or multi-agent coordination matters. For obvious one-file fixes, a short task contract and verification command may be enough.

Why do specs help coding agents?#

Specs externalize intent. They give the agent a stable contract, give reviewers something concrete to challenge, and give future sessions a durable handoff artifact instead of a long prompt thread.

Sources#

• GitHub Spec Kit repository, accessed July 17, 2026.
• GitHub Spec Kit documentation, accessed July 17, 2026.
• gstack repository, accessed July 17, 2026.
• gstack skills documentation, accessed July 17, 2026.
• Hacker News: Garry Tan's Claude Code Setup, accessed July 17, 2026.
• Hacker News: Get Shit Done spec-driven dev system, accessed July 17, 2026.
• Hugging Face Papers monthly page for July 2026, accessed July 17, 2026.