docs: 建立项目宪法并同步 speckit 模板
将项目约束正式落到 .specify/memory/constitution.md，并同步更新 plan、spec、tasks、checklist、agent 模板，使 Speckit 工作流默认遵循文档单一真源、范围收敛、Archive 隔离与校验闭环。
This commit is contained in:
parent
524865cb41
commit
aba7071723
100
.specify/memory/constitution.md
Normal file
100
.specify/memory/constitution.md
Normal file
@ -0,0 +1,100 @@
|
||||
<!--
|
||||
Sync Impact Report
|
||||
Version change: template -> 1.0.0
|
||||
Modified principles:
|
||||
- 模板占位原则 1 -> I. 主文档单一真源
|
||||
- 模板占位原则 2 -> II. 范围交集优先
|
||||
- 模板占位原则 3 -> III. Archive 隔离与可追溯
|
||||
- 模板占位原则 4 -> IV. 一致性优先于扩写
|
||||
- 模板占位原则 5 -> V. 校验与台账闭环
|
||||
Added sections:
|
||||
- 文档与资料约束
|
||||
- 执行流程与质量门禁
|
||||
Removed sections:
|
||||
- 无
|
||||
Templates requiring updates:
|
||||
- ✅ updated /Volumes/Dpan/github/fujian_water_biz_doc/.specify/templates/plan-template.md
|
||||
- ✅ updated /Volumes/Dpan/github/fujian_water_biz_doc/.specify/templates/spec-template.md
|
||||
- ✅ updated /Volumes/Dpan/github/fujian_water_biz_doc/.specify/templates/tasks-template.md
|
||||
- ✅ updated /Volumes/Dpan/github/fujian_water_biz_doc/.specify/templates/checklist-template.md
|
||||
- ✅ updated /Volumes/Dpan/github/fujian_water_biz_doc/.specify/templates/agent-file-template.md
|
||||
- ✅ checked /Volumes/Dpan/github/fujian_water_biz_doc/.specify/templates/constitution-template.md
|
||||
- ✅ checked /Volumes/Dpan/github/fujian_water_biz_doc/README.md
|
||||
- ✅ checked /Volumes/Dpan/github/fujian_water_biz_doc/AGENTS.md
|
||||
Follow-up TODOs:
|
||||
- `.specify/templates/commands/` 目录不存在，本次无命令模板需要同步。
|
||||
-->
|
||||
# 福建水务营收系统 Constitution
|
||||
|
||||
## Core Principles
|
||||
|
||||
### I. 主文档单一真源
|
||||
正式内容 MUST 优先落在既有主文档中维护：`docs/design/01_Overview/03_Summary_Design.md`、`docs/design/02_Detailed_Design/01_Detailed_Design.md`、`docs/design/03_Technical_Design/01_Database_Design.md`、`docs/design/03_Technical_Design/03_Interface_Design.md`、`docs/design/03_Technical_Design/04_Security_Design.md`、`docs/design/03_Technical_Design/05_Deployment_Design.md`。若既有主文档可以承载内容，任何规格、计划、任务或实施说明 MUST 引导回主文档修订，不得默认创建“新版本”“最终版”“修订版”等平行正式稿。
|
||||
|
||||
Rationale：本仓库的首要目标是形成可评审、可交付、可持续维护的正式文档体系；平行稿会直接破坏单一真源。
|
||||
|
||||
### II. 范围交集优先
|
||||
新增或补完的功能、模块、接口、外部系统与约束 MUST 先落在当前范围基线内。范围判断 MUST 以 `docs/design/01_Overview/03_Summary_Design.md` 与 `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md` 的交集收敛：两者均覆盖可直接推进；仅一方覆盖 MUST 标记“需确认”；两者均未覆盖 MUST 视为超范围并停止扩写。
|
||||
|
||||
Rationale：当前项目以“对齐既有设计、保守补完”为主，不以新需求发散为目标。
|
||||
|
||||
### III. Archive 隔离与可追溯
|
||||
`docs/design/04_Appendix/Archive/` MUST 作为来源、核对与归档区使用，默认不作为正式主稿直接改写替代。引用 Archive 内容时 MUST 回写到 P0/P1 正式文档后再作为正式结论输出。迁移归档资料时，Markdown 文件与同名 `_images/` 目录 MUST 成组维护，引用路径 MUST 同步修复，来源关系 MUST 可追溯。
|
||||
|
||||
Rationale：Archive 的价值在于追溯与核对，而不是替代正式交付口径。
|
||||
|
||||
### IV. 一致性优先于扩写
|
||||
所有修改 MUST 优先保证系统名称、数据库口径、模块编号、接口编号、图表、链接和术语的一致性。正式系统名称 MUST 使用“福建水务营收系统”；接口编号 MUST 与模块编号区分并优先采用 `IF-` 前缀；图表 MUST 优先使用 Mermaid 并与正文一致；仓库内引用 MUST 使用相对路径。无依据时 MUST 先修正结构和一致性，不得为了“完整”而臆造实现细节、代码、DDL 或伪代码。
|
||||
|
||||
Rationale：对当前仓库而言，不一致比不完整更容易导致评审和实施偏差。
|
||||
|
||||
### V. 校验与台账闭环
|
||||
每次正式文档变更后 MUST 执行与改动范围匹配的最小校验，并在适用时回写管理台账。单文件修订至少 MUST 执行 `make validate-file FILE=<目标文件>`；涉及链接、目录或跨文档引用时 MUST 执行 `make check-links`；涉及图表时 MUST 执行 `make validate-mermaid`；重要治理或结构变更 MUST 更新 `docs/design/00_Management/01_Project_Progress.md`，明确任务完成时 SHOULD 同步更新 `docs/design/00_Management/03_Task_Checklist.md`。
|
||||
|
||||
Rationale：本仓库的交付价值依赖“文档可读 + 链接有效 + 图文一致 + 台账可追踪”的闭环，而不是仅完成局部文字编辑。
|
||||
|
||||
## 文档与资料约束
|
||||
|
||||
- 正式文档内容 MUST 使用中文；技术术语、框架名、代码标识符可保留原文。
|
||||
- 文档层级 MUST 与抽象粒度匹配：概要设计讲边界与结构，详细设计讲流程/规则/接口/数据，技术专项讲数据库/接口/安全/部署等专题。
|
||||
- Speckit 产物若用于本仓库，MUST 默认把“文档修订”视为交付对象，而非默认生成软件代码结构。
|
||||
- 需求、计划、任务、检查清单 MUST 明确来源文档、影响文档、验收方式与是否涉及台账更新。
|
||||
- 未经用户明确要求，规格与计划 MUST 避免把实现代码、数据库脚本、部署脚本、压测指标或测试细节写成默认必交付项。
|
||||
|
||||
## 执行流程与质量门禁
|
||||
|
||||
1. 开始任何正式文档任务前，执行者 MUST 先阅读：
|
||||
- `docs/design/00_Management/01_Project_Progress.md`
|
||||
- `docs/design/00_Management/02_Delivery_Standards.md`
|
||||
- `docs/design/00_Management/03_Task_Checklist.md`
|
||||
- 与任务直接相关的目标文档
|
||||
2. 结构性调整任务还 MUST 额外阅读：
|
||||
- `docs/design/00_Management/04_Writing_Guide.md`
|
||||
- `docs/design/00_Management/08_AI_Agent_Maintenance_SOP.md`
|
||||
- `docs/design/00_Management/10_AI_Retrieval_Whitelist.md`
|
||||
- `docs/design/00_Management/11_Main_Doc_Chapter_Index.md`
|
||||
3. 计划文档 MUST 在“Constitution Check”中显式检查：主文档归属、范围基线、Archive 使用方式、一致性影响、校验与台账动作。
|
||||
4. 任务文档 MUST 将“目标文档修订”“链接/图表校验”“台账同步”列为显式任务，而不是隐含工作。
|
||||
5. 质量门禁最低要求 MUST 满足：断链数量为 0、Mermaid 语法错误为 0、平行正式稿新增数量为 0、关键口径冲突数量为 0。
|
||||
|
||||
## Governance
|
||||
|
||||
本 Constitution 高于 `.specify/` 下其他模板中的默认假设；若模板、计划或任务与本 Constitution 冲突，MUST 以本 Constitution 为准并同步修订模板。
|
||||
|
||||
修订流程如下：
|
||||
1. 先基于当前主文档、治理文档与必要的 Archive 来源形成修订草案。
|
||||
2. 在修订草案中明确版本变更类型，并说明是 MAJOR、MINOR 还是 PATCH 及其依据。
|
||||
3. 同步检查 `.specify/templates/`、`README.md`、`AGENTS.md` 及相关运行指导文档是否仍与宪法一致；若不一致，MUST 在同一轮修订中更新或显式记录 pending 项。
|
||||
4. 所有规格、计划、任务与检查清单在生成或更新时 MUST 执行一次合规复核，确认满足五项核心原则。
|
||||
|
||||
版本策略如下：
|
||||
- MAJOR：移除核心原则、重定义治理边界、改变单一真源或范围控制方式。
|
||||
- MINOR：新增原则、增加新的强制门禁或新增治理章节。
|
||||
- PATCH：纯措辞澄清、错别字修正、非语义调整。
|
||||
|
||||
合规复核要求如下：
|
||||
- 每份计划 MUST 记录 Constitution Check。
|
||||
- 每份任务清单 MUST 能映射到目标文档、校验动作与台账动作。
|
||||
- 每次重要变更完成后 MUST 在结果摘要中说明修改文件、校验结果、剩余风险与后续建议。
|
||||
|
||||
**Version**: 1.0.0 | **Ratified**: 2026-03-13 | **Last Amended**: 2026-03-13
|
||||
46
.specify/templates/agent-file-template.md
Normal file
46
.specify/templates/agent-file-template.md
Normal file
@ -0,0 +1,46 @@
|
||||
# [PROJECT NAME] Development Guidelines
|
||||
|
||||
Auto-generated from all feature plans. Last updated: [DATE]
|
||||
|
||||
## Working Mode
|
||||
|
||||
- This repository is document-first and governance-driven.
|
||||
- Prefer updating existing main documents instead of creating parallel formal documents.
|
||||
- Use Archive materials for verification and traceability, not as direct replacement for formal output.
|
||||
|
||||
## Active Work Products
|
||||
|
||||
[EXTRACTED FROM ALL PLAN.MD FILES]
|
||||
|
||||
## Project Structure
|
||||
|
||||
```text
|
||||
docs/design/
|
||||
├── 00_Management/
|
||||
├── 01_Overview/
|
||||
├── 02_Detailed_Design/
|
||||
├── 03_Technical_Design/
|
||||
└── 04_Appendix/Archive/
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
- `make validate-file FILE=<target-file>`
|
||||
- `make check-links`
|
||||
- `make validate-mermaid`
|
||||
- `make check-ai-governance`
|
||||
|
||||
## Code Style
|
||||
|
||||
- Formal content uses Chinese.
|
||||
- Technical terms and identifiers may remain in original form.
|
||||
- Relative links only.
|
||||
- Mermaid preferred for formal diagrams.
|
||||
- Preserve single source of truth and cross-document consistency.
|
||||
|
||||
## Recent Changes
|
||||
|
||||
[LAST 3 FEATURES AND WHAT THEY ADDED]
|
||||
|
||||
<!-- MANUAL ADDITIONS START -->
|
||||
<!-- MANUAL ADDITIONS END -->
|
||||
42
.specify/templates/checklist-template.md
Normal file
42
.specify/templates/checklist-template.md
Normal file
@ -0,0 +1,42 @@
|
||||
# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
|
||||
|
||||
**Purpose**: [Brief description of what this checklist covers]
|
||||
**Created**: [DATE]
|
||||
**Feature**: [Link to spec.md or relevant documentation]
|
||||
|
||||
**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements.
|
||||
|
||||
## Source & Scope
|
||||
|
||||
- [ ] CHK001 Target documents are explicitly identified
|
||||
- [ ] CHK002 Governing source-of-truth documents are explicitly identified
|
||||
- [ ] CHK003 Allowed reference sources are identified and Archive is not treated as direct formal output
|
||||
- [ ] CHK004 Scope decision is recorded: in scope / needs confirmation / out of scope
|
||||
|
||||
## Consistency & Content
|
||||
|
||||
- [ ] CHK005 System name, terminology, numbering, and database wording align with current main docs
|
||||
- [ ] CHK006 Relative links and anchors are updated where affected
|
||||
- [ ] CHK007 Diagrams and surrounding text remain consistent
|
||||
- [ ] CHK008 No new parallel formal document was introduced without explicit approval
|
||||
|
||||
## Validation & Ledger
|
||||
|
||||
- [ ] CHK009 Required validation commands are listed for each target file
|
||||
- [ ] CHK010 `make validate-file FILE=<target-file>` has been executed or scheduled
|
||||
- [ ] CHK011 `make check-links` and `make validate-mermaid` are included whenever applicable
|
||||
- [ ] CHK012 `docs/design/00_Management/01_Project_Progress.md` update need is assessed
|
||||
- [ ] CHK013 `docs/design/00_Management/03_Task_Checklist.md` update need is assessed
|
||||
|
||||
## Final Review
|
||||
|
||||
- [ ] CHK014 Final summary lists modified files
|
||||
- [ ] CHK015 Final summary lists validation results
|
||||
- [ ] CHK016 Final summary lists remaining risks and next-step suggestions
|
||||
|
||||
## Notes
|
||||
|
||||
- Check items off as completed: `[x]`
|
||||
- Add comments or findings inline
|
||||
- Link to relevant resources or documentation
|
||||
- Items are numbered sequentially for easy reference
|
||||
50
.specify/templates/constitution-template.md
Normal file
50
.specify/templates/constitution-template.md
Normal file
@ -0,0 +1,50 @@
|
||||
# [PROJECT_NAME] Constitution
|
||||
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
|
||||
|
||||
## Core Principles
|
||||
|
||||
### [PRINCIPLE_1_NAME]
|
||||
<!-- Example: I. Library-First -->
|
||||
[PRINCIPLE_1_DESCRIPTION]
|
||||
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
|
||||
|
||||
### [PRINCIPLE_2_NAME]
|
||||
<!-- Example: II. CLI Interface -->
|
||||
[PRINCIPLE_2_DESCRIPTION]
|
||||
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
|
||||
|
||||
### [PRINCIPLE_3_NAME]
|
||||
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
|
||||
[PRINCIPLE_3_DESCRIPTION]
|
||||
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
|
||||
|
||||
### [PRINCIPLE_4_NAME]
|
||||
<!-- Example: IV. Integration Testing -->
|
||||
[PRINCIPLE_4_DESCRIPTION]
|
||||
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
|
||||
|
||||
### [PRINCIPLE_5_NAME]
|
||||
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
|
||||
[PRINCIPLE_5_DESCRIPTION]
|
||||
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
|
||||
|
||||
## [SECTION_2_NAME]
|
||||
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
|
||||
|
||||
[SECTION_2_CONTENT]
|
||||
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
|
||||
|
||||
## [SECTION_3_NAME]
|
||||
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
|
||||
|
||||
[SECTION_3_CONTENT]
|
||||
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
|
||||
|
||||
## Governance
|
||||
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
|
||||
|
||||
[GOVERNANCE_RULES]
|
||||
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
|
||||
|
||||
**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
|
||||
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
|
||||
77
.specify/templates/plan-template.md
Normal file
77
.specify/templates/plan-template.md
Normal file
@ -0,0 +1,77 @@
|
||||
# Implementation Plan: [FEATURE]
|
||||
|
||||
**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
|
||||
**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
|
||||
|
||||
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow.
|
||||
|
||||
## Summary
|
||||
|
||||
[Extract from feature spec: primary requirement + target documents + intended update approach]
|
||||
|
||||
## Technical Context
|
||||
|
||||
<!--
|
||||
ACTION REQUIRED: Replace this section with the real project context.
|
||||
For this repository, prefer documenting document-system context rather than
|
||||
inventing software implementation context.
|
||||
-->
|
||||
|
||||
**Primary Work Product**: [e.g., Markdown design docs, management docs, link/index governance or NEEDS CLARIFICATION]
|
||||
**Source of Truth Documents**: [List the authoritative docs that this change must align with]
|
||||
**Reference Sources**: [Archive/guides/other references allowed for verification]
|
||||
**Validation Commands**: [e.g., make validate-file FILE=..., make check-links, make validate-mermaid]
|
||||
**Target Scope**: [e.g., specific chapters, specific main docs, cross-doc governance]
|
||||
**Project Type**: 文档治理仓库
|
||||
**Constraints**: [e.g., no new parallel formal docs, no invented business rules, relative links only]
|
||||
**Scale/Scope**: [e.g., single document / cross-document / structural governance]
|
||||
|
||||
## Constitution Check
|
||||
|
||||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||||
|
||||
- [ ] **主文档归属已确认**：本次改动将优先落在既有主文档或治理文档，而不是新增平行正式稿。
|
||||
- [ ] **范围基线已确认**：若涉及新增功能、模块、接口或外部协同，已按 `03_Summary_Design.md` 与 Archive 范围基线交集完成判定。
|
||||
- [ ] **Archive 使用方式合规**：Archive 仅作为来源/核对输入，不直接替代正式口径。
|
||||
- [ ] **一致性影响已列出**：已识别系统名称、数据库口径、编号、图表、链接、术语等受影响项。
|
||||
- [ ] **校验与台账动作已规划**：已明确需要执行的校验命令，以及是否需要更新 `01_Project_Progress.md` / `03_Task_Checklist.md`。
|
||||
|
||||
## Project Structure
|
||||
|
||||
### Documentation (this feature)
|
||||
|
||||
```text
|
||||
specs/[###-feature]/
|
||||
├── plan.md # This file (/speckit.plan command output)
|
||||
├── research.md # Phase 0 output (/speckit.plan command)
|
||||
├── data-model.md # Optional: document entities/traceability objects
|
||||
├── quickstart.md # Optional: validation or review quickstart
|
||||
├── contracts/ # Optional: interface or section-level artifacts
|
||||
└── tasks.md # Phase 2 output (/speckit.tasks command)
|
||||
```
|
||||
|
||||
### Repository Touchpoints
|
||||
|
||||
```text
|
||||
docs/design/
|
||||
├── 00_Management/
|
||||
├── 01_Overview/
|
||||
├── 02_Detailed_Design/
|
||||
├── 03_Technical_Design/
|
||||
└── 04_Appendix/Archive/
|
||||
|
||||
README.md
|
||||
AGENTS.md
|
||||
.specify/templates/
|
||||
```
|
||||
|
||||
**Structure Decision**: [Document the exact files to be updated and the reason each file is in scope]
|
||||
|
||||
## Complexity Tracking
|
||||
|
||||
> **Fill ONLY if Constitution Check has violations that must be justified**
|
||||
|
||||
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
||||
|-----------|------------|-------------------------------------|
|
||||
| [e.g., temporary appendix doc] | [current need] | [why existing main doc could not safely absorb it] |
|
||||
| [e.g., Archive citation exception] | [specific traceability reason] | [why normal main-doc source was insufficient] |
|
||||
98
.specify/templates/spec-template.md
Normal file
98
.specify/templates/spec-template.md
Normal file
@ -0,0 +1,98 @@
|
||||
# Feature Specification: [FEATURE NAME]
|
||||
|
||||
**Feature Branch**: `[###-feature-name]`
|
||||
**Created**: [DATE]
|
||||
**Status**: Draft
|
||||
**Input**: User description: "$ARGUMENTS"
|
||||
|
||||
## Document Scope & Sources *(mandatory)*
|
||||
|
||||
- **Target documents**: [List the exact files intended to be updated]
|
||||
- **Primary source of truth**: [List the authoritative main docs]
|
||||
- **Reference sources**: [List allowed Archive/guides/supporting docs]
|
||||
- **Scope decision**: [State whether this request is in scope, needs confirmation, or is out of scope]
|
||||
|
||||
## User Scenarios & Testing *(mandatory)*
|
||||
|
||||
<!--
|
||||
For this repository, user stories should describe document-maintenance journeys
|
||||
that deliver independently reviewable value.
|
||||
-->
|
||||
|
||||
### User Story 1 - [Brief Title] (Priority: P1)
|
||||
|
||||
[Describe the document-maintenance user journey in plain language]
|
||||
|
||||
**Why this priority**: [Explain the value and why it has this priority level]
|
||||
|
||||
**Independent Test**: [Describe how this can be reviewed independently, e.g. by validating one target document and checking impacted links]
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
||||
2. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
||||
|
||||
---
|
||||
|
||||
### User Story 2 - [Brief Title] (Priority: P2)
|
||||
|
||||
[Describe this user journey in plain language]
|
||||
|
||||
**Why this priority**: [Explain the value and why it has this priority level]
|
||||
|
||||
**Independent Test**: [Describe how this can be tested independently]
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
||||
|
||||
---
|
||||
|
||||
### User Story 3 - [Brief Title] (Priority: P3)
|
||||
|
||||
[Describe this user journey in plain language]
|
||||
|
||||
**Why this priority**: [Explain the value and why it has this priority level]
|
||||
|
||||
**Independent Test**: [Describe how this can be tested independently]
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
||||
|
||||
---
|
||||
|
||||
### Edge Cases
|
||||
|
||||
- What happens when a requested change is only supported by Archive history but not by current main docs?
|
||||
- How does the workflow handle broken relative links, unstable anchors, or Mermaid syntax regressions introduced by edits?
|
||||
- What happens when one document changes numbering or terminology that affects other linked documents?
|
||||
|
||||
## Requirements *(mandatory)*
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- **FR-001**: Specification MUST identify the exact target documents that will be changed.
|
||||
- **FR-002**: Specification MUST identify the main source-of-truth documents that govern the change.
|
||||
- **FR-003**: Specification MUST record whether the request is in scope, requires confirmation, or is out of scope under the project range baseline.
|
||||
- **FR-004**: System MUST preserve the single-source-of-truth model and MUST NOT assume creation of new parallel formal documents unless explicitly approved.
|
||||
- **FR-005**: System MUST list the validation actions needed after the change, including file validation and any required link or Mermaid checks.
|
||||
- **FR-006**: System MUST state whether management ledgers need updates in `01_Project_Progress.md` and `03_Task_Checklist.md`.
|
||||
- **FR-007**: System MUST capture cross-document consistency impacts when terminology, numbering, diagrams, or references may change.
|
||||
|
||||
### Key Entities *(include if feature involves data)*
|
||||
|
||||
- **Target Document**: A Markdown file that will be modified as part of the request.
|
||||
- **Source of Truth Document**: A main document or governance document that constrains allowed conclusions.
|
||||
- **Reference Source**: Archive or guide material used only for verification, traceability, or scope judgment.
|
||||
- **Validation Action**: A command or review step that proves the document set remains consistent after change.
|
||||
- **Ledger Update**: A required change to project progress or task checklist records after important modifications.
|
||||
|
||||
## Success Criteria *(mandatory)*
|
||||
|
||||
### Measurable Outcomes
|
||||
|
||||
- **SC-001**: Every target document is explicitly named before implementation begins.
|
||||
- **SC-002**: Every completed change can be traced to at least one source-of-truth or approved reference source.
|
||||
- **SC-003**: Required validation actions are explicitly listed and can be executed without ambiguity.
|
||||
- **SC-004**: Reviewers can determine from the spec alone whether ledger updates and cross-document sync are required.
|
||||
131
.specify/templates/tasks-template.md
Normal file
131
.specify/templates/tasks-template.md
Normal file
@ -0,0 +1,131 @@
|
||||
---
|
||||
description: "Task list template for feature implementation"
|
||||
---
|
||||
|
||||
# Tasks: [FEATURE NAME]
|
||||
|
||||
**Input**: Design documents from `/specs/[###-feature-name]/`
|
||||
**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/
|
||||
|
||||
**Validation**: Validation tasks are NOT optional in this repository. Every document change task set MUST include the applicable validation and ledger-sync tasks.
|
||||
|
||||
**Organization**: Tasks are grouped by user story so each document-maintenance slice can be completed, reviewed, and validated independently.
|
||||
|
||||
## Format: `[ID] [P?] [Story] Description`
|
||||
|
||||
- **[P]**: Can run in parallel (different files, no dependencies)
|
||||
- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
|
||||
- Include exact file paths in descriptions
|
||||
|
||||
## Path Conventions
|
||||
|
||||
- Main documents: `docs/design/01_Overview/`, `docs/design/02_Detailed_Design/`, `docs/design/03_Technical_Design/`
|
||||
- Governance documents: `docs/design/00_Management/`
|
||||
- Archive references: `docs/design/04_Appendix/Archive/`
|
||||
- Runtime guidance: `README.md`, `AGENTS.md`, `.specify/templates/`
|
||||
|
||||
## Phase 1: Scope & Source Confirmation (Shared Foundation)
|
||||
|
||||
**Purpose**: Confirm the source-of-truth set and impact boundary before editing.
|
||||
|
||||
- [ ] T001 Confirm target documents and exact chapters from spec.md
|
||||
- [ ] T002 Confirm governing source-of-truth documents and allowed references
|
||||
- [ ] T003 [P] Record scope judgment (in scope / needs confirmation / out of scope)
|
||||
- [ ] T004 [P] Identify cross-document impacts: terminology, numbering, diagrams, links, ledger updates
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: User Story 1 - [Title] (Priority: P1) 🎯 MVP
|
||||
|
||||
**Goal**: [Brief description of the first independently reviewable document update]
|
||||
|
||||
**Independent Test**: [How to verify this story on its own]
|
||||
|
||||
### Implementation for User Story 1
|
||||
|
||||
- [ ] T005 [US1] Update target document in docs/design/... with the approved scope
|
||||
- [ ] T006 [US1] Sync affected anchors, references, numbering, or glossary terms in impacted docs
|
||||
- [ ] T007 [US1] Run `make validate-file FILE=<target-file>` and capture result
|
||||
- [ ] T008 [US1] Run any required cross-document validation (`make check-links`, `make validate-mermaid`) and capture result
|
||||
- [ ] T009 [US1] Update `docs/design/00_Management/01_Project_Progress.md` if the change is important
|
||||
- [ ] T010 [US1] Update `docs/design/00_Management/03_Task_Checklist.md` if a tracked task is completed or materially changed
|
||||
|
||||
**Checkpoint**: User Story 1 is reviewable, validated, and ledger-synced independently
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: User Story 2 - [Title] (Priority: P2)
|
||||
|
||||
**Goal**: [Brief description of the second independently reviewable update]
|
||||
|
||||
**Independent Test**: [How to verify this story on its own]
|
||||
|
||||
### Implementation for User Story 2
|
||||
|
||||
- [ ] T011 [US2] Update target document in docs/design/... with approved changes
|
||||
- [ ] T012 [US2] Sync affected references, diagrams, or traceability entries
|
||||
- [ ] T013 [US2] Run `make validate-file FILE=<target-file>` and capture result
|
||||
- [ ] T014 [US2] Run any additional required validation and capture result
|
||||
- [ ] T015 [US2] Update relevant management ledgers if applicable
|
||||
|
||||
**Checkpoint**: User Story 2 is reviewable and validated independently
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: User Story 3 - [Title] (Priority: P3)
|
||||
|
||||
**Goal**: [Brief description of the third independently reviewable update]
|
||||
|
||||
**Independent Test**: [How to verify this story on its own]
|
||||
|
||||
### Implementation for User Story 3
|
||||
|
||||
- [ ] T016 [US3] Update target document in docs/design/... with approved changes
|
||||
- [ ] T017 [US3] Sync affected supporting documents or guidance files
|
||||
- [ ] T018 [US3] Run `make validate-file FILE=<target-file>` and capture result
|
||||
- [ ] T019 [US3] Run any additional required validation and capture result
|
||||
- [ ] T020 [US3] Update relevant management ledgers if applicable
|
||||
|
||||
**Checkpoint**: All planned document updates are independently reviewable and validated
|
||||
|
||||
---
|
||||
|
||||
## Final Phase: Cross-Cutting Closure
|
||||
|
||||
**Purpose**: Ensure repository-wide consistency after all story slices are complete.
|
||||
|
||||
- [ ] T021 [P] Re-check source-of-truth alignment across all modified files
|
||||
- [ ] T022 [P] Re-check relative links, stable anchors, and Mermaid consistency across all modified files
|
||||
- [ ] T023 Prepare final summary with modified files, validation results, remaining risks, and next-step suggestions
|
||||
|
||||
---
|
||||
|
||||
## Dependencies & Execution Order
|
||||
|
||||
### Phase Dependencies
|
||||
|
||||
- **Scope & Source Confirmation**: No dependencies; MUST finish before content edits
|
||||
- **User Stories**: Depend on confirmed scope and sources
|
||||
- **Final Phase**: Depends on all selected user stories being complete
|
||||
|
||||
### Within Each User Story
|
||||
|
||||
- Update target document before syncing impacted documents
|
||||
- Complete content edits before validation
|
||||
- Complete validation before ledger updates are marked done
|
||||
- Complete ledger sync before final summary
|
||||
|
||||
### Parallel Opportunities
|
||||
|
||||
- Scope analysis tasks marked [P] can run in parallel
|
||||
- Different impacted supporting files can be updated in parallel if they do not touch the same file
|
||||
- Validation tasks for different files can run in parallel when commands are independent
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Every task set MUST preserve the single-source-of-truth model
|
||||
- Archive is for verification and traceability, not direct formal output replacement
|
||||
- Do not omit validation or ledger tasks when they apply
|
||||
- Avoid vague tasks; every task should name the file path and expected outcome
|
||||
Loading…
x
Reference in New Issue
Block a user