It would be great if **spec-kit** could support the following workflow. #750
Description
It would be great if spec-kit could support the following workflow.
(This might just reflect my personal preference, but I truly find it necessary.)
When dealing with end-to-end requirements, it’s almost impossible to fully follow TDD — I usually start with only a general idea, without a concrete implementation plan, let alone writing tests first to drive the development of new features.
What I can usually do is add tests afterward for already confirmed features, to support future iterations and refactoring.
Here’s my proposed approach:
Allow non-constitutional specification documents (such as spec, plan, and tasks documents) to be adjusted during the manual end-to-end testing and acceptance phase based on reviewers’ feedback.
These adjustments serve as guidance for corresponding changes to meet the needs of timely iteration.
Only requirements where the idea and the implementation finally align are considered to have passed acceptance.
The resulting feature code is regarded as production-ready only when it meets the reviewers’ intended outcomes.
Therefore, the specification documents must be continuously revised under the reviewers’ guidance, while the functional code must be implemented and iterated under the guidance of the specification documents.
验收与实现的关系 · Relationship Between Acceptance and Implementation
| 阶段 / Phase | 规范状态 / Spec Status | 代码行为 / Code Behavior | 验收标准 / Acceptance Criteria |
|---|---|---|---|
| 开发前 / Before Dev | 规范冻结 / Spec Frozen | 按规范实现 / Implement by spec | 必须符合规范 / Must match spec |
| 验收中 / During Acceptance | 可指导性修订 / Spec adjustable (guided) | 按指导意见临时调整 / Adjust provisionally | 由验收人员确认结果 / Reviewer confirms intent |
| 验收后 / After Acceptance | 规范正式修订 / Spec ratified | 代码对齐生产标准 / Code finalized for production | 实现与规范一致 / Spec & code fully aligned |
### Acceptance-Driven Specification Iteration
During the manual end-to-end testing and acceptance stage after feature implementation, specification documents (spec, plan, tasks) are **allowed and encouraged** to be *guidance-adjusted* based on feedback from acceptance reviewers, enabling agile iteration of requirements.
**Core Principles**:
- **Alignment between idea and implementation** is the only acceptance criterion:
Functional code is considered production-ready only when it meets the actual needs and expectations of the acceptance reviewers.
- **Specifications guide the code**:
Code implementation and iteration must strictly follow the specification documents and must not deviate from them.
- **Acceptance feedback guides the specifications**:
Specification documents must be revised according to the reviewers’ feedback to accurately reflect real business needs.
**Workflow**:
1. **Initial Specification Drafting**: Create `spec.md`, `plan.md`, and `tasks.md` based on the initial understanding of requirements.
2. **Implementation**: Develop strictly according to the specification documents without deviation.
3. **End-to-End Acceptance**: Reviewers conduct manual testing and provide feedback.
4. **Specification Iteration**: Update the specification documents (`spec/plan/tasks`) according to the feedback, clearly recording the reasons for each change.
5. **Code Adjustment**: Adjust code implementation based on the updated specifications.
6. **Repeat Steps 3–5** until the reviewers confirm the feature meets expectations.
7. **Acceptance Approval**: Once idea and implementation are aligned, the feature is ready for production release.
**Documentation Revision Rules**:
- Each specification revision must include a change log at the top of the document (date, reason, and summary of changes).
- The version number of the specification should increment (by date or sequence).
- Acceptance feedback must serve as the explicit basis for each revision and be referenced within the document.
- Commit messages for code changes must reference the corresponding specification document version.
**Rationale**:
Traditional “frozen specification” approaches assume requirements can be fully defined before development.
In reality, users can only accurately evaluate whether a feature meets expectations after seeing it in action.
By allowing iterative updates to specification documents during the acceptance phase, we establish a **two-way feedback loop**:
code faithfully implements specifications, and specifications faithfully reflect acceptance needs — ensuring the final deliverable truly satisfies user expectations.flowchart TD
A[初始规格编写 / Initial Spec] --> B[代码实现 / Implementation]
B --> C[人工端到端验收 / Manual E2E Acceptance]
C --> D{验收通过? / Accepted?}
D -- 否 / No --> E[根据验收意见修订规格 / Revise Spec per Feedback]
E --> F[调整代码实现 / Adjust Code]
F --> C
D -- 是 / Yes --> G[验收通过 / Final Acceptance]
G --> H[功能进入生产 / Production Release]
Originally posted by @LuSrackhall in #152 (comment)