Spec Kit with your team, from ticket to acceptance
GitHub Spec Kit run by your team. Product owner and manager approve the spec, the architect the plan, a developer the code, QA the result. Each step waits for its role.
Spec Kit gives coding agents a method: specify, plan, break into tasks, implement. It names who should look at each document, but nothing stops an agent, or a hurried teammate, from going straight to the code. This workflow runs Spec Kit with roles: each phase is confided to the people who own it, they are notified when it is their turn, and only they can move it forward (or a workspace owner or admin in their place, and the timeline says so).
How it works
- Specify. An agent turns the ticket into a Spec Kit specification (user stories, acceptance criteria, open questions) and copies it into Memory, where people without a terminal can read it.
- Product owner and product manager, in parallel, approve the spec or request changes: the agent rewrites it with their comments, until both approve.
- Architect. An interactive step: the agent drafts the technical plan with Spec Kit, then works it through with the architect in a terminal tab of SideHub. The architect validates the plan.
- Developer. The agent breaks the plan into tasks, checks them against the spec and implements them. The developer reviews the diff in To review, and asks for a fix if needed.
- Acceptance check. An agent compares the code with every acceptance criterion and runs the tests. A missing criterion sends the work back to step 4, three rounds at most.
- QA signs off on the acceptance report, or requests changes, which go back through the check and the code.
Nothing is pushed before the developer approved the work: once approved, the commits show up in To push.
Roles
- po (Product owner) and pm (Product manager): approve the specification.
- architect (Architect or tech lead): shapes and validates the technical plan in a terminal, so a member of the workspace (not a collaborator).
- dev (Developer): reviews the code the agent wrote.
- qa (QA): signs off on the acceptance report.
Give each role its default holders in the workflow after the import. At each launch you can change them for this ticket only.
What you need
- An agent connected to the repository's machine, with Claude Code logged in (the reference CLI for the interactive step).
- For the Spec Kit method, uv on that machine: the first run initializes Spec Kit in
the repository (
specify init), and that change goes through To review like the rest. Choose thesidehubmethod to follow the same phases without Spec Kit. - The people who hold the roles, invited to the workspace.
Steps
1. Specify the ticket
Turn this ticket into a specification, in the git repository of the current directory. The method chosen for this run is `{{inputs.method}}`. {{inputs.ticket}} 1. Record the current commit before touching anything: `git rev-parse HEAD` (write `none` if the repository has no commit yet). 2. Read the project's conventions: CLAUDE.md, AGENTS.md, CONTRIBUTING.md and the README. 3. With the method `spec-kit`: if the repository has no `.specify/` folder yet, initialize GitHub Spec Kit with `uvx --from git+https://github.com/github/spec-kit.git specify init --here --force --integration claude --script sh` (versions before 1.3 name the option `--ai`; if an option is refused, read `specify init --help`). Commit the files it adds on their own, with a message saying Spec Kit was initialized. Then follow the instructions of Spec Kit's `speckit.specify` command (its file is in `.claude/commands/`, or under `.specify/`) with the ticket above as its argument. Let Spec Kit create its feature branch and its `specs/` folder: the next steps work on that branch. 4. With the method `sidehub`: create a branch named after the ticket, then write `specs/<short-name>/spec.md` with the same sections as a Spec Kit specification: summary, user stories with priorities, functional requirements, acceptance criteria written so they can be checked one by one, and open questions marked `[NEEDS CLARIFICATION]`. 5. Do not design the technical solution and do not write code: this step only says what to build and why. 6. Commit the specification on the branch. Never push. If your input contains comments from the product owner or the product manager, they asked for changes: apply each one to the specification, answer the open questions they settled, and list what you changed at the top of your output. Write the whole specification as your output, followed by its path in the repository and the branch, so that the product owner and the product manager can read it without opening the repository. Complete the step with `--value base=<the commit recorded in step 1>`.2. Product owner: is the spec ready? (human approval)
Check the need, the user stories and the acceptance criteria: are they right, complete and testable? Approve, or request changes with your comments: the agent rewrites the specification.
3. Product manager: is the spec ready? (human approval)
Check the scope and the priorities: is this the right thing to build now, and is anything missing or too much? Approve, or request changes with your comments.
4. Technical plan with the architect (interactive, with you in the terminal)
You prepare the technical plan of the specification in your input, then work it through with the architect who holds this step, live in this terminal. The method chosen for this run is `{{inputs.method}}`. Stay on the branch of the specification. 1. Read the specification and the code it touches, and the project's conventions (CLAUDE.md, AGENTS.md, CONTRIBUTING.md). 2. With the method `spec-kit`: follow the instructions of Spec Kit's `speckit.plan` command (in `.claude/commands/` or under `.specify/`), which writes `plan.md` and its companions (research, data model, contracts) next to the specification. With the method `sidehub`: write `plan.md` next to `spec.md`, with the architecture, the components touched, the data model, the interfaces, the risks and the testing strategy. 3. Present the plan to the architect in a few lines, with the choices you made and the questions you need them to settle. Wait for their answers, revise the plan, and repeat until they say it suits them. 4. Commit the plan on the branch. Never push. Run step-complete only once the architect validates the step. Your output is the whole plan, with its path in the repository.5. Tasks and implementation
Implement the specification and the technical plan in your input, in the git repository of the current directory, on their branch. The method chosen for this run is `{{inputs.method}}`. 1. Record the current commit before touching anything: `git rev-parse HEAD`. 2. With the method `spec-kit`: follow Spec Kit's `speckit.tasks` command to write `tasks.md`, then `speckit.analyze` to check the specification, the plan and the tasks agree (fix any blocking inconsistency it reports), then `speckit.implement` to carry out the tasks. Their files are in `.claude/commands/` or under `.specify/`. With the method `sidehub`: write `tasks.md` next to the plan (ordered tasks, each tied to the requirements it serves), then implement them in that order. 3. Add or update the tests each acceptance criterion needs. Build the project and run its tests, and fix what you broke. 4. Commit your work on the branch with messages that describe it. Never push, never rewrite existing commits. If your input contains an acceptance report or comments from QA, the work came back to you: fix each criterion marked missing and each change QA asked for, and say how in your output. Write a summary as your output: what you implemented, the tasks done and left, the tests run and their result. Complete the step with `--value base=<the commit recorded in step 1>`. A developer reviews your diff in To review.6. Check the acceptance criteria
You check, read-only, that the work in your input meets the acceptance criteria of its specification. Do not modify, create or delete any file in the repository, do not commit, do not push. Use a temporary directory outside the repository if you need one. 1. List every acceptance criterion of the specification. 2. For each one, find the code and the tests that meet it (`git diff {{steps.5.outputs.base}}` shows the work), and run the tests that prove it. A criterion is met only when you saw it in the code and a test or a run confirms it. 3. If your input contains comments from QA, they asked for changes: add each change they asked for to your list, met only when the code already does it. Write the acceptance report as your output, in Markdown: a one-line verdict, then a table with each criterion, met or missing, and the evidence (file:line, test, command run). For a missing one, say what is missing. Complete the step with `--value missing=<number of criteria or requested changes still missing>`.7. QA: acceptance (human approval)
Read the acceptance report: each criterion with its evidence. Approve to close the ticket, or request changes with what fails: the check runs again and sends the work back to the code.
FAQ
Who can approve a step?
Only the holders of its role for this execution, chosen at launch from the defaults. A workspace owner or admin can decide in their place or reassign the role, and the timeline records it. Anyone else sees the step but cannot act on it.
Do the product owner and QA need a terminal?
No. They read the specification and the acceptance report in Memory, and approve or request changes from the execution, an e-mail or Telegram. Only the architect works in a terminal tab.
Does it need Spec Kit installed?
The first run installs it in the repository with uv if it is not there yet, and you review that change. With the sidehub method, nothing is installed and the agent follows the same phases on its own.
Can a role be held by several people?
Yes. Each holder is notified and the first one to decide settles the step. To require both the product owner and the product manager, the template has one approval for each, in parallel.