Skip to content

feat: add a generated human plan overview to the Spec Kit preset - #41

Merged
MrPointer merged 2 commits into
mainfrom
chore/design-doc-workflow-anchor
Nov 11, 2026
Merged

MrPointer merged 2 commits into
mainfrom
chore/design-doc-workflow-anchor

Conversation

@MrPointer

Copy link
Copy Markdown
Owner

📝 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. Preset 0.5.0 adds a generated, read-only plan-overview.md that the human reads instead. A separate reviewer checks that it matches plan.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.md is generated from plan.md and never edited by hand. If reading it changes the human's mind, the change becomes a decision in plan.md and the overview is generated again. With one source and a generated view, the two can never drift apart and need reconciling. The header names the plan.md Revision it reflects. No later phase reads the overview, so it never becomes a second authority.

⏱️ Two Generation Points Inside /speckit.plan

The 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-fidelity reviewer runs after plan-design and plan-clarity pass. 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 of plan.md. The writer fixes overview-only findings directly. A finding located in plan.md goes to the human as a proposed fix. The result is a third Review Record entry in plan.md, and Design Acceptance is gated on it.

✍️ Writer Role Packet

writers/plan-overview.md defines 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.md records each plan review finding, whether the human accepted or declined it, and why. plan-design and plan-clarity read 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. No tasks or implement phase reads this file.

🤖 Local Reviewer Agent

Adds mid-tier-plan-overview-fidelity-reviewer for Claude Code and OpenCode, so the new role has a matching agent locally. The mid-tier-technical-writer description now also covers one-pass generation.

🔄 Before & After

Area Before After
Human reading basis for Design Acceptance plan.md only Generated plan-overview.md
Plan Review Record plan_design, plan_clarity Adds plan_overview_fidelity
Review reruns Prior report only Prior report plus human dispositions
Preset role kinds Reviewer, implementation packet Adds writer
Preset version 0.4.1 0.5.0 (no migration; 0.4.x plans restart their plan phase)
Architecture doc Described an older preset (preflight, checkboxes, checkpoints) Matches 0.5.0 references

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.
@MrPointer
MrPointer merged commit 6cdf8fb into main Nov 11, 2026
5 checks passed
@MrPointer
MrPointer deleted the chore/design-doc-workflow-anchor branch November 11, 2026 22:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant