Repository navigation
feat: add a generated human plan overview to the Spec Kit preset - #41
Merged
Merged
Conversation
Dense agent-facing plans took days to read, and reviewer fixes could change the design without the human seeing it. The preset now gives the human a read-only plan-overview.md generated from plan.md, so Design Acceptance rests on a readable view with no second source to drift from. /speckit.plan generates the overview after the first plan draft and again before Design Acceptance. A writer role packet produces it, and a new plan-overview-fidelity reviewer checks it against plan.md once the design and clarity reviews pass. Plan review reruns also receive the human's recorded dispositions from review-dispositions.md, so declined findings are not raised again without new evidence. Bumps the preset to 0.5.0 and adds the local fidelity reviewer agent for Claude and OpenCode.
The architecture doc still described an older preset: a package integrity preflight, composed upstream commands, task checkboxes, execution groups, and checkpoint-based integration. It now matches the 0.5.0 references, including the plan overview, review dispositions, human approval of design-changing fixes, and per-packet integration. Tool-version validation history is dropped, since it goes stale faster than it can be maintained.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📝 Summary
Spec Kit plans (
plan.md) are written for agents and are slow for a human to read before Design Acceptance. Reviewer fixes could also change the design without the human seeing them. Preset0.5.0adds a generated, read-onlyplan-overview.mdthat the human reads instead. A separate reviewer checks that it matchesplan.md, and plan review reruns now see the human's earlier answers. The architecture doc is brought up to date with the current preset.Key Decisions
📖 Plan Overview As A Generated View
plan-overview.mdis generated fromplan.mdand never edited by hand. If reading it changes the human's mind, the change becomes a decision inplan.mdand the overview is generated again. With one source and a generated view, the two can never drift apart and need reconciling. The header names theplan.mdRevision it reflects. No later phase reads the overview, so it never becomes a second authority.⏱️ Two Generation Points Inside
/speckit.planThe overview is generated after the first plan draft, so the human confirms direction before the expensive reviews. It is generated again after the design and clarity reviews pass, so the human sees the final shape before Design Acceptance. Both steps run automatically inside the command, so there is no separate command to remember.
🔍 Overview Fidelity Review
A new mid-tier
plan-overview-fidelityreviewer runs afterplan-designandplan-claritypass. It flags overview text that contradicts or bends a decision, and any titled decision that appears neither in the body nor in the "Not covered here" list. It may not flag the overview as too short. That rule keeps the overview from growing into a copy ofplan.md. The writer fixes overview-only findings directly. A finding located inplan.mdgoes to the human as a proposed fix. The result is a third Review Record entry inplan.md, and Design Acceptance is gated on it.✍️ Writer Role Packet
writers/plan-overview.mddefines the writer by tier and role description, the same way reviewers are bound. This keeps the preset agent-agnostic. Writer is added as a third role kind: it may modify only its declared output.🗂️ Review Dispositions
A tracked
review-dispositions.mdrecords each plan review finding, whether the human accepted or declined it, and why.plan-designandplan-clarityread it on reruns. A new finding caused by an earlier fix must name that fix, and a declined suggestion is not raised again without new evidence. Notasksorimplementphase reads this file.🤖 Local Reviewer Agent
Adds
mid-tier-plan-overview-fidelity-reviewerfor Claude Code and OpenCode, so the new role has a matching agent locally. Themid-tier-technical-writerdescription now also covers one-pass generation.🔄 Before & After
plan.mdonlyplan-overview.mdplan_design,plan_clarityplan_overview_fidelity0.4.10.5.0(no migration;0.4.xplans restart their plan phase)0.5.0references