AI Coding Workflows

The Human Part of GitHub Spec Kit: How to Talk to Agents Between Commands

Spec Kit can generate the artifacts, but humans still have to expose assumptions, own decisions, propagate changes, set stop conditions, and decide what evidence is enough.

25 min read

GitHub Spec Kit gives an AI coding agent a disciplined sequence: specify, clarify, plan, create tasks, analyze, implement, and verify convergence.

But the sequence does not remove the human from software design. It changes the human’s job.

The agent can write a convincing spec.md, plan.md, and tasks.md. It can also fill gaps with reasonable defaults, infer links between requirements and tasks, recommend architecture, and mark implementation work complete. Those outputs may be useful without being approved, evidenced, or correct.

The human part is to make the hidden judgment visible:

  • Which statements are evidence, assumptions, or decisions?
  • Who owns each consequential choice?
  • Which artifacts must change when an answer changes?
  • What must be true before the next command runs?
  • What evidence is enough to accept the implementation?

This is not an article about creating another Spec Kit skill, preset, or extension. It is a practical guide to the conversation around the built-in commands: what to ask before moving forward, when to stop, and how to keep one clarification from leaving three stale artifacts behind.

TL;DR

  • Treat every Spec Kit command as producing a proposal for review, not an approval.
  • After /speckit.specify, inspect assumptions and defaults, not only obvious clarification markers.
  • Run /speckit.clarify by high-impact category. Five answered questions do not necessarily mean the feature is ready.
  • After /speckit.plan, ask whether research or design changed any user story, edge case, acceptance criterion, or assumption. Reconcile the spec before generating tasks.
  • Before /speckit.tasks, state the test policy explicitly. The current core task template says tests are optional unless the spec or user requests them.
  • /speckit.analyze is read-only. “Analyze and resolve” is a loop: analyze, decide, edit the owning artifact, regenerate downstream artifacts, then analyze again.
  • A decisions/ folder can be a useful team convention, but the first-party planning artifact is research.md, which records decisions, rationale, and alternatives.
  • During implementation, stop when code evidence contradicts an approved artifact. Classify the mismatch before changing anything.
  • A checked task is progress evidence, not acceptance evidence. Require requirement mapping, command output, test results, deviations, and remaining risk.
  • As of GitHub Spec Kit v0.15.1 on July 31, 2026, /speckit.converge is the post-implementation command for comparing code with the spec, plan, and tasks and appending missed work.

What You Will Learn Here

  • What judgment remains human at every Spec Kit phase
  • How to improve the prompts you already use after specify, plan, tasks, analyze, and implement
  • How to rank uncertainty by impact instead of asking random clarification questions
  • How to distinguish agent research from human approval
  • When a clarification should force changes to the spec, plan, tasks, contracts, tests, or code
  • How to use subagents for evidence without delegating decision ownership
  • A reusable prompt sequence for readiness, implementation, and validation

The Core Model: Commands Transform Artifacts; Humans Control Gates

The official Spec Kit reference describes an agentic workflow:

/speckit.constitution
  -> /speckit.specify
  -> /speckit.clarify
  -> /speckit.plan
  -> /speckit.checklist
  -> /speckit.tasks
  -> /speckit.analyze
  -> /speckit.implement
  -> /speckit.converge

In the official reference, clarify, checklist, and analyze are optional quality gates for work with meaningful ambiguity; the diagram is a production-oriented path, not a mandatory sequence for every change.

That is the command path. The human control loop is different:

generate
  -> expose evidence, assumptions, and unknowns
  -> assign decision ownership
  -> approve or reject tradeoffs
  -> propagate changes through affected artifacts
  -> challenge the result
  -> approve one bounded next action
  -> execute
  -> inspect validation evidence

The second loop is what prevents a polished artifact chain from becoming a chain of inherited mistakes.

The distinction matters because current Spec Kit behavior deliberately includes model judgment:

  • specify can use informed defaults and record assumptions.
  • clarify asks up to five questions per session, prioritized by impact and uncertainty.
  • plan turns technical unknowns into research and records decisions, rationale, and alternatives.
  • tasks infers implementation work and only includes test tasks when requested.
  • analyze estimates requirement-to-task coverage using explicit references, keywords, and key phrases, and does not edit files.
  • implement executes tasks and updates checkboxes.
  • converge checks the implementation against the artifacts and appends remaining work to tasks.md.

These are useful automation choices. None of them decides whether a product tradeoff is acceptable, an architecture choice is authorized, or a test result is sufficient for your risk level.

The five human responsibilities appear at every stage:

PhaseHidden judgmentHuman control
ConstitutionWhich rules are truly non-negotiable?Own and approve governing principles
SpecifyWhich defaults became requirements?Expose assumptions and unknowns
ClarifyWhich answer represents product or policy intent?Approve consequential answers
PlanWhich evidence and tradeoff justify the design?Own architecture and risk decisions
Checklist and tasksWhat work and proof are mandatory?Propagate approved scope into executable work
AnalyzeDoes an inferred relationship reflect reality?Verify findings and route them to the owning phase
Implement and convergeDoes completed work satisfy accepted intent?Verify evidence and accept or reject residual risk

Calibrate the rigor to the blast radius

Not every feature needs named approvers, a decision record, and an evidence ledger for every choice. That would replace hidden judgment with approval theater.

RiskAppropriate human control
Low: reversible internal tool, prototype, isolated copy changePolicy-backed delegation, automated checks, short assumption review
Medium: user-facing behavior, shared component, recoverable data changeHuman review of high-impact assumptions, plan tradeoffs, and validation evidence
High: authorization, money, personal data, compliance, irreversible migration, shared platformNamed owner, recorded decision, explicit stop conditions, independent evidence, rollout and rollback review

The goal is not maximum ceremony. It is enough human attention for the cost of being wrong.

/speckit.constitution: Humans own the governing rules

The constitution is evaluated by later phases, so an accidental principle can distort every artifact that follows. Humans should decide:

  • which rules are durable and project-wide
  • who may approve or amend them
  • which rules are mandatory versus preferred
  • whether a feature discovery belongs in the feature artifacts or changes a project-wide invariant

Use:

Before updating the constitution:
- cite the project evidence for each proposed principle
- separate durable invariants from feature-specific decisions
- identify who can approve each MUST rule
- show which templates or active features the amendment may affect

Recommend changes, but do not treat them as approved until the named owner confirms.

Before Every Command: Establish the Control Surface

Before discussing phase-specific prompts, make four things explicit.

1. Confirm the active feature

In v0.15.1, downstream scripts use SPECIFY_FEATURE_DIRECTORY when it is set; otherwise they read the feature directory from .specify/feature.json. Checking out another Git branch alone does not switch the active feature.

That means changing branches alone is not a reliable way to change command context.

Use this short preflight:

Before continuing, report:
- the active feature directory
- the artifacts this command will read
- the artifacts this command may write
- the current git branch as separate context

Stop if the active feature is not the feature we are discussing.

2. Label the source of every consequential statement

Agents often turn missing information into smooth prose. Make provenance part of the conversation:

Before editing any artifact, classify each material statement as:
- Confirmed repository evidence — cite path, symbol, test, or command output
- External evidence — cite the primary source and date
- Human decision — name the owner and decision date
- Assumption — state the impact if wrong
- Unknown — state what evidence or decision is needed

Do not convert absence of evidence into a confirmed requirement.

You do not need this label on every sentence. Use it for statements that can change behavior, architecture, security, operations, cost, or acceptance.

3. Name decision owners

An agent can recommend an authentication boundary. It cannot accept the risk on behalf of the security owner. It can rank product options. It cannot decide which customer behavior the business wants.

For consequential choices, ask for:

- decision category: product, architecture, security, operations, or delivery
- accountable human owner
- options considered
- evidence for the recommendation
- consequence of delaying the decision
- artifacts affected

4. Set a stop condition before starting

“Continue until done” is dangerous when “done” has not been defined.

Examples of useful stop conditions:

  • stop after listing uncertainties; do not edit
  • stop on any unresolved security or data-retention choice
  • stop before tasks if planning changes user-visible behavior
  • implement only tasks T001-T006
  • stop if runtime evidence contradicts plan.md
  • do not proceed while any critical analyze finding remains

After /speckit.specify: Find Hidden Uncertainty

A strong post-specify move is to continue listing uncertainties and clarify them by impact.

The improvement is to inspect both explicit gaps and silently chosen defaults. The absence of a clarification marker does not prove the requirement was supplied by a human.

Use this:

Do not edit yet.

Re-scan spec.md and list unresolved judgment by impact:
1. Blocker
2. High
3. Medium
4. Low

Group findings by:
- scope and non-goals
- actors and permissions
- data and lifecycle
- security, privacy, and compliance
- UX and edge cases
- reliability and operations
- success and validation

Include both explicit clarification markers and defaults recorded as assumptions.
For each item, name:
- why it matters
- the evidence needed
- the likely decision owner
- the artifacts it could affect

Ask which category I want to clarify first.

This produces an uncertainty inventory instead of a flat question list.

Then clarify one category at a time:

/speckit.clarify Focus only on [category].

Ask one decision question at a time.
After each answer, report:
- the spec sections changed
- the assumption replaced
- affected user stories or edge cases
- whether the answer may change plan.md or tasks.md

At session end, list deferred and outstanding categories by impact.

The official clarify workflow is intentionally bounded to five questions per session and can be run repeatedly. The human decision is not “did clarify finish?” It is “are the remaining unknowns safe to carry into planning?”

A useful recommendation gate

Before planning, ask:

Recommend whether this spec is ready for technical planning.

Return:
- ready / ready with accepted assumptions / not ready
- unresolved blockers and high-impact unknowns
- assumptions we explicitly accept for planning
- product decisions still awaiting an owner
- user stories that are independently testable
- measurable success criteria that remain weak

This is an agent recommendation. Name the human owner who records the decision.
Do not run /speckit.plan.

After /speckit.plan: Check Whether Design Changed the Problem

Summarizing the plan and asking whether assumptions, edge cases, or user stories changed is one of the highest-value pauses in the workflow.

Planning discovers things. An API limitation can change the UX. A data-retention rule can remove a user story. A migration constraint can create a new failure state. If those discoveries stay only in research.md or plan.md, the artifact chain has already drifted.

Use a short recap:

After /speckit.plan, give a maximum 10-bullet summary covering:
- selected approach
- binding constraints
- important assumptions
- rejected alternatives
- data and interface changes
- test and validation strategy
- operational risks
- unresolved evidence gaps

Then answer:
Did planning change any assumption, edge case, acceptance criterion,
success criterion, or user story?

If yes, stop before tasks and propose the required spec reconciliation.

Then run an adversarial review:

Review this plan as a skeptical architect who must operate and roll it back.

Find:
- the strongest counterargument to the selected approach
- irreversible or expensive choices
- unsupported research conclusions
- missing failure and recovery behavior
- security and permission boundary failures
- scale assumptions without evidence
- simpler rejected alternatives worth reconsidering

Do not edit.
Separate facts, inferences, and recommendations.

This is a better use of an agent than asking, “Is the plan good?” The latter invites agreement. The former gives the model a falsification task.

Where decisions belong

The core plan workflow creates research.md with:

  • Decision
  • Rationale
  • Alternatives considered

If your team already uses specs/<feature>/decisions/, keep using it for durable, individually reviewable decisions. But describe that honestly as a team convention, not a built-in Spec Kit requirement.

A practical instruction is:

For each material planning decision, record:
- context
- options considered
- decision
- accountable owner and approval date
- evidence
- consequences
- affected artifacts
- superseded decision, if any

Use research.md for normal planning decisions.
Use specs/<feature>/decisions/ only when this project convention exists
or the decision needs an independently reviewable record.

Subagents may collect evidence and compare options. The accountable human still approves the choice.

After /speckit.checklist: Review the Test of the Requirements

Spec Kit describes checklists as “unit tests for requirements.” The analogy is useful, but a generated checklist also contains judgment: which dimensions matter, how strict each item is, and whether an exception is acceptable.

Ask:

Review this checklist before treating it as a gate.

Report:
- which risk or requirement each item protects
- important dimensions the checklist does not cover
- items that are subjective or not independently verifiable
- exceptions requested, with owner and rationale
- spec sections that must change for failed items

Recommend pass, conditional pass, or fail.
A human owner records any exception and the gate decision.

A checked checklist means its questions were answered against the artifact. It does not approve the product behavior or prove the implementation.

Before /speckit.tasks: Make Work Policy Explicit

Do not run tasks with an unstated testing policy. The v0.15.1 task command says tests are optional and generated only when the feature specification or user explicitly requests them.

That makes this preflight important:

Before generating tasks, restate:
- approved user-story scope and priority
- explicitly deferred scope
- required test policy
- migration work
- rollout and rollback work
- documentation and observability work
- accepted architecture decisions

Stop if any of these conflict with spec.md or plan.md.

Then:

/speckit.tasks

In tasks.md:
- reference the relevant user story, requirement, or success criterion
- give each user story an observable verifier
- include required test tasks
- include migration, rollout, rollback, documentation, and validation tasks
  where the approved plan requires them
- flag file paths and [P] markers that still require human confirmation
- do not introduce behavior absent from the approved spec

Spec Kit already organizes tasks by user story and marks parallel work. The human review should challenge semantic dependencies the file layout cannot prove:

  • Can these tasks really run in parallel against the same schema or interface?
  • Does a “foundational” task hide product behavior?
  • Can the stated user story actually be demonstrated after its phase?
  • Did the task list omit operational work because it is not a code file?

/speckit.analyze: Analyze First, Resolve Separately

The phrase “run /speckit.analyze and resolve with decision records and evidence” contains two operations, not one.

The official analyze command is strictly read-only. It reports inconsistencies, ambiguity, constitution conflicts, and coverage gaps. It may suggest remediation, but it requires explicit approval before follow-up editing.

Use:

/speckit.analyze

Keep the review read-only.
For each CRITICAL or HIGH finding, include:
- concrete evidence
- owning artifact and owning phase
- human decision required, if any
- downstream artifacts affected
- recommended rerun sequence

Treat semantic requirement-to-task coverage as a hypothesis, not proof.
Do not remediate until I approve finding IDs.

Then resolve only approved findings:

Resolve only approved findings: [IDs].

Group edits by owning artifact.
For each material decision, record:
- context
- options
- decision
- owner and date
- evidence
- consequences
- artifacts requiring reconciliation

Update the owning source first.
Regenerate or reconcile downstream artifacts in order.
Then rerun /speckit.analyze.

The owning-source rule prevents tasks.md from silently redefining product intent. A requirement defect returns to specify or clarify. A design defect returns to plan. A decomposition defect returns to tasks.

When a Clarification Arrives Late: Build an Impact Matrix

The question “How does this recent clarification impact spec, plan, and tasks, and do I need to run analyze?” should be a standard change-control prompt.

Expand it slightly:

Given this clarification: [decision]

Show its impact on:
- spec.md
- research.md
- plan.md
- data-model.md
- contracts/
- quickstart.md
- tasks.md
- tests
- current implementation

For every "no change," explain why.
Identify invalidated assumptions and decisions.
Recommend which phases must rerun and whether /speckit.analyze must rerun.
Do not edit or implement until I approve the propagation plan.

Use this decision rule:

ChangeMinimum response
Wording only; behavior unchangedUpdate owning artifact; no automatic rerun
Acceptance criterion or edge case changedUpdate spec, reconcile tasks/tests, rerun analyze
Architecture, data model, interface, or operational constraint changedUpdate plan artifacts, regenerate tasks, rerun analyze
New user-visible capabilityReopen scope or create a follow-up spec
Implementation discovery contradicts approved intentStop, classify, obtain decision, then reconcile

Do not rerun everything mechanically. Rerun the phases whose inputs changed, plus analyze when cross-artifact consistency may have changed.

Mini-example: a late authorization decision

Suppose the generated plan assumes any workspace member can export audit events. During security review, the human owner decides only workspace administrators may export.

Agent assumption:
  Any authenticated workspace member may export.

Human decision:
  Only workspace administrators may export.

Propagation:
  spec.md        -> actor, requirement, acceptance and denial scenarios
  plan.md        -> authorization boundary and enforcement point
  contracts/     -> forbidden response for non-admin callers
  tasks.md       -> policy enforcement and negative-test tasks
  tests          -> admin success and member denial evidence

Rerun:
  tasks, then analyze

The agent can propose that impact map. The security or product owner authorizes the behavior. Validation must then demonstrate both the allowed and denied paths.

Using Subagents Without Outsourcing Judgment

“Run more subagents” improves results only when each subagent has an independent evidence job. Sending three agents the same vague request can produce three correlated opinions.

For a fix:

Investigate [failure] with independent subagents:
- one reproduces the failure and gathers runtime evidence
- one traces the affected requirement, plan decision, and task
- one evaluates fix alternatives and regression risk

Subagents gather evidence; they do not approve requirement or architecture changes.
Consolidate agreements and disagreements.
Stop for the accountable human decision.
Record any material decision and reconcile affected artifacts before implementation.

Good independence comes from different questions:

  • What happened? Reproduction and logs
  • What should have happened? Spec and acceptance criteria
  • Why did the design permit it? Plan, contracts, and boundaries
  • What are the fix options? Alternatives and consequences

The human resolves conflicts between those views.

Before and During /speckit.implement: Bound the Work

Do not hand implementation an open-ended artifact folder and hope that scope remains stable.

Use an implementation readiness gate:

Before implementation, report:
- active feature directory
- approved task IDs or phase
- checklist status and any requested override
- unresolved analyze findings
- expected files and tests
- human-owned decisions still open
- explicit stop conditions

Wait for approval in the form:
"Approve implementation of [task range or phase]."

For larger features, this aligns with the official guidance to scope implementation by phase or task range and validate each stage before continuing.

During implementation, use a deviation protocol:

If implementation evidence conflicts with spec.md, plan.md, or tasks.md:
1. Stop after preserving the current safe state.
2. Classify it as:
   - code defect
   - plan discovery
   - requirement change
   - new scope
3. Cite the evidence.
4. List affected artifacts and tests.
5. Propose alternatives without silently choosing one.
6. Wait for the decision owner.

This prevents code from becoming the source of truth merely because it exists.

After Implementation: Demand Evidence, Then Converge

A task checkbox means the agent believes the work was performed. It is not proof that the requirement is satisfied.

Ask for an evidence ledger:

For each completed task, report:
- task ID
- requirement or acceptance criterion addressed
- changed files
- validation commands executed
- exit status and relevant output
- manual validation performed
- checks not run and why
- deviations from approved artifacts
- remaining risk

Do not use the [X] checkbox as acceptance evidence.

Then use /speckit.converge. In v0.15.1, this command inspects code paths and concepts derived from the feature’s spec, plan, and tasks. It either reports that it found no gaps or appends traceable tasks for actionable missing, partial, contradictory, or unrequested work. This remains an agent-generated assessment, not formal proof of correctness. The loop is:

/speckit.implement
  -> inspect evidence
  -> /speckit.converge
     -> converged: human review and release checks
     -> tasks appended: inspect, approve, implement, and converge again

Convergence is still not a release authorization. Security review, operational readiness, stakeholder acceptance, and risk acceptance remain human or team gates.

A Q&A Recap Before the Next Action

Your request to recap the spec, plan, and tasks as Q&A is useful because it tests whether the artifact set tells one coherent story.

Use:

Recap the current spec, plan, and tasks as Q&A:

- What problem and outcome are approved?
- Who are the actors and decision owners?
- What is explicitly out of scope?
- Which assumptions remain?
- Which clarifications changed the original request?
- What architecture and alternatives were approved?
- What is the MVP and task order?
- How will each user story be validated?
- What risks or decisions remain?
- What is the next gate?

Cite the owning artifact section for each answer.
Flag contradictions instead of choosing one silently.

The citations are important. Without them, the recap can become another plausible summary detached from the files.

A Compact Human Prompt Pack

If you want the shortest usable version, keep these prompts nearby.

After specify

List remaining uncertainties by impact and category.
Include assumptions and inferred defaults, not only explicit markers.
Name the evidence, owner, and affected artifacts for each.
Do not edit yet.

During clarify

Focus on [category]. Ask one decision at a time.
After each answer, show changed assumptions, stories, edge cases,
acceptance criteria, and downstream impact.

After plan

Summarize the plan in 10 bullets maximum.
Did planning change any assumption, edge case, acceptance criterion,
success criterion, or user story?
If yes, stop before tasks and propose spec reconciliation.

Before tasks

Restate approved scope, deferred scope, test policy, migration,
rollout, rollback, documentation, observability, and accepted decisions.
Stop on conflicts before generating tasks.

Analyze and resolve

Run /speckit.analyze read-only.
For high-severity findings, cite evidence, owning artifact, decision owner,
affected artifacts, and rerun sequence.
Wait for approval of finding IDs before remediation.

Before implementation

Report active feature, approved task range, checklist status,
open analyze findings, expected files/tests, and stop conditions.
Wait for explicit approval of the task range.

After implementation

Map completed tasks to requirements and validation evidence.
List commands, exit status, unrun checks, deviations, and remaining risk.
Then run /speckit.converge and review any appended tasks before continuing.

The Counterpoint: Human Review Can Also Fail

Human review is expensive and fallible. A person can misunderstand a generated summary, become a queue that blocks delivery, or click through gates without reading them.

The answer is not to require a meeting for every agent choice. Pre-authorize low-risk decisions through the constitution, templates, architecture rules, test policy, and explicit thresholds. Escalate only when work crosses those boundaries.

Useful escalation triggers include:

  • the repository and artifacts provide conflicting evidence
  • a choice changes user-visible behavior or accepted scope
  • a security, privacy, money, compliance, or irreversible data boundary is involved
  • the agent proposes an exception to a governing rule
  • implementation evidence invalidates an approved assumption
  • validation is missing for a high-impact requirement

Human judgment adds value when it resolves a decision the policy cannot. It adds delay when it merely repeats a decision the policy already made.

What I Recommend Keeping Human-Owned

For this workflow, I recommend assigning a named accountable person to these responsibilities when their risk justifies it:

  • approving user-visible behavior and non-goals
  • accepting privacy, security, compliance, or data-retention tradeoffs
  • authorizing irreversible architecture or migration choices
  • deciding which assumptions are safe to carry
  • accepting incomplete checklists or unresolved findings
  • approving requirement changes discovered during implementation
  • deciding whether validation evidence is sufficient
  • accepting residual risk and authorizing release

The agent can prepare each decision exceptionally well. It can gather evidence, compare options, expose contradictions, and record the result. Preparation is not ownership.

Failure Modes This Conversation Prevents

“Clarify finished, so ambiguity is gone”

It asked up to five questions. Other categories may remain unresolved. Inspect the completion coverage and choose whether to run another focused pass.

“Analyze said 100% coverage”

The command infers task coverage from requirement IDs, keywords, and key phrases. That is useful consistency checking, not formal proof that the implementation satisfies the requirement.

“All tasks are checked”

That proves task state was updated. It does not prove the expected behavior, security property, performance target, or operational outcome.

“The agent researched and selected the architecture”

research.md should expose the decision, rationale, and alternatives. A human still approves choices with meaningful cost, risk, or organizational consequences.

“We fixed the code, so the plan can stay stale”

Only if the code was wrong and the approved plan remains correct. If the implementation exposed a valid design or requirement change, reconcile the owning artifact and all derived artifacts.

“More subagents means more confidence”

Only when they investigate independently, cite evidence, and expose disagreement. More unsupported agreement is not stronger evidence.

Final Takeaway

The human part of GitHub Spec Kit is not writing all the Markdown yourself. It is controlling the conversion of uncertainty into commitment.

At each phase:

  1. expose what the agent inferred
  2. separate evidence from assumptions
  3. assign consequential decisions to people
  4. propagate approved changes to every affected artifact
  5. set a bounded next action and a stop condition
  6. require evidence before acceptance

Spec Kit gives the conversation a durable structure. The human makes sure that structure contains decisions the team actually understands and accepts.

The best prompt is not the longest one. It is the one that makes the next decision, owner, evidence requirement, and stopping point impossible to miss.

Sources

Primary Spec Kit sources reviewed against v0.15.1, released July 31, 2026:

Supporting governance guidance:

The command behavior above is source-backed. The prompt patterns, decision gates, artifact-impact matrix, and recommendation to treat each output as a proposal are my editorial synthesis.

Spec Kit command behavior changes over time. Verify these prompts against the templates installed in your project rather than assuming v0.15.1 behavior applies to every future version.