cc-devflow 2.4.6 → 4.1.0

package/.claude/docs/templates/_shared/CONSTITUTION_CHECK.md

@@ -0,0 +1,125 @@
+# Constitution Check Template Component
+
+> **Purpose**: Shared Constitution compliance check section for PRD/EPIC/TECH_DESIGN templates
+> **Version**: 1.0.0
+> **Reference**: `.claude/rules/project-constitution.md` (v2.1.0)
+
+---
+
+## Usage
+
+Include this component in templates via reference:
+```markdown
+{{INCLUDE: _shared/CONSTITUTION_CHECK.md}}
+```
+
+Or copy relevant sections based on document type.
+
+---
+
+## Constitution Check (宪法符合性检查)
+
+*GATE: 必须在下一阶段前通过*
+
+### Article I: Quality First (质量至上)
+
+- [ ] **I.1 - NO PARTIAL IMPLEMENTATION**: 内容完整且明确？无占位符和模糊表述？
+- [ ] **I.2 - Testing Mandate**: 测试策略明确？覆盖率目标 ≥80%？
+- [ ] **I.3 - No Simplification**: 避免"暂时简化，后续完善"的描述？
+- [ ] **I.4 - Quality Gates**: 验收标准具体、可测试、可衡量？
+
+### Article II: Architectural Consistency (架构一致性)
+
+- [ ] **II.1 - NO CODE DUPLICATION**: 识别可复用的现有系统和组件？
+- [ ] **II.2 - Consistent Naming**: 命名约定遵循现有代码库模式？
+- [ ] **II.3 - Anti-Over-Engineering**: 解决方案适合问题规模？无过度设计？
+- [ ] **II.4 - Single Responsibility**: 清晰的边界和职责划分？
+
+### Article III: Security First (安全优先)
+
+- [ ] **III.1 - NO HARDCODED SECRETS**: 定义了密钥管理策略（环境变量/密钥服务）？
+- [ ] **III.2 - Input Validation**: 输入验证需求明确？
+- [ ] **III.3 - Least Privilege**: 身份验证/授权机制清晰？
+- [ ] **III.4 - Secure by Default**: 数据加密策略定义？
+
+### Article IV: Performance Accountability (性能责任)
+
+- [ ] **IV.1 - NO RESOURCE LEAKS**: 考虑了资源管理（连接、文件句柄等）？
+- [ ] **IV.2 - Algorithm Efficiency**: 性能目标现实且可测量？
+- [ ] **IV.3 - Lazy Loading**: 按需加载策略规划？
+- [ ] **IV.4 - Caching Strategy**: 规划了监控和缓存策略？
+
+### Article V: Maintainability (可维护性)
+
+- [ ] **V.1 - NO DEAD CODE**: 避免不必要的功能？仅实现明确需求？
+- [ ] **V.2 - Separation of Concerns**: 代码易于理解和修改？
+- [ ] **V.3 - Documentation**: 文档完整（架构、API、配置）？
+- [ ] **V.4 - File Size Limits**: 遵循单一职责原则？单文件 ≤500行？
+
+### Article VI: Test-First Development (测试优先开发)
+
+- [ ] **VI.1 - TDD Mandate**: TDD 流程明确定义？
+- [ ] **VI.2 - Test Independence**: 测试隔离策略定义？
+- [ ] **VI.3 - Meaningful Tests**: 测试质量标准明确？
+
+### Article X: Requirement Boundary (需求边界)
+
+- [ ] **X.1 - Forced Clarification**: 所有不明确之处标记 `[NEEDS CLARIFICATION]`？
+- [ ] **X.2 - No Speculative Features**: 无"可能需要"、"未来会"、"建议添加"的功能？
+- [ ] **X.3 - User Story Independence**: 每个故事有明确优先级和独立测试标准？
+
+---
+
+## Phase -1 Gates (前置闸门)
+
+*仅适用于 EPIC/TECH_DESIGN*
+
+### Simplicity Gate (Article VII)
+
+- [ ] **项目数量**: 使用 ≤3 个项目/模块？
+- [ ] **NO FUTURE-PROOFING**: 没有为"未来可能需要"的功能做准备？
+- [ ] **Minimal Dependencies**: 只使用必需的依赖库？
+
+### Anti-Abstraction Gate (Article VIII)
+
+- [ ] **Framework Trust**: 直接使用框架功能，没有封装？
+- [ ] **Single Model Representation**: 实体只有一种数据表示？
+- [ ] **No Unnecessary Interfaces**: 没有单一实现的接口？
+
+### Integration-First Gate (Article IX)
+
+- [ ] **Contracts Defined First**: API contracts 在实现前定义？
+- [ ] **Contract Tests Planned**: Contract tests 在 Phase 2 计划？
+- [ ] **Real Environment**: 使用真实数据库而非 mocks？
+
+---
+
+## Constitutional Violations (宪法违规记录)
+
+*仅在有需要说明的宪法违规时填写*
+
+**重要**: 任何违规都必须有充分理由，否则文档不通过
+
+| 违规的 Article | 具体违规内容 | 为何需要 | 缓解措施 |
+|----------------|-------------|----------|----------|
+| {{ARTICLE_NUM}} | {{VIOLATION_DETAIL}} | {{JUSTIFICATION}} | {{MITIGATION}} |
+
+---
+
+## Gate Status Summary
+
+| Gate | Status | Notes |
+|------|--------|-------|
+| Article I-V Core | {{PASS/FAIL}} | {{NOTES}} |
+| Article VI TDD | {{PASS/FAIL}} | {{NOTES}} |
+| Article VII Simplicity | {{PASS/FAIL}} | {{NOTES}} |
+| Article VIII Anti-Abstraction | {{PASS/FAIL}} | {{NOTES}} |
+| Article IX Integration-First | {{PASS/FAIL}} | {{NOTES}} |
+| Article X Boundary | {{PASS/FAIL}} | {{NOTES}} |
+
+**Overall Status**: {{PASS/FAIL}}
+**Ready for Next Phase**: {{YES/NO}}
+
+---
+
+[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/docs/templates/_shared/VALIDATION_CHECKLIST.md

@@ -0,0 +1,187 @@
+# Validation Checklist Template Component
+
+> **Purpose**: Shared validation checklist section for all spec templates
+> **Version**: 1.0.0
+> **Usage**: Include relevant sections based on document type
+
+---
+
+## Usage
+
+Include this component in templates via reference:
+```markdown
+{{INCLUDE: _shared/VALIDATION_CHECKLIST.md#prd}}
+{{INCLUDE: _shared/VALIDATION_CHECKLIST.md#epic}}
+{{INCLUDE: _shared/VALIDATION_CHECKLIST.md#tech}}
+{{INCLUDE: _shared/VALIDATION_CHECKLIST.md#ui}}
+```
+
+---
+
+## Common Validation Items
+
+### Content Completeness
+
+- [ ] 所有必需章节已填写
+- [ ] 没有 {{PLACEHOLDER}} 未替换
+- [ ] 没有 TODO 或 TBD 标记
+- [ ] 所有引用的文件存在
+
+### Quality Standards
+
+- [ ] 语言清晰、无歧义
+- [ ] 格式一致、结构清晰
+- [ ] 无重复内容
+- [ ] 无矛盾描述
+
+### Constitution Compliance
+
+- [ ] 通过所有宪法检查
+- [ ] 违规已文档化并说明理由
+- [ ] 安全要求符合 NO HARDCODED SECRETS
+- [ ] 质量要求符合 NO PARTIAL IMPLEMENTATION
+
+---
+
+## PRD-Specific Validation {#prd}
+
+### 需求不扩散验证
+
+- [ ] **NO SPECULATION**: 所有功能都由用户明确提出或必需
+- [ ] **ALL CLARIFIED**: 没有未解决的 [NEEDS CLARIFICATION] 标记
+- [ ] **NO TECH DETAILS**: 没有技术实现细节（API, 数据库, 框架等）
+- [ ] **STORY INDEPENDENCE**: 每个故事都有 Independent Test 标准
+- [ ] **PRIORITY ASSIGNED**: 所有故事都有明确优先级 (P1, P2, P3...)
+- [ ] **MVP IDENTIFIED**: P1 故事能够作为独立 MVP 交付
+
+### 用户故事质量 (INVEST 原则)
+
+- [ ] **Independent**: 每个故事可独立交付和测试
+- [ ] **Negotiable**: 细节可以讨论，实现方式灵活
+- [ ] **Valuable**: 有明确的用户/业务价值
+- [ ] **Estimable**: 可以估算工作量
+- [ ] **Small**: 可在一个迭代内完成
+- [ ] **Testable**: 有明确的验收标准和测试方法
+
+### 验收标准质量
+
+- [ ] 使用 Given-When-Then 格式
+- [ ] 包含正常流程（Happy Path）
+- [ ] 包含边界情况（Edge Cases）
+- [ ] 包含错误场景（Error Handling）
+- [ ] 具体且可测试（非模糊描述）
+
+---
+
+## EPIC-Specific Validation {#epic}
+
+### PRD 对齐
+
+- [ ] 所有用户故事已映射到 Epic
+- [ ] 所有验收标准已包含
+- [ ] 成功指标与 PRD 一致
+- [ ] 技术约束已考虑
+
+### 技术方案完整性
+
+- [ ] 架构设计清晰
+- [ ] 数据模型完整
+- [ ] API 契约定义
+- [ ] 技术栈选型合理
+
+### TDD 准备
+
+- [ ] Phase 2 明确定义为"Tests First"
+- [ ] TEST VERIFICATION CHECKPOINT 已标记
+- [ ] 测试策略明确
+- [ ] Phase 3 依赖 Phase 2 完成
+
+### 可执行性
+
+- [ ] 实施阶段清晰
+- [ ] 依赖已识别
+- [ ] 资源需求明确
+- [ ] 风险已评估
+
+---
+
+## TECH_DESIGN-Specific Validation {#tech}
+
+### 技术完整性
+
+- [ ] **Section 1**: System Architecture - Complete
+- [ ] **Section 2**: Technology Stack - Complete with versions
+- [ ] **Section 3**: Data Model Design - Complete
+- [ ] **Section 4**: API Design - Complete
+- [ ] **Section 5**: Security Design - Complete
+- [ ] **Section 6**: Performance Design - Complete
+- [ ] **Section 7**: Constitution Check - Complete
+
+### 技术规范
+
+- [ ] 所有技术都有具体版本号
+- [ ] 所有表都有主键和关系定义
+- [ ] 所有 API 端点都有请求/响应 schema
+- [ ] 所有密钥使用环境变量
+
+### Baseline Adherence
+
+- [ ] 所有 baseline 技术已复用
+- [ ] 所有新技术都有 PRD 需求支撑
+- [ ] 无不必要的重构
+
+---
+
+## UI_PROTOTYPE-Specific Validation {#ui}
+
+### Anti-Generic-Design
+
+- [ ] 无占位图片（所有图片使用 Picsum URL）
+- [ ] 无常见 AI 紫色/蓝色配色
+- [ ] 无 Emoji 图标（使用 SVG 或图标库）
+- [ ] 无 Lorem Ipsum 占位文本
+
+### 设计系统
+
+- [ ] 色彩系统完整（主/辅/中性/状态）
+- [ ] 字体系统支持中英文混排
+- [ ] 间距系统基于统一基准
+- [ ] 响应式断点定义（至少 3 个）
+
+### 交互完整性
+
+- [ ] SPA 路由系统正常工作
+- [ ] 所有按钮/链接有点击交互
+- [ ] 表单有验证逻辑
+- [ ] 模态框可打开/关闭
+
+### 响应式
+
+- [ ] 在 320px 宽度下页面可用
+- [ ] 在 768px 宽度下页面可用
+- [ ] 在 1280px 宽度下页面可用
+- [ ] 所有 Touch Targets ≥ 44px
+
+---
+
+## Progress Tracking
+
+### 完成状态
+
+- [ ] 所有必需章节完成
+- [ ] Constitution Check 通过
+- [ ] 质量检查通过
+
+### 闸门状态
+
+| Gate | Status |
+|------|--------|
+| Constitution Check | {{PASS/FAIL}} |
+| Completeness | {{PASS/FAIL}} |
+| Quality | {{PASS/FAIL}} |
+
+**Ready for Next Phase**: {{YES/NO}}
+
+---
+
+[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/docs/templates/_shared/YAML_FRONTMATTER.md

@@ -0,0 +1,164 @@
+# YAML Frontmatter Template Component
+
+> **Purpose**: Shared YAML frontmatter patterns for all spec documents
+> **Version**: 1.0.0
+> **Usage**: Copy relevant frontmatter based on document type
+
+---
+
+## Usage
+
+Select the appropriate frontmatter template based on document type.
+
+---
+
+## PRD Frontmatter
+
+```yaml
+---
+req_id: "{{REQ_ID}}"
+title: "{{TITLE}}"
+type: "PRD"
+status: "Draft"
+created_at: "{{ISO_8601_TIMESTAMP}}"
+updated_at: "{{ISO_8601_TIMESTAMP}}"
+version: "1.0.0"
+author: "prd-writer"
+constitution_version: "v2.1.0"
+---
+```
+
+---
+
+## TECH_DESIGN Frontmatter
+
+```yaml
+---
+req_id: "{{REQ_ID}}"
+title: "{{TITLE}}"
+type: "Technical Design"
+status: "Draft"
+created_at: "{{ISO_8601_TIMESTAMP}}"
+updated_at: "{{ISO_8601_TIMESTAMP}}"
+version: "1.0.0"
+author: "tech-architect"
+constitution_version: "v2.1.0"
+baseline_tech_stack:
+  frontend: "{{BASELINE_FRONTEND}}"
+  backend: "{{BASELINE_BACKEND}}"
+  database: "{{BASELINE_DATABASE}}"
+---
+```
+
+---
+
+## EPIC Frontmatter
+
+```yaml
+---
+req_id: "{{REQ_ID}}"
+title: "{{TITLE}}"
+type: "Epic"
+status: "Planned"
+created_at: "{{ISO_8601_TIMESTAMP}}"
+updated_at: "{{ISO_8601_TIMESTAMP}}"
+version: "1.0.0"
+author: "planner"
+constitution_version: "v2.1.0"
+phases:
+  - name: "Setup"
+    status: "pending"
+  - name: "Tests First"
+    status: "pending"
+  - name: "Implementation"
+    status: "pending"
+  - name: "Integration"
+    status: "pending"
+  - name: "Polish"
+    status: "pending"
+---
+```
+
+---
+
+## UI_PROTOTYPE Frontmatter (HTML Comment)
+
+```html
+<!--
+Generated: {{ISO_8601_TIMESTAMP}}
+REQ-ID: {{REQ_ID}}
+Title: {{TITLE}}
+Type: UI Prototype
+Version: 1.0.0
+Author: ui-designer
+
+Design Inspirations:
+  - Inspiration 1: {{ARTIST_1}} ({{CATEGORY}})
+  - Inspiration 2: {{ARTIST_2}} ({{CATEGORY}})
+
+Design System:
+  Primary Color: {{PRIMARY_COLOR}}
+  Font Family: {{FONT_FAMILY}}
+  Base Spacing: {{BASE_SPACING}}
+
+Responsive Breakpoints:
+  Mobile: 320px - 767px
+  Tablet: 768px - 1023px
+  Desktop: 1024px+
+
+Constitution Check: {{PASS/FAIL}}
+-->
+```
+
+---
+
+## TASKS Frontmatter
+
+```yaml
+---
+req_id: "{{REQ_ID}}"
+title: "{{TITLE}}"
+type: "Tasks"
+status: "In Progress"
+created_at: "{{ISO_8601_TIMESTAMP}}"
+updated_at: "{{ISO_8601_TIMESTAMP}}"
+version: "1.0.0"
+author: "planner"
+total_tasks: {{TOTAL}}
+completed_tasks: {{COMPLETED}}
+progress: "{{PERCENTAGE}}%"
+current_phase: "{{PHASE_NAME}}"
+---
+```
+
+---
+
+## Common Fields Reference
+
+| Field | Type | Description | Required |
+|-------|------|-------------|----------|
+| `req_id` | string | Requirement ID (REQ-XXX) | Yes |
+| `title` | string | Document title | Yes |
+| `type` | string | Document type | Yes |
+| `status` | string | Draft/Planned/In Progress/Complete | Yes |
+| `created_at` | string | ISO 8601 timestamp | Yes |
+| `updated_at` | string | ISO 8601 timestamp | Yes |
+| `version` | string | Semantic version | Yes |
+| `author` | string | Agent or person name | Yes |
+| `constitution_version` | string | Constitution version | Recommended |
+
+---
+
+## Status Values
+
+| Status | Description | Applicable To |
+|--------|-------------|---------------|
+| `Draft` | Initial creation, not reviewed | PRD, TECH_DESIGN |
+| `Planned` | Reviewed and approved | EPIC |
+| `In Progress` | Currently being worked on | TASKS |
+| `Complete` | All work finished | All |
+| `Archived` | No longer active | All |
+
+---
+
+[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/docs/templates/context/dev.jsonl.template

@@ -0,0 +1,6 @@
+{"type": "file", "path": "TASKS.md", "purpose": "Current task list and progress"}
+{"type": "file", "path": "EPIC.md", "purpose": "Epic overview and phases"}
+{"type": "file", "path": "TECH_DESIGN.md", "purpose": "Technical implementation guide"}
+{"type": "file", "path": "ERROR_LOG.md", "purpose": "Previous errors to avoid", "optional": true}
+{"type": "spec", "path": "devflow/spec/frontend/style.md", "purpose": "Frontend style guide", "optional": true}
+{"type": "spec", "path": "devflow/spec/backend/api.md", "purpose": "Backend API conventions", "optional": true}

package/.claude/docs/templates/context/epic.jsonl.template

@@ -0,0 +1,5 @@
+{"type": "file", "path": "PRD.md", "purpose": "Product requirements for task breakdown"}
+{"type": "file", "path": "TECH_DESIGN.md", "purpose": "Technical design decisions"}
+{"type": "file", "path": "data-model.md", "purpose": "Data structures"}
+{"type": "directory", "path": "contracts/", "purpose": "API contracts"}
+{"type": "file", "path": "UI_PROTOTYPE.html", "purpose": "UI prototype reference", "optional": true}

package/.claude/docs/templates/context/prd.jsonl.template

@@ -0,0 +1,4 @@
+{"type": "file", "path": "BRAINSTORM.md", "purpose": "Original intent and design decisions"}
+{"type": "file", "path": "research/research-summary.md", "purpose": "Research findings summary"}
+{"type": "file", "path": "research/internal/codebase-overview.md", "purpose": "Existing codebase patterns"}
+{"type": "spec", "path": "devflow/spec/shared/naming.md", "purpose": "Naming conventions"}

package/.claude/docs/templates/context/research.jsonl.template

@@ -0,0 +1,4 @@
+{"type": "file", "path": "research/research.md", "purpose": "Research findings and analysis"}
+{"type": "file", "path": "research/research-summary.md", "purpose": "Condensed research summary"}
+{"type": "file", "path": "research/internal/codebase-overview.md", "purpose": "Codebase structure analysis"}
+{"type": "directory", "path": "research/mcp/", "purpose": "MCP-fetched documentation", "depth": 2}

package/.claude/docs/templates/context/review.jsonl.template

@@ -0,0 +1,5 @@
+{"type": "file", "path": "PRD.md", "purpose": "Requirements to verify against"}
+{"type": "file", "path": "TASKS.md", "purpose": "Completed tasks to review"}
+{"type": "file", "path": "TECH_DESIGN.md", "purpose": "Design decisions to validate"}
+{"type": "directory", "path": "contracts/", "purpose": "API contracts to verify"}
+{"type": "file", "path": "ERROR_LOG.md", "purpose": "Known issues", "optional": true}

package/.claude/docs/templates/context/tech.jsonl.template

@@ -0,0 +1,5 @@
+{"type": "file", "path": "PRD.md", "purpose": "Product requirements"}
+{"type": "file", "path": "BRAINSTORM.md", "purpose": "Original intent alignment"}
+{"type": "file", "path": "research/internal/codebase-overview.md", "purpose": "Existing architecture"}
+{"type": "spec", "path": "devflow/spec/backend/api.md", "purpose": "API conventions"}
+{"type": "spec", "path": "devflow/spec/shared/security.md", "purpose": "Security standards"}