cc-devflow 4.1.5 → 4.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. package/.claude/CLAUDE.md +87 -1091
  2. package/.claude/commands/core/architecture.md +2 -2
  3. package/.claude/commands/core/guidelines.md +2 -2
  4. package/.claude/commands/core/roadmap.md +4 -4
  5. package/.claude/commands/core/style.md +40 -268
  6. package/.claude/commands/flow/CLAUDE.md +28 -0
  7. package/.claude/commands/flow/archive.md +2 -2
  8. package/.claude/commands/flow/checklist.md +9 -251
  9. package/.claude/commands/flow/clarify.md +9 -127
  10. package/.claude/commands/flow/constitution.md +1 -1
  11. package/.claude/commands/flow/context.md +1 -1
  12. package/.claude/commands/flow/dev.md +19 -395
  13. package/.claude/commands/flow/ideate.md +13 -13
  14. package/.claude/commands/flow/init.md +19 -30
  15. package/.claude/commands/flow/new.md +12 -268
  16. package/.claude/commands/flow/quality.md +10 -153
  17. package/.claude/commands/flow/release.md +18 -81
  18. package/.claude/commands/flow/restart.md +15 -16
  19. package/.claude/commands/flow/spec.md +14 -164
  20. package/.claude/commands/flow/status.md +12 -12
  21. package/.claude/commands/flow/update.md +4 -4
  22. package/.claude/commands/flow/upgrade.md +6 -6
  23. package/.claude/commands/flow/verify.md +19 -78
  24. package/.claude/commands/flow/workspace.md +1 -1
  25. package/.claude/docs/guides/INIT_TROUBLESHOOTING.md +7 -7
  26. package/.claude/docs/guides/NEW_TROUBLESHOOTING.md +44 -96
  27. package/.claude/docs/guides/ROADMAP_TROUBLESHOOTING.md +1 -1
  28. package/.claude/docs/guides/TASK_COMPLETION_MARKING.md +5 -5
  29. package/.claude/docs/templates/ATTEMPT_TEMPLATE.md +1 -1
  30. package/.claude/docs/templates/BACKLOG_TEMPLATE.md +3 -3
  31. package/.claude/docs/templates/CLARIFICATION_REPORT_TEMPLATE.md +5 -5
  32. package/.claude/docs/templates/ERROR_LOG_TEMPLATE.md +2 -2
  33. package/.claude/docs/templates/INIT_FLOW_TEMPLATE.md +3 -3
  34. package/.claude/docs/templates/NEW_ORCHESTRATION_TEMPLATE.md +33 -64
  35. package/.claude/docs/templates/RESEARCH_TEMPLATE.md +3 -3
  36. package/.claude/docs/templates/ROADMAP_DIALOGUE_TEMPLATE.md +2 -2
  37. package/.claude/docs/templates/ROADMAP_TEMPLATE.md +2 -2
  38. package/.claude/docs/templates/STYLE_TEMPLATE.md +3 -3
  39. package/.claude/docs/templates/UI_PROTOTYPE_TEMPLATE.md +8 -9
  40. package/.claude/guides/workflow-guides/flow-orchestrator.md +31 -265
  41. package/.claude/hooks/CLAUDE.md +1 -1
  42. package/.claude/hooks/checklist-gate.js +4 -4
  43. package/.claude/hooks/inject-agent-context.ts +2 -2
  44. package/.claude/scripts/calculate-checklist-completion.sh +2 -2
  45. package/.claude/scripts/check-prerequisites.sh +2 -2
  46. package/.claude/scripts/checklist-errors.sh +4 -4
  47. package/.claude/scripts/flow-quality-full.sh +5 -5
  48. package/.claude/scripts/flow-quality-quick.sh +4 -4
  49. package/.claude/scripts/flow-workspace-init.sh +2 -2
  50. package/.claude/scripts/generate-clarification-report.sh +4 -4
  51. package/.claude/scripts/recover-workflow.sh +70 -73
  52. package/.claude/scripts/run-quality-gates.sh +1 -1
  53. package/.claude/scripts/setup-epic.sh +2 -2
  54. package/.claude/scripts/setup-ralph-loop.sh +2 -2
  55. package/.claude/scripts/validate-research.sh +1 -1
  56. package/.claude/scripts/verify-setup.sh +1 -1
  57. package/.claude/skills/cc-devflow-orchestrator/SKILL.md +88 -108
  58. package/.claude/skills/workflow/CLAUDE.md +24 -0
  59. package/.claude/skills/workflow/flow-dev/CLAUDE.md +14 -76
  60. package/.claude/skills/workflow/flow-dev/SKILL.md +29 -67
  61. package/.claude/skills/workflow/flow-dev/context.jsonl +4 -8
  62. package/.claude/skills/workflow/flow-init/SKILL.md +24 -151
  63. package/.claude/skills/workflow/flow-init/assets/RESEARCH_TEMPLATE.md +1 -1
  64. package/.claude/skills/workflow/flow-init/context.jsonl +3 -3
  65. package/.claude/skills/workflow/flow-init/scripts/check-prerequisites.sh +1 -1
  66. package/.claude/skills/workflow/flow-init/scripts/validate-research.sh +1 -1
  67. package/.claude/skills/workflow/flow-release/SKILL.md +23 -56
  68. package/.claude/skills/workflow/flow-release/context.jsonl +5 -7
  69. package/.claude/skills/workflow/flow-spec/CLAUDE.md +15 -101
  70. package/.claude/skills/workflow/flow-spec/SKILL.md +15 -518
  71. package/.claude/skills/workflow/flow-spec/context.jsonl +5 -7
  72. package/.claude/skills/workflow/flow-verify/CLAUDE.md +10 -0
  73. package/.claude/skills/workflow/flow-verify/SKILL.md +53 -0
  74. package/.claude/skills/workflow/flow-verify/context.jsonl +5 -0
  75. package/.claude/skills/workflow.yaml +72 -267
  76. package/CHANGELOG.md +31 -0
  77. package/README.md +91 -69
  78. package/README.zh-CN.md +90 -67
  79. package/bin/harness.js +22 -0
  80. package/docs/commands/README.md +34 -38
  81. package/docs/commands/README.zh-CN.md +34 -36
  82. package/docs/commands/core-roadmap.md +2 -2
  83. package/docs/commands/core-roadmap.zh-CN.md +2 -2
  84. package/docs/commands/core-style.md +29 -381
  85. package/docs/commands/core-style.zh-CN.md +29 -381
  86. package/docs/commands/flow-init.md +10 -10
  87. package/docs/commands/flow-init.zh-CN.md +11 -11
  88. package/docs/commands/flow-new.md +25 -260
  89. package/docs/commands/flow-new.zh-CN.md +26 -257
  90. package/docs/guides/getting-started.md +16 -15
  91. package/docs/guides/getting-started.zh-CN.md +10 -12
  92. package/lib/compiler/__tests__/manifest.test.js +156 -0
  93. package/lib/compiler/__tests__/parser.test.js +21 -0
  94. package/lib/compiler/index.js +17 -1
  95. package/lib/compiler/manifest.js +68 -6
  96. package/lib/compiler/parser.js +5 -0
  97. package/lib/harness/CLAUDE.md +21 -0
  98. package/lib/harness/cli.js +208 -0
  99. package/lib/harness/index.js +16 -0
  100. package/lib/harness/operations/dispatch.js +285 -0
  101. package/lib/harness/operations/init.js +48 -0
  102. package/lib/harness/operations/janitor.js +74 -0
  103. package/lib/harness/operations/pack.js +100 -0
  104. package/lib/harness/operations/plan.js +29 -0
  105. package/lib/harness/operations/release.js +83 -0
  106. package/lib/harness/operations/resume.js +44 -0
  107. package/lib/harness/operations/verify.js +163 -0
  108. package/lib/harness/planner.js +141 -0
  109. package/lib/harness/schemas.js +108 -0
  110. package/lib/harness/store.js +240 -0
  111. package/package.json +9 -1
@@ -4,54 +4,50 @@
4
4
 
5
5
  ---
6
6
 
7
- ## 🎯 Requirement Management Commands
7
+ ## 🎯 Requirement Commands
8
8
 
9
9
  | Command | Purpose | Quick Example | Detailed Docs |
10
10
  |---------|---------|---------------|---------------|
11
- | `/flow-new` | 🚀 Start New Requirement Development | `/flow-new "REQ-123\|Feature"` | [→](./flow-new.md) |
12
- | `/flow-init` | 📦 Initialize Requirement Structure | `/flow-init "REQ-123\|Feature"` | [→](./flow-init.md) |
13
- | `/flow-status` | 📊 Query Development Progress | `/flow-status REQ-123` | [→](./flow-status.md) |
14
- | `/flow-restart` | 🔄 Resume Interrupted Development | `/flow-restart "REQ-123"` | [→](./flow-restart.md) |
15
- | `/flow-update` | Update Task Progress | `/flow-update "REQ-123" "T001"` | [→](./flow-update.md) |
16
-
17
- ## 🏗️ Architecture Design Commands
18
-
19
- | Command | Purpose | Quick Example | Detailed Docs |
20
- |---------|---------|---------------|---------------|
21
- | `/core-roadmap` | 🗺️ Generate Product Roadmap | `/core-roadmap` | [→](./core-roadmap.md) |
22
- | `/core-architecture` | 🏛️ Generate System Architecture | `/core-architecture` | [→](./core-architecture.md) |
23
- | `/core-guidelines` | 📘 Generate Project Guidelines | `/core-guidelines` | [→](./core-guidelines.md) |
24
-
25
- ## 🧪 Quality Assurance Commands
11
+ | `/flow:init` | 📦 Initialize requirement context | `/flow:init "REQ-123\|Feature"` | [→](../../.claude/commands/flow/init.md) |
12
+ | `/flow:spec` | 📋 Generate task-manifest | `/flow:spec "REQ-123"` | [→](../../.claude/commands/flow/spec.md) |
13
+ | `/flow:dev` | 🛠️ Dispatch or resume task execution | `/flow:dev "REQ-123" --resume` | [→](../../.claude/commands/flow/dev.md) |
14
+ | `/flow:verify` | Quick/strict quality gates | `/flow:verify "REQ-123" --strict` | [→](../../.claude/commands/flow/verify.md) |
15
+ | `/flow:release` | 🚢 Release + runtime cleanup | `/flow:release "REQ-123"` | [→](../../.claude/commands/flow/release.md) |
16
+ | `/flow:status` | 📊 Query progress snapshot | `/flow:status REQ-123` | [→](../../.claude/commands/flow/status.md) |
17
+ | `/flow:restart` | 🔄 Recover interrupted workflow | `/flow:restart "REQ-123" --from=dev` | [→](../../.claude/commands/flow/restart.md) |
18
+ | `/flow:update` | ✅ Update task progress | `/flow:update "REQ-123" "T001"` | [→](../../.claude/commands/flow/update.md) |
19
+ | `/flow:fix` | 🐛 Bug fix workflow | `/flow:fix "BUG-001\|Description"` | [→](../../.claude/commands/flow/fix.md) |
20
+
21
+ ## ⚠️ Deprecated Commands
22
+
23
+ | Deprecated | Migration |
24
+ |------------|-----------|
25
+ | `/flow:new` | `/flow:init -> /flow:spec -> /flow:dev -> /flow:verify -> /flow:release` |
26
+ | `/flow:clarify` | Use `/flow:spec` |
27
+ | `/flow:checklist` | Use `/flow:verify --strict` |
28
+ | `/flow:quality` | Use `/flow:verify` |
29
+
30
+ ## 🏗️ Core Commands
26
31
 
27
32
  | Command | Purpose | Quick Example | Detailed Docs |
28
33
  |---------|---------|---------------|---------------|
29
- | `/flow-checklist` | Requirement Quality Check | `/flow-checklist --type ux` | [→](../../.claude/commands/flow-checklist.md) |
30
- | `/flow-verify` | 🔍 Verify Document Consistency | `/flow-verify "REQ-123"` | [→](./flow-verify.md) |
31
- | `/flow-qa` | 🧪 Execute Quality Assurance | `/flow-qa "REQ-123"` | [→](./flow-qa.md) |
32
- | `/flow-constitution` | 📜 Constitution Compliance | `/flow-constitution --verify` | [→](./flow-constitution.md) |
33
-
34
- ## 🛠️ Tool Commands
35
-
36
- | Command | Purpose | Quick Example | Detailed Docs |
37
- |---------|---------|---------------|---------------|
38
- | `/flow-fix` | 🐛 Bug Fix Flow | `/flow-fix "BUG-001\|Description"` | [→](./flow-fix.md) |
39
- | `/flow-release` | 🚢 Create Release | `/flow-release "REQ-123"` | [→](./flow-release.md) |
34
+ | `/core:roadmap` | 🗺️ Generate product roadmap | `/core:roadmap` | [→](./core-roadmap.md) |
35
+ | `/core:architecture` | 🏛️ Generate system architecture | `/core:architecture` | [→](./core-architecture.md) |
36
+ | `/core:guidelines` | 📘 Generate project guidelines | `/core:guidelines` | [→](./core-guidelines.md) |
37
+ | `/core:style` | 🎨 Generate style system guide | `/core:style` | [→](./core-style.md) |
40
38
 
41
39
  ## 🎯 Quick Selection Guide
42
40
 
43
- ```
41
+ ```text
44
42
  Your Scenario:
45
- ├─ Start brand new feature? → /flow-new "REQ-123|Feature"
46
- ├─ Plan product direction? → /core-roadmap
47
- ├─ Design system architecture? → /core-architecture
48
- ├─ Validate requirement quality? → /flow-checklist --type ux,api,security
49
- ├─ Continue interrupted development? → /flow-restart "REQ-123"
50
- ├─ Check development progress? → /flow-status REQ-123
51
- ├─ Found document conflicts? → /flow-verify "REQ-123"
52
- ├─ Development complete, test? → /flow-qa "REQ-123"
53
- ├─ Fix production bug? → /flow-fix "BUG-001|Description"
54
- └─ Ready to release? → /flow-release "REQ-123"
43
+ ├─ Start requirement delivery? → /flow:init "REQ-123|Feature|URLs"
44
+ ├─ Need executable plan? → /flow:spec "REQ-123"
45
+ ├─ Need implementation/resume? → /flow:dev "REQ-123" [--resume]
46
+ ├─ Need release gates? → /flow:verify "REQ-123" --strict
47
+ ├─ Ready to ship? → /flow:release "REQ-123"
48
+ ├─ Check progress? → /flow:status REQ-123
49
+ ├─ Fix production bug? → /flow:fix "BUG-001|Description"
50
+ └─ Project-level planning? → /core:roadmap /core:architecture /core:guidelines
55
51
  ```
56
52
 
57
53
  ## 📚 Related Documentation
@@ -1,51 +1,49 @@
1
1
  # 📋 命令参考文档
2
2
 
3
- ## 🎯 需求管理命令
3
+ ## 🎯 需求命令
4
4
 
5
5
  | 命令 | 用途 | 快速示例 |
6
6
  |------|------|----------|
7
- | `/flow-new` | 🚀 启动新需求开发 | `/flow-new "REQ-123|功能"` → [详细文档](./flow-new.md) |
8
- | `/flow-init` | 📦 初始化需求结构 | `/flow-init "REQ-123|功能"` → [详细文档](./flow-init.md) |
9
- | `/flow-status` | 📊 查询开发进度 | `/flow-status REQ-123` → [详细文档](./flow-status.md) |
10
- | `/flow-restart` | 🔄 恢复中断的开发 | `/flow-restart "REQ-123"` → [详细文档](./flow-restart.md) |
11
- | `/flow-update` | 更新任务进度 | `/flow-update "REQ-123" "T001"` → [详细文档](./flow-update.md) |
12
-
13
- ## 🏗️ 架构设计命令
14
-
15
- | 命令 | 用途 | 快速示例 |
16
- |------|------|----------|
17
- | `/core-roadmap` | 🗺️ 生成产品路线图 | `/core-roadmap` → [详细文档](./core-roadmap.md) |
18
- | `/core-architecture` | 🏛️ 生成系统架构 | `/core-architecture` → [详细文档](./core-architecture.md) |
19
- | `/core-guidelines` | 📘 生成项目规范 | `/core-guidelines` → [详细文档](./core-guidelines.md) |
20
-
21
- ## 🧪 质量保证命令
7
+ | `/flow:init` | 📦 初始化需求上下文 | `/flow:init "REQ-123|功能"` → [详细文档](../../.claude/commands/flow/init.md) |
8
+ | `/flow:spec` | 📋 生成可执行任务清单 | `/flow:spec "REQ-123"` → [详细文档](../../.claude/commands/flow/spec.md) |
9
+ | `/flow:dev` | 🛠️ 分发/恢复任务执行 | `/flow:dev "REQ-123" --resume` → [详细文档](../../.claude/commands/flow/dev.md) |
10
+ | `/flow:verify` | 执行快速/严格质量闸 | `/flow:verify "REQ-123" --strict` → [详细文档](../../.claude/commands/flow/verify.md) |
11
+ | `/flow:release` | 🚢 发布并清理运行时 | `/flow:release "REQ-123"` → [详细文档](../../.claude/commands/flow/release.md) |
12
+ | `/flow:status` | 📊 查询开发进度 | `/flow:status REQ-123` → [详细文档](../../.claude/commands/flow/status.md) |
13
+ | `/flow:restart` | 🔄 恢复中断工作流 | `/flow:restart "REQ-123" --from=dev` → [详细文档](../../.claude/commands/flow/restart.md) |
14
+ | `/flow:update` | ✅ 更新任务进度 | `/flow:update "REQ-123" "T001"` → [详细文档](../../.claude/commands/flow/update.md) |
15
+ | `/flow:fix` | 🐛 Bug 修复流程 | `/flow:fix "BUG-001\|描述"` → [详细文档](../../.claude/commands/flow/fix.md) |
16
+
17
+ ## ⚠️ 已废弃命令
18
+
19
+ | 废弃命令 | 迁移路径 |
20
+ |----------|----------|
21
+ | `/flow:new` | `/flow:init -> /flow:spec -> /flow:dev -> /flow:verify -> /flow:release` |
22
+ | `/flow:clarify` | 使用 `/flow:spec` |
23
+ | `/flow:checklist` | 使用 `/flow:verify --strict` |
24
+ | `/flow:quality` | 使用 `/flow:verify` |
25
+
26
+ ## 🏗️ 核心命令
22
27
 
23
28
  | 命令 | 用途 | 快速示例 |
24
29
  |------|------|----------|
25
- | `/flow-verify` | 🔍 验证文档一致性 | `/flow-verify "REQ-123"` → [详细文档](./flow-verify.md) |
26
- | `/flow-qa` | 🧪 执行质量保证 | `/flow-qa "REQ-123"` → [详细文档](./flow-qa.md) |
27
- | `/flow-constitution` | 📜 Constitution 合规 | `/flow-constitution --verify` → [详细文档](./flow-constitution.md) |
28
-
29
- ## 🛠️ 工具命令
30
-
31
- | 命令 | 用途 | 快速示例 |
32
- |------|------|----------|
33
- | `/flow-fix` | 🐛 Bug 修复流程 | `/flow-fix "BUG-001\|描述"` → [详细文档](./flow-fix.md) |
34
- | `/flow-release` | 🚢 创建发布 | `/flow-release "REQ-123"` → [详细文档](./flow-release.md) |
30
+ | `/core:roadmap` | 🗺️ 生成产品路线图 | `/core:roadmap` → [详细文档](./core-roadmap.md) |
31
+ | `/core:architecture` | 🏛️ 生成系统架构 | `/core:architecture` → [详细文档](./core-architecture.md) |
32
+ | `/core:guidelines` | 📘 生成项目规范 | `/core:guidelines` → [详细文档](./core-guidelines.md) |
33
+ | `/core:style` | 🎨 生成设计风格指南 | `/core:style` → [详细文档](./core-style.md) |
35
34
 
36
35
  ## 🎯 快速选择指南
37
36
 
38
- ```
37
+ ```text
39
38
  你的场景:
40
- ├─ 启动全新功能? → /flow-new "REQ-123|功能"
41
- ├─ 规划产品方向? → /core-roadmap
42
- ├─ 设计系统架构? → /core-architecture
43
- ├─ 开发中断继续? → /flow-restart "REQ-123"
44
- ├─ 检查开发进度? → /flow-status REQ-123
45
- ├─ 发现文档冲突? → /flow-verify "REQ-123"
46
- ├─ 开发完成测试? → /flow-qa "REQ-123"
47
- ├─ 修复生产 Bug? → /flow-fix "BUG-001|描述"
48
- └─ 准备发布上线? → /flow-release "REQ-123"
39
+ ├─ 启动需求交付? → /flow:init "REQ-123|功能|URLs"
40
+ ├─ 生成可执行计划? → /flow:spec "REQ-123"
41
+ ├─ 执行或恢复开发? → /flow:dev "REQ-123" [--resume]
42
+ ├─ 进行发布门禁? → /flow:verify "REQ-123" --strict
43
+ ├─ 准备发布上线? → /flow:release "REQ-123"
44
+ ├─ 检查进度? → /flow:status REQ-123
45
+ ├─ 修复生产 Bug? → /flow:fix "BUG-001|描述"
46
+ └─ 做项目级规划? → /core:roadmap /core:architecture /core:guidelines
49
47
  ```
50
48
 
51
49
  ## 📚 相关文档
@@ -22,7 +22,7 @@ Generate comprehensive product roadmap and requirement priority planning through
22
22
  - Present product plan to team
23
23
 
24
24
  ### ❌ Not Recommended Scenarios
25
- - Single requirement development → Use `/flow-new`
25
+ - Single requirement development → Use `/flow:init` (then `/flow:spec` → `/flow:dev` → `/flow:verify` → `/flow:release`)
26
26
 
27
27
  ## 🔄 Execution Flow (6-Stage Interactive Dialogue)
28
28
 
@@ -96,7 +96,7 @@ User: Target users are Tech Leads and senior engineers in development teams.
96
96
  ## 🔗 Related Commands
97
97
 
98
98
  - [`/core-architecture`](./core-architecture.md) - Generate architecture based on roadmap
99
- - [`/flow-init`](./flow-init.md) - Initialize requirement based on roadmap
99
+ - [`/flow:init`](./flow-init.md) - Initialize requirement based on roadmap
100
100
  - `.claude/scripts/sync-roadmap-progress.sh` - Sync progress to roadmap
101
101
 
102
102
  ## 📚 Deep Reading
@@ -18,7 +18,7 @@
18
18
  - 向团队展示产品规划
19
19
 
20
20
  ### ❌ 不推荐场景
21
- - 单个需求开发 → 使用 `/flow-new`
21
+ - 单个需求开发 → 使用 `/flow:init`(随后 `/flow:spec` → `/flow:dev` → `/flow:verify` → `/flow:release`)
22
22
 
23
23
  ## 🔄 执行流程(6阶段交互式对话)
24
24
 
@@ -92,7 +92,7 @@ User: 目标用户是开发团队的 Tech Lead 和高级工程师。
92
92
  ## 🔗 相关命令
93
93
 
94
94
  - [`/core-architecture`](./core-architecture.md) - 基于路线图生成架构
95
- - [`/flow-init`](./flow-init.md) - 基于路线图初始化需求
95
+ - [`/flow:init`](./flow-init.md) - 基于路线图初始化需求
96
96
  - `.claude/scripts/sync-roadmap-progress.sh` - 同步进度到路线图
97
97
 
98
98
  ## 📚 深度阅读
@@ -2,404 +2,52 @@
2
2
 
3
3
  [中文文档](./core-style.zh-CN.md) | [English](./core-style.md)
4
4
 
5
- ---
5
+ Generate or update `devflow/STYLE.md` as project-level design SSOT.
6
6
 
7
- ## 📋 Overview
8
-
9
- Generate project-level design style guide (STYLE.md) from reference designs or existing code analysis, ensuring visual consistency across the entire project.
10
-
11
- ## 🎯 Syntax
12
-
13
- ```bash
14
- /core-style # Generate new design style guide
15
- /core-style --update # Update existing design style guide
16
- ```
17
-
18
- ## 🎬 Use Cases
19
-
20
- ### ✅ Recommended Scenarios
21
- - Establish design standards during project initialization
22
- - Unify project visual style
23
- - Extract design system from reference designs
24
- - Organize design specifications from existing code
25
- - Update guide when design style changes
26
-
27
- ### ❌ Not Recommended Scenarios
28
- - UI design for a single requirement → Use `/flow-ui`
29
- - Temporary style adjustments → Directly modify component code
30
-
31
- ## 🧭 Positioning
32
-
33
- **Project-level command** (similar to `/core-roadmap`)
34
-
35
- - `/core-roadmap` defines product roadmap (feature planning)
36
- - `/core-style` defines design style guide (visual specification)
37
- - Both are **SSOT (Single Source of Truth)** for the project
38
-
39
- ## 💡 Core Philosophy
40
-
41
- > "Design systems are the grammar of visual language, code is the implementation of grammar. Without grammar, there is no consistency."
42
-
43
- **Role of STYLE.md**:
44
- - ✅ Single Source of Truth (SSOT) for project design
45
- - ✅ Primary reference for `/flow-ui` when generating UI prototypes
46
- - ✅ Mandatory specification for `/flow-dev` during frontend development
47
- - ✅ Ensures visual consistency across all requirement UIs
48
-
49
- ## 🔄 Execution Flow (3 Phases)
50
-
51
- ```text
52
- Phase 1: Entry Gate & Project Type Detection
53
- ├─ Detect existing style guide (does STYLE.md exist?)
54
- ├─ Detect project type (new project vs existing project)
55
- └─ Route selection (new → reference design collection / existing → code analysis)
56
-
57
- Phase 2: Reference Design Collection & Replication (New Projects Only)
58
- ├─ Guide user to provide reference design (URL / screenshot / HTML+CSS)
59
- ├─ Generate single HTML file replica (reference-001.html)
60
- ├─ User refinement loop (reference-002.html, reference-003.html...)
61
- └─ Confirm final version (reference-final.html)
62
-
63
- Phase 3: Style Analysis & STYLE.md Generation
64
- ├─ Analyze input source (reference-final.html or project code)
65
- ├─ Generate style analysis document (research/style_analysis.md)
66
- ├─ Invoke style-guide-generator Agent
67
- └─ Output STYLE.md
68
-
69
- Exit Gate: File check + Constitution validation + Status update
70
- ```
71
-
72
- ## 📂 Output Files
73
-
74
- ```
75
- devflow/
76
- ├── STYLE.md # Project design style guide (SSOT)
77
- ├── research/
78
- │ ├── style_analysis.md # Style analysis document
79
- │ └── style_reference_designs/ # Reference designs (new projects)
80
- │ ├── reference-001.html # Version 1 replica
81
- │ ├── reference-002.html # Version 2 (refined)
82
- │ └── reference-final.html # Final confirmed version
83
- ├── project_status.json # Project status (updated)
84
- └── EXECUTION_LOG.md # Execution log (updated)
85
- ```
86
-
87
- ## 📋 STYLE.md Contents
88
-
89
- STYLE.md is a comprehensive design style guide containing these 15 core sections:
90
-
91
- 1. **Overview** - Design system overview (name, version, philosophy, update history)
92
- 2. **Color Palette** - Color system (primary, secondary, semantic, neutrals with Hex/RGB/HSL)
93
- 3. **Typography** - Font system (font families, type scale, responsive fonts, combination rules)
94
- 4. **Spacing System** - Spacing system (base unit, spacing scale, use cases)
95
- 5. **Component Styles** - Component library (Button, Input, Card, Modal, etc. with variants, sizes, states)
96
- 6. **Shadows & Elevation** - Shadow and elevation system (shadow levels, use cases)
97
- 7. **Animations & Transitions** - Animations and transitions (duration, easing, common animations)
98
- 8. **Border Radius** - Border radius system (radius levels, use cases)
99
- 9. **Opacity & Transparency** - Opacity system (opacity levels, use cases)
100
- 10. **Common Tailwind CSS Usage** - Tailwind usage specifications (if applicable)
101
- 11. **Example Component Reference Design Code** - Example component code (at least 3 complete implementations)
102
- 12. **Design Principles** - Design principles (simplicity, consistency, accessibility, etc.)
103
- 13. **Responsive Design** - Responsive design (breakpoints, strategy, examples)
104
- 14. **Accessibility** - Accessibility (color contrast, keyboard navigation, ARIA attributes)
105
- 15. **Assets** - Asset specifications (Icon, Image, Logo, etc., if applicable)
106
-
107
- **All definitions include**:
108
- - Concrete values (not "TBD" or placeholders)
109
- - Semantic naming (e.g., `--color-primary`, `--spacing-md`)
110
- - Use case descriptions
111
- - Example code (CSS Variables / Tailwind Config)
112
-
113
- **Example code characteristics**:
114
- - ✅ Copy-paste ready
115
- - ✅ Complete HTML structure and CSS/Tailwind classes
116
- - ✅ Clear comments explaining design decisions
117
- - ❌ Not pseudocode or placeholders
118
-
119
- ## 🆕 New Project Workflow Example
120
-
121
- ### Scenario: You have a favorite design you want to use as the project's design foundation
122
-
123
- ```bash
124
- # Step 1: Run command
125
- /core-style
126
-
127
- # Step 2: Agent guidance
128
- Agent: Detected a new project (no frontend code).
129
-
130
- Please provide the design you want to reference:
131
- - Website URL (I'll fetch and analyze it)
132
- - Design screenshot (PNG/JPG)
133
- - Extracted HTML + CSS code
134
-
135
- I'll help you replicate this design into a single HTML file.
136
-
137
- # Step 3: User provides reference
138
- User: I want to reference https://example.com/design, here's the screenshot and extracted CSS...
139
-
140
- # Step 4: Agent generates replica
141
- Agent: Generated devflow/research/style_reference_designs/reference-001.html
142
-
143
- Please open the file to review. Are you satisfied? If not, tell me what needs adjustment:
144
- - Colors (e.g., primary color too bright, change to softer blue)
145
- - Fonts (e.g., heading font too bold, change to medium weight)
146
- - Spacing (e.g., card spacing too small, increase to 24px)
147
- - Component styles (e.g., button radius too large, change to 4px)
148
-
149
- # Step 5: User refinement
150
- User: Change primary color to #3B82F6, button radius to 6px.
151
-
152
- # Step 6: Agent adjusts and confirms again
153
- Agent: Adjusted, generated reference-002.html. Please review. Satisfied?
154
-
155
- User: Yes!
156
-
157
- # Step 7: Agent generates STYLE.md
158
- Agent: Analyzing reference-final.html, generating STYLE.md...
159
-
160
- ✅ STYLE.md generated!
161
-
162
- Content statistics:
163
- - Color definitions: 15
164
- - Font definitions: 8
165
- - Spacing levels: 10
166
- - Component styles: 12
167
- - Example code: 3
168
-
169
- Next steps:
170
- 1. Review devflow/STYLE.md for completeness
171
- 2. Run /flow-prd to start requirement development
172
- ```
173
-
174
- ## 🏢 Existing Project Workflow Example
175
-
176
- ### Scenario: You have a project with existing frontend code and want to organize design specifications
7
+ ## Syntax
177
8
 
178
9
  ```bash
179
- # Step 1: Run command
180
10
  /core-style
181
-
182
- # Step 2: Agent auto-analyzes
183
- Agent: Detected an existing project (found src/components/, styles/, etc.).
184
-
185
- Analyzing project code, extracting design styles...
186
- - Analyzing files: src/components/**/*.tsx, styles/**/*.css
187
- - Extracting colors: Primary #3B82F6, Secondary #8B5CF6, ...
188
- - Extracting fonts: Inter, Roboto Mono
189
- - Extracting spacing: 4px, 8px, 16px, 24px, 32px...
190
-
191
- Generated devflow/research/style_analysis.md, generating STYLE.md...
192
-
193
- ✅ STYLE.md generated!
194
-
195
- Content statistics:
196
- - Color definitions: 18
197
- - Font definitions: 6
198
- - Spacing levels: 8
199
- - Component styles: 15
200
- - Example code: 3
201
-
202
- Tech stack:
203
- - Framework: React
204
- - CSS: Tailwind CSS
205
-
206
- Next steps:
207
- 1. Review devflow/STYLE.md for completeness
208
- 2. Adjust inconsistent components based on STYLE.md (if any)
209
- ```
210
-
211
- ## 🔄 Update Mode Example
212
-
213
- ### Scenario: Design style changes, need to update STYLE.md
214
-
215
- ```bash
216
- # Step 1: Run command
217
11
  /core-style --update
218
-
219
- # Step 2: Agent analyzes and updates
220
- Agent: Detected existing STYLE.md (v1.0.0), entering update mode.
221
-
222
- Analyzing latest code, detecting new design patterns...
223
- - Found new color: Warning #F59E0B
224
- - Found new components: Tooltip, Pagination
225
- - Found new spacing: 96px
226
-
227
- Merged into STYLE.md (v1.1.0).
228
-
229
- Update content:
230
- - New colors: 1
231
- - New components: 2
232
- - New spacing: 1
233
-
234
- ✅ STYLE.md update complete!
235
-
236
- Next steps:
237
- 1. Review changes
238
- 2. Update existing UI prototypes (if any)
239
12
  ```
240
13
 
241
- ## 🔗 Integration with Other Workflows
242
-
243
- ### `/flow-ui` Integration
14
+ ## Positioning
244
15
 
245
- **Before** (no STYLE.md):
246
- - `/flow-ui` uses default sampling strategy (80+ design masters)
247
- - Each requirement's UI may have inconsistent styles
16
+ `/core-style` is a project command (same level as `/core-roadmap`) and feeds the delivery mainline:
248
17
 
249
- **After** (with STYLE.md):
250
- - `/flow-ui` prioritizes loading `devflow/STYLE.md`
251
- - All colors, fonts, spacing, components strictly follow STYLE.md
252
- - Default sampling strategy only used for parts not covered by STYLE.md
18
+ - `/flow:spec`: reads STYLE guidance for UI/UX acceptance criteria.
19
+ - `/flow:dev`: enforces STYLE tokens and component conventions in implementation.
20
+ - `/flow:verify`: checks style consistency as part of quality gates.
253
21
 
254
- **Example**:
255
- ```bash
256
- # Run /flow-ui
257
- /flow-ui "REQ-001"
22
+ ## Execution Flow
258
23
 
259
- # Agent auto-references STYLE.md
260
- Agent: Detected devflow/STYLE.md (v1.0.0), will strictly follow design style guide.
24
+ 1. Detect mode (`create` or `update`).
25
+ 2. Collect style inputs:
26
+ - new project: use reference design URL/screenshot/HTML+CSS.
27
+ - existing project: mine tokens/components from current code.
28
+ 3. Produce `devflow/research/style_analysis.md`.
29
+ 4. Generate `devflow/STYLE.md` from `STYLE_TEMPLATE.md`.
30
+ 5. Validate structure + constitution constraints.
261
31
 
262
- Generating UI prototype...
263
- - Primary color: #3B82F6 (from STYLE.md)
264
- - Font: Inter (from STYLE.md)
265
- - Button radius: 6px (from STYLE.md)
32
+ ## Outputs
266
33
 
267
- ✅ UI_PROTOTYPE.html generated, all styles comply with STYLE.md.
34
+ ```text
35
+ devflow/STYLE.md
36
+ devflow/research/style_analysis.md
37
+ devflow/project_status.json (updated)
38
+ EXECUTION_LOG.md (updated)
268
39
  ```
269
40
 
270
- ### `/flow-dev` Integration
271
-
272
- **After** (with STYLE.md):
273
- - `/flow-dev` auto-loads `devflow/STYLE.md` when generating frontend code
274
- - All component implementations must follow STYLE.md style definitions
275
- - Pay special attention to: color usage, font usage, spacing usage, component structure
41
+ ## Minimal Post-Style Workflow
276
42
 
277
- **Example**:
278
43
  ```bash
279
- # Run /flow-dev
280
- /flow-dev "REQ-001"
281
-
282
- # Agent auto-references STYLE.md
283
- Agent: Detected devflow/STYLE.md (v1.0.0), all frontend code will follow design style guide.
284
-
285
- Implementing Task T003: Implement login button...
286
- - Using STYLE.md Button Primary style
287
- - Color: var(--color-primary)
288
- - Radius: var(--radius-md)
289
- - Spacing: var(--spacing-2) var(--spacing-4)
290
-
291
- ✅ Login button implementation complete, style complies with STYLE.md.
44
+ /flow:init "REQ-123|Feature"
45
+ /flow:spec "REQ-123"
46
+ /flow:dev "REQ-123"
47
+ /flow:verify "REQ-123" --strict
292
48
  ```
293
49
 
294
- ## 💡 Design Philosophy
295
-
296
- ### 1. SSOT Principle (Single Source of Truth)
297
- - STYLE.md is the sole source of truth for project design
298
- - All UI-related work must reference STYLE.md
299
- - Avoid design style fragmentation and inconsistency
300
-
301
- ### 2. Consistency First
302
- - Unified visual language enhances product professionalism
303
- - Consistent component styles reduce development and maintenance costs
304
- - Smoother, more predictable user experience
305
-
306
- ### 3. Reusability
307
- - All definitions are concrete and executable
308
- - Example code is copy-paste ready, not pseudocode
309
- - Reduce repetitive work, improve development efficiency
310
-
311
- ### 4. Evolvability
312
- - Support iteration through `--update` parameter
313
- - Version control (v1.0.0, v1.1.0...)
314
- - Record reasons and changes for each update
315
-
316
- ### 5. User-Centered
317
- - New projects through reference design collection + refinement loop
318
- - Ensure user satisfaction
319
- - Avoid large-scale refactoring later
320
-
321
- ## 📊 Workflow Position
322
-
323
- ```
324
- /flow-init → research.md + tasks.json
325
-
326
- /core-roadmap → ROADMAP.md + BACKLOG.md (optional, project-level)
327
-
328
- /core-style → STYLE.md (optional, project-level design style guide) ⭐ NEW
329
-
330
- /flow-prd → PRD.md
331
-
332
- /flow-tech → TECH_DESIGN.md + data-model + contracts
333
-
334
- /flow-ui → UI_PROTOTYPE.html (must reference STYLE.md) ⭐ CHANGED
335
-
336
- /flow-epic → EPIC.md + TASKS.md
337
-
338
- /flow-dev → TASKS.md execution (frontend code must reference STYLE.md) ⭐ CHANGED
339
-
340
- /flow-qa → QA reports
341
-
342
- /flow-release → PR creation
343
- ```
344
-
345
- ## ⚠️ Error Handling
346
-
347
- | Error Scenario | Handling |
348
- |----------------|----------|
349
- | **STYLE.md exists without --update** | Ask for confirmation to overwrite, exit if user declines |
350
- | **No frontend features and no reference design** | Prompt user to provide reference design or confirm pure backend project |
351
- | **Reference design replication fails** | Request more detailed design info (HTML/CSS/screenshot) |
352
- | **Agent generation fails** | Keep style_analysis.md, prompt user to check and retry |
353
- | **Constitution validation fails** | Block based on severity (warning level only prompts) |
354
-
355
- ## 🎯 Next Steps
356
-
357
- 1. **Review STYLE.md** - Ensure design style guide is complete and meets project needs
358
- 2. **Update existing components** (existing projects) - Adjust inconsistent components based on STYLE.md
359
- 3. **Run /flow-prd** - Start requirement development (if applicable)
360
- 4. **Run /core-roadmap** - Generate product roadmap (if applicable)
361
-
362
- ## 🔗 Related Commands
363
-
364
- - [`/core-roadmap`](./core-roadmap.md) - Generate product roadmap
365
- - [`/flow-ui`](./flow-ui.md) - Generate UI prototype (will reference STYLE.md)
366
- - [`/flow-dev`](./flow-dev.md) - Execute development tasks (will reference STYLE.md)
367
- - [`/flow-verify`](./flow-verify.md) - Consistency check (can check if code complies with STYLE.md)
368
-
369
- ## 📚 Deep Reading
370
-
371
- - [Design System Guide](../guides/design-system-guide.md) (TBD)
372
- - [Visual Consistency Management](../guides/visual-consistency.md) (TBD)
373
- - [STYLE_TEMPLATE](../../.claude/docs/templates/STYLE_TEMPLATE.md)
374
-
375
- ## ❓ FAQ
376
-
377
- ### Q: When should I run `/core-style`?
378
- A:
379
- - ✅ During project initialization (establish design standards)
380
- - ✅ When you have a reference design to replicate
381
- - ✅ When existing project needs design specification organization
382
- - ✅ When design style changes (use `--update`)
383
-
384
- ### Q: What's the difference between `/core-style` and `/flow-ui`?
385
- A:
386
- - **core-style**: Generates **project-level** design style guide (STYLE.md), one-time or as-needed updates
387
- - **flow-ui**: Generates UI prototype (UI_PROTOTYPE.html) for **specific requirements**, runs per requirement
388
-
389
- ### Q: Do I need to run `/core-style` for a pure backend project?
390
- A: No. `/core-style` is designed for frontend or full-stack projects. Pure backend projects don't need a design style guide.
391
-
392
- ### Q: Can I manually edit STYLE.md after it's generated?
393
- A: Yes. STYLE.md is a Markdown file, you can edit it manually. However, it's recommended to use `/core-style --update` for consistency and version control.
394
-
395
- ### Q: What if I'm not satisfied with the reference design replica?
396
- A: The agent provides a refinement loop where you can adjust multiple times until satisfied. Each adjustment generates a new version (reference-002.html, reference-003.html...), and you can revert anytime.
397
-
398
- ### Q: Will STYLE.md automatically apply to code?
399
- A: No automatic code modification. However, `/flow-ui` and `/flow-dev` will auto-reference STYLE.md to ensure newly generated code complies with the style guide. Existing code needs manual adjustment (or use `/flow-verify` to check inconsistencies).
400
-
401
- ### Q: If my project uses Tailwind CSS, will STYLE.md include Tailwind configuration?
402
- A: Yes. The agent auto-detects the tech stack. If using Tailwind CSS, STYLE.md will include Tailwind Config example code.
50
+ ## Notes
403
51
 
404
- ### Q: What does STYLE.md contain?
405
- A: Contains 15 core sections: Overview, Color Palette, Typography, Spacing System, Component Styles, Shadows, Animations, Border Radius, Opacity, Tailwind Usage, Example Code, Design Principles, Responsive Design, Accessibility, Assets. See [STYLE_TEMPLATE](../../.claude/docs/templates/STYLE_TEMPLATE.md) for details.
52
+ - STYLE is a living SSOT; prefer `--update` instead of ad-hoc per-task overrides.
53
+ - Keep style decisions semantic (tokens/components), not page-specific patches.