cc-devflow 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,507 @@
+# Changelog
+
+All notable changes to cc-devflow will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [2.3.0] - 2025-12-19
+
+### 🎯 REQ-005 完成：Command Emitter (Multi-Platform Adapter Compiler)
+
+v2.3.0 实现了命令模板编译器，将 `.claude/commands/*.md` 作为 SSOT 编译到 Codex/Cursor/Qwen/Antigravity 四个平台。
+
+#### Added - 核心功能
+
+- **`npm run adapt`** - 多平台命令编译器
+  - `--platform <name>`: 指定目标平台 (codex, cursor, qwen, antigravity)
+  - `--all`: 编译到所有平台 (默认)
+  - `--check`: 漂移检测，不执行编译
+  - `--skills`: 生成 skills-registry.json
+  - `--verbose`: 详细输出
+
+- **Parser 模块** (`lib/compiler/parser.js`)
+  - 使用 gray-matter 解析 frontmatter
+  - 检测占位符: `{SCRIPT:*}`, `{AGENT_SCRIPT}`, `$ARGUMENTS`
+  - 生成 SHA-256 hash 支持增量编译
+
+- **Transformer 模块** (`lib/compiler/transformer.js`)
+  - `{SCRIPT:alias}` → `"bash <path>"`
+  - `$ARGUMENTS` 平台映射: Qwen→`{{args}}`, Antigravity→`[arguments]`
+  - `{AGENT_SCRIPT}` + `__AGENT__` 替换
+
+- **Emitter 模块** (`lib/compiler/emitters/`)
+  - `codex-emitter.js`: `.codex/prompts/*.md` (YAML frontmatter)
+  - `cursor-emitter.js`: `.cursor/commands/*.md` (纯 Markdown)
+  - `qwen-emitter.js`: `.qwen/commands/*.toml` (TOML 格式)
+  - `antigravity-emitter.js`: `.agent/workflows/*.md` (12K 限制，自动拆分)
+
+- **Manifest 模块** (`lib/compiler/manifest.js`)
+  - 增量编译支持 (source/target hash 对比)
+  - 漂移检测 (`--check` 模式)
+  - 位置: `devflow/.generated/manifest.json`
+
+- **Skills Registry** (`lib/compiler/skills-registry.js`)
+  - 解析 `.claude/skills/` 目录
+  - 生成 `skills-registry.json`
+  - 支持 Markdown table 输出
+
+#### Added - 新增文件
+
+- `bin/adapt.js` - CLI 入口 (198 lines)
+- `lib/compiler/index.js` - 编译器入口 (161 lines)
+- `lib/compiler/parser.js` - 解析器 (170 lines)
+- `lib/compiler/transformer.js` - 转换器 (95 lines)
+- `lib/compiler/manifest.js` - Manifest 管理 (160 lines)
+- `lib/compiler/schemas.js` - Zod schemas (100 lines)
+- `lib/compiler/errors.js` - 错误类型 (100 lines)
+- `lib/compiler/skills-registry.js` - Skills 注册表 (101 lines)
+- `lib/compiler/emitters/*.js` - 4 个平台发射器
+- `lib/compiler/CLAUDE.md` - 架构文档
+
+#### Quality Metrics
+
+- **测试覆盖率**: 79.81% (目标 ≥80%)
+- **测试用例**: 203 passed
+- **性能**: 单文件 1.6ms, 全量 <200ms (远优于 100ms/5s 目标)
+
+---
+
+## [2.2.0] - 2025-12-16
+
+### 🎯 里程碑 M2 完成：质量左移 (Quality Left-Shift)
+
+v2.2.0 完成了里程碑 M2，实现了完整的质量左移流程，在需求澄清后、任务分解前引入质量门禁检查。
+
+#### Added - 核心功能
+
+- **`/flow-checklist`** - 需求质量检查命令
+  - 6 种 Checklist 类型 (ux, api, security, performance, data, general)
+  - 5 质量维度评估 (Completeness, Clarity, Consistency, Measurability, Coverage)
+  - Anti-Example 规则防止生成实现测试
+  - 80% 门禁阈值与 `/flow-epic` Entry Gate 集成
+  - 完成度计算脚本 (`calculate-checklist-completion.sh`)
+  - 可视化报告 (`--status` 表格输出)
+  - JSON 格式输出 (`--json` 参数)
+
+#### Added - 新增文件
+
+- `.claude/commands/flow-checklist.md` - 命令定义 (255 lines)
+- `.claude/agents/checklist-agent.md` - 生成逻辑 (175 lines)
+- `.claude/hooks/checklist-gate.js` - 门禁验证 (397 lines)
+- `.claude/scripts/calculate-checklist-completion.sh` - 完成度计算 (243 lines)
+- `.claude/scripts/checklist-errors.sh` - 错误码定义 (131 lines)
+- `.claude/docs/templates/CHECKLIST_TEMPLATE.md` - 输出模板 (52 lines)
+- `.claude/config/quality-rules.yml` - 质量规则配置 (161 lines)
+
+#### Changed - 功能增强
+
+- **`/flow-epic`** - 添加 Entry Gate 集成
+  - Step 5 Checklist Gate 自动检查 PRD 质量
+  - 支持 `--skip-gate --reason` 跳过门禁（需提供原因）
+  - 审计日志记录所有门禁跳过操作
+
+- **`.claude/skills/cc-devflow-orchestrator/SKILL.md`** - 工作流路由更新
+  - 添加 `/flow-checklist` 命令路由
+  - 更新工作流依赖关系
+
+#### Quality Metrics
+
+- **测试覆盖率**: 90% (26/29 AC covered)
+- **安全评分**: 96.75/100 (0 Critical, 0 High issues)
+- **User Stories**: 6/6 (100% delivered, including P2/P3 stories)
+- **Constitution Compliance**: PASS
+
+#### Technical Details
+
+- 检查规则存储: `.claude/config/quality-rules.yml`
+- Checklist 输出: `devflow/requirements/{REQ}/checklists/*.md`
+- 最低通过分数: 80% (可配置)
+- 技术栈: Bash, Node.js 18+, Claude API, YAML, Markdown
+
+---
+
+## [2.2.1] - 2025-12-16
+
+### ✨ 功能增强：分支命名优化
+
+v2.2.1 完成了 RM-003（M3 里程碑的一部分），增强了 Git 分支命名功能，支持中文特性名自动转换为拼音。
+
+#### Added - 核心功能
+
+- **中文转拼音分支命名支持**
+  - 在 `slugify()` 函数中集成 `pypinyin` 库
+  - 支持多音字智能选择（使用 `lazy_pinyin` 进行词组识别）
+  - 保留英文和数字字符
+  - 自动过滤特殊字符
+  - 100% 向后兼容（英文输入行为不变）
+
+#### Added - 新增函数
+
+- `_chinese_to_pinyin()` - 中文转拼音辅助函数
+  - 使用 Python `pypinyin` 库进行转换
+  - 支持词组级识别，优化多音字处理
+  - 缺失依赖时提供友好的警告信息
+
+#### Changed - 功能增强
+
+- **`slugify()` 函数增强**
+  - 自动检测中文字符（Unicode 范围 \u4e00-\u9fff）
+  - 中文输入时自动调用 `_chinese_to_pinyin()` 转换
+  - 转换结果与其他字符统一处理为 slug 格式
+
+#### Added - 测试覆盖
+
+- `.claude/tests/slugify.bats` - 完整的单元测试套件 (10 个测试用例)
+  - 英文输入兼容性测试（回归测试）
+  - 中文输入转换测试
+  - 混合输入处理测试
+  - 特殊字符过滤测试
+  - 多音字处理测试
+
+#### Changed - 文档更新
+
+- `README.md` - 添加 `pypinyin` 可选依赖说明
+- `.claude/commands/flow-dev.md` - 文档修正
+
+#### Technical Details
+
+- **依赖**: `pypinyin` (Python 库，可选安装)
+- **安装命令**: `pip install pypinyin`
+- **文件修改**: `.claude/scripts/common.sh` (+71 lines)
+- **测试文件**: `.claude/tests/slugify.bats` (+82 lines)
+- **向后兼容**: ✅ 100% 兼容现有英文分支命名
+
+#### Example
+
+```bash
+# 中文输入自动转换为拼音
+slugify "用户登录功能"  # => "yong-hu-deng-lu-gong-neng"
+
+# 混合输入处理
+slugify "OAuth2认证"    # => "oauth2-ren-zheng"
+
+# 英文输入行为不变（向后兼容）
+slugify "User Login"    # => "user-login"
+```
+
+---
+
+## [2.1.0] - 2025-11-07
+
+### 🏢 核心突破：引入项目级命令（Project-Level Commands）
+
+v2.1.0 的核心突破是引入了**项目级命令**，与之前的**需求级命令**形成两层体系：
+
+#### Added - 项目级命令
+
+**项目级命令** - 项目整体规划和架构设计（项目初期执行一次）
+
+- **`/flow-roadmap`** - 交互式产品路线图生成
+  - 6阶段交互式对话（愿景、用户、功能、技术、里程碑、指标）
+  - 生成 `devflow/ROADMAP.md` 和 `devflow/BACKLOG.md`
+  - 季度规划（Q1-Q4）和里程碑定义（M1-M8）
+  - Feature Roadmap 表格和 Implementation Tracking 表格
+
+- **`/flow-architecture`** - 系统架构设计与图生成
+  - 生成 4 种架构图（Mermaid 格式）
+    1. Feature Architecture（功能分层架构）
+    2. Technical Architecture（技术架构）
+    3. Module Structure（模块结构图）
+    4. Requirement Dependency（需求依赖关系）
+  - 生成 `devflow/ARCHITECTURE.md`
+
+- **`/flow-guidelines`** - 项目规范生成
+  - 基于 package.json 自动识别技术栈
+  - 生成 frontend-guidelines Skill（React/Vue/Angular等）
+  - 生成 backend-guidelines Skill（Node/Go/Python等）
+  - 包含编码规范、最佳实践、测试要求
+
+#### Added - 需求级命令增强
+
+**Stage 1.5: 路线图与架构上下文加载** (`/flow-init` 增强)
+
+- 初始化需求时自动检查 `ROADMAP.md` 存在性
+- 自动定位需求在路线图中的位置
+  - RM-ID (Roadmap Item ID)
+  - Milestone (M{n}-Q{q}-{yyyy})
+  - Quarter & Cluster
+- 自动加载 `ARCHITECTURE.md` 并显示架构上下文
+  - Feature Architecture Layer
+  - Technical Architecture (Tech Stack)
+  - Module Structure (Target Modules)
+
+#### Added - 新增代理
+
+- **`architecture-designer`** - 架构设计专家（4种架构图生成）
+- **`project-guidelines-generator`** - 项目规范生成器
+- **`roadmap-planner`** - 产品路线图规划师（已规划，待实现）
+
+#### Added - 新增脚本
+
+- `locate-requirement-in-roadmap.sh` - 从 ROADMAP.md 定位需求位置
+- `sync-roadmap-progress.sh` - 同步实际开发进度到路线图
+- `calculate-quarter.sh` - 计算日期对应的季度
+- `validate-hooks.sh` - 验证 Hooks 配置和执行权限
+- `check-dependencies.sh` - 检查项目依赖完整性
+
+#### Added - 新增模板
+
+- `ROADMAP_TEMPLATE.md` - 产品路线图模板
+- `ARCHITECTURE_TEMPLATE.md` - 架构设计模板
+- `BACKLOG_TEMPLATE.md` - 需求待办列表模板
+
+#### Changed - 文档改进
+
+- **README 完全重构**
+  - 从 2,101 行精简到 377 行（减少 82%）
+  - 使用 `<details>` 折叠非核心内容
+  - 添加完整目录（可点击锚点导航）
+  - 新增"核心概念"章节（Hooks 系统、Skills 系统）
+  - 大幅扩展"命令参考"章节
+    - 明确区分**项目级命令**和**需求级命令**
+    - 每个命令都有详细的使用说明
+    - 包含使用场景表（✅ 推荐 / ❌ 不推荐）
+    - 提供多个实际示例
+    - 说明预期输出
+    - 列出相关命令
+  - 新增"版本历史"章节
+  - 双语同步（中文/英文）
+
+- **新增 25+ 个详细文档**
+  - `docs/commands/*.md` - 13 个命令详细文档
+  - `docs/guides/*.md` - 5 个使用指南
+  - `docs/architecture/*.md` - 4 个架构文档
+  - `docs/examples/*.md` - 3 个示例文档
+
+#### Changed - 配置变更
+
+- `.claude/settings.json` 更新所有 hook 路径为 `.sh`
+- 新增 Skills 配置（roadmap-planner, architecture-designer）
+
+#### Fixed - Bug 修复
+
+- 修复 flow-init Stage 2.6 的 `populate-research-tasks.sh` 调用缺失问题
+- 修复 research.md TODO 占位符问题
+- 实施数据契约一致性
+
+---
+
+## [1.0.0] - 2025-09-25
+
+### 🎉 Major Updates
+
+#### Added - Constitution System v2.0.0
+
+- **10 Articles** governing quality, security, and architecture
+  1. Article I: Quality First
+  2. Article II: Security First
+  3. Article III: No Hardcoded Secrets
+  4. Article IV: Test-First Development
+  5. Article V: Deployment-First Integration
+  6. Article VI: Test Coverage Mandate
+  7. Article VII: No Code Duplication
+  8. Article VIII: Fail Fast
+  9. Article IX: Clear Error Messages
+  10. Article X: Requirement Boundary
+
+- **Phase -1 Constitutional Gates**
+  - Simplicity Gate（简洁性闸门）
+  - Anti-Abstraction Gate（反抽象闸门）
+  - Integration-First Gate（集成优先闸门）
+
+- **100% test coverage** (38/38 tests passed)
+- Automated compliance checking at every workflow stage
+- Amendment process with formal versioning and auto-propagation
+
+#### Added - Research Agent Model
+
+**Execution Model**: Research Agents + Main Agent
+
+- **11 Read-only Analysis Agents**
+  - prd-writer
+  - ui-designer (conditional)
+  - tech-architect
+  - planner
+  - dev-implementer
+  - qa-tester (called twice)
+  - security-reviewer (called twice)
+  - release-manager
+  - impact-analyzer
+  - compatibility-checker
+  - consistency-checker
+  - bug-analyzer
+
+- **Main Agent (Claude)** handles all code operations
+
+- **Clear Tool Distribution**
+  - Research Agents: Read, Grep, Glob (analysis only)
+  - Main Agent: Edit, Write, Bash, Git (execution)
+
+#### Added - Template-Driven Development
+
+**Self-Executable Templates**:
+
+- `PRD_TEMPLATE.md` - Product Requirements (10-step execution flow)
+- `UI_PROTOTYPE_TEMPLATE.md` - UI Prototype (Artistic design guidance)
+- `EPIC_TEMPLATE.md` - Epic Planning (10-step execution flow)
+- `TASKS_TEMPLATE.md` - Task Breakdown (TDD-ordered phases)
+- `INTENT_CLARIFICATION_TEMPLATE.md` - Intent-driven clarification flow
+
+**Template Usage**:
+1. Agent reads template
+2. Follows Execution Flow steps
+3. Generates complete document
+4. No placeholders left unfilled
+5. Passes Validation Checklist
+
+#### Added - Unified Script Infrastructure
+
+**Standardized Scripts** (`.claude/scripts/`):
+
+- `common.sh` - Core functions (log_event, get_repo_root)
+- `check-prerequisites.sh` - Prerequisites validation
+- `setup-epic.sh` - Epic/Tasks structure initialization
+- `check-task-status.sh` - Task status and progress tracking
+- `mark-task-complete.sh` - Task completion marking
+- `generate-status-report.sh` - Status report generation
+- `validate-constitution.sh` - Constitution compliance checking
+- `recover-workflow.sh` - Workflow recovery logic
+
+**Benefits**:
+- 100% test coverage
+- JSON output support (`--json` flag)
+- Consistent code paths across all agents
+- Easier maintenance and updates
+
+#### Added - Quality Gates & Hooks
+
+**Quality Gates**:
+- Pre-push Guard (TypeScript, tests, linting, security, build)
+- Constitution Compliance (enforced at every stage)
+- TDD Checkpoint (TEST VERIFICATION CHECKPOINT)
+- Markdown Formatter (automatic documentation formatting)
+- Conventional Commits (standardized commit message format)
+
+**Hooks System**:
+- PreToolUse Hook - Block non-compliant operations (real-time)
+- PostToolUse Hook - Auto-record file changes
+- UserPromptSubmit Hook - Intelligent skill recommendations
+- Stop Hook - Error handling hints
+
+#### Added - Core Commands
+
+**Requirement Management**:
+- `/flow-new` - Start new requirement development (full flow)
+- `/flow-init` - Initialize requirement structure
+- `/flow-status` - Query development progress
+- `/flow-restart` - Resume interrupted development
+- `/flow-update` - Update task progress
+
+**Quality Assurance**:
+- `/flow-verify` - Verify document consistency
+- `/flow-qa` - Execute quality assurance
+- `/flow-constitution` - Manage Constitution compliance
+
+**Tools**:
+- `/flow-fix` - One-command bug fix flow
+- `/flow-ideate` - Intent-driven requirement development
+- `/flow-upgrade` - PRD version management
+- `/flow-release` - Create release
+
+#### Added - Single-Track Architecture
+
+**Philosophy**: Keep one canonical workspace per requirement
+
+```
+devflow/requirements/REQ-123/
+├── orchestration_status.json  # Single source of truth
+├── EXECUTION_LOG.md           # Audit trail
+├── PRD.md
+├── EPIC.md
+├── TASKS.md                   # Single unified task list
+├── tasks/                     # Task artifacts
+├── research/                  # External references
+├── TEST_PLAN.md
+├── TEST_REPORT.md
+├── SECURITY_PLAN.md
+└── SECURITY_REPORT.md
+```
+
+#### Added - Testing Framework
+
+**100% Test Coverage**:
+
+**Script Test Suites** (8/8 Passed):
+- test_check_prerequisites (18 tests)
+- test_check_task_status (18 tests)
+- test_common (15 tests)
+- test_mark_task_complete (15 tests)
+- test_setup_epic (13 tests)
+- test_validate_constitution (4 tests)
+
+**Constitution Test Suites** (4/4 Passed):
+- test_version_consistency (5 tests)
+- test_article_coverage (10 tests)
+- test_template_completeness (10 tests)
+- test_agent_assignment (13 tests)
+
+**Total**: 38/38 tests passed ✅
+
+#### Added - Three-Layer Information Architecture
+
+**Constitution Layer** (Immutable Principles):
+- 10 Articles + Phase -1 Gates
+- Quality gates and compliance standards
+- Highest authority
+
+**Guides Layer** (Operational How-To):
+- Workflow SOPs
+- Technical operation guides
+- Agent coordination protocols
+
+**Rules Layer** (Project Conventions):
+- Core Patterns (4 fundamental principles)
+- DevFlow Conventions (CC-DevFlow specific)
+
+**Benefits**:
+- 55% reduction in rules context (~100KB tokens saved)
+- Clear separation of concerns
+- Easy maintenance
+- Scalable for 10+ years
+
+---
+
+## [0.9.0] - 2025-09-10 (Beta)
+
+### Added
+
+- Initial beta release
+- Basic workflow commands (`/flow-new`, `/flow-init`)
+- PRD and EPIC generation
+- Basic quality gates
+- Git integration
+
+### Known Issues
+
+- No Constitution system
+- Manual task tracking
+- Limited test coverage
+- No consistency verification
+
+---
+
+## Future Releases
+
+See [ROADMAP.md](devflow/ROADMAP.md) for planned features and improvements.
+
+---
+
+## Links
+
+- [GitHub Repository](https://github.com/Dimon94/cc-devflow)
+- [Documentation](docs/)
+- [Contributing](CONTRIBUTING.md)
+- [License](LICENSE)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CC-DevFlow Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.