From 121e834459eda56926a0f0313b56f4965599f956 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Mon, 2 Mar 2026 15:25:56 +0800 Subject: [PATCH] feat: add multi-mode workflow planning skill with session management and task generation --- .claude/skills/ccw-help/SKILL.md | 136 +- .claude/skills/ccw-help/command.json | 991 ++++++++------- .claude/skills/ccw-help/index/all-agents.json | 15 + .../skills/ccw-help/index/all-commands.json | 164 ++- .claude/skills/ccw-help/index/all-skills.json | 362 ++++++ .../skills/ccw-help/index/by-category.json | 168 ++- .../skills/ccw-help/index/by-use-case.json | 272 +++- .../ccw-help/index/command-relationships.json | 139 +- .../ccw-help/index/essential-commands.json | 2 +- .../ccw-help/index/skills-by-category.json | 374 ++++++ .../ccw-help/scripts/analyze_commands.py | 135 +- .claude/skills/team-perf-opt/SKILL.md | 349 ++++++ .../team-perf-opt/role-specs/benchmarker.md | 85 ++ .../team-perf-opt/role-specs/optimizer.md | 76 ++ .../team-perf-opt/role-specs/profiler.md | 73 ++ .../team-perf-opt/role-specs/reviewer.md | 69 + .../team-perf-opt/role-specs/strategist.md | 73 ++ .../roles/coordinator/commands/dispatch.md | 175 +++ .../roles/coordinator/commands/monitor.md | 201 +++ .../team-perf-opt/roles/coordinator/role.md | 252 ++++ .../team-perf-opt/specs/team-config.json | 208 +++ .../subagents/discuss-subagent.md | 89 ++ .../subagents/explore-subagent.md | 108 ++ .codex/skills/brainstorm/SKILL.md | 725 +++++++++++ .codex/skills/roadmap-with-file/SKILL.md | 20 +- .codex/skills/workflow-execute/SKILL.md | 1114 +++++++++++++++++ .../SKILL.md | 0 .codex/skills/workflow-plan/SKILL.md | 636 ++++++++++ 28 files changed, 6478 insertions(+), 533 deletions(-) create mode 100644 .claude/skills/ccw-help/index/all-skills.json create mode 100644 .claude/skills/ccw-help/index/skills-by-category.json create mode 100644 .claude/skills/team-perf-opt/SKILL.md create mode 100644 .claude/skills/team-perf-opt/role-specs/benchmarker.md create mode 100644 .claude/skills/team-perf-opt/role-specs/optimizer.md create mode 100644 .claude/skills/team-perf-opt/role-specs/profiler.md create mode 100644 .claude/skills/team-perf-opt/role-specs/reviewer.md create mode 100644 .claude/skills/team-perf-opt/role-specs/strategist.md create mode 100644 .claude/skills/team-perf-opt/roles/coordinator/commands/dispatch.md create mode 100644 .claude/skills/team-perf-opt/roles/coordinator/commands/monitor.md create mode 100644 .claude/skills/team-perf-opt/roles/coordinator/role.md create mode 100644 .claude/skills/team-perf-opt/specs/team-config.json create mode 100644 .claude/skills/team-perf-opt/subagents/discuss-subagent.md create mode 100644 .claude/skills/team-perf-opt/subagents/explore-subagent.md create mode 100644 .codex/skills/brainstorm/SKILL.md create mode 100644 .codex/skills/workflow-execute/SKILL.md rename .codex/skills/{wave-plan-pipeline => workflow-lite-planex}/SKILL.md (100%) create mode 100644 .codex/skills/workflow-plan/SKILL.md diff --git a/.claude/skills/ccw-help/SKILL.md b/.claude/skills/ccw-help/SKILL.md index c92b18a4..027ec7c5 100644 --- a/.claude/skills/ccw-help/SKILL.md +++ b/.claude/skills/ccw-help/SKILL.md @@ -1,18 +1,18 @@ --- name: ccw-help -description: CCW command help system. Search, browse, recommend commands. Triggers "ccw-help", "ccw-issue". +description: CCW command help system. Search, browse, recommend commands, skills, teams. Triggers "ccw-help", "ccw-issue". allowed-tools: Read, Grep, Glob, AskUserQuestion -version: 7.0.0 +version: 8.0.0 --- # CCW-Help Skill -CCW 命令帮助系统，提供命令搜索、推荐、文档查看功能。 +CCW 命令帮助系统，提供命令搜索、推荐、文档查看、Skill/Team 浏览功能。 ## Trigger Conditions -- 关键词: "ccw-help", "ccw-issue", "帮助", "命令", "怎么用", "ccw 怎么用", "工作流" -- 场景: 询问命令用法、搜索命令、请求下一步建议、询问任务应该用哪个工作流 +- 关键词: "ccw-help", "ccw-issue", "帮助", "命令", "怎么用", "ccw 怎么用", "工作流", "skill", "team" +- 场景: 询问命令用法、搜索命令、请求下一步建议、询问任务应该用哪个工作流、浏览 Skill/Team 目录 ## Operation Modes @@ -61,7 +61,7 @@ CCW 命令帮助系统，提供命令搜索、推荐、文档查看功能。 4. Get user confirmation 5. Execute chain with TODO tracking -**Supported Workflows**: +**Supported Workflows** (参考 [ccw.md](../../commands/ccw.md)): - **Level 1** (Lite-Lite-Lite): Ultra-simple quick tasks - **Level 2** (Rapid/Hotfix): Bug fixes, simple features, documentation - **Level 2.5** (Rapid-to-Issue): Bridge from quick planning to issue workflow @@ -71,12 +71,17 @@ CCW 命令帮助系统，提供命令搜索、推荐、文档查看功能。 - Test-fix workflows (debug failing tests) - Review workflows (code review and fixes) - UI design workflows + - Multi-CLI collaborative workflows + - Cycle workflows (integration-test, refactor) - **Level 4** (Full): Exploratory tasks with brainstorming - **With-File Workflows**: Documented exploration with multi-CLI collaboration - - `brainstorm-with-file`: Multi-perspective ideation - - `debug-with-file`: Hypothesis-driven debugging - - `analyze-with-file`: Collaborative analysis + - `brainstorm-with-file`: Multi-perspective ideation → workflow-plan → workflow-execute + - `debug-with-file`: Hypothesis-driven debugging (standalone) + - `analyze-with-file`: Collaborative analysis → workflow-lite-planex + - `collaborative-plan-with-file`: Multi-agent planning → unified-execute + - `roadmap-with-file`: Strategic requirement roadmap → team-planex - **Issue Workflow**: Batch issue discovery, planning, queueing, execution +- **Team Workflow**: team-planex wave pipeline for parallel execution ### Mode 6: Issue Reporting @@ -86,6 +91,16 @@ CCW 命令帮助系统，提供命令搜索、推荐、文档查看功能。 1. Use AskUserQuestion to gather context 2. Generate structured issue template +### Mode 7: Skill & Team Browsing + +**Triggers**: "skill", "team", "技能", "团队", "有哪些 skill", "team 怎么用" + +**Process**: +1. Query `command.json` skills array +2. Filter by category: workflow / team / review / meta / utility / standalone +3. Present categorized skill list with descriptions +4. For team skills, explain team architecture and usage patterns + ## Data Source Single source of truth: **[command.json](command.json)** @@ -94,8 +109,9 @@ Single source of truth: **[command.json](command.json)** |-------|---------| | `commands[]` | Flat command list with metadata | | `commands[].flow` | Relationships (next_steps, prerequisites) | -| `commands[].essential` | Essential flag for onboarding | | `agents[]` | Agent directory | +| `skills[]` | Skill directory with categories | +| `skills[].is_team` | Whether skill uses team architecture | | `essential_commands[]` | Core commands list | ### Source Path Format @@ -109,6 +125,77 @@ Single source of truth: **[command.json](command.json)** } ``` +## Skill Catalog + +### Workflow Skills (核心工作流) + +| Skill | 内部流水线 | 触发词 | +|-------|-----------|--------| +| `workflow-lite-planex` | explore → plan → confirm → execute | "lite-plan", 快速任务 | +| `workflow-plan` | session → context → convention → gen → verify | "workflow-plan", 正式规划 | +| `workflow-execute` | session discovery → task processing → commit | "workflow-execute", 执行 | +| `workflow-tdd-plan` | 6-phase TDD plan → verify | "tdd-plan", TDD 开发 | +| `workflow-test-fix` | session → context → analysis → gen → cycle | "test-fix", 测试修复 | +| `workflow-multi-cli-plan` | ACE context → CLI discussion → plan → execute | "multi-cli", 多CLI协作 | +| `workflow-skill-designer` | Meta-skill for designing workflow skills | "skill-designer" | + +### Team Skills (团队协作) + +Team Skills 使用 `team-worker` agent 架构，Coordinator 编排流水线，Workers 是加载了 role-spec 的 `team-worker` agents。 + +| Skill | 用途 | 架构 | +|-------|------|------| +| `team-planex` | 规划+执行 wave pipeline | planner + executor, 适合清晰 issue/roadmap | +| `team-lifecycle-v5` | 完整生命周期 (spec/impl/test) | team-worker agents with role-specs | +| `team-lifecycle-v4` | 优化版生命周期 | Optimized pipeline | +| `team-lifecycle-v3` | 基础版生命周期 | All roles invoke unified skill | +| `team-coordinate-v2` | 通用动态团队协调 | 运行时动态生成 role-specs | +| `team-coordinate` | 通用团队协调 v1 | Dynamic role generation | +| `team-brainstorm` | 团队头脑风暴 | Multi-perspective analysis | +| `team-frontend` | 前端开发团队 | Frontend specialists | +| `team-issue` | Issue 解决团队 | Issue resolution pipeline | +| `team-iterdev` | 迭代开发团队 | Iterative development | +| `team-review` | 代码扫描/漏洞审查 | Scanning + vulnerability review | +| `team-roadmap-dev` | Roadmap 驱动开发 | Requirement → implementation | +| `team-tech-debt` | 技术债务清理 | Debt identification + cleanup | +| `team-testing` | 测试团队 | Test planning + execution | +| `team-quality-assurance` | QA 团队 | Quality assurance pipeline | +| `team-uidesign` | UI 设计团队 | Design system + prototyping | +| `team-ultra-analyze` | 深度协作分析 | Deep collaborative analysis | +| `team-executor` | 轻量执行 (恢复会话) | Resume existing sessions | +| `team-executor-v2` | 轻量执行 v2 | Improved session resumption | + +### Standalone Skills (独立技能) + +| Skill | 用途 | +|-------|------| +| `brainstorm` | 双模头脑风暴 (auto pipeline / single role) | +| `review-code` | 多维度代码审查 | +| `review-cycle` | 审查+自动修复编排 | +| `spec-generator` | 6阶段规格文档链 (product-brief → PRD → architecture → epics) | +| `issue-manage` | 交互式 Issue 管理 (CRUD) | +| `memory-capture` | 统一记忆捕获 (session compact / quick tip) | +| `memory-manage` | 统一记忆管理 (CLAUDE.md + documentation) | +| `command-generator` | 命令文件生成器 | +| `skill-generator` | Meta-skill: 创建新 Skill | +| `skill-tuning` | Skill 诊断与优化 | + +## Workflow Mapping (CCW Auto-Route) + +CCW 根据任务意图自动选择工作流级别（参考 [ccw.md](../../commands/ccw.md)）： + +| 输入示例 | 类型 | 级别 | 流水线 | +|---------|------|------|--------| +| "Add API endpoint" | feature (low) | 2 | workflow-lite-planex → workflow-test-fix | +| "Fix login timeout" | bugfix | 2 | workflow-lite-planex → workflow-test-fix | +| "协作分析: 认证架构" | analyze-file | 3 | analyze-with-file → workflow-lite-planex | +| "重构 auth 模块" | refactor | 3 | workflow:refactor-cycle | +| "multi-cli: API设计" | multi-cli | 3 | workflow-multi-cli-plan → workflow-test-fix | +| "头脑风暴: 通知系统" | brainstorm | 4 | brainstorm-with-file → workflow-plan → workflow-execute | +| "roadmap: OAuth + 2FA" | roadmap | 4 | roadmap-with-file → team-planex | +| "specification: 用户系统" | spec-driven | 4 | spec-generator → workflow-plan → workflow-execute | +| "team planex: 用户系统" | team-planex | Team | team-planex | + ## Slash Commands ```bash @@ -116,6 +203,8 @@ Single source of truth: **[command.json](command.json)** /ccw-help # General help entry /ccw-help search # Search commands /ccw-help next # Get next step suggestions +/ccw-help skills # Browse skill catalog +/ccw-help teams # Browse team skills /ccw-issue # Issue reporting ``` @@ -128,6 +217,9 @@ Single source of truth: **[command.json](command.json)** /ccw "头脑风暴: 用户通知系统" # → detect brainstorm, use brainstorm-with-file /ccw "深度调试: 系统随机崩溃" # → detect debug-file, use debug-with-file /ccw "协作分析: 认证架构设计" # → detect analyze-file, use analyze-with-file +/ccw "roadmap: OAuth + 2FA 路线图" # → roadmap-with-file → team-planex +/ccw "集成测试: 支付流程" # → integration-test-cycle +/ccw "重构 auth 模块" # → refactor-cycle ``` ## Maintenance @@ -135,6 +227,7 @@ Single source of truth: **[command.json](command.json)** ### Update Mechanism CCW-Help skill supports manual updates through user confirmation dialog. +Script scans `commands/`, `agents/`, and `skills/` directories to regenerate all indexes. #### How to Update @@ -153,18 +246,33 @@ cd D:/Claude_dms3/.claude/skills/ccw-help python scripts/auto-update.py ``` -This runs `analyze_commands.py` to scan commands/ and agents/ directories and regenerate `command.json`. +This runs `analyze_commands.py` to scan commands/, agents/, and skills/ directories and regenerate `command.json` + all index files. #### Update Scripts - **`auto-update.py`**: Simple wrapper that runs analyze_commands.py -- **`analyze_commands.py`**: Scans directories and generates command index +- **`analyze_commands.py`**: Scans directories and generates command/agent/skill indexes + +#### Generated Index Files + +| File | Content | +|------|---------| +| `command.json` | Master index: commands + agents + skills | +| `index/all-commands.json` | Flat command list | +| `index/all-agents.json` | Agent directory | +| `index/all-skills.json` | Skill directory with metadata | +| `index/skills-by-category.json` | Skills grouped by category | +| `index/by-category.json` | Commands by category | +| `index/by-use-case.json` | Commands by usage scenario | +| `index/essential-commands.json` | Core commands for onboarding | +| `index/command-relationships.json` | Command flow relationships | ## Statistics - **Commands**: 50+ -- **Agents**: 16 -- **Workflows**: 6 main levels + 3 with-file variants +- **Agents**: 22 +- **Skills**: 36+ (7 workflow, 19 team, 10+ standalone/utility) +- **Workflows**: 6 main levels + 5 with-file variants + 2 cycle variants - **Essential**: 10 core commands ## Core Principle diff --git a/.claude/skills/ccw-help/command.json b/.claude/skills/ccw-help/command.json index 736315aa..412b392c 100644 --- a/.claude/skills/ccw-help/command.json +++ b/.claude/skills/ccw-help/command.json @@ -1,13 +1,16 @@ { "_metadata": { - "version": "3.0.0", - "total_commands": 73, - "total_agents": 19, + "version": "4.0.0", + "total_commands": 48, + "total_agents": 22, + "total_skills": 36, "description": "Auto-generated CCW-Help command index from analyze_commands.py", - "generated": "Auto-updated - all commands synced from file system", + "generated": "Auto-updated - all commands, agents, skills synced from file system", "last_sync": "command.json now stays in sync with CLI definitions" }, - "essential_commands": [], + "essential_commands": [ + "start" + ], "commands": [ { "name": "ccw-coordinator", @@ -18,18 +21,7 @@ "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/ccw-coordinator.md" - }, - { - "name": "ccw-debug", - "command": "/ccw-debug", - "description": "Aggregated debug command - combines debugging diagnostics and test verification in a synergistic workflow supporting cli-quick / debug-first / test-first / bidirectional-verification modes", - "arguments": "[--mode cli|debug|test|bidirectional] [--yes|-y] [--hotfix] \\\"bug description or error message\\", - "category": "general", - "subcategory": null, - "usage_scenario": "general", - "difficulty": "Intermediate", - "source": "../../commands/ccw-debug.md" + "source": "../../../commands/ccw-coordinator.md" }, { "name": "ccw", @@ -40,7 +32,7 @@ "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/ccw.md" + "source": "../../../commands/ccw.md" }, { "name": "cli-init", @@ -51,7 +43,7 @@ "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/cli/cli-init.md" + "source": "../../../commands/cli/cli-init.md" }, { "name": "codex-review", @@ -62,7 +54,73 @@ "subcategory": null, "usage_scenario": "analysis", "difficulty": "Intermediate", - "source": "../../commands/cli/codex-review.md" + "source": "../../../commands/cli/codex-review.md" + }, + { + "name": "flow-create", + "command": "/flow-create", + "description": "", + "arguments": "", + "category": "general", + "subcategory": null, + "usage_scenario": "implementation", + "difficulty": "Intermediate", + "source": "../../../commands/flow-create.md" + }, + { + "name": "add", + "command": "/idaw:add", + "description": "Add IDAW tasks - manual creation or import from ccw issue", + "arguments": "[-y|--yes] [--from-issue [,,...]] \\\"description\\\" [--type ] [--priority <1-5>]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/add.md" + }, + { + "name": "resume", + "command": "/idaw:resume", + "description": "Resume interrupted IDAW session from last checkpoint", + "arguments": "[-y|--yes] [session-id]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "session-management", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/resume.md" + }, + { + "name": "run-coordinate", + "command": "/idaw:run-coordinate", + "description": "IDAW coordinator - execute task skill chains via external CLI with hook callbacks and git checkpoints", + "arguments": "[-y|--yes] [--task [,,...]] [--dry-run] [--tool ]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/run-coordinate.md" + }, + { + "name": "run", + "command": "/idaw:run", + "description": "IDAW orchestrator - execute task skill chains serially with git checkpoints", + "arguments": "[-y|--yes] [--task [,,...]] [--dry-run]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/run.md" + }, + { + "name": "status", + "command": "/idaw:status", + "description": "View IDAW task and session progress", + "arguments": "[session-id]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "session-management", + "difficulty": "Beginner", + "source": "../../../commands/idaw/status.md" }, { "name": "convert-to-plan", @@ -73,7 +131,7 @@ "subcategory": null, "usage_scenario": "planning", "difficulty": "Intermediate", - "source": "../../commands/issue/convert-to-plan.md" + "source": "../../../commands/issue/convert-to-plan.md" }, { "name": "issue:discover-by-prompt", @@ -84,7 +142,7 @@ "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/issue/discover-by-prompt.md" + "source": "../../../commands/issue/discover-by-prompt.md" }, { "name": "issue:discover", @@ -95,7 +153,7 @@ "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/issue/discover.md" + "source": "../../../commands/issue/discover.md" }, { "name": "execute", @@ -106,7 +164,7 @@ "subcategory": null, "usage_scenario": "implementation", "difficulty": "Intermediate", - "source": "../../commands/issue/execute.md" + "source": "../../../commands/issue/execute.md" }, { "name": "from-brainstorm", @@ -117,7 +175,7 @@ "subcategory": null, "usage_scenario": "planning", "difficulty": "Intermediate", - "source": "../../commands/issue/from-brainstorm.md" + "source": "../../../commands/issue/from-brainstorm.md" }, { "name": "new", @@ -128,7 +186,7 @@ "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/issue/new.md" + "source": "../../../commands/issue/new.md" }, { "name": "plan", @@ -139,7 +197,7 @@ "subcategory": null, "usage_scenario": "planning", "difficulty": "Intermediate", - "source": "../../commands/issue/plan.md" + "source": "../../../commands/issue/plan.md" }, { "name": "queue", @@ -150,51 +208,18 @@ "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/issue/queue.md" + "source": "../../../commands/issue/queue.md" }, { - "name": "compact", - "command": "/memory:compact", - "description": "Compact current session memory into structured text for session recovery, extracting objective/plan/files/decisions/constraints/state, and save via MCP core_memory tool", - "arguments": "[optional: session description]", - "category": "memory", - "subcategory": null, - "usage_scenario": "general", - "difficulty": "Intermediate", - "source": "../../commands/memory/compact.md" - }, - { - "name": "docs-full-cli", - "command": "/memory:docs-full-cli", - "description": "Generate full project documentation using CLI execution (Layer 3→1) with batched agents (4 modules/agent) and gemini→qwen→codex fallback, <20 modules uses direct parallel", - "arguments": "[path] [--tool ]", - "category": "memory", - "subcategory": null, - "usage_scenario": "documentation", - "difficulty": "Intermediate", - "source": "../../commands/memory/docs-full-cli.md" - }, - { - "name": "docs-related-cli", - "command": "/memory:docs-related-cli", - "description": "Generate/update documentation for git-changed modules using CLI execution with batched agents (4 modules/agent) and gemini→qwen→codex fallback, <15 modules uses direct parallel", - "arguments": "[--tool ]", - "category": "memory", - "subcategory": null, - "usage_scenario": "documentation", - "difficulty": "Intermediate", - "source": "../../commands/memory/docs-related-cli.md" - }, - { - "name": "load", - "command": "/memory:load", + "name": "prepare", + "command": "/memory:prepare", "description": "Delegate to universal-executor agent to analyze project via Gemini/Qwen CLI and return JSON core content package for task context", "arguments": "[--tool gemini|qwen] \\\"task context description\\", "category": "memory", "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/memory/load.md" + "source": "../../../commands/memory/prepare.md" }, { "name": "style-skill-memory", @@ -205,51 +230,7 @@ "subcategory": null, "usage_scenario": "documentation", "difficulty": "Intermediate", - "source": "../../commands/memory/style-skill-memory.md" - }, - { - "name": "tips", - "command": "/memory:tips", - "description": "Quick note-taking command to capture ideas, snippets, reminders, and insights for later reference", - "arguments": " [--tag ] [--context ]", - "category": "memory", - "subcategory": null, - "usage_scenario": "general", - "difficulty": "Intermediate", - "source": "../../commands/memory/tips.md" - }, - { - "name": "update-full", - "command": "/memory:update-full", - "description": "Update all CLAUDE.md files using layer-based execution (Layer 3→1) with batched agents (4 modules/agent) and gemini→qwen→codex fallback, <20 modules uses direct parallel", - "arguments": "[--tool gemini|qwen|codex] [--path ]", - "category": "memory", - "subcategory": null, - "usage_scenario": "general", - "difficulty": "Intermediate", - "source": "../../commands/memory/update-full.md" - }, - { - "name": "update-related", - "command": "/memory:update-related", - "description": "Update CLAUDE.md for git-changed modules using batched agent execution (4 modules/agent) with gemini→qwen→codex fallback, <15 modules uses direct execution", - "arguments": "[--tool gemini|qwen|codex]", - "category": "memory", - "subcategory": null, - "usage_scenario": "general", - "difficulty": "Intermediate", - "source": "../../commands/memory/update-related.md" - }, - { - "name": "ccw view", - "command": "/ccw view", - "description": "Dashboard - Open CCW workflow dashboard for managing tasks and sessions", - "arguments": "", - "category": "general", - "subcategory": null, - "usage_scenario": "general", - "difficulty": "Intermediate", - "source": "../../commands/view.md" + "source": "../../../commands/memory/style-skill-memory.md" }, { "name": "analyze-with-file", @@ -260,51 +241,7 @@ "subcategory": null, "usage_scenario": "analysis", "difficulty": "Beginner", - "source": "../../commands/workflow/analyze-with-file.md" - }, - { - "name": "artifacts", - "command": "/workflow:brainstorm:artifacts", - "description": "Interactive clarification generating confirmed guidance specification through role-based analysis and synthesis", - "arguments": "[-y|--yes] topic or challenge description [--count N]", - "category": "workflow", - "subcategory": "brainstorm", - "usage_scenario": "general", - "difficulty": "Intermediate", - "source": "../../commands/workflow/brainstorm/artifacts.md" - }, - { - "name": "auto-parallel", - "command": "/workflow:brainstorm:auto-parallel", - "description": "Parallel brainstorming automation with dynamic role selection and concurrent execution across multiple perspectives", - "arguments": "[-y|--yes] topic or challenge description [--count N]", - "category": "workflow", - "subcategory": "brainstorm", - "usage_scenario": "general", - "difficulty": "Advanced", - "source": "../../commands/workflow/brainstorm/auto-parallel.md" - }, - { - "name": "role-analysis", - "command": "/workflow:brainstorm:role-analysis", - "description": "Unified role-specific analysis generation with interactive context gathering and incremental updates", - "arguments": "[role-name] [--session session-id] [--update] [--include-questions] [--skip-questions]", - "category": "workflow", - "subcategory": "brainstorm", - "usage_scenario": "general", - "difficulty": "Intermediate", - "source": "../../commands/workflow/brainstorm/role-analysis.md" - }, - { - "name": "synthesis", - "command": "/workflow:brainstorm:synthesis", - "description": "Clarify and refine role analyses through intelligent Q&A and targeted updates with synthesis agent", - "arguments": "[-y|--yes] [optional: --session session-id]", - "category": "workflow", - "subcategory": "brainstorm", - "usage_scenario": "general", - "difficulty": "Advanced", - "source": "../../commands/workflow/brainstorm/synthesis.md" + "source": "../../../commands/workflow/analyze-with-file.md" }, { "name": "brainstorm-with-file", @@ -315,7 +252,7 @@ "subcategory": null, "usage_scenario": "planning", "difficulty": "Intermediate", - "source": "../../commands/workflow/brainstorm-with-file.md" + "source": "../../../commands/workflow/brainstorm-with-file.md" }, { "name": "clean", @@ -326,7 +263,18 @@ "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/workflow/clean.md" + "source": "../../../commands/workflow/clean.md" + }, + { + "name": "workflow:collaborative-plan-with-file", + "command": "/workflow:collaborative-plan-with-file", + "description": "Collaborative planning with Plan Note - Understanding agent creates shared plan-note.md template, parallel agents fill pre-allocated sections, conflict detection without merge. Outputs executable plan-note.md.", + "arguments": "[-y|--yes] [--max-agents=5]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "planning", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/collaborative-plan-with-file.md" }, { "name": "debug-with-file", @@ -337,150 +285,73 @@ "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/workflow/debug-with-file.md" + "source": "../../../commands/workflow/debug-with-file.md" }, { - "name": "execute", - "command": "/workflow-execute", - "description": "Coordinate agent execution for workflow tasks with automatic session discovery, parallel task processing, and status tracking", - "arguments": "[-y|--yes] [--resume-session=\\\"session-id\\\"]", + "name": "init-guidelines", + "command": "/workflow:init-guidelines", + "description": "Interactive wizard to fill specs/*.md based on project analysis", + "arguments": "[--reset]", "category": "workflow", "subcategory": null, - "usage_scenario": "implementation", + "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/workflow/execute.md" + "source": "../../../commands/workflow/init-guidelines.md" + }, + { + "name": "init-specs", + "command": "/workflow:init-specs", + "description": "Interactive wizard to create individual specs or personal constraints with scope selection", + "arguments": "[--scope ] [--dimension ] [--category ]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/init-specs.md" }, { "name": "init", "command": "/workflow:init", "description": "Initialize project-level state with intelligent project analysis using cli-explore-agent", - "arguments": "[--regenerate]", + "arguments": "[--regenerate] [--skip-specs]", "category": "workflow", "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/workflow/init.md" + "source": "../../../commands/workflow/init.md" }, { - "name": "lite-fix", - "command": "/workflow:lite-fix", - "description": "Lightweight bug diagnosis and fix workflow with intelligent severity assessment and optional hotfix mode for production incidents", - "arguments": "[-y|--yes] [--hotfix] \\\"bug description or issue reference\\", + "name": "integration-test-cycle", + "command": "/workflow:integration-test-cycle", + "description": "Self-iterating integration test workflow with codebase exploration, test development, autonomous test-fix cycles, and reflection-driven strategy adjustment", + "arguments": "[-y|--yes] [-c|--continue] [--max-iterations=N] \\\"module or feature description\\", + "category": "workflow", + "subcategory": null, + "usage_scenario": "testing", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/integration-test-cycle.md" + }, + { + "name": "refactor-cycle", + "command": "/workflow:refactor-cycle", + "description": "Tech debt discovery and self-iterating refactoring with multi-dimensional analysis, prioritized execution, regression validation, and reflection-driven adjustment", + "arguments": "[-y|--yes] [-c|--continue] [--scope=module|project] \\\"module or refactoring goal\\", "category": "workflow", "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/workflow/lite-fix.md" + "source": "../../../commands/workflow/refactor-cycle.md" }, { - "name": "workflow:lite-lite-lite", - "command": "/workflow:lite-lite-lite", - "description": "Ultra-lightweight multi-tool analysis and direct execution. No artifacts for simple tasks; auto-creates planning docs in .workflow/.scratchpad/ for complex tasks. Auto tool selection based on task analysis, user-driven iteration via AskUser.", - "arguments": "[-y|--yes] ", + "name": "roadmap-with-file", + "command": "/workflow:roadmap-with-file", + "description": "Strategic requirement roadmap with iterative decomposition and issue creation. Outputs roadmap.md (human-readable, single source) + issues.jsonl (machine-executable). Handoff to team-planex.", + "arguments": "[-y|--yes] [-c|--continue] [-m progressive|direct|auto] \\\"requirement description\\", "category": "workflow", "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/workflow/lite-lite-lite.md" - }, - { - "name": "lite-plan", - "command": "/workflow-lite-planex", - "description": "Lightweight interactive planning and execution workflow (Phase 1: plan, Phase 2: execute) with in-memory planning, code exploration, and automatic execution after user confirmation", - "arguments": "[-y|--yes] [-e|--explore] \\\"task description\\\"|file.md", - "category": "workflow", - "subcategory": null, - "usage_scenario": "planning", - "difficulty": "Intermediate", - "source": "../../commands/workflow/lite-plan.md" - }, - { - "name": "workflow-multi-cli-plan", - "command": "/workflow-multi-cli-plan", - "description": "Multi-CLI collaborative planning workflow with ACE context gathering and iterative cross-verification. Uses cli-discuss-agent for Gemini+Codex+Claude analysis to converge on optimal execution plan.", - "arguments": "[-y|--yes] [--max-rounds=3] [--tools=gemini,codex] [--mode=parallel|serial]", - "category": "workflow", - "subcategory": null, - "usage_scenario": "planning", - "difficulty": "Intermediate", - "source": "../../commands/workflow/multi-cli-plan.md" - }, - { - "name": "plan-verify", - "command": "/workflow-plan-verify", - "description": "Perform READ-ONLY verification analysis between IMPL_PLAN.md, task JSONs, and brainstorming artifacts. Generates structured report with quality gate recommendation. Does NOT modify any files.", - "arguments": "[optional: --session session-id]", - "category": "workflow", - "subcategory": null, - "usage_scenario": "planning", - "difficulty": "Intermediate", - "source": "../../commands/workflow/plan-verify.md" - }, - { - "name": "plan", - "command": "/workflow-plan", - "description": "5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs", - "arguments": "[-y|--yes] \\\"text description\\\"|file.md", - "category": "workflow", - "subcategory": null, - "usage_scenario": "planning", - "difficulty": "Intermediate", - "source": "../../commands/workflow/plan.md" - }, - { - "name": "replan", - "command": "/workflow:replan", - "description": "Interactive workflow replanning with session-level artifact updates and boundary clarification through guided questioning", - "arguments": "[-y|--yes] [--session session-id] [task-id] \\\"requirements\\\"|file.md [--interactive]", - "category": "workflow", - "subcategory": null, - "usage_scenario": "planning", - "difficulty": "Intermediate", - "source": "../../commands/workflow/replan.md" - }, - { - "name": "review-cycle-fix", - "command": "/workflow:review-cycle-fix", - "description": "Automated fixing of code review findings with AI-powered planning and coordinated execution. Uses intelligent grouping, multi-stage timeline coordination, and test-driven verification.", - "arguments": " [--resume] [--max-iterations=N]", - "category": "workflow", - "subcategory": null, - "usage_scenario": "analysis", - "difficulty": "Intermediate", - "source": "../../commands/workflow/review-cycle-fix.md" - }, - { - "name": "review-module-cycle", - "command": "/workflow:review-module-cycle", - "description": "Independent multi-dimensional code review for specified modules/files. Analyzes specific code paths across 7 dimensions with hybrid parallel-iterative execution, independent of workflow sessions.", - "arguments": " [--dimensions=security,architecture,...] [--max-iterations=N]", - "category": "workflow", - "subcategory": null, - "usage_scenario": "analysis", - "difficulty": "Intermediate", - "source": "../../commands/workflow/review-module-cycle.md" - }, - { - "name": "review-session-cycle", - "command": "/workflow:review-session-cycle", - "description": "Session-based comprehensive multi-dimensional code review. Analyzes git changes from workflow session across 7 dimensions with hybrid parallel-iterative execution, aggregates findings, and performs focused deep-dives on critical issues until quality gates met.", - "arguments": "[session-id] [--dimensions=security,architecture,...] [--max-iterations=N]", - "category": "workflow", - "subcategory": null, - "usage_scenario": "session-management", - "difficulty": "Intermediate", - "source": "../../commands/workflow/review-session-cycle.md" - }, - { - "name": "review", - "command": "/workflow:review", - "description": "Post-implementation review with specialized types (security/architecture/action-items/quality) using analysis agents and Gemini", - "arguments": "[--type=security|architecture|action-items|quality] [--archived] [optional: session-id]", - "category": "workflow", - "subcategory": null, - "usage_scenario": "analysis", - "difficulty": "Intermediate", - "source": "../../commands/workflow/review.md" + "source": "../../../commands/workflow/roadmap-with-file.md" }, { "name": "complete", @@ -491,7 +362,7 @@ "subcategory": "session", "usage_scenario": "session-management", "difficulty": "Intermediate", - "source": "../../commands/workflow/session/complete.md" + "source": "../../../commands/workflow/session/complete.md" }, { "name": "list", @@ -502,7 +373,7 @@ "subcategory": "session", "usage_scenario": "general", "difficulty": "Beginner", - "source": "../../commands/workflow/session/list.md" + "source": "../../../commands/workflow/session/list.md" }, { "name": "resume", @@ -513,18 +384,18 @@ "subcategory": "session", "usage_scenario": "session-management", "difficulty": "Intermediate", - "source": "../../commands/workflow/session/resume.md" + "source": "../../../commands/workflow/session/resume.md" }, { "name": "solidify", "command": "/workflow:session:solidify", - "description": "Crystallize session learnings and user-defined constraints into permanent project guidelines", - "arguments": "[-y|--yes] [--type ] [--category ] \\\"rule or insight\\", + "description": "Crystallize session learnings and user-defined constraints into permanent project guidelines, or compress recent memories", + "arguments": "[-y|--yes] [--type ] [--category ] [--limit ] \\\"rule or insight\\", "category": "workflow", "subcategory": "session", "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/workflow/session/solidify.md" + "source": "../../../commands/workflow/session/solidify.md" }, { "name": "start", @@ -535,150 +406,18 @@ "subcategory": "session", "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/workflow/session/start.md" + "source": "../../../commands/workflow/session/start.md" }, { - "name": "tdd-plan", - "command": "/workflow-tdd-plan", - "description": "TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking", - "arguments": "\\\"feature description\\\"|file.md", + "name": "sync", + "command": "/workflow:session:sync", + "description": "Quick-sync session work to specs/*.md and project-tech", + "arguments": "[-y|--yes] [\\\"what was done\\\"]", "category": "workflow", - "subcategory": null, - "usage_scenario": "planning", - "difficulty": "Advanced", - "source": "../../commands/workflow/tdd-plan.md" - }, - { - "name": "tdd-verify", - "command": "/workflow-tdd-verify", - "description": "Verify TDD workflow compliance against Red-Green-Refactor cycles. Generates quality report with coverage analysis and quality gate recommendation. Orchestrates sub-commands for comprehensive validation.", - "arguments": "[optional: --session WFS-session-id]", - "category": "workflow", - "subcategory": null, - "usage_scenario": "testing", - "difficulty": "Advanced", - "source": "../../commands/workflow/tdd-verify.md" - }, - { - "name": "test-cycle-execute", - "command": "/workflow-test-fix", - "description": "Execute test-fix workflow with dynamic task generation and iterative fix cycles until test pass rate >= 95% or max iterations reached. Uses @cli-planning-agent for failure analysis and task generation.", - "arguments": "[--resume-session=\\\"session-id\\\"] [--max-iterations=N]", - "category": "workflow", - "subcategory": null, - "usage_scenario": "implementation", - "difficulty": "Intermediate", - "source": "../../commands/workflow/test-cycle-execute.md" - }, - { - "name": "test-fix-gen", - "command": "/workflow-test-fix", - "description": "Create test-fix workflow session from session ID, description, or file path with test strategy generation and task planning", - "arguments": "(source-session-id | \\\"feature description\\\" | /path/to/file.md)", - "category": "workflow", - "subcategory": null, - "usage_scenario": "testing", - "difficulty": "Intermediate", - "source": "../../commands/workflow/test-fix-gen.md" - }, - { - "name": "test-gen", - "command": "/workflow:test-gen", - "description": "Create independent test-fix workflow session from completed implementation session, analyzes code to generate test tasks", - "arguments": "source-session-id", - "category": "workflow", - "subcategory": null, - "usage_scenario": "testing", - "difficulty": "Intermediate", - "source": "../../commands/workflow/test-gen.md" - }, - { - "name": "conflict-resolution", - "command": "/workflow:tools:conflict-resolution", - "description": "Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis with Gemini/Qwen", - "arguments": "[-y|--yes] --session WFS-session-id --context path/to/context-package.json", - "category": "workflow", - "subcategory": "tools", - "usage_scenario": "general", - "difficulty": "Advanced", - "source": "../../commands/workflow/tools/conflict-resolution.md" - }, - { - "name": "gather", - "command": "/workflow:tools:gather", - "description": "Intelligently collect project context using context-search-agent based on task description, packages into standardized JSON", - "arguments": "--session WFS-session-id \\\"task description\\", - "category": "workflow", - "subcategory": "tools", + "subcategory": "session", "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/workflow/tools/context-gather.md" - }, - { - "name": "task-generate-agent", - "command": "/workflow:tools:task-generate-agent", - "description": "Generate implementation plan documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent - produces planning artifacts, does NOT execute code implementation", - "arguments": "[-y|--yes] --session WFS-session-id", - "category": "workflow", - "subcategory": "tools", - "usage_scenario": "implementation", - "difficulty": "Advanced", - "source": "../../commands/workflow/tools/task-generate-agent.md" - }, - { - "name": "task-generate-tdd", - "command": "/workflow:tools:task-generate-tdd", - "description": "Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation", - "arguments": "[-y|--yes] --session WFS-session-id", - "category": "workflow", - "subcategory": "tools", - "usage_scenario": "implementation", - "difficulty": "Advanced", - "source": "../../commands/workflow/tools/task-generate-tdd.md" - }, - { - "name": "tdd-coverage-analysis", - "command": "/workflow:tools:tdd-coverage-analysis", - "description": "Analyze test coverage and TDD cycle execution with Red-Green-Refactor compliance verification", - "arguments": "--session WFS-session-id", - "category": "workflow", - "subcategory": "tools", - "usage_scenario": "testing", - "difficulty": "Advanced", - "source": "../../commands/workflow/tools/tdd-coverage-analysis.md" - }, - { - "name": "test-concept-enhanced", - "command": "/workflow:tools:test-concept-enhanced", - "description": "Coordinate test analysis workflow using cli-execution-agent to generate test strategy via Gemini", - "arguments": "--session WFS-test-session-id --context path/to/test-context-package.json", - "category": "workflow", - "subcategory": "tools", - "usage_scenario": "testing", - "difficulty": "Intermediate", - "source": "../../commands/workflow/tools/test-concept-enhanced.md" - }, - { - "name": "test-context-gather", - "command": "/workflow:tools:test-context-gather", - "description": "Collect test coverage context using test-context-search-agent and package into standardized test-context JSON", - "arguments": "--session WFS-test-session-id", - "category": "workflow", - "subcategory": "tools", - "usage_scenario": "testing", - "difficulty": "Intermediate", - "source": "../../commands/workflow/tools/test-context-gather.md" - }, - { - "name": "test-task-generate", - "command": "/workflow:tools:test-task-generate", - "description": "Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) using action-planning-agent - produces test planning artifacts, does NOT execute tests", - "arguments": "--session WFS-test-session-id", - "category": "workflow", - "subcategory": "tools", - "usage_scenario": "implementation", - "difficulty": "Intermediate", - "source": "../../commands/workflow/tools/test-task-generate.md" + "source": "../../../commands/workflow/session/sync.md" }, { "name": "animation-extract", @@ -689,7 +428,7 @@ "subcategory": "ui-design", "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/workflow/ui-design/animation-extract.md" + "source": "../../../commands/workflow/ui-design/animation-extract.md" }, { "name": "workflow:ui-design:codify-style", @@ -700,7 +439,7 @@ "subcategory": "ui-design", "usage_scenario": "planning", "difficulty": "Intermediate", - "source": "../../commands/workflow/ui-design/codify-style.md" + "source": "../../../commands/workflow/ui-design/codify-style.md" }, { "name": "design-sync", @@ -711,7 +450,7 @@ "subcategory": "ui-design", "usage_scenario": "planning", "difficulty": "Intermediate", - "source": "../../commands/workflow/ui-design/design-sync.md" + "source": "../../../commands/workflow/ui-design/design-sync.md" }, { "name": "explore-auto", @@ -722,7 +461,7 @@ "subcategory": "ui-design", "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/workflow/ui-design/explore-auto.md" + "source": "../../../commands/workflow/ui-design/explore-auto.md" }, { "name": "generate", @@ -733,7 +472,7 @@ "subcategory": "ui-design", "usage_scenario": "implementation", "difficulty": "Intermediate", - "source": "../../commands/workflow/ui-design/generate.md" + "source": "../../../commands/workflow/ui-design/generate.md" }, { "name": "imitate-auto", @@ -744,7 +483,7 @@ "subcategory": "ui-design", "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/workflow/ui-design/imitate-auto.md" + "source": "../../../commands/workflow/ui-design/imitate-auto.md" }, { "name": "workflow:ui-design:import-from-code", @@ -755,7 +494,7 @@ "subcategory": "ui-design", "usage_scenario": "planning", "difficulty": "Intermediate", - "source": "../../commands/workflow/ui-design/import-from-code.md" + "source": "../../../commands/workflow/ui-design/import-from-code.md" }, { "name": "layout-extract", @@ -766,7 +505,7 @@ "subcategory": "ui-design", "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/workflow/ui-design/layout-extract.md" + "source": "../../../commands/workflow/ui-design/layout-extract.md" }, { "name": "workflow:ui-design:reference-page-generator", @@ -777,7 +516,7 @@ "subcategory": "ui-design", "usage_scenario": "planning", "difficulty": "Intermediate", - "source": "../../commands/workflow/ui-design/reference-page-generator.md" + "source": "../../../commands/workflow/ui-design/reference-page-generator.md" }, { "name": "style-extract", @@ -788,18 +527,18 @@ "subcategory": "ui-design", "usage_scenario": "general", "difficulty": "Intermediate", - "source": "../../commands/workflow/ui-design/style-extract.md" + "source": "../../../commands/workflow/ui-design/style-extract.md" }, { "name": "unified-execute-with-file", "command": "/workflow:unified-execute-with-file", "description": "Universal execution engine for consuming any planning/brainstorm/analysis output with minimal progress tracking, multi-agent coordination, and incremental execution", - "arguments": "[-y|--yes] [-p|--plan ] [-m|--mode sequential|parallel] [\\\"execution context or task name\\\"]", + "arguments": "[-y|--yes] [[,] | -p|--plan [,]] [--auto-commit] [--commit-prefix \\\"prefix\\\"] [\\\"execution context or task name\\\"]", "category": "workflow", "subcategory": null, "usage_scenario": "implementation", "difficulty": "Intermediate", - "source": "../../commands/workflow/unified-execute-with-file.md" + "source": "../../../commands/workflow/unified-execute-with-file.md" } ], "agents": [ @@ -833,6 +572,11 @@ "description": "|", "source": "../../../agents/cli-planning-agent.md" }, + { + "name": "cli-roadmap-plan-agent", + "description": "|", + "source": "../../../agents/cli-roadmap-plan-agent.md" + }, { "name": "code-developer", "description": "|", @@ -878,6 +622,16 @@ "description": "|", "source": "../../../agents/tdd-developer.md" }, + { + "name": "team-worker", + "description": "|", + "source": "../../../agents/team-worker.md" + }, + { + "name": "test-action-planning-agent", + "description": "|", + "source": "../../../agents/test-action-planning-agent.md" + }, { "name": "test-context-search-agent", "description": "|", @@ -899,13 +653,382 @@ "source": "../../../agents/universal-executor.md" } ], + "skills": [ + { + "name": "brainstorm", + "description": "Unified brainstorming skill with dual-mode operation - auto pipeline and single role analysis. Triggers on \"brainstorm\", \"头脑风暴\".", + "category": "standalone", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/brainstorm/SKILL.md" + }, + { + "name": "command-generator", + "description": "Command file generator - 5 phase workflow for creating Claude Code command files with YAML frontmatter. Generates .md command files for project or user scope. Triggers on \"create command\", \"new command\", \"command generator\".", + "category": "meta", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/command-generator/SKILL.md" + }, + { + "name": "issue-manage", + "description": "Interactive issue management with menu-driven CRUD operations. Use when managing issues, viewing issue status, editing issue fields, performing bulk operations, or viewing issue history. Triggers on \"manage issue\", \"list issues\", \"edit issue\", \"delete issue\", \"bulk update\", \"issue dashboard\", \"issue history\", \"completed issues\".", + "category": "utility", + "is_team": false, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/issue-manage/SKILL.md" + }, + { + "name": "memory-capture", + "description": "Unified memory capture with routing - session compact or quick tips. Triggers on \"memory capture\", \"compact session\", \"save session\", \"quick tip\", \"memory tips\", \"记录\", \"压缩会话\".", + "category": "utility", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/memory-capture/SKILL.md" + }, + { + "name": "memory-manage", + "description": "Unified memory management - CLAUDE.md updates and documentation generation with interactive routing. Triggers on \"memory manage\", \"update claude\", \"update memory\", \"generate docs\", \"更新记忆\", \"生成文档\".", + "category": "utility", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/memory-manage/SKILL.md" + }, + { + "name": "review-code", + "description": "Multi-dimensional code review with structured reports. Analyzes correctness, readability, performance, security, testing, and architecture. Triggers on \"review code\", \"code review\", \"审查代码\", \"代码审查\".", + "category": "review", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/review-code/SKILL.md" + }, + { + "name": "review-cycle", + "description": "Unified multi-dimensional code review with automated fix orchestration. Routes to session-based (git changes), module-based (path patterns), or fix mode. Triggers on \"workflow:review-cycle\", \"workflow:review-session-cycle\", \"workflow:review-module-cycle\", \"workflow:review-cycle-fix\".", + "category": "review", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/review-cycle/SKILL.md" + }, + { + "name": "skill-generator", + "description": "Meta-skill for creating new Claude Code skills with configurable execution modes. Supports sequential (fixed order) and autonomous (stateless) phase patterns. Use for skill scaffolding, skill creation, or building new workflows. Triggers on \"create skill\", \"new skill\", \"skill generator\".", + "category": "meta", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/skill-generator/SKILL.md" + }, + { + "name": "skill-tuning", + "description": "Universal skill diagnosis and optimization tool. Detect and fix skill execution issues including context explosion, long-tail forgetting, data flow disruption, and agent coordination failures. Supports Gemini CLI for deep analysis. Triggers on \"skill tuning\", \"tune skill\", \"skill diagnosis\", \"optimize skill\", \"skill debug\".", + "category": "meta", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/skill-tuning/SKILL.md" + }, + { + "name": "spec-generator", + "description": "Specification generator - 6 phase document chain producing product brief, PRD, architecture, and epics. Triggers on \"generate spec\", \"create specification\", \"spec generator\", \"workflow:spec\".", + "category": "meta", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/spec-generator/SKILL.md" + }, + { + "name": "team-brainstorm", + "description": "Unified team skill for brainstorming team. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team brainstorm\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-brainstorm/SKILL.md" + }, + { + "name": "team-coordinate", + "description": "Universal team coordination skill with dynamic role generation. Only coordinator is built-in -- all worker roles are generated at runtime based on task analysis. Beat/cadence model for orchestration. Triggers on \"team coordinate\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-coordinate/SKILL.md" + }, + { + "name": "team-coordinate-v2", + "description": "Universal team coordination skill with dynamic role generation. Uses team-worker agent architecture with role-spec files. Only coordinator is built-in -- all worker roles are generated at runtime as role-specs and spawned via team-worker agent. Beat/cadence model for orchestration. Triggers on \"team coordinate v2\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-coordinate-v2/SKILL.md" + }, + { + "name": "team-executor", + "description": "Lightweight session execution skill. Resumes existing team-coordinate sessions for pure execution. No analysis, no role generation -- only loads and executes. Session path required. Triggers on \"team executor\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-executor/SKILL.md" + }, + { + "name": "team-executor-v2", + "description": "Lightweight session execution skill. Resumes existing team-coordinate-v2 sessions for pure execution via team-worker agents. No analysis, no role generation -- only loads and executes. Session path required. Triggers on \"team executor v2\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-executor-v2/SKILL.md" + }, + { + "name": "team-frontend", + "description": "Unified team skill for frontend development team. All roles invoke this skill with --role arg. Built-in ui-ux-pro-max design intelligence. Triggers on \"team frontend\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-frontend/SKILL.md" + }, + { + "name": "team-issue", + "description": "Unified team skill for issue resolution. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team issue\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-issue/SKILL.md" + }, + { + "name": "team-iterdev", + "description": "Unified team skill for iterative development team. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team iterdev\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-iterdev/SKILL.md" + }, + { + "name": "team-lifecycle-v3", + "description": "Unified team skill for full lifecycle - spec/impl/test. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team lifecycle\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-lifecycle-v3/SKILL.md" + }, + { + "name": "team-lifecycle-v4", + "description": "Unified team skill for full lifecycle - spec/impl/test. Optimized cadence with inline discuss subagent and shared explore. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team lifecycle\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-lifecycle-v4/SKILL.md" + }, + { + "name": "team-lifecycle-v5", + "description": "Unified team skill for full lifecycle - spec/impl/test. Uses team-worker agent architecture with role-spec files for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents loaded with role-specific Phase 2-4 specs. Triggers on \"team lifecycle\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": true, + "version": "", + "source": "../../../skills/team-lifecycle-v5/SKILL.md" + }, + { + "name": "team-planex", + "description": "Unified team skill for plan-and-execute pipeline. Uses team-worker agent architecture with role-spec files for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on \"team planex\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": true, + "version": "", + "source": "../../../skills/team-planex/SKILL.md" + }, + { + "name": "team-quality-assurance", + "description": "Unified team skill for quality assurance team. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team quality-assurance\", \"team qa\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-quality-assurance/SKILL.md" + }, + { + "name": "team-review", + "description": "Unified team skill for code scanning, vulnerability review, optimization suggestions, and automated fix. 4-role team: coordinator, scanner, reviewer, fixer. Triggers on team-review.", + "category": "team", + "is_team": false, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-review/SKILL.md" + }, + { + "name": "team-roadmap-dev", + "description": "Unified team skill for roadmap-driven development workflow. Coordinator discusses roadmap with user, then dispatches phased execution pipeline (plan -> execute -> verify). All roles invoke this skill with --role arg. Triggers on \"team roadmap-dev\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-roadmap-dev/SKILL.md" + }, + { + "name": "team-tech-debt", + "description": "Unified team skill for tech debt identification and cleanup. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team tech-debt\", \"tech debt cleanup\", \"技术债务\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-tech-debt/SKILL.md" + }, + { + "name": "team-testing", + "description": "Unified team skill for testing team. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team testing\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-testing/SKILL.md" + }, + { + "name": "team-uidesign", + "description": "Unified team skill for UI design team. All roles invoke this skill with --role arg for role-specific execution. CP-9 Dual-Track design+implementation.", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-uidesign/SKILL.md" + }, + { + "name": "team-ultra-analyze", + "description": "Unified team skill for deep collaborative analysis. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team ultra-analyze\", \"team analyze\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-ultra-analyze/SKILL.md" + }, + { + "name": "workflow-execute", + "description": "Coordinate agent execution for workflow tasks with automatic session discovery, parallel task processing, and status tracking. Triggers on \"workflow-execute\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-execute/SKILL.md" + }, + { + "name": "workflow-lite-planex", + "description": "Lightweight planning and execution skill (Phase 1: plan, Phase 2: execute). Triggers on \"workflow-lite-planex\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-lite-planex/SKILL.md" + }, + { + "name": "workflow-multi-cli-plan", + "description": "Multi-CLI collaborative planning and execution skill with integrated execution phase. Triggers on \"workflow-multi-cli-plan\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-multi-cli-plan/SKILL.md" + }, + { + "name": "workflow-plan", + "description": "Unified planning skill - 4-phase planning workflow, plan verification, and interactive replanning. Triggers on \"workflow-plan\", \"workflow-plan-verify\", \"workflow:replan\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-plan/SKILL.md" + }, + { + "name": "workflow-skill-designer", + "description": "Meta-skill for designing orchestrator+phases structured workflow skills. Creates SKILL.md coordinator with progressive phase loading, TodoWrite patterns, and data flow. Triggers on \"design workflow skill\", \"create workflow skill\", \"workflow skill designer\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-skill-designer/SKILL.md" + }, + { + "name": "workflow-tdd-plan-plan", + "description": "Unified TDD workflow skill combining 6-phase TDD planning with Red-Green-Refactor task chain generation, and 4-phase TDD verification with compliance reporting. Triggers on \"workflow-tdd-plan\", \"workflow-tdd-verify\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-tdd-plan/SKILL.md" + }, + { + "name": "workflow-test-fix", + "description": "Unified test-fix pipeline combining test generation (session, context, analysis, task gen) with iterative test-cycle execution (adaptive strategy, progressive testing, CLI fallback). Triggers on \"workflow-test-fix\", \"workflow-test-fix\", \"test fix workflow\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-test-fix/SKILL.md" + } + ], "categories": [ "cli", "general", + "idaw", "issue", "memory", - "workflow", - "ui-design", - "tools" + "workflow" + ], + "skill_categories": [ + "meta", + "review", + "standalone", + "team", + "utility", + "workflow" ] } \ No newline at end of file diff --git a/.claude/skills/ccw-help/index/all-agents.json b/.claude/skills/ccw-help/index/all-agents.json index 7b111545..27cd5737 100644 --- a/.claude/skills/ccw-help/index/all-agents.json +++ b/.claude/skills/ccw-help/index/all-agents.json @@ -29,6 +29,11 @@ "description": "|", "source": "../../../agents/cli-planning-agent.md" }, + { + "name": "cli-roadmap-plan-agent", + "description": "|", + "source": "../../../agents/cli-roadmap-plan-agent.md" + }, { "name": "code-developer", "description": "|", @@ -74,6 +79,16 @@ "description": "|", "source": "../../../agents/tdd-developer.md" }, + { + "name": "team-worker", + "description": "|", + "source": "../../../agents/team-worker.md" + }, + { + "name": "test-action-planning-agent", + "description": "|", + "source": "../../../agents/test-action-planning-agent.md" + }, { "name": "test-context-search-agent", "description": "|", diff --git a/.claude/skills/ccw-help/index/all-commands.json b/.claude/skills/ccw-help/index/all-commands.json index 5ff53791..2e1ee0ed 100644 --- a/.claude/skills/ccw-help/index/all-commands.json +++ b/.claude/skills/ccw-help/index/all-commands.json @@ -43,6 +43,72 @@ "difficulty": "Intermediate", "source": "../../../commands/cli/codex-review.md" }, + { + "name": "flow-create", + "command": "/flow-create", + "description": "", + "arguments": "", + "category": "general", + "subcategory": null, + "usage_scenario": "implementation", + "difficulty": "Intermediate", + "source": "../../../commands/flow-create.md" + }, + { + "name": "add", + "command": "/idaw:add", + "description": "Add IDAW tasks - manual creation or import from ccw issue", + "arguments": "[-y|--yes] [--from-issue [,,...]] \\\"description\\\" [--type ] [--priority <1-5>]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/add.md" + }, + { + "name": "resume", + "command": "/idaw:resume", + "description": "Resume interrupted IDAW session from last checkpoint", + "arguments": "[-y|--yes] [session-id]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "session-management", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/resume.md" + }, + { + "name": "run-coordinate", + "command": "/idaw:run-coordinate", + "description": "IDAW coordinator - execute task skill chains via external CLI with hook callbacks and git checkpoints", + "arguments": "[-y|--yes] [--task [,,...]] [--dry-run] [--tool ]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/run-coordinate.md" + }, + { + "name": "run", + "command": "/idaw:run", + "description": "IDAW orchestrator - execute task skill chains serially with git checkpoints", + "arguments": "[-y|--yes] [--task [,,...]] [--dry-run]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/run.md" + }, + { + "name": "status", + "command": "/idaw:status", + "description": "View IDAW task and session progress", + "arguments": "[session-id]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "session-management", + "difficulty": "Beginner", + "source": "../../../commands/idaw/status.md" + }, { "name": "convert-to-plan", "command": "/issue:convert-to-plan", @@ -131,6 +197,17 @@ "difficulty": "Intermediate", "source": "../../../commands/issue/queue.md" }, + { + "name": "prepare", + "command": "/memory:prepare", + "description": "Delegate to universal-executor agent to analyze project via Gemini/Qwen CLI and return JSON core content package for task context", + "arguments": "[--tool gemini|qwen] \\\"task context description\\", + "category": "memory", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/memory/prepare.md" + }, { "name": "style-skill-memory", "command": "/memory:style-skill-memory", @@ -175,6 +252,17 @@ "difficulty": "Intermediate", "source": "../../../commands/workflow/clean.md" }, + { + "name": "workflow:collaborative-plan-with-file", + "command": "/workflow:collaborative-plan-with-file", + "description": "Collaborative planning with Plan Note - Understanding agent creates shared plan-note.md template, parallel agents fill pre-allocated sections, conflict detection without merge. Outputs executable plan-note.md.", + "arguments": "[-y|--yes] [--max-agents=5]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "planning", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/collaborative-plan-with-file.md" + }, { "name": "debug-with-file", "command": "/workflow:debug-with-file", @@ -186,17 +274,72 @@ "difficulty": "Intermediate", "source": "../../../commands/workflow/debug-with-file.md" }, + { + "name": "init-guidelines", + "command": "/workflow:init-guidelines", + "description": "Interactive wizard to fill specs/*.md based on project analysis", + "arguments": "[--reset]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/init-guidelines.md" + }, + { + "name": "init-specs", + "command": "/workflow:init-specs", + "description": "Interactive wizard to create individual specs or personal constraints with scope selection", + "arguments": "[--scope ] [--dimension ] [--category ]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/init-specs.md" + }, { "name": "init", "command": "/workflow:init", "description": "Initialize project-level state with intelligent project analysis using cli-explore-agent", - "arguments": "[--regenerate]", + "arguments": "[--regenerate] [--skip-specs]", "category": "workflow", "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", "source": "../../../commands/workflow/init.md" }, + { + "name": "integration-test-cycle", + "command": "/workflow:integration-test-cycle", + "description": "Self-iterating integration test workflow with codebase exploration, test development, autonomous test-fix cycles, and reflection-driven strategy adjustment", + "arguments": "[-y|--yes] [-c|--continue] [--max-iterations=N] \\\"module or feature description\\", + "category": "workflow", + "subcategory": null, + "usage_scenario": "testing", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/integration-test-cycle.md" + }, + { + "name": "refactor-cycle", + "command": "/workflow:refactor-cycle", + "description": "Tech debt discovery and self-iterating refactoring with multi-dimensional analysis, prioritized execution, regression validation, and reflection-driven adjustment", + "arguments": "[-y|--yes] [-c|--continue] [--scope=module|project] \\\"module or refactoring goal\\", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/refactor-cycle.md" + }, + { + "name": "roadmap-with-file", + "command": "/workflow:roadmap-with-file", + "description": "Strategic requirement roadmap with iterative decomposition and issue creation. Outputs roadmap.md (human-readable, single source) + issues.jsonl (machine-executable). Handoff to team-planex.", + "arguments": "[-y|--yes] [-c|--continue] [-m progressive|direct|auto] \\\"requirement description\\", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/roadmap-with-file.md" + }, { "name": "complete", "command": "/workflow:session:complete", @@ -233,8 +376,8 @@ { "name": "solidify", "command": "/workflow:session:solidify", - "description": "Crystallize session learnings and user-defined constraints into permanent project guidelines", - "arguments": "[-y|--yes] [--type ] [--category ] \\\"rule or insight\\", + "description": "Crystallize session learnings and user-defined constraints into permanent project guidelines, or compress recent memories", + "arguments": "[-y|--yes] [--type ] [--category ] [--limit ] \\\"rule or insight\\", "category": "workflow", "subcategory": "session", "usage_scenario": "general", @@ -252,6 +395,17 @@ "difficulty": "Intermediate", "source": "../../../commands/workflow/session/start.md" }, + { + "name": "sync", + "command": "/workflow:session:sync", + "description": "Quick-sync session work to specs/*.md and project-tech", + "arguments": "[-y|--yes] [\\\"what was done\\\"]", + "category": "workflow", + "subcategory": "session", + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/session/sync.md" + }, { "name": "animation-extract", "command": "/workflow:ui-design:animation-extract", @@ -366,11 +520,11 @@ "name": "unified-execute-with-file", "command": "/workflow:unified-execute-with-file", "description": "Universal execution engine for consuming any planning/brainstorm/analysis output with minimal progress tracking, multi-agent coordination, and incremental execution", - "arguments": "[-y|--yes] [-p|--plan ] [-m|--mode sequential|parallel] [\\\"execution context or task name\\\"]", + "arguments": "[-y|--yes] [[,] | -p|--plan [,]] [--auto-commit] [--commit-prefix \\\"prefix\\\"] [\\\"execution context or task name\\\"]", "category": "workflow", "subcategory": null, "usage_scenario": "implementation", "difficulty": "Intermediate", "source": "../../../commands/workflow/unified-execute-with-file.md" } -] +] \ No newline at end of file diff --git a/.claude/skills/ccw-help/index/all-skills.json b/.claude/skills/ccw-help/index/all-skills.json new file mode 100644 index 00000000..722024cd --- /dev/null +++ b/.claude/skills/ccw-help/index/all-skills.json @@ -0,0 +1,362 @@ +[ + { + "name": "brainstorm", + "description": "Unified brainstorming skill with dual-mode operation - auto pipeline and single role analysis. Triggers on \"brainstorm\", \"头脑风暴\".", + "category": "standalone", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/brainstorm/SKILL.md" + }, + { + "name": "command-generator", + "description": "Command file generator - 5 phase workflow for creating Claude Code command files with YAML frontmatter. Generates .md command files for project or user scope. Triggers on \"create command\", \"new command\", \"command generator\".", + "category": "meta", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/command-generator/SKILL.md" + }, + { + "name": "issue-manage", + "description": "Interactive issue management with menu-driven CRUD operations. Use when managing issues, viewing issue status, editing issue fields, performing bulk operations, or viewing issue history. Triggers on \"manage issue\", \"list issues\", \"edit issue\", \"delete issue\", \"bulk update\", \"issue dashboard\", \"issue history\", \"completed issues\".", + "category": "utility", + "is_team": false, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/issue-manage/SKILL.md" + }, + { + "name": "memory-capture", + "description": "Unified memory capture with routing - session compact or quick tips. Triggers on \"memory capture\", \"compact session\", \"save session\", \"quick tip\", \"memory tips\", \"记录\", \"压缩会话\".", + "category": "utility", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/memory-capture/SKILL.md" + }, + { + "name": "memory-manage", + "description": "Unified memory management - CLAUDE.md updates and documentation generation with interactive routing. Triggers on \"memory manage\", \"update claude\", \"update memory\", \"generate docs\", \"更新记忆\", \"生成文档\".", + "category": "utility", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/memory-manage/SKILL.md" + }, + { + "name": "review-code", + "description": "Multi-dimensional code review with structured reports. Analyzes correctness, readability, performance, security, testing, and architecture. Triggers on \"review code\", \"code review\", \"审查代码\", \"代码审查\".", + "category": "review", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/review-code/SKILL.md" + }, + { + "name": "review-cycle", + "description": "Unified multi-dimensional code review with automated fix orchestration. Routes to session-based (git changes), module-based (path patterns), or fix mode. Triggers on \"workflow:review-cycle\", \"workflow:review-session-cycle\", \"workflow:review-module-cycle\", \"workflow:review-cycle-fix\".", + "category": "review", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/review-cycle/SKILL.md" + }, + { + "name": "skill-generator", + "description": "Meta-skill for creating new Claude Code skills with configurable execution modes. Supports sequential (fixed order) and autonomous (stateless) phase patterns. Use for skill scaffolding, skill creation, or building new workflows. Triggers on \"create skill\", \"new skill\", \"skill generator\".", + "category": "meta", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/skill-generator/SKILL.md" + }, + { + "name": "skill-tuning", + "description": "Universal skill diagnosis and optimization tool. Detect and fix skill execution issues including context explosion, long-tail forgetting, data flow disruption, and agent coordination failures. Supports Gemini CLI for deep analysis. Triggers on \"skill tuning\", \"tune skill\", \"skill diagnosis\", \"optimize skill\", \"skill debug\".", + "category": "meta", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/skill-tuning/SKILL.md" + }, + { + "name": "spec-generator", + "description": "Specification generator - 6 phase document chain producing product brief, PRD, architecture, and epics. Triggers on \"generate spec\", \"create specification\", \"spec generator\", \"workflow:spec\".", + "category": "meta", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/spec-generator/SKILL.md" + }, + { + "name": "team-brainstorm", + "description": "Unified team skill for brainstorming team. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team brainstorm\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-brainstorm/SKILL.md" + }, + { + "name": "team-coordinate", + "description": "Universal team coordination skill with dynamic role generation. Only coordinator is built-in -- all worker roles are generated at runtime based on task analysis. Beat/cadence model for orchestration. Triggers on \"team coordinate\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-coordinate/SKILL.md" + }, + { + "name": "team-coordinate-v2", + "description": "Universal team coordination skill with dynamic role generation. Uses team-worker agent architecture with role-spec files. Only coordinator is built-in -- all worker roles are generated at runtime as role-specs and spawned via team-worker agent. Beat/cadence model for orchestration. Triggers on \"team coordinate v2\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-coordinate-v2/SKILL.md" + }, + { + "name": "team-executor", + "description": "Lightweight session execution skill. Resumes existing team-coordinate sessions for pure execution. No analysis, no role generation -- only loads and executes. Session path required. Triggers on \"team executor\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-executor/SKILL.md" + }, + { + "name": "team-executor-v2", + "description": "Lightweight session execution skill. Resumes existing team-coordinate-v2 sessions for pure execution via team-worker agents. No analysis, no role generation -- only loads and executes. Session path required. Triggers on \"team executor v2\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-executor-v2/SKILL.md" + }, + { + "name": "team-frontend", + "description": "Unified team skill for frontend development team. All roles invoke this skill with --role arg. Built-in ui-ux-pro-max design intelligence. Triggers on \"team frontend\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-frontend/SKILL.md" + }, + { + "name": "team-issue", + "description": "Unified team skill for issue resolution. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team issue\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-issue/SKILL.md" + }, + { + "name": "team-iterdev", + "description": "Unified team skill for iterative development team. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team iterdev\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-iterdev/SKILL.md" + }, + { + "name": "team-lifecycle-v3", + "description": "Unified team skill for full lifecycle - spec/impl/test. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team lifecycle\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-lifecycle-v3/SKILL.md" + }, + { + "name": "team-lifecycle-v4", + "description": "Unified team skill for full lifecycle - spec/impl/test. Optimized cadence with inline discuss subagent and shared explore. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team lifecycle\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-lifecycle-v4/SKILL.md" + }, + { + "name": "team-lifecycle-v5", + "description": "Unified team skill for full lifecycle - spec/impl/test. Uses team-worker agent architecture with role-spec files for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents loaded with role-specific Phase 2-4 specs. Triggers on \"team lifecycle\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": true, + "version": "", + "source": "../../../skills/team-lifecycle-v5/SKILL.md" + }, + { + "name": "team-planex", + "description": "Unified team skill for plan-and-execute pipeline. Uses team-worker agent architecture with role-spec files for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on \"team planex\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": true, + "version": "", + "source": "../../../skills/team-planex/SKILL.md" + }, + { + "name": "team-quality-assurance", + "description": "Unified team skill for quality assurance team. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team quality-assurance\", \"team qa\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-quality-assurance/SKILL.md" + }, + { + "name": "team-review", + "description": "Unified team skill for code scanning, vulnerability review, optimization suggestions, and automated fix. 4-role team: coordinator, scanner, reviewer, fixer. Triggers on team-review.", + "category": "team", + "is_team": false, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-review/SKILL.md" + }, + { + "name": "team-roadmap-dev", + "description": "Unified team skill for roadmap-driven development workflow. Coordinator discusses roadmap with user, then dispatches phased execution pipeline (plan -> execute -> verify). All roles invoke this skill with --role arg. Triggers on \"team roadmap-dev\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-roadmap-dev/SKILL.md" + }, + { + "name": "team-tech-debt", + "description": "Unified team skill for tech debt identification and cleanup. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team tech-debt\", \"tech debt cleanup\", \"技术债务\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-tech-debt/SKILL.md" + }, + { + "name": "team-testing", + "description": "Unified team skill for testing team. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team testing\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-testing/SKILL.md" + }, + { + "name": "team-uidesign", + "description": "Unified team skill for UI design team. All roles invoke this skill with --role arg for role-specific execution. CP-9 Dual-Track design+implementation.", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-uidesign/SKILL.md" + }, + { + "name": "team-ultra-analyze", + "description": "Unified team skill for deep collaborative analysis. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team ultra-analyze\", \"team analyze\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-ultra-analyze/SKILL.md" + }, + { + "name": "workflow-execute", + "description": "Coordinate agent execution for workflow tasks with automatic session discovery, parallel task processing, and status tracking. Triggers on \"workflow-execute\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-execute/SKILL.md" + }, + { + "name": "workflow-lite-planex", + "description": "Lightweight planning and execution skill (Phase 1: plan, Phase 2: execute). Triggers on \"workflow-lite-planex\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-lite-planex/SKILL.md" + }, + { + "name": "workflow-multi-cli-plan", + "description": "Multi-CLI collaborative planning and execution skill with integrated execution phase. Triggers on \"workflow-multi-cli-plan\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-multi-cli-plan/SKILL.md" + }, + { + "name": "workflow-plan", + "description": "Unified planning skill - 4-phase planning workflow, plan verification, and interactive replanning. Triggers on \"workflow-plan\", \"workflow-plan-verify\", \"workflow:replan\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-plan/SKILL.md" + }, + { + "name": "workflow-skill-designer", + "description": "Meta-skill for designing orchestrator+phases structured workflow skills. Creates SKILL.md coordinator with progressive phase loading, TodoWrite patterns, and data flow. Triggers on \"design workflow skill\", \"create workflow skill\", \"workflow skill designer\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-skill-designer/SKILL.md" + }, + { + "name": "workflow-tdd-plan-plan", + "description": "Unified TDD workflow skill combining 6-phase TDD planning with Red-Green-Refactor task chain generation, and 4-phase TDD verification with compliance reporting. Triggers on \"workflow-tdd-plan\", \"workflow-tdd-verify\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-tdd-plan/SKILL.md" + }, + { + "name": "workflow-test-fix", + "description": "Unified test-fix pipeline combining test generation (session, context, analysis, task gen) with iterative test-cycle execution (adaptive strategy, progressive testing, CLI fallback). Triggers on \"workflow-test-fix\", \"workflow-test-fix\", \"test fix workflow\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-test-fix/SKILL.md" + } +] \ No newline at end of file diff --git a/.claude/skills/ccw-help/index/by-category.json b/.claude/skills/ccw-help/index/by-category.json index 50f09362..023b8fa9 100644 --- a/.claude/skills/ccw-help/index/by-category.json +++ b/.claude/skills/ccw-help/index/by-category.json @@ -22,6 +22,17 @@ "usage_scenario": "general", "difficulty": "Intermediate", "source": "../../../commands/ccw.md" + }, + { + "name": "flow-create", + "command": "/flow-create", + "description": "", + "arguments": "", + "category": "general", + "subcategory": null, + "usage_scenario": "implementation", + "difficulty": "Intermediate", + "source": "../../../commands/flow-create.md" } ] }, @@ -51,6 +62,65 @@ } ] }, + "idaw": { + "_root": [ + { + "name": "add", + "command": "/idaw:add", + "description": "Add IDAW tasks - manual creation or import from ccw issue", + "arguments": "[-y|--yes] [--from-issue [,,...]] \\\"description\\\" [--type ] [--priority <1-5>]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/add.md" + }, + { + "name": "resume", + "command": "/idaw:resume", + "description": "Resume interrupted IDAW session from last checkpoint", + "arguments": "[-y|--yes] [session-id]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "session-management", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/resume.md" + }, + { + "name": "run-coordinate", + "command": "/idaw:run-coordinate", + "description": "IDAW coordinator - execute task skill chains via external CLI with hook callbacks and git checkpoints", + "arguments": "[-y|--yes] [--task [,,...]] [--dry-run] [--tool ]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/run-coordinate.md" + }, + { + "name": "run", + "command": "/idaw:run", + "description": "IDAW orchestrator - execute task skill chains serially with git checkpoints", + "arguments": "[-y|--yes] [--task [,,...]] [--dry-run]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/run.md" + }, + { + "name": "status", + "command": "/idaw:status", + "description": "View IDAW task and session progress", + "arguments": "[session-id]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "session-management", + "difficulty": "Beginner", + "source": "../../../commands/idaw/status.md" + } + ] + }, "issue": { "_root": [ { @@ -145,6 +215,17 @@ }, "memory": { "_root": [ + { + "name": "prepare", + "command": "/memory:prepare", + "description": "Delegate to universal-executor agent to analyze project via Gemini/Qwen CLI and return JSON core content package for task context", + "arguments": "[--tool gemini|qwen] \\\"task context description\\", + "category": "memory", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/memory/prepare.md" + }, { "name": "style-skill-memory", "command": "/memory:style-skill-memory", @@ -193,6 +274,17 @@ "difficulty": "Intermediate", "source": "../../../commands/workflow/clean.md" }, + { + "name": "workflow:collaborative-plan-with-file", + "command": "/workflow:collaborative-plan-with-file", + "description": "Collaborative planning with Plan Note - Understanding agent creates shared plan-note.md template, parallel agents fill pre-allocated sections, conflict detection without merge. Outputs executable plan-note.md.", + "arguments": "[-y|--yes] [--max-agents=5]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "planning", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/collaborative-plan-with-file.md" + }, { "name": "debug-with-file", "command": "/workflow:debug-with-file", @@ -204,22 +296,77 @@ "difficulty": "Intermediate", "source": "../../../commands/workflow/debug-with-file.md" }, + { + "name": "init-guidelines", + "command": "/workflow:init-guidelines", + "description": "Interactive wizard to fill specs/*.md based on project analysis", + "arguments": "[--reset]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/init-guidelines.md" + }, + { + "name": "init-specs", + "command": "/workflow:init-specs", + "description": "Interactive wizard to create individual specs or personal constraints with scope selection", + "arguments": "[--scope ] [--dimension ] [--category ]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/init-specs.md" + }, { "name": "init", "command": "/workflow:init", "description": "Initialize project-level state with intelligent project analysis using cli-explore-agent", - "arguments": "[--regenerate]", + "arguments": "[--regenerate] [--skip-specs]", "category": "workflow", "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", "source": "../../../commands/workflow/init.md" }, + { + "name": "integration-test-cycle", + "command": "/workflow:integration-test-cycle", + "description": "Self-iterating integration test workflow with codebase exploration, test development, autonomous test-fix cycles, and reflection-driven strategy adjustment", + "arguments": "[-y|--yes] [-c|--continue] [--max-iterations=N] \\\"module or feature description\\", + "category": "workflow", + "subcategory": null, + "usage_scenario": "testing", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/integration-test-cycle.md" + }, + { + "name": "refactor-cycle", + "command": "/workflow:refactor-cycle", + "description": "Tech debt discovery and self-iterating refactoring with multi-dimensional analysis, prioritized execution, regression validation, and reflection-driven adjustment", + "arguments": "[-y|--yes] [-c|--continue] [--scope=module|project] \\\"module or refactoring goal\\", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/refactor-cycle.md" + }, + { + "name": "roadmap-with-file", + "command": "/workflow:roadmap-with-file", + "description": "Strategic requirement roadmap with iterative decomposition and issue creation. Outputs roadmap.md (human-readable, single source) + issues.jsonl (machine-executable). Handoff to team-planex.", + "arguments": "[-y|--yes] [-c|--continue] [-m progressive|direct|auto] \\\"requirement description\\", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/roadmap-with-file.md" + }, { "name": "unified-execute-with-file", "command": "/workflow:unified-execute-with-file", "description": "Universal execution engine for consuming any planning/brainstorm/analysis output with minimal progress tracking, multi-agent coordination, and incremental execution", - "arguments": "[-y|--yes] [-p|--plan ] [-m|--mode sequential|parallel] [\\\"execution context or task name\\\"]", + "arguments": "[-y|--yes] [[,] | -p|--plan [,]] [--auto-commit] [--commit-prefix \\\"prefix\\\"] [\\\"execution context or task name\\\"]", "category": "workflow", "subcategory": null, "usage_scenario": "implementation", @@ -264,8 +411,8 @@ { "name": "solidify", "command": "/workflow:session:solidify", - "description": "Crystallize session learnings and user-defined constraints into permanent project guidelines", - "arguments": "[-y|--yes] [--type ] [--category ] \\\"rule or insight\\", + "description": "Crystallize session learnings and user-defined constraints into permanent project guidelines, or compress recent memories", + "arguments": "[-y|--yes] [--type ] [--category ] [--limit ] \\\"rule or insight\\", "category": "workflow", "subcategory": "session", "usage_scenario": "general", @@ -282,6 +429,17 @@ "usage_scenario": "general", "difficulty": "Intermediate", "source": "../../../commands/workflow/session/start.md" + }, + { + "name": "sync", + "command": "/workflow:session:sync", + "description": "Quick-sync session work to specs/*.md and project-tech", + "arguments": "[-y|--yes] [\\\"what was done\\\"]", + "category": "workflow", + "subcategory": "session", + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/session/sync.md" } ], "ui-design": [ @@ -397,4 +555,4 @@ } ] } -} +} \ No newline at end of file diff --git a/.claude/skills/ccw-help/index/by-use-case.json b/.claude/skills/ccw-help/index/by-use-case.json index ac6a0f1d..d74a9413 100644 --- a/.claude/skills/ccw-help/index/by-use-case.json +++ b/.claude/skills/ccw-help/index/by-use-case.json @@ -33,6 +33,39 @@ "difficulty": "Intermediate", "source": "../../../commands/cli/cli-init.md" }, + { + "name": "add", + "command": "/idaw:add", + "description": "Add IDAW tasks - manual creation or import from ccw issue", + "arguments": "[-y|--yes] [--from-issue [,,...]] \\\"description\\\" [--type ] [--priority <1-5>]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/add.md" + }, + { + "name": "run-coordinate", + "command": "/idaw:run-coordinate", + "description": "IDAW coordinator - execute task skill chains via external CLI with hook callbacks and git checkpoints", + "arguments": "[-y|--yes] [--task [,,...]] [--dry-run] [--tool ]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/run-coordinate.md" + }, + { + "name": "run", + "command": "/idaw:run", + "description": "IDAW orchestrator - execute task skill chains serially with git checkpoints", + "arguments": "[-y|--yes] [--task [,,...]] [--dry-run]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/run.md" + }, { "name": "issue:discover-by-prompt", "command": "/issue:discover-by-prompt", @@ -77,6 +110,17 @@ "difficulty": "Intermediate", "source": "../../../commands/issue/queue.md" }, + { + "name": "prepare", + "command": "/memory:prepare", + "description": "Delegate to universal-executor agent to analyze project via Gemini/Qwen CLI and return JSON core content package for task context", + "arguments": "[--tool gemini|qwen] \\\"task context description\\", + "category": "memory", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/memory/prepare.md" + }, { "name": "clean", "command": "/workflow:clean", @@ -99,17 +143,61 @@ "difficulty": "Intermediate", "source": "../../../commands/workflow/debug-with-file.md" }, + { + "name": "init-guidelines", + "command": "/workflow:init-guidelines", + "description": "Interactive wizard to fill specs/*.md based on project analysis", + "arguments": "[--reset]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/init-guidelines.md" + }, + { + "name": "init-specs", + "command": "/workflow:init-specs", + "description": "Interactive wizard to create individual specs or personal constraints with scope selection", + "arguments": "[--scope ] [--dimension ] [--category ]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/init-specs.md" + }, { "name": "init", "command": "/workflow:init", "description": "Initialize project-level state with intelligent project analysis using cli-explore-agent", - "arguments": "[--regenerate]", + "arguments": "[--regenerate] [--skip-specs]", "category": "workflow", "subcategory": null, "usage_scenario": "general", "difficulty": "Intermediate", "source": "../../../commands/workflow/init.md" }, + { + "name": "refactor-cycle", + "command": "/workflow:refactor-cycle", + "description": "Tech debt discovery and self-iterating refactoring with multi-dimensional analysis, prioritized execution, regression validation, and reflection-driven adjustment", + "arguments": "[-y|--yes] [-c|--continue] [--scope=module|project] \\\"module or refactoring goal\\", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/refactor-cycle.md" + }, + { + "name": "roadmap-with-file", + "command": "/workflow:roadmap-with-file", + "description": "Strategic requirement roadmap with iterative decomposition and issue creation. Outputs roadmap.md (human-readable, single source) + issues.jsonl (machine-executable). Handoff to team-planex.", + "arguments": "[-y|--yes] [-c|--continue] [-m progressive|direct|auto] \\\"requirement description\\", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/roadmap-with-file.md" + }, { "name": "list", "command": "/workflow:session:list", @@ -124,8 +212,8 @@ { "name": "solidify", "command": "/workflow:session:solidify", - "description": "Crystallize session learnings and user-defined constraints into permanent project guidelines", - "arguments": "[-y|--yes] [--type ] [--category ] \\\"rule or insight\\", + "description": "Crystallize session learnings and user-defined constraints into permanent project guidelines, or compress recent memories", + "arguments": "[-y|--yes] [--type ] [--category ] [--limit ] \\\"rule or insight\\", "category": "workflow", "subcategory": "session", "usage_scenario": "general", @@ -143,6 +231,17 @@ "difficulty": "Intermediate", "source": "../../../commands/workflow/session/start.md" }, + { + "name": "sync", + "command": "/workflow:session:sync", + "description": "Quick-sync session work to specs/*.md and project-tech", + "arguments": "[-y|--yes] [\\\"what was done\\\"]", + "category": "workflow", + "subcategory": "session", + "usage_scenario": "general", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/session/sync.md" + }, { "name": "animation-extract", "command": "/workflow:ui-design:animation-extract", @@ -223,6 +322,98 @@ "source": "../../../commands/workflow/analyze-with-file.md" } ], + "implementation": [ + { + "name": "flow-create", + "command": "/flow-create", + "description": "", + "arguments": "", + "category": "general", + "subcategory": null, + "usage_scenario": "implementation", + "difficulty": "Intermediate", + "source": "../../../commands/flow-create.md" + }, + { + "name": "execute", + "command": "/issue:execute", + "description": "Execute queue with DAG-based parallel orchestration (one commit per solution)", + "arguments": "[-y|--yes] --queue [--worktree []]", + "category": "issue", + "subcategory": null, + "usage_scenario": "implementation", + "difficulty": "Intermediate", + "source": "../../../commands/issue/execute.md" + }, + { + "name": "generate", + "command": "/workflow:ui-design:generate", + "description": "Assemble UI prototypes by combining layout templates with design tokens (default animation support), pure assembler without new content generation", + "arguments": "[--design-id ] [--session ]", + "category": "workflow", + "subcategory": "ui-design", + "usage_scenario": "implementation", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/ui-design/generate.md" + }, + { + "name": "unified-execute-with-file", + "command": "/workflow:unified-execute-with-file", + "description": "Universal execution engine for consuming any planning/brainstorm/analysis output with minimal progress tracking, multi-agent coordination, and incremental execution", + "arguments": "[-y|--yes] [[,] | -p|--plan [,]] [--auto-commit] [--commit-prefix \\\"prefix\\\"] [\\\"execution context or task name\\\"]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "implementation", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/unified-execute-with-file.md" + } + ], + "session-management": [ + { + "name": "resume", + "command": "/idaw:resume", + "description": "Resume interrupted IDAW session from last checkpoint", + "arguments": "[-y|--yes] [session-id]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "session-management", + "difficulty": "Intermediate", + "source": "../../../commands/idaw/resume.md" + }, + { + "name": "status", + "command": "/idaw:status", + "description": "View IDAW task and session progress", + "arguments": "[session-id]", + "category": "idaw", + "subcategory": null, + "usage_scenario": "session-management", + "difficulty": "Beginner", + "source": "../../../commands/idaw/status.md" + }, + { + "name": "complete", + "command": "/workflow:session:complete", + "description": "Mark active workflow session as complete, archive with lessons learned, update manifest, remove active flag", + "arguments": "[-y|--yes] [--detailed]", + "category": "workflow", + "subcategory": "session", + "usage_scenario": "session-management", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/session/complete.md" + }, + { + "name": "resume", + "command": "/workflow:session:resume", + "description": "Resume the most recently paused workflow session with automatic session discovery and status update", + "arguments": "", + "category": "workflow", + "subcategory": "session", + "usage_scenario": "session-management", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/session/resume.md" + } + ], "planning": [ { "name": "convert-to-plan", @@ -268,6 +459,17 @@ "difficulty": "Intermediate", "source": "../../../commands/workflow/brainstorm-with-file.md" }, + { + "name": "workflow:collaborative-plan-with-file", + "command": "/workflow:collaborative-plan-with-file", + "description": "Collaborative planning with Plan Note - Understanding agent creates shared plan-note.md template, parallel agents fill pre-allocated sections, conflict detection without merge. Outputs executable plan-note.md.", + "arguments": "[-y|--yes] [--max-agents=5]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "planning", + "difficulty": "Intermediate", + "source": "../../../commands/workflow/collaborative-plan-with-file.md" + }, { "name": "workflow:ui-design:codify-style", "command": "/workflow:ui-design:codify-style", @@ -313,41 +515,6 @@ "source": "../../../commands/workflow/ui-design/reference-page-generator.md" } ], - "implementation": [ - { - "name": "execute", - "command": "/issue:execute", - "description": "Execute queue with DAG-based parallel orchestration (one commit per solution)", - "arguments": "[-y|--yes] --queue [--worktree []]", - "category": "issue", - "subcategory": null, - "usage_scenario": "implementation", - "difficulty": "Intermediate", - "source": "../../../commands/issue/execute.md" - }, - { - "name": "generate", - "command": "/workflow:ui-design:generate", - "description": "Assemble UI prototypes by combining layout templates with design tokens (default animation support), pure assembler without new content generation", - "arguments": "[--design-id ] [--session ]", - "category": "workflow", - "subcategory": "ui-design", - "usage_scenario": "implementation", - "difficulty": "Intermediate", - "source": "../../../commands/workflow/ui-design/generate.md" - }, - { - "name": "unified-execute-with-file", - "command": "/workflow:unified-execute-with-file", - "description": "Universal execution engine for consuming any planning/brainstorm/analysis output with minimal progress tracking, multi-agent coordination, and incremental execution", - "arguments": "[-y|--yes] [-p|--plan ] [-m|--mode sequential|parallel] [\\\"execution context or task name\\\"]", - "category": "workflow", - "subcategory": null, - "usage_scenario": "implementation", - "difficulty": "Intermediate", - "source": "../../../commands/workflow/unified-execute-with-file.md" - } - ], "documentation": [ { "name": "style-skill-memory", @@ -361,28 +528,17 @@ "source": "../../../commands/memory/style-skill-memory.md" } ], - "session-management": [ + "testing": [ { - "name": "complete", - "command": "/workflow:session:complete", - "description": "Mark active workflow session as complete, archive with lessons learned, update manifest, remove active flag", - "arguments": "[-y|--yes] [--detailed]", + "name": "integration-test-cycle", + "command": "/workflow:integration-test-cycle", + "description": "Self-iterating integration test workflow with codebase exploration, test development, autonomous test-fix cycles, and reflection-driven strategy adjustment", + "arguments": "[-y|--yes] [-c|--continue] [--max-iterations=N] \\\"module or feature description\\", "category": "workflow", - "subcategory": "session", - "usage_scenario": "session-management", + "subcategory": null, + "usage_scenario": "testing", "difficulty": "Intermediate", - "source": "../../../commands/workflow/session/complete.md" - }, - { - "name": "resume", - "command": "/workflow:session:resume", - "description": "Resume the most recently paused workflow session with automatic session discovery and status update", - "arguments": "", - "category": "workflow", - "subcategory": "session", - "usage_scenario": "session-management", - "difficulty": "Intermediate", - "source": "../../../commands/workflow/session/resume.md" + "source": "../../../commands/workflow/integration-test-cycle.md" } ] -} +} \ No newline at end of file diff --git a/.claude/skills/ccw-help/index/command-relationships.json b/.claude/skills/ccw-help/index/command-relationships.json index 2c3845c8..039acd81 100644 --- a/.claude/skills/ccw-help/index/command-relationships.json +++ b/.claude/skills/ccw-help/index/command-relationships.json @@ -1,15 +1,146 @@ { + "workflow-plan": { + "calls_internally": [ + "workflow:session:start", + "workflow:tools:context-gather", + "workflow:tools:conflict-resolution", + "workflow:tools:task-generate-agent" + ], + "next_steps": [ + "workflow-plan-verify", + "workflow:status", + "workflow-execute" + ], + "alternatives": [ + "workflow-tdd-plan" + ], + "prerequisites": [] + }, + "workflow-tdd-plan": { + "calls_internally": [ + "workflow:session:start", + "workflow:tools:context-gather", + "workflow:tools:task-generate-tdd" + ], + "next_steps": [ + "workflow-tdd-verify", + "workflow:status", + "workflow-execute" + ], + "alternatives": [ + "workflow-plan" + ], + "prerequisites": [] + }, + "workflow-execute": { + "prerequisites": [ + "workflow-plan", + "workflow-tdd-plan" + ], + "related": [ + "workflow:status", + "workflow:resume" + ], + "next_steps": [ + "workflow:review", + "workflow-tdd-verify" + ] + }, + "workflow-plan-verify": { + "prerequisites": [ + "workflow-plan" + ], + "next_steps": [ + "workflow-execute" + ], + "related": [ + "workflow:status" + ] + }, + "workflow-tdd-verify": { + "prerequisites": [ + "workflow-execute" + ], + "related": [ + "workflow:tools:tdd-coverage-analysis" + ] + }, "workflow:session:start": { - "next_steps": [], + "next_steps": [ + "workflow-plan", + "workflow-execute" + ], "related": [ "workflow:session:list", "workflow:session:resume" ] }, "workflow:session:resume": { - "alternatives": [], + "alternatives": [ + "workflow:resume" + ], "related": [ - "workflow:session:list" + "workflow:session:list", + "workflow:status" + ] + }, + "workflow-lite-planex": { + "calls_internally": [], + "next_steps": [ + "workflow:status" + ], + "alternatives": [ + "workflow-plan" + ], + "prerequisites": [] + }, + "workflow:lite-fix": { + "next_steps": [ + "workflow:status" + ], + "alternatives": [ + "workflow-lite-planex" + ], + "related": [ + "workflow-test-fix" + ] + }, + "workflow:review-session-cycle": { + "prerequisites": [ + "workflow-execute" + ], + "next_steps": [ + "workflow:review-fix" + ], + "related": [ + "workflow:review-module-cycle" + ] + }, + "workflow:review-fix": { + "prerequisites": [ + "workflow:review-module-cycle", + "workflow:review-session-cycle" + ], + "related": [ + "workflow-test-fix" + ] + }, + "memory:docs": { + "calls_internally": [ + "workflow:session:start", + "workflow:tools:context-gather" + ], + "next_steps": [ + "workflow-execute" + ] + }, + "memory:skill-memory": { + "next_steps": [ + "workflow-plan", + "cli:analyze" + ], + "related": [ + "memory:load-skill-memory" ] } -} +} \ No newline at end of file diff --git a/.claude/skills/ccw-help/index/essential-commands.json b/.claude/skills/ccw-help/index/essential-commands.json index ef26efdb..23e39f20 100644 --- a/.claude/skills/ccw-help/index/essential-commands.json +++ b/.claude/skills/ccw-help/index/essential-commands.json @@ -10,4 +10,4 @@ "difficulty": "Intermediate", "source": "../../../commands/workflow/session/start.md" } -] +] \ No newline at end of file diff --git a/.claude/skills/ccw-help/index/skills-by-category.json b/.claude/skills/ccw-help/index/skills-by-category.json new file mode 100644 index 00000000..bd2b77de --- /dev/null +++ b/.claude/skills/ccw-help/index/skills-by-category.json @@ -0,0 +1,374 @@ +{ + "standalone": [ + { + "name": "brainstorm", + "description": "Unified brainstorming skill with dual-mode operation - auto pipeline and single role analysis. Triggers on \"brainstorm\", \"头脑风暴\".", + "category": "standalone", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/brainstorm/SKILL.md" + } + ], + "meta": [ + { + "name": "command-generator", + "description": "Command file generator - 5 phase workflow for creating Claude Code command files with YAML frontmatter. Generates .md command files for project or user scope. Triggers on \"create command\", \"new command\", \"command generator\".", + "category": "meta", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/command-generator/SKILL.md" + }, + { + "name": "skill-generator", + "description": "Meta-skill for creating new Claude Code skills with configurable execution modes. Supports sequential (fixed order) and autonomous (stateless) phase patterns. Use for skill scaffolding, skill creation, or building new workflows. Triggers on \"create skill\", \"new skill\", \"skill generator\".", + "category": "meta", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/skill-generator/SKILL.md" + }, + { + "name": "skill-tuning", + "description": "Universal skill diagnosis and optimization tool. Detect and fix skill execution issues including context explosion, long-tail forgetting, data flow disruption, and agent coordination failures. Supports Gemini CLI for deep analysis. Triggers on \"skill tuning\", \"tune skill\", \"skill diagnosis\", \"optimize skill\", \"skill debug\".", + "category": "meta", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/skill-tuning/SKILL.md" + }, + { + "name": "spec-generator", + "description": "Specification generator - 6 phase document chain producing product brief, PRD, architecture, and epics. Triggers on \"generate spec\", \"create specification\", \"spec generator\", \"workflow:spec\".", + "category": "meta", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/spec-generator/SKILL.md" + } + ], + "utility": [ + { + "name": "issue-manage", + "description": "Interactive issue management with menu-driven CRUD operations. Use when managing issues, viewing issue status, editing issue fields, performing bulk operations, or viewing issue history. Triggers on \"manage issue\", \"list issues\", \"edit issue\", \"delete issue\", \"bulk update\", \"issue dashboard\", \"issue history\", \"completed issues\".", + "category": "utility", + "is_team": false, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/issue-manage/SKILL.md" + }, + { + "name": "memory-capture", + "description": "Unified memory capture with routing - session compact or quick tips. Triggers on \"memory capture\", \"compact session\", \"save session\", \"quick tip\", \"memory tips\", \"记录\", \"压缩会话\".", + "category": "utility", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/memory-capture/SKILL.md" + }, + { + "name": "memory-manage", + "description": "Unified memory management - CLAUDE.md updates and documentation generation with interactive routing. Triggers on \"memory manage\", \"update claude\", \"update memory\", \"generate docs\", \"更新记忆\", \"生成文档\".", + "category": "utility", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/memory-manage/SKILL.md" + } + ], + "review": [ + { + "name": "review-code", + "description": "Multi-dimensional code review with structured reports. Analyzes correctness, readability, performance, security, testing, and architecture. Triggers on \"review code\", \"code review\", \"审查代码\", \"代码审查\".", + "category": "review", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/review-code/SKILL.md" + }, + { + "name": "review-cycle", + "description": "Unified multi-dimensional code review with automated fix orchestration. Routes to session-based (git changes), module-based (path patterns), or fix mode. Triggers on \"workflow:review-cycle\", \"workflow:review-session-cycle\", \"workflow:review-module-cycle\", \"workflow:review-cycle-fix\".", + "category": "review", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/review-cycle/SKILL.md" + } + ], + "team": [ + { + "name": "team-brainstorm", + "description": "Unified team skill for brainstorming team. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team brainstorm\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-brainstorm/SKILL.md" + }, + { + "name": "team-coordinate", + "description": "Universal team coordination skill with dynamic role generation. Only coordinator is built-in -- all worker roles are generated at runtime based on task analysis. Beat/cadence model for orchestration. Triggers on \"team coordinate\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-coordinate/SKILL.md" + }, + { + "name": "team-coordinate-v2", + "description": "Universal team coordination skill with dynamic role generation. Uses team-worker agent architecture with role-spec files. Only coordinator is built-in -- all worker roles are generated at runtime as role-specs and spawned via team-worker agent. Beat/cadence model for orchestration. Triggers on \"team coordinate v2\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-coordinate-v2/SKILL.md" + }, + { + "name": "team-executor", + "description": "Lightweight session execution skill. Resumes existing team-coordinate sessions for pure execution. No analysis, no role generation -- only loads and executes. Session path required. Triggers on \"team executor\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-executor/SKILL.md" + }, + { + "name": "team-executor-v2", + "description": "Lightweight session execution skill. Resumes existing team-coordinate-v2 sessions for pure execution via team-worker agents. No analysis, no role generation -- only loads and executes. Session path required. Triggers on \"team executor v2\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-executor-v2/SKILL.md" + }, + { + "name": "team-frontend", + "description": "Unified team skill for frontend development team. All roles invoke this skill with --role arg. Built-in ui-ux-pro-max design intelligence. Triggers on \"team frontend\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-frontend/SKILL.md" + }, + { + "name": "team-issue", + "description": "Unified team skill for issue resolution. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team issue\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-issue/SKILL.md" + }, + { + "name": "team-iterdev", + "description": "Unified team skill for iterative development team. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team iterdev\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-iterdev/SKILL.md" + }, + { + "name": "team-lifecycle-v3", + "description": "Unified team skill for full lifecycle - spec/impl/test. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team lifecycle\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-lifecycle-v3/SKILL.md" + }, + { + "name": "team-lifecycle-v4", + "description": "Unified team skill for full lifecycle - spec/impl/test. Optimized cadence with inline discuss subagent and shared explore. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team lifecycle\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-lifecycle-v4/SKILL.md" + }, + { + "name": "team-lifecycle-v5", + "description": "Unified team skill for full lifecycle - spec/impl/test. Uses team-worker agent architecture with role-spec files for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents loaded with role-specific Phase 2-4 specs. Triggers on \"team lifecycle\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": true, + "version": "", + "source": "../../../skills/team-lifecycle-v5/SKILL.md" + }, + { + "name": "team-planex", + "description": "Unified team skill for plan-and-execute pipeline. Uses team-worker agent architecture with role-spec files for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on \"team planex\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": true, + "version": "", + "source": "../../../skills/team-planex/SKILL.md" + }, + { + "name": "team-quality-assurance", + "description": "Unified team skill for quality assurance team. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team quality-assurance\", \"team qa\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-quality-assurance/SKILL.md" + }, + { + "name": "team-review", + "description": "Unified team skill for code scanning, vulnerability review, optimization suggestions, and automated fix. 4-role team: coordinator, scanner, reviewer, fixer. Triggers on team-review.", + "category": "team", + "is_team": false, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-review/SKILL.md" + }, + { + "name": "team-roadmap-dev", + "description": "Unified team skill for roadmap-driven development workflow. Coordinator discusses roadmap with user, then dispatches phased execution pipeline (plan -> execute -> verify). All roles invoke this skill with --role arg. Triggers on \"team roadmap-dev\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-roadmap-dev/SKILL.md" + }, + { + "name": "team-tech-debt", + "description": "Unified team skill for tech debt identification and cleanup. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team tech-debt\", \"tech debt cleanup\", \"技术债务\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-tech-debt/SKILL.md" + }, + { + "name": "team-testing", + "description": "Unified team skill for testing team. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team testing\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-testing/SKILL.md" + }, + { + "name": "team-uidesign", + "description": "Unified team skill for UI design team. All roles invoke this skill with --role arg for role-specific execution. CP-9 Dual-Track design+implementation.", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-uidesign/SKILL.md" + }, + { + "name": "team-ultra-analyze", + "description": "Unified team skill for deep collaborative analysis. All roles invoke this skill with --role arg for role-specific execution. Triggers on \"team ultra-analyze\", \"team analyze\".", + "category": "team", + "is_team": true, + "has_phases": false, + "has_role_specs": false, + "version": "", + "source": "../../../skills/team-ultra-analyze/SKILL.md" + } + ], + "workflow": [ + { + "name": "workflow-execute", + "description": "Coordinate agent execution for workflow tasks with automatic session discovery, parallel task processing, and status tracking. Triggers on \"workflow-execute\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-execute/SKILL.md" + }, + { + "name": "workflow-lite-planex", + "description": "Lightweight planning and execution skill (Phase 1: plan, Phase 2: execute). Triggers on \"workflow-lite-planex\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-lite-planex/SKILL.md" + }, + { + "name": "workflow-multi-cli-plan", + "description": "Multi-CLI collaborative planning and execution skill with integrated execution phase. Triggers on \"workflow-multi-cli-plan\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-multi-cli-plan/SKILL.md" + }, + { + "name": "workflow-plan", + "description": "Unified planning skill - 4-phase planning workflow, plan verification, and interactive replanning. Triggers on \"workflow-plan\", \"workflow-plan-verify\", \"workflow:replan\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-plan/SKILL.md" + }, + { + "name": "workflow-skill-designer", + "description": "Meta-skill for designing orchestrator+phases structured workflow skills. Creates SKILL.md coordinator with progressive phase loading, TodoWrite patterns, and data flow. Triggers on \"design workflow skill\", \"create workflow skill\", \"workflow skill designer\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-skill-designer/SKILL.md" + }, + { + "name": "workflow-tdd-plan-plan", + "description": "Unified TDD workflow skill combining 6-phase TDD planning with Red-Green-Refactor task chain generation, and 4-phase TDD verification with compliance reporting. Triggers on \"workflow-tdd-plan\", \"workflow-tdd-verify\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-tdd-plan/SKILL.md" + }, + { + "name": "workflow-test-fix", + "description": "Unified test-fix pipeline combining test generation (session, context, analysis, task gen) with iterative test-cycle execution (adaptive strategy, progressive testing, CLI fallback). Triggers on \"workflow-test-fix\", \"workflow-test-fix\", \"test fix workflow\".", + "category": "workflow", + "is_team": false, + "has_phases": true, + "has_role_specs": false, + "version": "", + "source": "../../../skills/workflow-test-fix/SKILL.md" + } + ] +} \ No newline at end of file diff --git a/.claude/skills/ccw-help/scripts/analyze_commands.py b/.claude/skills/ccw-help/scripts/analyze_commands.py index 584afde5..37a2b151 100644 --- a/.claude/skills/ccw-help/scripts/analyze_commands.py +++ b/.claude/skills/ccw-help/scripts/analyze_commands.py @@ -1,11 +1,10 @@ #!/usr/bin/env python3 """ -Analyze all command/agent files and generate index files for ccw-help skill. +Analyze all command/agent/skill files and generate index files for ccw-help skill. Outputs relative paths pointing to source files (no reference folder duplication). """ import os -import re import json from pathlib import Path from collections import defaultdict @@ -15,9 +14,13 @@ from typing import Dict, List, Any BASE_DIR = Path("D:/Claude_dms3/.claude") COMMANDS_DIR = BASE_DIR / "commands" AGENTS_DIR = BASE_DIR / "agents" +SKILLS_DIR = BASE_DIR / "skills" SKILL_DIR = BASE_DIR / "skills" / "ccw-help" INDEX_DIR = SKILL_DIR / "index" +# Skills to skip (internal/shared, not user-facing) +SKIP_SKILLS = {"_shared", "ccw-help"} + def parse_frontmatter(content: str) -> Dict[str, Any]: """Extract YAML frontmatter from markdown content.""" frontmatter = {} @@ -139,6 +142,66 @@ def analyze_agent_file(file_path: Path) -> Dict[str, Any]: "source": rel_path # Relative from index/ dir (e.g., "../../../agents/...") } +def categorize_skill(name: str, description: str) -> str: + """Determine skill category from name and description.""" + if name.startswith('team-'): + return "team" + if name.startswith('workflow-'): + return "workflow" + if name.startswith('review-'): + return "review" + if name.startswith('spec-') or name.startswith('command-') or name.startswith('skill-'): + return "meta" + if name.startswith('memory-') or name.startswith('issue-'): + return "utility" + return "standalone" + + +def analyze_skill_dir(skill_path: Path) -> Dict[str, Any] | None: + """Analyze a skill directory and extract metadata from SKILL.md.""" + skill_md = skill_path / "SKILL.md" + if not skill_md.exists(): + return None + + with open(skill_md, 'r', encoding='utf-8') as f: + content = f.read() + + frontmatter = parse_frontmatter(content) + + name = frontmatter.get('name', skill_path.name) + description = frontmatter.get('description', '') + allowed_tools = frontmatter.get('allowed-tools', '') + version = frontmatter.get('version', '') + + category = categorize_skill(name, description) + + # Detect if it's a team skill (uses TeamCreate + SendMessage together) + is_team = 'TeamCreate' in allowed_tools and 'SendMessage' in allowed_tools + + # Detect if it has phases + phases_dir = skill_path / "phases" + has_phases = phases_dir.exists() and any(phases_dir.iterdir()) if phases_dir.exists() else False + + # Detect if it has role-specs + role_specs_dir = skill_path / "role-specs" + has_role_specs = role_specs_dir.exists() and any(role_specs_dir.iterdir()) if role_specs_dir.exists() else False + + # Build relative path from INDEX_DIR + rel_from_base = skill_path.relative_to(BASE_DIR) + rel_path = "../../../" + str(rel_from_base).replace('\\', '/') + "/SKILL.md" + + return { + "name": name, + "description": description, + "category": category, + "is_team": is_team, + "has_phases": has_phases, + "has_role_specs": has_role_specs, + "version": version, + "source": rel_path + } + + def build_command_relationships() -> Dict[str, Any]: """Build command relationship mappings.""" return { @@ -263,7 +326,24 @@ def main(): except Exception as e: print(f" ERROR analyzing {agent_file}: {e}") - print(f"\nAnalyzed {len(all_commands)} commands, {len(all_agents)} agents") + # Analyze skill directories + print("\n=== Analyzing Skill Files ===") + skill_dirs = [d for d in SKILLS_DIR.iterdir() if d.is_dir() and d.name not in SKIP_SKILLS] + print(f"Found {len(skill_dirs)} skill directories") + + all_skills = [] + for skill_dir in sorted(skill_dirs): + try: + metadata = analyze_skill_dir(skill_dir) + if metadata: + all_skills.append(metadata) + print(f" OK {metadata['name']} [{metadata['category']}]") + else: + print(f" SKIP {skill_dir.name} (no SKILL.md)") + except Exception as e: + print(f" ERROR analyzing {skill_dir}: {e}") + + print(f"\nAnalyzed {len(all_commands)} commands, {len(all_agents)} agents, {len(all_skills)} skills") # Generate index files INDEX_DIR.mkdir(parents=True, exist_ok=True) @@ -316,15 +396,62 @@ def main(): json.dump(relationships, f, indent=2, ensure_ascii=False) print(f"OK Generated {relationships_path.name} ({os.path.getsize(relationships_path)} bytes)") + # 7. all-skills.json + all_skills_path = INDEX_DIR / "all-skills.json" + with open(all_skills_path, 'w', encoding='utf-8') as f: + json.dump(all_skills, f, indent=2, ensure_ascii=False) + print(f"OK Generated {all_skills_path.name} ({os.path.getsize(all_skills_path)} bytes)") + + # 8. skills-by-category.json + skills_by_cat = defaultdict(list) + for skill in all_skills: + skills_by_cat[skill['category']].append(skill) + + skills_by_cat_path = INDEX_DIR / "skills-by-category.json" + with open(skills_by_cat_path, 'w', encoding='utf-8') as f: + json.dump(dict(skills_by_cat), f, indent=2, ensure_ascii=False) + print(f"OK Generated {skills_by_cat_path.name} ({os.path.getsize(skills_by_cat_path)} bytes)") + + # Generate master command.json (includes commands, agents, skills) + master = { + "_metadata": { + "version": "4.0.0", + "total_commands": len(all_commands), + "total_agents": len(all_agents), + "total_skills": len(all_skills), + "description": "Auto-generated CCW-Help command index from analyze_commands.py", + "generated": "Auto-updated - all commands, agents, skills synced from file system", + "last_sync": "command.json now stays in sync with CLI definitions" + }, + "essential_commands": [cmd['name'] for cmd in essential], + "commands": all_commands, + "agents": all_agents, + "skills": all_skills, + "categories": sorted(set(cmd['category'] for cmd in all_commands)), + "skill_categories": sorted(skills_by_cat.keys()) + } + + master_path = SKILL_DIR / "command.json" + with open(master_path, 'w', encoding='utf-8') as f: + json.dump(master, f, indent=2, ensure_ascii=False) + print(f"\nOK Generated command.json ({os.path.getsize(master_path)} bytes)") + # Print summary print("\n=== Summary ===") print(f"Commands: {len(all_commands)}") print(f"Agents: {len(all_agents)}") + print(f"Skills: {len(all_skills)}") print(f"Essential: {len(essential)}") - print(f"\nBy category:") + print(f"\nCommands by category:") for cat in sorted(by_category.keys()): total = sum(len(cmds) for cmds in by_category[cat].values()) print(f" {cat}: {total}") + print(f"\nSkills by category:") + for cat in sorted(skills_by_cat.keys()): + print(f" {cat}: {len(skills_by_cat[cat])}") + for skill in skills_by_cat[cat]: + team_tag = " [team]" if skill['is_team'] else "" + print(f" - {skill['name']}{team_tag}") print(f"\nIndex: {INDEX_DIR}") print("=== Complete ===") diff --git a/.claude/skills/team-perf-opt/SKILL.md b/.claude/skills/team-perf-opt/SKILL.md new file mode 100644 index 00000000..5eed4180 --- /dev/null +++ b/.claude/skills/team-perf-opt/SKILL.md @@ -0,0 +1,349 @@ +--- +name: team-perf-opt +description: Unified team skill for performance optimization. Uses team-worker agent architecture with role-spec files for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team perf-opt". +allowed-tools: Task, TaskCreate, TaskList, TaskGet, TaskUpdate, TeamCreate, TeamDelete, SendMessage, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep, mcp__ace-tool__search_context +--- + +# Team Performance Optimization + +Unified team skill: Profile application performance, identify bottlenecks, design optimization strategies, implement changes, benchmark improvements, and review code quality. Built on **team-worker agent architecture** -- all worker roles share a single agent definition with role-specific Phase 2-4 loaded from markdown specs. + +## Architecture + +``` ++---------------------------------------------------+ +| Skill(skill="team-perf-opt") | +| args="" | ++-------------------+-------------------------------+ + | + Orchestration Mode (auto -> coordinator) + | + Coordinator (inline) + Phase 0-5 orchestration + | + +-------+-------+-------+-------+ + v v v v v + [tw] [tw] [tw] [tw] [tw] +profiler strate- optim- bench- review- + gist izer marker er + + Subagents (callable by workers, not team members): + [explore] [discuss] + +(tw) = team-worker agent +``` + +## Role Router + +This skill is **coordinator-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly. + +### Input Parsing + +Parse `$ARGUMENTS`. No `--role` needed -- always routes to coordinator. + +### Role Registry + +| Role | Spec | Task Prefix | Type | Inner Loop | +|------|------|-------------|------|------------| +| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | orchestrator | - | +| profiler | [role-specs/profiler.md](role-specs/profiler.md) | PROFILE-* | orchestration | false | +| strategist | [role-specs/strategist.md](role-specs/strategist.md) | STRATEGY-* | orchestration | false | +| optimizer | [role-specs/optimizer.md](role-specs/optimizer.md) | IMPL-* / FIX-* | code_generation | true | +| benchmarker | [role-specs/benchmarker.md](role-specs/benchmarker.md) | BENCH-* | validation | false | +| reviewer | [role-specs/reviewer.md](role-specs/reviewer.md) | REVIEW-* / QUALITY-* | read_only_analysis | false | + +### Subagent Registry + +| Subagent | Spec | Callable By | Purpose | +|----------|------|-------------|---------| +| explore | [subagents/explore-subagent.md](subagents/explore-subagent.md) | profiler, optimizer | Shared codebase exploration for performance-critical code paths | +| discuss | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | strategist, reviewer | Multi-perspective discussion for optimization approaches and review findings | + +### Dispatch + +Always route to coordinator. Coordinator reads `roles/coordinator/role.md` and executes its phases. + +### Orchestration Mode + +User just provides task description. + +**Invocation**: `Skill(skill="team-perf-opt", args="")` + +**Lifecycle**: +``` +User provides task description + -> coordinator Phase 1-3: Requirement clarification -> TeamCreate -> Create task chain + -> coordinator Phase 4: spawn first batch workers (background) -> STOP + -> Worker (team-worker agent) executes -> SendMessage callback -> coordinator advances + -> Loop until pipeline complete -> Phase 5 report + completion action +``` + +**User Commands** (wake paused coordinator): + +| Command | Action | +|---------|--------| +| `check` / `status` | Output execution status graph, no advancement | +| `resume` / `continue` | Check worker states, advance next step | +| `revise [feedback]` | Create revision task + cascade downstream | +| `feedback ` | Analyze feedback impact, create targeted revision chain | +| `recheck` | Re-run quality check | +| `improve [dimension]` | Auto-improve weakest dimension | + +--- + +## Command Execution Protocol + +When coordinator needs to execute a command (dispatch, monitor): + +1. **Read the command file**: `roles/coordinator/commands/.md` +2. **Follow the workflow** defined in the command file (Phase 2-4 structure) +3. **Commands are inline execution guides** -- NOT separate agents or subprocesses +4. **Execute synchronously** -- complete the command workflow before proceeding + +Example: +``` +Phase 3 needs task dispatch + -> Read roles/coordinator/commands/dispatch.md + -> Execute Phase 2 (Context Loading) + -> Execute Phase 3 (Task Chain Creation) + -> Execute Phase 4 (Validation) + -> Continue to Phase 4 +``` + +--- + +## Coordinator Spawn Template + +### v5 Worker Spawn (all roles) + +When coordinator spawns workers, use `team-worker` agent with role-spec path: + +``` +Task({ + subagent_type: "team-worker", + description: "Spawn worker", + team_name: , + name: "", + run_in_background: true, + prompt: `## Role Assignment +role: +role_spec: .claude/skills/team-perf-opt/role-specs/.md +session: +session_id: +team_name: +requirement: +inner_loop: + +Read role_spec file to load Phase 2-4 domain instructions. +Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).` +}) +``` + +**Inner Loop roles** (optimizer): Set `inner_loop: true`. The team-worker agent handles the loop internally. + +**Single-task roles** (profiler, strategist, benchmarker, reviewer): Set `inner_loop: false`. + +--- + +## Pipeline Definitions + +### Pipeline Diagram + +``` +Pipeline: Linear with Review-Fix Cycle +===================================================================== +Stage 1 Stage 2 Stage 3 Stage 4 +(W:1) (W:2) (W:3) (W:4) + +-----------+ +PROFILE-001 --> STRATEGY-001 --> IMPL-001 --> | BENCH-001 | +[profiler] [strategist] [optimizer] | [bench] | + ^ +-----------+ + | | + | +-----------+ + +<--FIX--->| REVIEW-001| + | | [reviewer]| + | +-----------+ + | | + (max 3 iterations) v + COMPLETE +===================================================================== +``` + +### Cadence Control + +**Beat model**: Event-driven, each beat = coordinator wake -> process -> spawn -> STOP. + +``` +Beat Cycle (single beat) +====================================================================== + Event Coordinator Workers +---------------------------------------------------------------------- + callback/resume --> +- handleCallback -+ + | mark completed | + | check pipeline | + +- handleSpawnNext -+ + | find ready tasks | + | spawn workers ---+--> [team-worker A] Phase 1-5 + | (parallel OK) --+--> [team-worker B] Phase 1-5 + +- STOP (idle) -----+ | + | + callback <-----------------------------------------+ + (next beat) SendMessage + TaskUpdate(completed) +====================================================================== + + Fast-Advance (skips coordinator for simple linear successors) +====================================================================== + [Worker A] Phase 5 complete + +- 1 ready task? simple successor? + | --> spawn team-worker B directly + | --> log fast_advance to message bus (coordinator syncs on next wake) + +- complex case? --> SendMessage to coordinator +====================================================================== +``` + +``` +Beat View: Performance Optimization Pipeline +====================================================================== + Event Coordinator Workers +---------------------------------------------------------------------- + new task --> +- Phase 1-3: clarify -+ + | TeamCreate | + | create PROFILE-001 | + +- Phase 4: spawn ------+--> [profiler] Phase 1-5 + +- STOP (idle) ---------+ | + | + callback <----------------------------------------------+ + (profiler done) --> +- handleCallback ------+ profile_complete + | mark PROFILE done | + | spawn strategist ----+--> [strategist] Phase 1-5 + +- STOP ----------------+ | + | + callback <----------------------------------------------+ + (strategist done)--> +- handleCallback ------+ strategy_complete + | mark STRATEGY done | + | spawn optimizer -----+--> [optimizer] Phase 1-5 + +- STOP ----------------+ | + | + callback <----------------------------------------------+ + (optimizer done) --> +- handleCallback ------+ impl_complete + | mark IMPL done | + | spawn bench+reviewer-+--> [benchmarker] Phase 1-5 + | (parallel) -------+--> [reviewer] Phase 1-5 + +- STOP ----------------+ | | + | | + callback x2 <--------------------------------------+-----------+ + --> +- handleCallback ------+ + | both done? | + | YES + pass -> Phase 5| + | NO / fail -> FIX task| + | spawn optimizer -----+--> [optimizer] FIX-001 + +- STOP or Phase 5 -----+ +====================================================================== +``` + +**Checkpoints**: + +| Checkpoint | Trigger | Location | Behavior | +|------------|---------|----------|----------| +| CP-1 | PROFILE-001 complete | After Stage 1 | User reviews bottleneck report, can refine scope | +| CP-2 | STRATEGY-001 complete | After Stage 2 | User reviews optimization plan, can adjust priorities | +| CP-3 | REVIEW/BENCH fail | Stage 4 | Auto-create FIX task, re-enter Stage 3 (max 3x) | +| CP-4 | All tasks complete | Phase 5 | Interactive completion action | + +### Task Metadata Registry + +| Task ID | Role | Phase | Dependencies | Description | +|---------|------|-------|-------------|-------------| +| PROFILE-001 | profiler | Stage 1 | (none) | Profile application, identify bottlenecks | +| STRATEGY-001 | strategist | Stage 2 | PROFILE-001 | Design optimization plan from bottleneck report | +| IMPL-001 | optimizer | Stage 3 | STRATEGY-001 | Implement highest-priority optimizations | +| BENCH-001 | benchmarker | Stage 4 | IMPL-001 | Run benchmarks, compare vs baseline | +| REVIEW-001 | reviewer | Stage 4 | IMPL-001 | Review optimization code for correctness | +| FIX-001 | optimizer | Stage 3 (cycle) | REVIEW-001 or BENCH-001 | Fix issues found in review/benchmark | + +--- + +## Completion Action + +When the pipeline completes (all tasks done, coordinator Phase 5): + +``` +AskUserQuestion({ + questions: [{ + question: "Team pipeline complete. What would you like to do?", + header: "Completion", + multiSelect: false, + options: [ + { label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" }, + { label: "Keep Active", description: "Keep session active for follow-up work or inspection" }, + { label: "Export Results", description: "Export deliverables to a specified location, then clean" } + ] + }] +}) +``` + +| Choice | Action | +|--------|--------| +| Archive & Clean | Update session status="completed" -> TeamDelete(perf-opt) -> output final summary | +| Keep Active | Update session status="paused" -> output resume instructions: `Skill(skill="team-perf-opt", args="resume")` | +| Export Results | AskUserQuestion for target path -> copy deliverables -> Archive & Clean | + +--- + +## Session Directory + +``` +.workflow// ++-- session.json # Session metadata + status ++-- artifacts/ +| +-- baseline-metrics.json # Profiler: before-optimization metrics +| +-- bottleneck-report.md # Profiler: ranked bottleneck findings +| +-- optimization-plan.md # Strategist: prioritized optimization plan +| +-- benchmark-results.json # Benchmarker: after-optimization metrics +| +-- review-report.md # Reviewer: code review findings ++-- explorations/ +| +-- cache-index.json # Shared explore cache +| +-- .md # Cached exploration results ++-- wisdom/ +| +-- patterns.md # Discovered patterns and conventions +| +-- shared-memory.json # Cross-role structured data ++-- discussions/ +| +-- DISCUSS-OPT.md # Strategy discussion record +| +-- DISCUSS-REVIEW.md # Review discussion record +``` + +## Session Resume + +Coordinator supports `--resume` / `--continue` for interrupted sessions: + +1. Scan session directory for sessions with status "active" or "paused" +2. Multiple matches -> AskUserQuestion for selection +3. Audit TaskList -> reconcile session state <-> task status +4. Reset in_progress -> pending (interrupted tasks) +5. Rebuild team and spawn needed workers only +6. Create missing tasks with correct blockedBy +7. Kick first executable task -> Phase 4 coordination loop + +## Shared Resources + +| Resource | Path | Usage | +|----------|------|-------| +| Performance Baseline | [/artifacts/baseline-metrics.json](/artifacts/baseline-metrics.json) | Before-optimization metrics for comparison | +| Bottleneck Report | [/artifacts/bottleneck-report.md](/artifacts/bottleneck-report.md) | Profiler output consumed by strategist | +| Optimization Plan | [/artifacts/optimization-plan.md](/artifacts/optimization-plan.md) | Strategist output consumed by optimizer | +| Benchmark Results | [/artifacts/benchmark-results.json](/artifacts/benchmark-results.json) | Benchmarker output consumed by reviewer | + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Role spec file not found | Error with expected path (role-specs/.md) | +| Command file not found | Fallback to inline execution in coordinator role.md | +| Subagent spec not found | Error with expected path (subagents/-subagent.md) | +| Fast-advance orphan detected | Coordinator resets task to pending on next check | +| consensus_blocked HIGH | Coordinator creates revision task or pauses pipeline | +| team-worker agent unavailable | Error: requires .claude/agents/team-worker.md | +| Completion action timeout | Default to Keep Active | +| Profiling tool not available | Fallback to static analysis methods | +| Benchmark regression detected | Auto-create FIX task with regression details | +| Review-fix cycle exceeds 3 iterations | Escalate to user with summary of remaining issues | diff --git a/.claude/skills/team-perf-opt/role-specs/benchmarker.md b/.claude/skills/team-perf-opt/role-specs/benchmarker.md new file mode 100644 index 00000000..cf6b0623 --- /dev/null +++ b/.claude/skills/team-perf-opt/role-specs/benchmarker.md @@ -0,0 +1,85 @@ +--- +prefix: BENCH +inner_loop: false +message_types: + success: bench_complete + error: error + fix: fix_required +--- + +# Performance Benchmarker + +Run benchmarks comparing before/after optimization metrics. Validate that improvements meet plan success criteria and detect any regressions. + +## Phase 2: Environment & Baseline Loading + +| Input | Source | Required | +|-------|--------|----------| +| Baseline metrics | /artifacts/baseline-metrics.json | Yes | +| Optimization plan | /artifacts/optimization-plan.md | Yes | +| shared-memory.json | /wisdom/shared-memory.json | Yes | + +1. Extract session path from task description +2. Read baseline metrics -- extract pre-optimization performance numbers +3. Read optimization plan -- extract success criteria and target thresholds +4. Load shared-memory.json for project type and optimization scope +5. Detect available benchmark tools from project: + +| Signal | Benchmark Tool | Method | +|--------|---------------|--------| +| package.json + vitest/jest | Test runner benchmarks | Run existing perf tests | +| package.json + webpack/vite | Bundle analysis | Compare build output sizes | +| Cargo.toml + criterion | Rust benchmarks | cargo bench | +| go.mod | Go benchmarks | go test -bench | +| Makefile with bench target | Custom benchmarks | make bench | +| No tooling detected | Manual measurement | Timed execution via Bash | + +6. Get changed files scope from shared-memory (optimizer namespace) + +## Phase 3: Benchmark Execution + +Run benchmarks matching detected project type: + +**Frontend benchmarks**: +- Compare bundle size before/after (build output analysis) +- Measure render performance for affected components +- Check for dependency weight changes + +**Backend benchmarks**: +- Measure endpoint response times for affected routes +- Profile memory usage under simulated load +- Verify database query performance improvements + +**CLI / Library benchmarks**: +- Measure execution time for representative workloads +- Compare memory peak usage +- Test throughput under sustained load + +**All project types**: +- Run existing test suite to verify no regressions +- Collect post-optimization metrics matching baseline format +- Calculate improvement percentages per metric + +## Phase 4: Result Analysis + +Compare against baseline and plan criteria: + +| Metric | Threshold | Verdict | +|--------|-----------|---------| +| Target improvement vs baseline | Meets plan success criteria | PASS | +| No regression in unrelated metrics | < 5% degradation allowed | PASS | +| All plan success criteria met | Every criterion satisfied | PASS | +| Improvement below target | > 50% of target achieved | WARN | +| Regression detected | Any unrelated metric degrades > 5% | FAIL -> fix_required | +| Plan criteria not met | Any criterion not satisfied | FAIL -> fix_required | + +1. Write benchmark results to `/artifacts/benchmark-results.json`: + - Per-metric: name, baseline value, current value, improvement %, verdict + - Overall verdict: PASS / WARN / FAIL + - Regression details (if any) + +2. Update `/wisdom/shared-memory.json` under `benchmarker` namespace: + - Read existing -> merge `{ "benchmarker": { verdict, improvements, regressions } }` -> write back + +3. If verdict is FAIL, include detailed feedback in message for FIX task creation: + - Which metrics failed, by how much, suggested investigation areas diff --git a/.claude/skills/team-perf-opt/role-specs/optimizer.md b/.claude/skills/team-perf-opt/role-specs/optimizer.md new file mode 100644 index 00000000..deed9e39 --- /dev/null +++ b/.claude/skills/team-perf-opt/role-specs/optimizer.md @@ -0,0 +1,76 @@ +--- +prefix: IMPL +inner_loop: true +additional_prefixes: [FIX] +subagents: [explore] +message_types: + success: impl_complete + error: error + fix: fix_required +--- + +# Code Optimizer + +Implement optimization changes following the strategy plan. For FIX tasks, apply targeted corrections based on review/benchmark feedback. + +## Modes + +| Mode | Task Prefix | Trigger | Focus | +|------|-------------|---------|-------| +| Implement | IMPL | Strategy plan ready | Apply optimizations per plan priority | +| Fix | FIX | Review/bench feedback | Targeted fixes for identified issues | + +## Phase 2: Plan & Context Loading + +| Input | Source | Required | +|-------|--------|----------| +| Optimization plan | /artifacts/optimization-plan.md | Yes (IMPL) | +| Review/bench feedback | From task description | Yes (FIX) | +| shared-memory.json | /wisdom/shared-memory.json | Yes | +| Wisdom files | /wisdom/patterns.md | No | +| Context accumulator | From prior IMPL/FIX tasks | Yes (inner loop) | + +1. Extract session path and task mode (IMPL or FIX) from task description +2. For IMPL: read optimization plan -- extract priority-ordered changes and success criteria +3. For FIX: parse review/benchmark feedback for specific issues to address +4. Use `explore` subagent to load implementation context for target files +5. For inner loop: load context_accumulator from prior IMPL/FIX tasks to avoid re-reading + +## Phase 3: Code Implementation + +Implementation backend selection: + +| Backend | Condition | Method | +|---------|-----------|--------| +| CLI | Multi-file optimization with clear plan | ccw cli --tool gemini --mode write | +| Direct | Single-file changes or targeted fixes | Inline Edit/Write tools | + +For IMPL tasks: +- Apply optimizations in plan priority order (P0 first, then P1, etc.) +- Follow implementation guidance from plan (target files, patterns) +- Preserve existing behavior -- optimization must not break functionality + +For FIX tasks: +- Read specific issues from review/benchmark feedback +- Apply targeted corrections to flagged code locations +- Verify the fix addresses the exact concern raised + +General rules: +- Make minimal, focused changes per optimization +- Add comments only where optimization logic is non-obvious +- Preserve existing code style and conventions + +## Phase 4: Self-Validation + +| Check | Method | Pass Criteria | +|-------|--------|---------------| +| Syntax | IDE diagnostics or build check | No new errors | +| File integrity | Verify all planned files exist and are modified | All present | +| Acceptance | Match optimization plan success criteria | All target metrics addressed | +| No regression | Run existing tests if available | No new failures | + +If validation fails, attempt auto-fix (max 2 attempts) before reporting error. + +Append to context_accumulator for next IMPL/FIX task: +- Files modified, optimizations applied, validation results +- Any discovered patterns or caveats for subsequent iterations diff --git a/.claude/skills/team-perf-opt/role-specs/profiler.md b/.claude/skills/team-perf-opt/role-specs/profiler.md new file mode 100644 index 00000000..07037533 --- /dev/null +++ b/.claude/skills/team-perf-opt/role-specs/profiler.md @@ -0,0 +1,73 @@ +--- +prefix: PROFILE +inner_loop: false +subagents: [explore] +message_types: + success: profile_complete + error: error +--- + +# Performance Profiler + +Profile application performance to identify CPU, memory, I/O, network, and rendering bottlenecks. Produce quantified baseline metrics and a ranked bottleneck report. + +## Phase 2: Context & Environment Detection + +| Input | Source | Required | +|-------|--------|----------| +| Task description | From task subject/description | Yes | +| Session path | Extracted from task description | Yes | +| shared-memory.json | /wisdom/shared-memory.json | No | + +1. Extract session path and target scope from task description +2. Detect project type by scanning for framework markers: + +| Signal File | Project Type | Profiling Focus | +|-------------|-------------|-----------------| +| package.json + React/Vue/Angular | Frontend | Render time, bundle size, FCP/LCP/CLS | +| package.json + Express/Fastify/NestJS | Backend Node | CPU hotspots, memory, DB queries | +| Cargo.toml / go.mod / pom.xml | Native/JVM Backend | CPU, memory, GC tuning | +| Mixed framework markers | Full-stack | Split into FE + BE profiling passes | +| CLI entry / bin/ directory | CLI Tool | Startup time, throughput, memory peak | +| No detection | Generic | All profiling dimensions | + +3. Use `explore` subagent to map performance-critical code paths within target scope +4. Detect available profiling tools (test runners, benchmark harnesses, linting tools) + +## Phase 3: Performance Profiling + +Execute profiling based on detected project type: + +**Frontend profiling**: +- Analyze bundle size and dependency weight via build output +- Identify render-blocking resources and heavy components +- Check for unnecessary re-renders, large DOM trees, unoptimized assets + +**Backend profiling**: +- Trace hot code paths via execution analysis or instrumented runs +- Identify slow database queries, N+1 patterns, missing indexes +- Check memory allocation patterns and potential leaks + +**CLI / Library profiling**: +- Measure startup time and critical path latency +- Profile throughput under representative workloads +- Identify memory peaks and allocation churn + +**All project types**: +- Collect quantified baseline metrics (timing, memory, throughput) +- Rank top 3-5 bottlenecks by severity (Critical / High / Medium) +- Record evidence: file paths, line numbers, measured values + +## Phase 4: Report Generation + +1. Write baseline metrics to `/artifacts/baseline-metrics.json`: + - Key metric names, measured values, units, measurement method + - Timestamp and environment details + +2. Write bottleneck report to `/artifacts/bottleneck-report.md`: + - Ranked list of bottlenecks with severity, location (file:line), measured impact + - Evidence summary per bottleneck + - Detected project type and profiling methods used + +3. Update `/wisdom/shared-memory.json` under `profiler` namespace: + - Read existing -> merge `{ "profiler": { project_type, bottleneck_count, top_bottleneck, scope } }` -> write back diff --git a/.claude/skills/team-perf-opt/role-specs/reviewer.md b/.claude/skills/team-perf-opt/role-specs/reviewer.md new file mode 100644 index 00000000..075ed943 --- /dev/null +++ b/.claude/skills/team-perf-opt/role-specs/reviewer.md @@ -0,0 +1,69 @@ +--- +prefix: REVIEW +inner_loop: false +additional_prefixes: [QUALITY] +discuss_rounds: [DISCUSS-REVIEW] +subagents: [discuss] +message_types: + success: review_complete + error: error + fix: fix_required +--- + +# Optimization Reviewer + +Review optimization code changes for correctness, side effects, regression risks, and adherence to best practices. Provide structured verdicts with actionable feedback. + +## Phase 2: Context Loading + +| Input | Source | Required | +|-------|--------|----------| +| Optimization code changes | From IMPL task artifacts / git diff | Yes | +| Optimization plan | /artifacts/optimization-plan.md | Yes | +| Benchmark results | /artifacts/benchmark-results.json | No | +| shared-memory.json | /wisdom/shared-memory.json | Yes | + +1. Extract session path from task description +2. Read optimization plan -- understand intended changes and success criteria +3. Load shared-memory.json for optimizer namespace (files modified, patterns applied) +4. Identify changed files from optimizer context -- read each modified file +5. If benchmark results available, read for cross-reference with code quality + +## Phase 3: Multi-Dimension Review + +Analyze optimization changes across five dimensions: + +| Dimension | Focus | Severity | +|-----------|-------|----------| +| Correctness | Logic errors, off-by-one, race conditions, null safety | Critical | +| Side effects | Unintended behavior changes, API contract breaks, data loss | Critical | +| Maintainability | Code clarity, complexity increase, naming, documentation | High | +| Regression risk | Impact on unrelated code paths, implicit dependencies | High | +| Best practices | Idiomatic patterns, framework conventions, optimization anti-patterns | Medium | + +Per-dimension review process: +- Scan modified files for patterns matching each dimension +- Record findings with severity (Critical / High / Medium / Low) +- Include specific file:line references and suggested fixes + +If any Critical findings detected, invoke `discuss` subagent (DISCUSS-REVIEW round) to validate the assessment before issuing verdict. + +## Phase 4: Verdict & Feedback + +Classify overall verdict based on findings: + +| Verdict | Condition | Action | +|---------|-----------|--------| +| APPROVE | No Critical or High findings | Send review_complete | +| REVISE | Has High findings, no Critical | Send fix_required with detailed feedback | +| REJECT | Has Critical findings or fundamental approach flaw | Send fix_required + flag for strategist escalation | + +1. Write review report to `/artifacts/review-report.md`: + - Per-dimension findings with severity, file:line, description + - Overall verdict with rationale + - Specific fix instructions for REVISE/REJECT verdicts + +2. Update `/wisdom/shared-memory.json` under `reviewer` namespace: + - Read existing -> merge `{ "reviewer": { verdict, finding_count, critical_count, dimensions_reviewed } }` -> write back + +3. If DISCUSS-REVIEW was triggered, record discussion summary in `/discussions/DISCUSS-REVIEW.md` diff --git a/.claude/skills/team-perf-opt/role-specs/strategist.md b/.claude/skills/team-perf-opt/role-specs/strategist.md new file mode 100644 index 00000000..946332b0 --- /dev/null +++ b/.claude/skills/team-perf-opt/role-specs/strategist.md @@ -0,0 +1,73 @@ +--- +prefix: STRATEGY +inner_loop: false +discuss_rounds: [DISCUSS-OPT] +subagents: [discuss] +message_types: + success: strategy_complete + error: error +--- + +# Optimization Strategist + +Analyze bottleneck reports and baseline metrics to design a prioritized optimization plan with concrete strategies, expected improvements, and risk assessments. + +## Phase 2: Analysis Loading + +| Input | Source | Required | +|-------|--------|----------| +| Bottleneck report | /artifacts/bottleneck-report.md | Yes | +| Baseline metrics | /artifacts/baseline-metrics.json | Yes | +| shared-memory.json | /wisdom/shared-memory.json | Yes | +| Wisdom files | /wisdom/patterns.md | No | + +1. Extract session path from task description +2. Read bottleneck report -- extract ranked bottleneck list with severities +3. Read baseline metrics -- extract current performance numbers +4. Load shared-memory.json for profiler findings (project_type, scope) +5. Assess overall optimization complexity: + +| Bottleneck Count | Severity Mix | Complexity | +|-----------------|-------------|------------| +| 1-2 | All Medium | Low | +| 2-3 | Mix of High/Medium | Medium | +| 3+ or any Critical | Any Critical present | High | + +## Phase 3: Strategy Formulation + +For each bottleneck, select optimization approach by type: + +| Bottleneck Type | Strategies | Risk Level | +|----------------|-----------|------------| +| CPU hotspot | Algorithm optimization, memoization, caching, worker threads | Medium | +| Memory leak/bloat | Pool reuse, lazy initialization, WeakRef, scope cleanup | High | +| I/O bound | Batching, async pipelines, streaming, connection pooling | Medium | +| Network latency | Request coalescing, compression, CDN, prefetching | Low | +| Rendering | Virtualization, memoization, CSS containment, code splitting | Medium | +| Database | Index optimization, query rewriting, caching layer, denormalization | High | + +Prioritize optimizations by impact/effort ratio: + +| Priority | Criteria | +|----------|----------| +| P0 (Critical) | High impact + Low effort -- quick wins | +| P1 (High) | High impact + Medium effort | +| P2 (Medium) | Medium impact + Low effort | +| P3 (Low) | Low impact or High effort -- defer | + +If complexity is High, invoke `discuss` subagent (DISCUSS-OPT round) to evaluate trade-offs between competing strategies before finalizing the plan. + +Define measurable success criteria per optimization (target metric value or improvement %). + +## Phase 4: Plan Output + +1. Write optimization plan to `/artifacts/optimization-plan.md`: + - Priority-ordered list of optimizations + - Per optimization: target bottleneck, strategy, expected improvement %, risk level + - Success criteria: specific metric thresholds to verify + - Implementation guidance: files to modify, patterns to apply + +2. Update `/wisdom/shared-memory.json` under `strategist` namespace: + - Read existing -> merge `{ "strategist": { complexity, optimization_count, priorities, discuss_used } }` -> write back + +3. If DISCUSS-OPT was triggered, record discussion summary in `/discussions/DISCUSS-OPT.md` diff --git a/.claude/skills/team-perf-opt/roles/coordinator/commands/dispatch.md b/.claude/skills/team-perf-opt/roles/coordinator/commands/dispatch.md new file mode 100644 index 00000000..840082f2 --- /dev/null +++ b/.claude/skills/team-perf-opt/roles/coordinator/commands/dispatch.md @@ -0,0 +1,175 @@ +# Command: Dispatch + +Create the performance optimization task chain with correct dependencies and structured task descriptions. + +## Phase 2: Context Loading + +| Input | Source | Required | +|-------|--------|----------| +| User requirement | From coordinator Phase 1 | Yes | +| Session folder | From coordinator Phase 2 | Yes | +| Pipeline definition | From SKILL.md Pipeline Definitions | Yes | + +1. Load user requirement and optimization scope from session.json +2. Load pipeline stage definitions from SKILL.md Task Metadata Registry +3. Determine if single-pass or multi-pass optimization is needed + +## Phase 3: Task Chain Creation + +### Task Description Template + +Every task description uses structured format for clarity: + +``` +TaskCreate({ + subject: "", + owner: "", + description: "PURPOSE: | Success: +TASK: + - + - + - +CONTEXT: + - Session: + - Scope: + - Upstream artifacts: , + - Shared memory: /wisdom/shared-memory.json +EXPECTED: + +CONSTRAINTS: +--- +InnerLoop: ", + blockedBy: [], + status: "pending" +}) +``` + +### Task Chain + +Create tasks in dependency order: + +**PROFILE-001** (profiler, Stage 1): +``` +TaskCreate({ + subject: "PROFILE-001", + description: "PURPOSE: Profile application performance to identify bottlenecks | Success: Baseline metrics captured, top 3-5 bottlenecks ranked by severity +TASK: + - Detect project type and available profiling tools + - Execute profiling across relevant dimensions (CPU, memory, I/O, network, rendering) + - Collect baseline metrics and rank bottlenecks by severity +CONTEXT: + - Session: + - Scope: + - Shared memory: /wisdom/shared-memory.json +EXPECTED: /artifacts/baseline-metrics.json + /artifacts/bottleneck-report.md | Quantified metrics with evidence +CONSTRAINTS: Focus on | Profile before any changes +--- +InnerLoop: false", + status: "pending" +}) +``` + +**STRATEGY-001** (strategist, Stage 2): +``` +TaskCreate({ + subject: "STRATEGY-001", + description: "PURPOSE: Design prioritized optimization plan from bottleneck analysis | Success: Actionable plan with measurable success criteria per optimization +TASK: + - Analyze bottleneck report and baseline metrics + - Select optimization strategies per bottleneck type + - Prioritize by impact/effort ratio, define success criteria +CONTEXT: + - Session: + - Scope: + - Upstream artifacts: baseline-metrics.json, bottleneck-report.md + - Shared memory: /wisdom/shared-memory.json +EXPECTED: /artifacts/optimization-plan.md | Priority-ordered with improvement targets +CONSTRAINTS: Focus on highest-impact optimizations | Risk assessment required +--- +InnerLoop: false", + blockedBy: ["PROFILE-001"], + status: "pending" +}) +``` + +**IMPL-001** (optimizer, Stage 3): +``` +TaskCreate({ + subject: "IMPL-001", + description: "PURPOSE: Implement optimization changes per strategy plan | Success: All planned optimizations applied, code compiles, existing tests pass +TASK: + - Load optimization plan and identify target files + - Apply optimizations in priority order (P0 first) + - Validate changes compile and pass existing tests +CONTEXT: + - Session: + - Scope: + - Upstream artifacts: optimization-plan.md + - Shared memory: /wisdom/shared-memory.json +EXPECTED: Modified source files + validation passing | Optimizations applied without regressions +CONSTRAINTS: Preserve existing behavior | Minimal changes per optimization | Follow code conventions +--- +InnerLoop: true", + blockedBy: ["STRATEGY-001"], + status: "pending" +}) +``` + +**BENCH-001** (benchmarker, Stage 4 - parallel): +``` +TaskCreate({ + subject: "BENCH-001", + description: "PURPOSE: Benchmark optimization results against baseline | Success: All plan success criteria met, no regressions detected +TASK: + - Load baseline metrics and plan success criteria + - Run benchmarks matching project type + - Compare before/after metrics, calculate improvements +CONTEXT: + - Session: + - Scope: + - Upstream artifacts: baseline-metrics.json, optimization-plan.md + - Shared memory: /wisdom/shared-memory.json +EXPECTED: /artifacts/benchmark-results.json | Per-metric comparison with verdicts +CONSTRAINTS: Must compare against baseline | Flag any regressions +--- +InnerLoop: false", + blockedBy: ["IMPL-001"], + status: "pending" +}) +``` + +**REVIEW-001** (reviewer, Stage 4 - parallel): +``` +TaskCreate({ + subject: "REVIEW-001", + description: "PURPOSE: Review optimization code for correctness, side effects, and regression risks | Success: All dimensions reviewed, verdict issued +TASK: + - Load modified files and optimization plan + - Review across 5 dimensions: correctness, side effects, maintainability, regression risk, best practices + - Issue verdict: APPROVE, REVISE, or REJECT with actionable feedback +CONTEXT: + - Session: + - Scope: + - Upstream artifacts: optimization-plan.md, benchmark-results.json (if available) + - Shared memory: /wisdom/shared-memory.json +EXPECTED: /artifacts/review-report.md | Per-dimension findings with severity +CONSTRAINTS: Focus on optimization changes only | Provide specific file:line references +--- +InnerLoop: false", + blockedBy: ["IMPL-001"], + status: "pending" +}) +``` + +## Phase 4: Validation + +Verify task chain integrity: + +| Check | Method | Expected | +|-------|--------|----------| +| All 5 tasks created | TaskList count | 5 tasks | +| Dependencies correct | STRATEGY blocks on PROFILE, IMPL blocks on STRATEGY, BENCH+REVIEW block on IMPL | All valid | +| No circular dependencies | Trace dependency graph | Acyclic | +| All task IDs use correct prefixes | PROFILE-*, STRATEGY-*, IMPL-*, BENCH-*, REVIEW-* | Match role registry | +| Structured descriptions complete | Each has PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS | All present | + +If validation fails, fix the specific task and re-validate. diff --git a/.claude/skills/team-perf-opt/roles/coordinator/commands/monitor.md b/.claude/skills/team-perf-opt/roles/coordinator/commands/monitor.md new file mode 100644 index 00000000..8c2860b0 --- /dev/null +++ b/.claude/skills/team-perf-opt/roles/coordinator/commands/monitor.md @@ -0,0 +1,201 @@ +# Command: Monitor + +Handle all coordinator monitoring events: worker callbacks, status checks, pipeline advancement, and completion. + +## Phase 2: Context Loading + +| Input | Source | Required | +|-------|--------|----------| +| Session state | /session.json | Yes | +| Task list | TaskList() | Yes | +| Trigger event | From Entry Router detection | Yes | +| Pipeline definition | From SKILL.md | Yes | + +1. Load session.json for current state and fix cycle count +2. Run TaskList() to get current task statuses +3. Identify trigger event type from Entry Router + +## Phase 3: Event Handlers + +### handleCallback + +Triggered when a worker sends completion message. + +1. Parse message to identify role and task ID +2. Mark task as completed: + +``` +TaskUpdate({ taskId: "", status: "completed" }) +``` + +3. Record completion in session state +4. Check if checkpoint feedback is configured for this stage: + +| Completed Task | Checkpoint | Action | +|---------------|------------|--------| +| PROFILE-001 | CP-1 | Notify user: bottleneck report ready for review | +| STRATEGY-001 | CP-2 | Notify user: optimization plan ready for review | +| BENCH-001 or REVIEW-001 | CP-3 | Check verdicts (see Review-Fix Cycle below) | + +5. Proceed to handleSpawnNext + +### handleSpawnNext + +Find and spawn the next ready tasks. + +1. Scan task list for tasks where: + - Status is "pending" + - All blockedBy tasks have status "completed" + +2. For each ready task, spawn team-worker: + +``` +Task({ + subagent_type: "team-worker", + description: "Spawn worker for ", + team_name: "perf-opt", + name: "", + run_in_background: true, + prompt: `## Role Assignment +role: +role_spec: .claude/skills/team-perf-opt/role-specs/.md +session: +session_id: +team_name: perf-opt +requirement: +inner_loop: + +Read role_spec file to load Phase 2-4 domain instructions. +Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.` +}) +``` + +3. For Stage 4 (BENCH-001 + REVIEW-001): spawn both in parallel since both block on IMPL-001 +4. STOP after spawning -- wait for next callback + +### Review-Fix Cycle (CP-3) + +When both BENCH-001 and REVIEW-001 are completed: + +1. Read benchmark verdict from shared-memory (benchmarker namespace) +2. Read review verdict from shared-memory (reviewer namespace) + +| Bench Verdict | Review Verdict | Action | +|--------------|----------------|--------| +| PASS | APPROVE | -> handleComplete | +| PASS | REVISE | Create FIX task with review feedback | +| FAIL | APPROVE | Create FIX task with benchmark feedback | +| FAIL | REVISE/REJECT | Create FIX task with combined feedback | +| Any | REJECT | Create FIX task + flag for strategist re-evaluation | + +3. Check fix cycle count: + +| Cycle Count | Action | +|-------------|--------| +| < 3 | Create FIX task, increment cycle count | +| >= 3 | Escalate to user with summary of remaining issues | + +4. Create FIX task if needed: + +``` +TaskCreate({ + subject: "FIX-", + description: "PURPOSE: Fix issues identified by review/benchmark | Success: All flagged issues resolved +TASK: + - Address review findings: + - Fix benchmark regressions: + - Re-validate after fixes +CONTEXT: + - Session: + - Upstream artifacts: review-report.md, benchmark-results.json + - Shared memory: /wisdom/shared-memory.json +EXPECTED: Fixed source files | All flagged issues addressed +CONSTRAINTS: Targeted fixes only | Do not introduce new changes +--- +InnerLoop: true", + blockedBy: [], + status: "pending" +}) +``` + +5. Create new BENCH and REVIEW tasks blocked on FIX task +6. Proceed to handleSpawnNext (spawns optimizer for FIX task) + +### handleCheck + +Output current pipeline status without advancing. + +1. Build status graph from task list: + +``` +Pipeline Status: + [DONE] PROFILE-001 (profiler) -> bottleneck-report.md + [DONE] STRATEGY-001 (strategist) -> optimization-plan.md + [RUN] IMPL-001 (optimizer) -> implementing... + [WAIT] BENCH-001 (benchmarker) -> blocked by IMPL-001 + [WAIT] REVIEW-001 (reviewer) -> blocked by IMPL-001 + +Fix Cycles: 0/3 +Session: +``` + +2. Output status -- do NOT advance pipeline + +### handleResume + +Resume pipeline after user pause or interruption. + +1. Audit task list for inconsistencies: + - Tasks stuck in "in_progress" -> reset to "pending" + - Tasks with completed blockers but still "pending" -> include in spawn list +2. Proceed to handleSpawnNext + +### handleConsensus + +Handle consensus_blocked signals from discuss rounds. + +| Severity | Action | +|----------|--------| +| HIGH | Pause pipeline, notify user with findings summary | +| MEDIUM | Create revision task for the blocked role | +| LOW | Log finding, continue pipeline | + +### handleComplete + +Triggered when all pipeline tasks are completed and no fix cycles remain. + +1. Verify all tasks have status "completed": + +``` +TaskList() +``` + +2. If any tasks not completed, return to handleSpawnNext +3. If all completed, transition to coordinator Phase 5 (Report + Completion Action) + +### handleRevise + +Triggered by user "revise [feedback]" command. + +1. Parse target task ID and optional feedback +2. Create revision task with same role but updated requirements +3. Set blockedBy to empty (immediate execution) +4. Cascade: create new downstream tasks that depend on the revised task +5. Proceed to handleSpawnNext + +### handleFeedback + +Triggered by user "feedback " command. + +1. Analyze feedback text to determine impact scope +2. Identify which pipeline stage and role should handle the feedback +3. Create targeted revision task +4. Proceed to handleSpawnNext + +## Phase 4: State Persistence + +After every handler execution: + +1. Update session.json with current state (active tasks, fix cycle count, last event) +2. Verify task list consistency +3. STOP and wait for next event diff --git a/.claude/skills/team-perf-opt/roles/coordinator/role.md b/.claude/skills/team-perf-opt/roles/coordinator/role.md new file mode 100644 index 00000000..4304400f --- /dev/null +++ b/.claude/skills/team-perf-opt/roles/coordinator/role.md @@ -0,0 +1,252 @@ +# Coordinator - Performance Optimization Team + +**Role**: coordinator +**Type**: Orchestrator +**Team**: perf-opt + +Orchestrates the performance optimization pipeline: manages task chains, spawns team-worker agents, handles review-fix cycles, and drives the pipeline to completion. + +## Boundaries + +### MUST + +- Use `team-worker` agent type for all worker spawns (NOT `general-purpose`) +- Follow Command Execution Protocol for dispatch and monitor commands +- Respect pipeline stage dependencies (blockedBy) +- Stop after spawning workers -- wait for callbacks +- Handle review-fix cycles with max 3 iterations +- Execute completion action in Phase 5 + +### MUST NOT + +- Implement domain logic (profiling, optimizing, reviewing) -- workers handle this +- Spawn workers without creating tasks first +- Skip checkpoints when configured +- Force-advance pipeline past failed review/benchmark +- Modify source code directly -- delegate to optimizer worker + +--- + +## Command Execution Protocol + +When coordinator needs to execute a command (dispatch, monitor): + +1. **Read the command file**: `roles/coordinator/commands/.md` +2. **Follow the workflow** defined in the command file (Phase 2-4 structure) +3. **Commands are inline execution guides** -- NOT separate agents or subprocesses +4. **Execute synchronously** -- complete the command workflow before proceeding + +Example: +``` +Phase 3 needs task dispatch + -> Read roles/coordinator/commands/dispatch.md + -> Execute Phase 2 (Context Loading) + -> Execute Phase 3 (Task Chain Creation) + -> Execute Phase 4 (Validation) + -> Continue to Phase 4 +``` + +--- + +## Entry Router + +When coordinator is invoked, detect invocation type: + +| Detection | Condition | Handler | +|-----------|-----------|---------| +| Worker callback | Message contains role tag [profiler], [strategist], [optimizer], [benchmarker], [reviewer] | -> handleCallback | +| Consensus blocked | Message contains "consensus_blocked" | -> handleConsensus | +| Status check | Arguments contain "check" or "status" | -> handleCheck | +| Manual resume | Arguments contain "resume" or "continue" | -> handleResume | +| Pipeline complete | All tasks have status "completed" | -> handleComplete | +| Interrupted session | Active/paused session exists | -> Phase 0 (Resume Check) | +| New session | None of above | -> Phase 1 (Requirement Clarification) | + +For callback/check/resume/complete: load `commands/monitor.md` and execute matched handler, then STOP. + +### Router Implementation + +1. **Load session context** (if exists): + - Scan `.workflow/.team/PERF-OPT-*/team-session.json` for active/paused sessions + - If found, extract session folder path and status + +2. **Parse $ARGUMENTS** for detection keywords: + - Check for role name tags in message content + - Check for "check", "status", "resume", "continue" keywords + - Check for "consensus_blocked" signal + +3. **Route to handler**: + - For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP + - For Phase 0: Execute Session Resume Check below + - For Phase 1: Execute Requirement Clarification below + +--- + +## Phase 0: Session Resume Check + +Triggered when an active/paused session is detected on coordinator entry. + +1. Load session.json from detected session folder +2. Audit task list: + +``` +TaskList() +``` + +3. Reconcile session state vs task status: + +| Task Status | Session Expects | Action | +|-------------|----------------|--------| +| in_progress | Should be running | Reset to pending (worker was interrupted) | +| completed | Already tracked | Skip | +| pending + unblocked | Ready to run | Include in spawn list | + +4. Rebuild team if not active: + +``` +TeamCreate({ team_name: "perf-opt" }) +``` + +5. Spawn workers for ready tasks -> Phase 4 coordination loop + +--- + +## Phase 1: Requirement Clarification + +1. Parse user task description from $ARGUMENTS +2. Identify optimization target: + +| Signal | Target | +|--------|--------| +| Specific file/module mentioned | Scoped optimization | +| "slow", "performance", generic | Full application profiling | +| Specific metric mentioned (FCP, memory, startup) | Targeted metric optimization | + +3. If target is unclear, ask for clarification: + +``` +AskUserQuestion({ + questions: [{ + question: "What should I optimize? Provide a target scope or describe the performance issue.", + header: "Scope" + }] +}) +``` + +4. Record optimization requirement with scope and target metrics + +--- + +## Phase 2: Session & Team Setup + +1. Create session directory: + +``` +Bash("mkdir -p .workflow//artifacts .workflow//explorations .workflow//wisdom .workflow//discussions") +``` + +2. Write session.json with status="active", team_name, requirement, timestamp + +3. Initialize shared-memory.json: + +``` +Write("/wisdom/shared-memory.json", { "session_id": "", "requirement": "" }) +``` + +4. Create team: + +``` +TeamCreate({ team_name: "perf-opt" }) +``` + +--- + +## Phase 3: Task Chain Creation + +Execute `commands/dispatch.md` inline (Command Execution Protocol): + +1. Read `roles/coordinator/commands/dispatch.md` +2. Follow dispatch Phase 2 (context loading) -> Phase 3 (task chain creation) -> Phase 4 (validation) +3. Result: all pipeline tasks created with correct blockedBy dependencies + +--- + +## Phase 4: Spawn & Coordination Loop + +### Initial Spawn + +Find first unblocked task and spawn its worker: + +``` +Task({ + subagent_type: "team-worker", + description: "Spawn profiler worker", + team_name: "perf-opt", + name: "profiler", + run_in_background: true, + prompt: `## Role Assignment +role: profiler +role_spec: .claude/skills/team-perf-opt/role-specs/profiler.md +session: +session_id: +team_name: perf-opt +requirement: +inner_loop: false + +Read role_spec file to load Phase 2-4 domain instructions. +Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.` +}) +``` + +**STOP** after spawning. Wait for worker callback. + +### Coordination (via monitor.md handlers) + +All subsequent coordination is handled by `commands/monitor.md` handlers triggered by worker callbacks: + +- handleCallback -> mark task done -> check pipeline -> handleSpawnNext +- handleSpawnNext -> find ready tasks -> spawn team-worker agents -> STOP +- handleComplete -> all done -> Phase 5 + +--- + +## Phase 5: Report + Completion Action + +1. Load session state -> count completed tasks, calculate duration +2. List deliverables: + +| Deliverable | Path | +|-------------|------| +| Baseline Metrics | /artifacts/baseline-metrics.json | +| Bottleneck Report | /artifacts/bottleneck-report.md | +| Optimization Plan | /artifacts/optimization-plan.md | +| Benchmark Results | /artifacts/benchmark-results.json | +| Review Report | /artifacts/review-report.md | + +3. Include discussion summaries if discuss rounds were used +4. Output pipeline summary: task count, duration, improvement metrics from benchmark results + +5. **Completion Action** (interactive): + +``` +AskUserQuestion({ + questions: [{ + question: "Team pipeline complete. What would you like to do?", + header: "Completion", + multiSelect: false, + options: [ + { label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" }, + { label: "Keep Active", description: "Keep session active for follow-up work or inspection" }, + { label: "Export Results", description: "Export deliverables to a specified location, then clean" } + ] + }] +}) +``` + +6. Handle user choice: + +| Choice | Steps | +|--------|-------| +| Archive & Clean | TaskList -> verify all completed -> update session status="completed" -> TeamDelete("perf-opt") -> output final summary with artifact paths | +| Keep Active | Update session status="paused" -> output: "Session paused. Resume with: Skill(skill='team-perf-opt', args='resume')" | +| Export Results | AskUserQuestion for target directory -> copy all artifacts -> Archive & Clean flow | diff --git a/.claude/skills/team-perf-opt/specs/team-config.json b/.claude/skills/team-perf-opt/specs/team-config.json new file mode 100644 index 00000000..8e6b2849 --- /dev/null +++ b/.claude/skills/team-perf-opt/specs/team-config.json @@ -0,0 +1,208 @@ +{ + "version": "5.0.0", + "team_name": "perf-opt", + "team_display_name": "Performance Optimization", + "skill_name": "team-perf-opt", + "skill_path": ".claude/skills/team-perf-opt/", + "worker_agent": "team-worker", + "pipeline_type": "Linear with Review-Fix Cycle", + "completion_action": "interactive", + "has_inline_discuss": true, + "has_shared_explore": true, + "has_checkpoint_feedback": true, + "has_session_resume": true, + + "roles": [ + { + "name": "coordinator", + "type": "orchestrator", + "description": "Orchestrates performance optimization pipeline, manages task chains, handles review-fix cycles", + "spec_path": "roles/coordinator/role.md", + "tools": ["Task", "TaskCreate", "TaskList", "TaskGet", "TaskUpdate", "TeamCreate", "TeamDelete", "SendMessage", "AskUserQuestion", "Read", "Write", "Bash", "Glob", "Grep"] + }, + { + "name": "profiler", + "type": "orchestration", + "description": "Profiles application performance, identifies CPU/memory/IO/network/rendering bottlenecks", + "role_spec": "role-specs/profiler.md", + "inner_loop": false, + "frontmatter": { + "prefix": "PROFILE", + "inner_loop": false, + "additional_prefixes": [], + "discuss_rounds": [], + "subagents": ["explore"], + "message_types": { + "success": "profile_complete", + "error": "error" + } + }, + "weight": 1, + "tools": ["Read", "Bash", "Glob", "Grep", "Task", "mcp__ace-tool__search_context"] + }, + { + "name": "strategist", + "type": "orchestration", + "description": "Analyzes bottleneck reports, designs prioritized optimization plans with concrete strategies", + "role_spec": "role-specs/strategist.md", + "inner_loop": false, + "frontmatter": { + "prefix": "STRATEGY", + "inner_loop": false, + "additional_prefixes": [], + "discuss_rounds": ["DISCUSS-OPT"], + "subagents": ["discuss"], + "message_types": { + "success": "strategy_complete", + "error": "error" + } + }, + "weight": 2, + "tools": ["Read", "Bash", "Glob", "Grep", "Task", "mcp__ace-tool__search_context"] + }, + { + "name": "optimizer", + "type": "code_generation", + "description": "Implements optimization changes following the strategy plan", + "role_spec": "role-specs/optimizer.md", + "inner_loop": true, + "frontmatter": { + "prefix": "IMPL", + "inner_loop": true, + "additional_prefixes": ["FIX"], + "discuss_rounds": [], + "subagents": ["explore"], + "message_types": { + "success": "impl_complete", + "error": "error", + "fix": "fix_required" + } + }, + "weight": 3, + "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Task", "mcp__ace-tool__search_context"] + }, + { + "name": "benchmarker", + "type": "validation", + "description": "Runs benchmarks, compares before/after metrics, validates performance improvements", + "role_spec": "role-specs/benchmarker.md", + "inner_loop": false, + "frontmatter": { + "prefix": "BENCH", + "inner_loop": false, + "additional_prefixes": [], + "discuss_rounds": [], + "subagents": [], + "message_types": { + "success": "bench_complete", + "error": "error", + "fix": "fix_required" + } + }, + "weight": 4, + "tools": ["Read", "Bash", "Glob", "Grep", "Task"] + }, + { + "name": "reviewer", + "type": "read_only_analysis", + "description": "Reviews optimization code for correctness, side effects, and regression risks", + "role_spec": "role-specs/reviewer.md", + "inner_loop": false, + "frontmatter": { + "prefix": "REVIEW", + "inner_loop": false, + "additional_prefixes": ["QUALITY"], + "discuss_rounds": ["DISCUSS-REVIEW"], + "subagents": ["discuss"], + "message_types": { + "success": "review_complete", + "error": "error", + "fix": "fix_required" + } + }, + "weight": 4, + "tools": ["Read", "Bash", "Glob", "Grep", "Task", "mcp__ace-tool__search_context"] + } + ], + + "pipeline": { + "stages": [ + { + "stage": 1, + "name": "Performance Profiling", + "roles": ["profiler"], + "blockedBy": [], + "fast_advance": true + }, + { + "stage": 2, + "name": "Optimization Strategy", + "roles": ["strategist"], + "blockedBy": ["PROFILE"], + "fast_advance": true + }, + { + "stage": 3, + "name": "Code Optimization", + "roles": ["optimizer"], + "blockedBy": ["STRATEGY"], + "fast_advance": false + }, + { + "stage": 4, + "name": "Benchmark & Review", + "roles": ["benchmarker", "reviewer"], + "blockedBy": ["IMPL"], + "fast_advance": false, + "parallel": true, + "review_fix_cycle": { + "trigger": "REVIEW or BENCH finds issues", + "target_stage": 3, + "max_iterations": 3 + } + } + ], + "diagram": "See pipeline-diagram section" + }, + + "subagents": [ + { + "name": "explore", + "agent_type": "cli-explore-agent", + "callable_by": ["profiler", "optimizer"], + "purpose": "Shared codebase exploration for performance-critical code paths", + "has_cache": true, + "cache_domain": "explorations" + }, + { + "name": "discuss", + "agent_type": "cli-discuss-agent", + "callable_by": ["strategist", "reviewer"], + "purpose": "Multi-perspective discussion for optimization approaches and review findings", + "has_cache": false + } + ], + + "shared_resources": [ + { + "name": "Performance Baseline", + "path": "/artifacts/baseline-metrics.json", + "usage": "Before-optimization metrics for comparison" + }, + { + "name": "Bottleneck Report", + "path": "/artifacts/bottleneck-report.md", + "usage": "Profiler output consumed by strategist" + }, + { + "name": "Optimization Plan", + "path": "/artifacts/optimization-plan.md", + "usage": "Strategist output consumed by optimizer" + }, + { + "name": "Benchmark Results", + "path": "/artifacts/benchmark-results.json", + "usage": "Benchmarker output consumed by reviewer" + } + ] +} diff --git a/.claude/skills/team-perf-opt/subagents/discuss-subagent.md b/.claude/skills/team-perf-opt/subagents/discuss-subagent.md new file mode 100644 index 00000000..cfc2e69d --- /dev/null +++ b/.claude/skills/team-perf-opt/subagents/discuss-subagent.md @@ -0,0 +1,89 @@ +# Discuss Subagent + +Multi-perspective discussion for evaluating optimization strategies and reviewing code change quality. Used by strategist (DISCUSS-OPT) and reviewer (DISCUSS-REVIEW) when complex trade-offs require multi-angle analysis. + +## Design Rationale + +Complex optimization decisions (e.g., choosing between algorithmic change vs caching layer) and nuanced code review findings (e.g., evaluating whether a side effect is acceptable) benefit from structured multi-perspective analysis. This subagent provides that analysis inline without spawning additional team members. + +## Invocation + +Called by strategist, reviewer after their primary analysis when complexity warrants multi-perspective evaluation: + +``` +Task({ + subagent_type: "cli-discuss-agent", + run_in_background: false, + description: "Discuss : for performance optimization", + prompt: `Conduct a multi-perspective discussion on the following topic. + +Round: +Topic: +Session: + +Context: + + +Perspectives to consider: +- Performance impact: Will this actually improve the target metric? +- Risk assessment: What could go wrong? Side effects? Regressions? +- Maintainability: Is the optimized code still understandable and maintainable? +- Alternative approaches: Are there simpler or safer ways to achieve the same goal? + +Evaluate trade-offs and provide a structured recommendation with: +- Consensus verdict: proceed / revise / escalate +- Confidence level: high / medium / low +- Key trade-offs identified +- Recommended approach with rationale +- Dissenting perspectives (if any)` +}) +``` + +## Round Configuration + +| Round | Artifact | Parameters | Calling Role | +|-------|----------|------------|-------------| +| DISCUSS-OPT | /discussions/DISCUSS-OPT.md | Optimization strategy trade-offs | strategist | +| DISCUSS-REVIEW | /discussions/DISCUSS-REVIEW.md | Code review finding validation | reviewer | + +## Integration with Calling Role + +The calling role is responsible for: + +1. **Before calling**: Complete primary analysis, identify the specific trade-off or finding needing discussion +2. **Calling**: Invoke subagent with round ID, topic, and relevant context +3. **After calling**: + +| Result | Action | +|--------|--------| +| consensus_reached (proceed) | Incorporate recommendation into output, continue | +| consensus_reached (revise) | Adjust findings/strategy based on discussion insights | +| consensus_blocked (HIGH) | Report to coordinator via message with severity | +| consensus_blocked (MEDIUM) | Include in output with recommendation for revision | +| consensus_blocked (LOW) | Note in output, proceed with original assessment | + +## Output Schema + +```json +{ + "round_id": "", + "topic": "", + "verdict": "", + "confidence": "", + "trade_offs": [ + { "dimension": "", "pro": "", "con": "" } + ], + "recommendation": "", + "rationale": "", + "dissenting_views": [""] +} +``` + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Single perspective analysis fails | Continue with partial perspectives | +| All analyses fail | Return basic recommendation from calling role's primary analysis | +| Artifact not found | Return error immediately | +| Discussion inconclusive | Return "revise" verdict with low confidence | diff --git a/.claude/skills/team-perf-opt/subagents/explore-subagent.md b/.claude/skills/team-perf-opt/subagents/explore-subagent.md new file mode 100644 index 00000000..549dd16e --- /dev/null +++ b/.claude/skills/team-perf-opt/subagents/explore-subagent.md @@ -0,0 +1,108 @@ +# Explore Subagent + +Shared codebase exploration for discovering performance-critical code paths, module structures, and optimization opportunities. Results are cached to avoid redundant exploration across profiler and optimizer roles. + +## Design Rationale + +Codebase exploration is a read-only operation shared between profiler (mapping bottlenecks) and optimizer (understanding implementation context). Caching explorations avoids redundant work when optimizer re-explores paths the profiler already mapped. + +## Invocation + +Called by profiler, optimizer after needing codebase context for performance analysis or implementation: + +``` +Task({ + subagent_type: "cli-explore-agent", + run_in_background: false, + description: "Explore codebase for performance-critical paths in ", + prompt: `Explore the codebase to identify performance-critical code paths. + +Target scope: +Session: +Focus: + +Tasks: +1. Map the module structure and entry points within scope +2. Identify hot code paths (frequently called functions, critical loops) +3. Find performance-relevant patterns (caching, lazy loading, async, pooling) +4. Note any existing performance optimizations or benchmark harnesses +5. List key files with their roles in the performance-critical path + +Output a structured exploration report with: +- Module map (key files and their relationships) +- Hot path analysis (call chains, loop nests, recursive patterns) +- Existing optimization patterns found +- Performance-relevant configuration (caching, pooling, batching settings) +- Recommended investigation targets for profiling` +}) +``` + +## Cache Mechanism + +### Cache Index Schema + +`/explorations/cache-index.json`: + +```json +{ + "entries": [ + { + "key": "", + "scope": "", + "focus": "", + "timestamp": "", + "result_file": ".md" + } + ] +} +``` + +### Cache Lookup Rules + +| Condition | Action | +|-----------|--------| +| Exact scope+focus match exists | Return cached result from .md | +| No match | Execute subagent, cache result to .md, update index | +| Cache file missing but index has entry | Remove stale entry, re-execute | +| Cache older than current session | Use cached (explorations are stable within session) | + +## Integration with Calling Role + +The calling role is responsible for: + +1. **Before calling**: Determine target scope and exploration focus +2. **Calling**: Check cache first, invoke subagent only on cache miss +3. **After calling**: + +| Result | Action | +|--------|--------| +| Exploration successful | Use findings to inform profiling/implementation | +| Exploration partial | Use available findings, note gaps | +| Exploration failed | Proceed without exploration context, use direct file reading | + +## Output Schema + +```json +{ + "scope": "", + "module_map": [ + { "file": "", "role": "", "hot_path": true } + ], + "hot_paths": [ + { "chain": "", "frequency": "", "files": [""] } + ], + "existing_optimizations": [ + { "type": "", "location": "", "description": "" } + ], + "investigation_targets": [""] +} +``` + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Single exploration angle fails | Continue with partial results | +| All exploration fails | Return basic result from direct file listing | +| Target scope not found | Return error immediately | +| Cache corrupt | Clear cache-index.json, re-execute | diff --git a/.codex/skills/brainstorm/SKILL.md b/.codex/skills/brainstorm/SKILL.md new file mode 100644 index 00000000..d70355ae --- /dev/null +++ b/.codex/skills/brainstorm/SKILL.md @@ -0,0 +1,725 @@ +--- +name: brainstorm +description: | + Dual-mode brainstorming pipeline. Auto mode: framework generation → parallel role analysis + (spawn_agents_on_csv) → cross-role synthesis. Single role mode: individual role analysis. + CSV-driven parallel coordination with NDJSON discovery board. +argument-hint: "[-y|--yes] [--count N] [--session ID] [--skip-questions] [--style-skill PKG] \"topic\" | [--session ID]" +allowed-tools: spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep +--- + +## Auto Mode + +When `--yes` or `-y`: Auto-select auto mode, auto-select recommended roles, skip all clarification questions, use defaults. + +# Brainstorm + +## Usage + +```bash +$brainstorm "Build real-time collaboration platform" --count 3 +$brainstorm -y "Design payment system" --count 5 +$brainstorm "Build notification system" --style-skill material-design +$brainstorm system-architect --session WFS-xxx +$brainstorm ux-expert --include-questions +``` + +**Flags**: +- `-y, --yes`: Skip all confirmations (auto mode) +- `--count N`: Number of roles to select (default: 3, max: 9) +- `--session ID`: Use existing session +- `--skip-questions / --include-questions`: Control interactive Q&A per role +- `--style-skill PKG`: Style skill package for ui-designer +- `--update`: Update existing role analysis + +--- + +## Overview + +Dual-mode brainstorming with CSV-driven parallel role analysis. Auto mode runs a full pipeline; single role mode runs one role analysis independently. + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ BRAINSTORM PIPELINE │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ Phase 1: Mode Detection & Routing │ +│ ├─ Parse flags and arguments │ +│ └─ Route to Auto Mode or Single Role Mode │ +│ │ +│ ═══ Auto Mode ═══ │ +│ │ +│ Phase 2: Interactive Framework Generation │ +│ ├─ Context collection → Topic analysis → Role selection │ +│ ├─ Generate guidance-specification.md │ +│ ├─ Generate roles.csv (1 row per selected role) │ +│ └─ User validates (skip if -y) │ +│ │ +│ Phase 3: Wave Role Analysis (spawn_agents_on_csv) │ +│ ├─ spawn_agents_on_csv(role instruction template) │ +│ ├─ Each role agent produces analysis.md + sub-documents │ +│ └─ discoveries.ndjson shared across role agents │ +│ │ +│ Phase 4: Synthesis Integration │ +│ ├─ Read all role analyses (read-only) │ +│ ├─ Cross-role analysis → conflict detection │ +│ ├─ Feature spec generation │ +│ └─ Output: feature-specs/ + feature-index.json │ +│ │ +│ ═══ Single Role Mode ═══ │ +│ │ +│ Phase 3S: Single Role Analysis (spawn_agent) │ +│ ├─ spawn_agent(conceptual-planning-agent) │ +│ └─ Output: {role}/analysis*.md │ +│ │ +└──────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Context Flow + +``` +roles.csv feature-specs/ +┌──────────────┐ ┌──────────────────┐ +│ R1: sys-arch │──findings───→│ F-001-auth.md │ +│ analysis.md │ │ (cross-role spec) │ +├──────────────┤ ├──────────────────┤ +│ R2: ui-design│──findings───→│ F-002-ui.md │ +│ analysis.md │ │ (cross-role spec) │ +├──────────────┤ ├──────────────────┤ +│ R3: test-str │──findings───→│ F-003-test.md │ +│ analysis.md │ │ (cross-role spec) │ +└──────────────┘ └──────────────────┘ + +Two context channels: +1. Directed: role findings → synthesis → feature specs +2. Broadcast: discoveries.ndjson (append-only shared board) +``` + +--- + +## CSV Schema + +### roles.csv + +```csv +id,role,title,focus,deps,wave,status,findings,output_files,error +"R1","system-architect","系统架构师","Technical architecture, scalability","","1","pending","","","" +"R2","ui-designer","UI设计师","Visual design, mockups","","1","pending","","","" +"R3","test-strategist","测试策略师","Test strategy, quality","","1","pending","","","" +``` + +**Columns**: + +| Column | Phase | Description | +|--------|-------|-------------| +| `id` | Input | Role ID: R1, R2, ... | +| `role` | Input | Role identifier (e.g., system-architect) | +| `title` | Input | Role display title | +| `focus` | Input | Role focus areas and keywords | +| `deps` | Input | Dependency IDs (usually empty — all wave 1) | +| `wave` | Computed | Wave number (usually 1 for all roles) | +| `status` | Output | `pending` → `completed` / `failed` | +| `findings` | Output | Key discoveries (max 800 chars) | +| `output_files` | Output | Generated analysis files (semicolon-separated) | +| `error` | Output | Error message if failed | + +--- + +## Available Roles + +| Role ID | Title | Focus Area | +|---------|-------|------------| +| `data-architect` | 数据架构师 | Data models, storage strategies, data flow | +| `product-manager` | 产品经理 | Product strategy, roadmap, prioritization | +| `product-owner` | 产品负责人 | Backlog management, user stories, acceptance criteria | +| `scrum-master` | 敏捷教练 | Process facilitation, impediment removal | +| `subject-matter-expert` | 领域专家 | Domain knowledge, business rules, compliance | +| `system-architect` | 系统架构师 | Technical architecture, scalability, integration | +| `test-strategist` | 测试策略师 | Test strategy, quality assurance | +| `ui-designer` | UI设计师 | Visual design, mockups, design systems | +| `ux-expert` | UX专家 | User research, information architecture, journey | + +--- + +## Session Structure + +``` +.workflow/active/WFS-{topic}/ +├── workflow-session.json # Session metadata +├── .process/ +│ └── context-package.json # Phase 0 context +├── roles.csv # Role analysis state (Phase 2-3) +├── discoveries.ndjson # Shared discovery board +└── .brainstorming/ + ├── guidance-specification.md # Framework (Phase 2) + ├── feature-index.json # Feature index (Phase 4) + ├── synthesis-changelog.md # Synthesis audit trail (Phase 4) + ├── feature-specs/ # Feature specs (Phase 4) + │ ├── F-001-{slug}.md + │ └── F-00N-{slug}.md + └── {role}/ # Role analyses (Phase 3, immutable) + ├── {role}-context.md # Interactive Q&A + ├── analysis.md # Main/index document + ├── analysis-cross-cutting.md # Cross-feature + └── analysis-F-{id}-{slug}.md # Per-feature +``` + +--- + +## Implementation + +### Session Initialization + +```javascript +const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() + +// Parse flags +const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') +const countMatch = $ARGUMENTS.match(/--count\s+(\d+)/) +const roleCount = countMatch ? Math.min(parseInt(countMatch[1]), 9) : 3 +const sessionMatch = $ARGUMENTS.match(/--session\s+(\S+)/) +const existingSessionId = sessionMatch ? sessionMatch[1] : null +const skipQuestions = $ARGUMENTS.includes('--skip-questions') +const includeQuestions = $ARGUMENTS.includes('--include-questions') +const styleSkillMatch = $ARGUMENTS.match(/--style-skill\s+(\S+)/) +const styleSkill = styleSkillMatch ? styleSkillMatch[1] : null +const updateMode = $ARGUMENTS.includes('--update') + +// Role detection +const VALID_ROLES = [ + 'data-architect', 'product-manager', 'product-owner', 'scrum-master', + 'subject-matter-expert', 'system-architect', 'test-strategist', + 'ui-designer', 'ux-expert' +] +const cleanArgs = $ARGUMENTS + .replace(/--yes|-y|--count\s+\d+|--session\s+\S+|--skip-questions|--include-questions|--style-skill\s+\S+|--update/g, '') + .trim() +const firstArg = cleanArgs.split(/\s+/)[0] +const isRole = VALID_ROLES.includes(firstArg) + +// Mode detection +let executionMode +if (AUTO_YES) { + executionMode = 'auto' +} else if (isRole) { + executionMode = 'single-role' +} else if (cleanArgs) { + executionMode = 'auto' +} else { + executionMode = null // Ask user +} + +const topic = isRole + ? cleanArgs.replace(firstArg, '').trim() + : cleanArgs.replace(/^["']|["']$/g, '') +``` + +--- + +### Phase 1: Mode Detection & Routing + +**Objective**: Parse arguments, determine execution mode, prepare session. + +**Steps**: + +1. **Detect Mode** + + ```javascript + if (executionMode === null) { + const modeAnswer = AskUserQuestion({ + questions: [{ + question: "Choose brainstorming mode:", + header: "Mode", + multiSelect: false, + options: [ + { label: "Auto Mode (Recommended)", description: "Full pipeline: framework → parallel roles → synthesis" }, + { label: "Single Role", description: "Run one role analysis independently" } + ] + }] + }) + executionMode = modeAnswer.Mode.startsWith('Auto') ? 'auto' : 'single-role' + } + ``` + +2. **Session Setup** + + ```javascript + let sessionId, sessionFolder + + if (existingSessionId) { + sessionId = existingSessionId + sessionFolder = `.workflow/active/${sessionId}` + } else if (executionMode === 'auto') { + const slug = topic.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-').substring(0, 40) + sessionId = `WFS-${slug}` + sessionFolder = `.workflow/active/${sessionId}` + Bash(`mkdir -p "${sessionFolder}/.brainstorming" "${sessionFolder}/.process"`) + + // Initialize workflow-session.json + Write(`${sessionFolder}/workflow-session.json`, JSON.stringify({ + session_id: sessionId, + topic: topic, + status: 'brainstorming', + execution_mode: executionMode, + created_at: getUtc8ISOString() + }, null, 2)) + } else { + // Single role mode requires existing session + const existing = Bash(`ls -d .workflow/active/WFS-* 2>/dev/null | head -1`).trim() + if (!existing) { + console.log('ERROR: No active session found. Run auto mode first to create a session.') + return + } + sessionId = existing.split('/').pop() + sessionFolder = existing + } + ``` + +**Route**: +- `executionMode === 'auto'` → Phase 2 +- `executionMode === 'single-role'` → Phase 3S + +--- + +### Phase 2: Interactive Framework Generation (Auto Mode) + +**Objective**: Analyze topic, select roles, generate guidance-specification.md and roles.csv. + +**Steps**: + +1. **Analyze Topic & Select Roles** + + ```javascript + Bash({ + command: `ccw cli -p "PURPOSE: Analyze brainstorming topic and recommend ${roleCount} expert roles for multi-perspective analysis. Success = well-matched roles with clear focus areas. +TASK: + • Analyze topic domain, complexity, and key dimensions + • Select ${roleCount} roles from: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert + • For each role: define focus area, key questions, and analysis scope + • Identify potential cross-role conflicts or synergies + • Generate feature decomposition if topic has distinct components +MODE: analysis +CONTEXT: @**/* +EXPECTED: JSON: {analysis: {domain, complexity, dimensions[]}, roles: [{id, role, title, focus, key_questions[]}], features: [{id, title, description}]} +CONSTRAINTS: Select exactly ${roleCount} roles | Each role must have distinct perspective | Roles must cover topic comprehensively + +TOPIC: ${topic}" --tool gemini --mode analysis --rule planning-breakdown-task-steps`, + run_in_background: true + }) + // Wait for CLI completion → { analysis, roles[], features[] } + ``` + +2. **User Validation** (skip if AUTO_YES) + + ```javascript + if (!AUTO_YES) { + console.log(`\n## Brainstorm Framework\n`) + console.log(`Topic: ${topic}`) + console.log(`Domain: ${analysis.domain} | Complexity: ${analysis.complexity}`) + console.log(`\nSelected Roles (${roles.length}):`) + roles.forEach(r => console.log(` - [${r.id}] ${r.title}: ${r.focus}`)) + if (features.length > 0) { + console.log(`\nFeatures (${features.length}):`) + features.forEach(f => console.log(` - [${f.id}] ${f.title}`)) + } + + const answer = AskUserQuestion({ + questions: [{ + question: "Approve brainstorm framework?", + header: "Validate", + multiSelect: false, + options: [ + { label: "Approve", description: "Proceed with role analysis" }, + { label: "Modify Roles", description: "Change role selection" }, + { label: "Cancel", description: "Abort" } + ] + }] + }) + + if (answer.Validate === "Cancel") return + if (answer.Validate === "Modify Roles") { + // Allow user to adjust via AskUserQuestion + const roleAnswer = AskUserQuestion({ + questions: [{ + question: "Select roles for analysis:", + header: "Roles", + multiSelect: true, + options: VALID_ROLES.map(r => ({ + label: r, + description: roles.find(sel => sel.role === r)?.focus || '' + })) + }] + }) + // Rebuild roles[] from selection + } + } + ``` + +3. **Generate Guidance Specification** + + ```javascript + const guidanceContent = `# Guidance Specification + +## Topic +${topic} + +## Analysis +- **Domain**: ${analysis.domain} +- **Complexity**: ${analysis.complexity} +- **Dimensions**: ${analysis.dimensions.join(', ')} + +## Selected Roles +${roles.map(r => `### ${r.title} (${r.role}) +- **Focus**: ${r.focus} +- **Key Questions**: ${r.key_questions.join('; ')}`).join('\n\n')} + +## Features +${features.map(f => `- **[${f.id}] ${f.title}**: ${f.description}`).join('\n')} +` + Write(`${sessionFolder}/.brainstorming/guidance-specification.md`, guidanceContent) + ``` + +4. **Generate roles.csv** + + ```javascript + const header = 'id,role,title,focus,deps,wave,status,findings,output_files,error' + const rows = roles.map(r => + [r.id, r.role, r.title, r.focus, '', '1', 'pending', '', '', ''] + .map(v => `"${String(v).replace(/"/g, '""')}"`) + .join(',') + ) + Write(`${sessionFolder}/roles.csv`, [header, ...rows].join('\n')) + ``` + + Update workflow-session.json with selected_roles. + +--- + +### Phase 3: Wave Role Analysis (spawn_agents_on_csv) — Auto Mode + +**Objective**: Execute parallel role analysis via `spawn_agents_on_csv`. Each role agent produces analysis documents. + +**Steps**: + +1. **Role Analysis Wave** + + ```javascript + const rolesCSV = parseCsv(Read(`${sessionFolder}/roles.csv`)) + + console.log(`\n## Phase 3: Parallel Role Analysis (${rolesCSV.length} roles)\n`) + + spawn_agents_on_csv({ + csv_path: `${sessionFolder}/roles.csv`, + id_column: "id", + instruction: buildRoleInstruction(sessionFolder, topic, features), + max_concurrency: Math.min(rolesCSV.length, 4), + max_runtime_seconds: 600, + output_csv_path: `${sessionFolder}/roles-results.csv`, + output_schema: { + type: "object", + properties: { + id: { type: "string" }, + status: { type: "string", enum: ["completed", "failed"] }, + findings: { type: "string" }, + output_files: { type: "array", items: { type: "string" } }, + error: { type: "string" } + }, + required: ["id", "status", "findings"] + } + }) + + // Merge results into roles.csv + const roleResults = parseCsv(Read(`${sessionFolder}/roles-results.csv`)) + for (const result of roleResults) { + updateMasterCsvRow(`${sessionFolder}/roles.csv`, result.id, { + status: result.status, + findings: result.findings || '', + output_files: Array.isArray(result.output_files) ? result.output_files.join(';') : (result.output_files || ''), + error: result.error || '' + }) + console.log(` [${result.id}] ${result.status === 'completed' ? '✓' : '✗'} ${rolesCSV.find(r => r.id === result.id)?.role}`) + } + + Bash(`rm -f "${sessionFolder}/roles-results.csv"`) + ``` + +2. **Role Instruction Template** + + ```javascript + function buildRoleInstruction(sessionFolder, topic, features) { + const featureList = features.length > 0 + ? features.map(f => `- [${f.id}] ${f.title}: ${f.description}`).join('\n') + : 'No feature decomposition — analyze topic holistically.' + + return ` +## ROLE ANALYSIS ASSIGNMENT + +### MANDATORY FIRST STEPS +1. Read guidance specification: ${sessionFolder}/.brainstorming/guidance-specification.md +2. Read shared discoveries: ${sessionFolder}/discoveries.ndjson (if exists) +3. Read project context: .workflow/project-tech.json (if exists) + +--- + +## Your Role + +**Role ID**: {id} +**Role**: {role} +**Title**: {title} +**Focus**: {focus} + +--- + +## Topic +${topic} + +## Features to Analyze +${featureList} + +--- + +## Analysis Protocol + +1. **Read guidance**: Load guidance-specification.md for full context +2. **Read discoveries**: Load discoveries.ndjson for shared findings from other roles +3. **Analyze from your perspective**: Apply your role expertise to the topic +4. **Per-feature analysis** (if features exist): + - Create \`${sessionFolder}/.brainstorming/{role}/analysis-{feature-id}-{slug}.md\` per feature + - Create \`${sessionFolder}/.brainstorming/{role}/analysis-cross-cutting.md\` for cross-feature concerns +5. **Create index document**: \`${sessionFolder}/.brainstorming/{role}/analysis.md\` + - Summary of all findings + - Links to sub-documents + - Key recommendations +6. **Share discoveries**: Append findings to shared board: + \`\`\`bash + echo '{"ts":"","worker":"{id}","type":"","data":{...}}' >> ${sessionFolder}/discoveries.ndjson + \`\`\` +7. **Report result**: Return JSON via report_agent_job_result + +### Document Constraints +- Main analysis.md: < 3000 words +- Sub-documents: < 2000 words each, max 5 +- Total per role: < 15000 words + +### Discovery Types to Share +- \`design_pattern\`: {name, rationale, applicability} — recommended patterns +- \`risk\`: {area, severity, mitigation} — identified risks +- \`requirement\`: {title, priority, source} — derived requirements +- \`constraint\`: {type, description, impact} — discovered constraints +- \`synergy\`: {roles[], area, description} — cross-role opportunities + +--- + +## Output (report_agent_job_result) + +Return JSON: +{ + "id": "{id}", + "status": "completed" | "failed", + "findings": "Key insights from {role} perspective (max 800 chars)", + "output_files": ["path/to/analysis.md", "path/to/analysis-F-001.md"], + "error": "" +} +` + } + ``` + +--- + +### Phase 3S: Single Role Analysis (spawn_agent) — Single Role Mode + +**Objective**: Run one role analysis via spawn_agent with optional interactive Q&A. + +```javascript +if (executionMode === 'single-role') { + const roleName = firstArg + const roleDir = `${sessionFolder}/.brainstorming/${roleName}` + Bash(`mkdir -p "${roleDir}"`) + + const agentId = spawn_agent({ + agent: `~/.codex/agents/conceptual-planning-agent.md`, + instruction: ` +Perform a ${roleName} analysis for the brainstorming session. + +**Session**: ${sessionFolder} +**Role**: ${roleName} +**Topic**: Read from ${sessionFolder}/.brainstorming/guidance-specification.md +${includeQuestions ? '**Mode**: Interactive — ask clarification questions before analysis' : ''} +${skipQuestions ? '**Mode**: Skip questions — proceed directly to analysis' : ''} +${styleSkill ? `**Style Skill**: ${styleSkill} — load .claude/skills/style-${styleSkill}/ for design reference` : ''} +${updateMode ? '**Update Mode**: Read existing analysis and enhance/update it' : ''} + +**Output**: Create analysis documents in ${roleDir}/ +- ${roleDir}/analysis.md (main index) +- ${roleDir}/analysis-*.md (sub-documents as needed) + +Follow the same analysis protocol as wave role analysis but with interactive refinement. +` + }) + + wait({ id: agentId }) + close_agent({ id: agentId }) + + console.log(`\n✓ ${roleName} analysis complete: ${roleDir}/analysis.md`) +} +``` + +--- + +### Phase 4: Synthesis Integration (Auto Mode) + +**Objective**: Read all role analyses, cross-reference, generate feature specs. + +**Steps**: + +1. **Collect Role Findings** + + ```javascript + const rolesCSV = parseCsv(Read(`${sessionFolder}/roles.csv`)) + const completedRoles = rolesCSV.filter(r => r.status === 'completed') + + // Read all analysis.md index files (optimized: skip sub-docs for token efficiency) + const roleAnalyses = {} + for (const role of completedRoles) { + const indexPath = `${sessionFolder}/.brainstorming/${role.role}/analysis.md` + const content = Read(indexPath) + if (content) roleAnalyses[role.role] = content + } + + // Read discoveries + const discoveriesPath = `${sessionFolder}/discoveries.ndjson` + const discoveries = Read(discoveriesPath) || '' + ``` + +2. **Synthesis via Agent** + + ```javascript + const synthesisAgent = spawn_agent({ + agent: `~/.codex/agents/conceptual-planning-agent.md`, + instruction: ` +## SYNTHESIS ASSIGNMENT + +Synthesize ${completedRoles.length} role analyses into unified feature specifications. + +**Session**: ${sessionFolder} +**Role Analyses**: ${completedRoles.map(r => `${sessionFolder}/.brainstorming/${r.role}/analysis.md`).join(', ')} +**Discoveries**: ${discoveriesPath} + +### Synthesis Protocol + +1. **Read all role analyses** (analysis.md files only — these are index documents) +2. **Cross-reference findings**: Identify agreements, conflicts, and unique insights +3. **Generate feature specs**: For each feature in guidance-specification.md: + - Create ${sessionFolder}/.brainstorming/feature-specs/F-{id}-{slug}.md + - Consolidate perspectives from all relevant roles + - Note conflicts and recommended resolutions +4. **Generate feature index**: ${sessionFolder}/.brainstorming/feature-index.json + - Array of {id, title, slug, roles_contributing[], conflict_count, priority} +5. **Generate changelog**: ${sessionFolder}/.brainstorming/synthesis-changelog.md + - Decisions made, conflicts resolved, trade-offs accepted + +### Complexity Assessment +Evaluate complexity score (0-8): +- Feature count (≤2: 0, 3-4: 1, ≥5: 2) +- Unresolved conflicts (0: 0, 1-2: 1, ≥3: 2) +- Participating roles (≤2: 0, 3-4: 1, ≥5: 2) +- Cross-feature dependencies (0: 0, 1-2: 1, ≥3: 2) + +### Output Files +- feature-specs/F-{id}-{slug}.md (one per feature) +- feature-index.json +- synthesis-changelog.md +` + }) + + wait({ id: synthesisAgent }) + close_agent({ id: synthesisAgent }) + ``` + +3. **Completion Summary** + + ```javascript + const featureIndex = JSON.parse(Read(`${sessionFolder}/.brainstorming/feature-index.json`) || '[]') + + console.log(` +## Brainstorm Complete + +Session: ${sessionId} +Roles analyzed: ${completedRoles.length} +Features synthesized: ${featureIndex.length} + +### Feature Specs +${featureIndex.map(f => ` - [${f.id}] ${f.title} (${f.roles_contributing?.length || 0} roles, ${f.conflict_count || 0} conflicts)`).join('\n')} + +### Next Steps +- /workflow-plan --session ${sessionId} → Generate implementation plan +- Review: ${sessionFolder}/.brainstorming/feature-specs/ + `) + ``` + +--- + +## Utility Functions + +### CSV Parser + +```javascript +function parseCsv(content) { + const lines = content.trim().split('\n') + if (lines.length < 2) return [] + const headers = parseCSVLine(lines[0]) + return lines.slice(1).map(line => { + const values = parseCSVLine(line) + const row = {} + headers.forEach((h, i) => row[h] = values[i] || '') + return row + }) +} +``` + +### CSV Row Updater + +```javascript +function updateMasterCsvRow(csvPath, id, updates) { + const content = Read(csvPath) + const lines = content.trim().split('\n') + const headers = parseCSVLine(lines[0]) + const idIdx = headers.indexOf('id') + + for (let i = 1; i < lines.length; i++) { + const values = parseCSVLine(lines[i]) + if (values[idIdx]?.replace(/"/g, '') === id) { + Object.entries(updates).forEach(([key, val]) => { + const idx = headers.indexOf(key) + if (idx >= 0) values[idx] = `"${String(val).replace(/"/g, '""')}"` + }) + lines[i] = values.join(',') + break + } + } + Write(csvPath, lines.join('\n')) +} +``` + +--- + +## Error Handling + +| Error | Recovery | +|-------|----------| +| Invalid role name | Show valid roles list, prompt again | +| No active session (single role) | Guide user to run auto mode first | +| Role agent failure | Mark failed in roles.csv, continue with remaining | +| Synthesis overflow (>100KB) | Read only analysis.md index files | +| Context compression | Re-read guidance-specification.md and roles.csv | + +--- + +## Compact Protection + +> **COMPACT DIRECTIVE**: If context compression occurs mid-execution, re-read the current phase's state: +> - Phase 2: Re-read `guidance-specification.md` +> - Phase 3: Re-read `roles.csv` for progress state +> - Phase 4: Re-read `feature-index.json` and `roles.csv` diff --git a/.codex/skills/roadmap-with-file/SKILL.md b/.codex/skills/roadmap-with-file/SKILL.md index cb90d376..7b22ee73 100644 --- a/.codex/skills/roadmap-with-file/SKILL.md +++ b/.codex/skills/roadmap-with-file/SKILL.md @@ -831,14 +831,14 @@ ${selectedMode === 'progressive' ? `**Progressive Mode**: case 'done': // Output paths and end - console.log(` -Roadmap saved: ${sessionFolder}/roadmap.md -Issues created: ${issueIds.length} - -To execute later: - $team-planex ${issueIds.slice(0, 3).join(' ')}... - ccw issue list --session ${sessionId} -`) + console.log([ + `Roadmap saved: ${sessionFolder}/roadmap.md`, + `Issues created: ${issueIds.length}`, + '', + 'To execute later:', + ` $team-planex ${issueIds.slice(0, 3).join(' ')}...`, + ` ccw issue list --session ${sessionId}` + ].join('\n')) break } ``` @@ -897,3 +897,7 @@ To execute later: | Collaborative multi-agent planning | `$collaborative-plan-with-file` | | Full specification documents | `$spec-generator` | | Code implementation from existing plan | `$workflow-lite-planex` | + +--- + +**Now execute roadmap-with-file for**: $ARGUMENTS diff --git a/.codex/skills/workflow-execute/SKILL.md b/.codex/skills/workflow-execute/SKILL.md new file mode 100644 index 00000000..f641088f --- /dev/null +++ b/.codex/skills/workflow-execute/SKILL.md @@ -0,0 +1,1114 @@ +--- +name: workflow-execute +description: | + Autonomous workflow execution pipeline with CSV wave engine. + Session discovery → plan validation → IMPL-*.json → CSV conversion → + wave execution via spawn_agents_on_csv → results sync. + Task JSONs remain the rich data source; CSV is brief + execution state. +argument-hint: "[-y|--yes] [-c|--concurrency N] [--resume-session=ID] [--with-commit]" +allowed-tools: spawn_agents_on_csv, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep +--- + +## Auto Mode + +When `--yes` or `-y`: Auto-select first session, auto-complete session after all tasks, skip all confirmations. + +# Workflow Execute + +## Usage + +```bash +$workflow-execute +$workflow-execute --yes +$workflow-execute --resume-session=WFS-auth +$workflow-execute -y --with-commit +$workflow-execute -y -c 4 --with-commit +$workflow-execute -y --with-commit --resume-session=WFS-auth +``` + +**Flags**: +- `-y, --yes`: Skip all confirmations (auto mode) +- `-c, --concurrency N`: Max concurrent agents per wave (default: 4) +- `--resume-session=ID`: Resume specific session (skip Phase 1-2) +- `--with-commit`: Auto-commit after each task completion + +--- + +## Overview + +Autonomous execution pipeline using `spawn_agents_on_csv` wave engine. Converts planning artifacts (IMPL-*.json + plan.json) into CSV for wave-based parallel execution, with full task JSON available via `task_json_path` column. + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ WORKFLOW EXECUTE PIPELINE │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ Phase 1: Session Discovery │ +│ ├─ Find active sessions │ +│ ├─ Auto-select (1 session) or prompt (multiple) │ +│ └─ Load session metadata │ +│ │ +│ Phase 2: Planning Document Validation │ +│ ├─ Verify IMPL_PLAN.md exists │ +│ ├─ Verify TODO_LIST.md exists │ +│ └─ Verify .task/ contains IMPL-*.json │ +│ │ +│ Phase 3: JSON → CSV Conversion │ +│ ├─ Read all IMPL-*.json + plan.json │ +│ ├─ Skip already-completed tasks (resume support) │ +│ ├─ Compute waves via Kahn's BFS (deps + plan hints) │ +│ ├─ Generate tasks.csv (21 cols) + context.csv │ +│ └─ Initialize discoveries.ndjson │ +│ │ +│ Phase 4: Wave Execute (spawn_agents_on_csv) │ +│ ├─ Per wave: build prev_context → wave-{N}.csv │ +│ ├─ spawn_agents_on_csv with execute instruction │ +│ ├─ Merge results → tasks.csv + task JSON status │ +│ ├─ Auto-commit per task (if --with-commit) │ +│ └─ Cleanup temp wave CSVs │ +│ │ +│ Phase 5: Results Sync │ +│ ├─ Export results.csv │ +│ ├─ Reconcile TODO_LIST.md with tasks.csv status │ +│ └─ User choice: Review | Complete Session │ +│ │ +│ Phase 6: Post-Implementation Review (Optional) │ +│ ├─ Select review type (quality/security/architecture) │ +│ ├─ CLI-assisted analysis │ +│ └─ Generate REVIEW-{type}.md │ +│ │ +│ Resume Mode (--resume-session): │ +│ └─ Skip Phase 1-2 → enter Phase 3 (skip completed tasks) │ +│ │ +└──────────────────────────────────────────────────────────────────┘ +``` + +--- + +## CSV Schemas + +### tasks.csv (21 columns) + +```csv +id,title,description,agent,scope,deps,execution_group,context_from,wave,task_json_path,hints,execution_directives,acceptance_criteria,prev_context,status,findings,files_modified,tests_passed,acceptance_met,summary_path,error +``` + +| Column | Phase | Source | Description | +|--------|-------|--------|-------------| +| `id` | Input | task.id | IMPL-001 etc | +| `title` | Input | task.title | Short title | +| `description` | Input | task.description | Full description | +| `agent` | Input | meta.agent or inferred | @code-developer etc | +| `scope` | Input | task.scope / focus_paths | File scope glob | +| `deps` | Input | depends_on.join(';') | Dependency IDs (semicolon-separated) | +| `execution_group` | Input | meta.execution_group | Parallel group identifier | +| `context_from` | Computed | deps + completed predecessors | Context source IDs | +| `wave` | Computed | Kahn's BFS | Wave number (1-based) | +| `task_json_path` | Input | relative path | `.task/IMPL-001.json` (agent reads full JSON) | +| `hints` | Input | artifacts + pre_analysis refs | `tips \|\| file1;file2` | +| `execution_directives` | Input | convergence.verification | Verification commands | +| `acceptance_criteria` | Input | convergence.criteria.join | Acceptance conditions | +| `prev_context` | Computed(per-wave) | context_from findings lookup | Predecessor task findings | +| `status` | Output | agent result | pending→completed/failed/skipped | +| `findings` | Output | agent result | Key findings (max 500 chars) | +| `files_modified` | Output | agent result | Modified files (semicolon-separated) | +| `tests_passed` | Output | agent result | true/false | +| `acceptance_met` | Output | agent result | Acceptance status | +| `summary_path` | Output | generated | .summaries/IMPL-X-summary.md | +| `error` | Output | agent result | Error message | + +**Key design**: `task_json_path` lets agents read the full task JSON (with pre_analysis, flow_control, convergence etc). CSV is "brief + execution state". + +### context.csv (4 columns) + +```csv +key,type,value,source +"tech_stack","array","TypeScript;React 18;Zustand","plan.json" +"conventions","array","Use useIntl;Barrel exports","plan.json" +"context_package_path","path",".process/context-package.json","session" +"discoveries_path","path","discoveries.ndjson","session" +``` + +Injected into instruction template as static context — avoids each agent rediscovering project basics. + +--- + +## Session Structure + +``` +.workflow/active/WFS-{session}/ +├── workflow-session.json # Session state +├── plan.json # Structured plan (machine-readable) +├── IMPL_PLAN.md # Implementation plan (human-readable) +├── TODO_LIST.md # Progress tracking (Phase 5 sync) +├── tasks.csv # Phase 3 generated, Phase 4 updated +├── context.csv # Phase 3 generated +├── results.csv # Phase 5 exported +├── discoveries.ndjson # Phase 3 initialized, Phase 4 agents append +├── .task/ # Task definitions (unchanged) +│ ├── IMPL-1.json +│ └── IMPL-N.json +├── .summaries/ # Agent-generated summaries +│ ├── IMPL-1-summary.md +│ └── IMPL-N-summary.md +├── .process/context-package.json# Unchanged +└── wave-{N}.csv # Phase 4 temporary (cleaned after each wave) +``` + +--- + +## Implementation + +### Session Initialization + +```javascript +const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() + +// Parse flags +const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') +const withCommit = $ARGUMENTS.includes('--with-commit') +const resumeMatch = $ARGUMENTS.match(/--resume-session[=\s]+(\S+)/) +const resumeSessionId = resumeMatch ? resumeMatch[1] : null +const isResumeMode = !!resumeSessionId +const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/) +const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 4 +``` + +--- + +### Phase 1: Session Discovery + +**Applies to**: Normal mode only (skipped if `--resume-session`). + +```javascript +let sessionId, sessionFolder + +if (isResumeMode) { + sessionId = resumeSessionId + sessionFolder = `.workflow/active/${sessionId}` + // Skip to Phase 3 +} else { + const sessions = Bash(`ls -d .workflow/active/WFS-* 2>/dev/null`).trim().split('\n').filter(Boolean) + + if (sessions.length === 0) { + console.log('ERROR: No active workflow sessions found.') + console.log('Run $workflow-plan "task description" to create a session.') + return + } + + if (sessions.length === 1) { + sessionFolder = sessions[0] + sessionId = sessionFolder.split('/').pop() + console.log(`Auto-selected session: ${sessionId}`) + } else { + if (AUTO_YES) { + sessionFolder = sessions[0] + sessionId = sessionFolder.split('/').pop() + console.log(`[--yes] Auto-selected: ${sessionId}`) + } else { + const sessionInfos = sessions.slice(0, 4).map(s => { + const id = s.split('/').pop() + const total = parseInt(Bash(`grep -c '^- \\[' "${s}/TODO_LIST.md" 2>/dev/null || echo 0`).trim()) || 0 + const done = parseInt(Bash(`grep -c '^- \\[x\\]' "${s}/TODO_LIST.md" 2>/dev/null || echo 0`).trim()) || 0 + return { id, path: s, progress: `${done}/${total} tasks` } + }) + + const answer = AskUserQuestion({ + questions: [{ + question: "Select session to execute:", + header: "Session", + multiSelect: false, + options: sessionInfos.map(s => ({ + label: s.id, + description: s.progress + })) + }] + }) + sessionId = answer.Session + sessionFolder = `.workflow/active/${sessionId}` + } + } +} +``` + +--- + +### Phase 2: Planning Document Validation + +**Applies to**: Normal mode only. + +```javascript +if (!isResumeMode) { + const checks = { + 'IMPL_PLAN.md': Bash(`test -f "${sessionFolder}/IMPL_PLAN.md" && echo yes`).trim() === 'yes', + 'TODO_LIST.md': Bash(`test -f "${sessionFolder}/TODO_LIST.md" && echo yes`).trim() === 'yes', + '.task/ has files': parseInt(Bash(`ls ${sessionFolder}/.task/IMPL-*.json 2>/dev/null | wc -l`).trim()) > 0 + } + + const missing = Object.entries(checks).filter(([_, ok]) => !ok).map(([name]) => name) + if (missing.length > 0) { + console.log(`ERROR: Missing planning documents: ${missing.join(', ')}`) + console.log(`Run $workflow-plan --session ${sessionId} to generate plan.`) + return + } + + console.log(`Planning documents validated.`) +} +``` + +--- + +### Phase 3: JSON → CSV Conversion + +**Applies to**: Both normal and resume modes (resume entry point). + +**Objective**: Convert IMPL-*.json + plan.json into tasks.csv + context.csv with computed waves. + +```javascript +console.log(`\n## Phase 3: JSON → CSV Conversion\n`) + +// Update session status to active +Bash(`cd "${sessionFolder}" && jq '.status = "active" | .execution_started_at = (.execution_started_at // "'"$(date -Iseconds)"'")' workflow-session.json > tmp.json && mv tmp.json workflow-session.json 2>/dev/null || true`) +Bash(`mkdir -p "${sessionFolder}/.summaries"`) + +// 3.1: Read all IMPL-*.json +const taskFiles = Bash(`ls ${sessionFolder}/.task/IMPL-*.json 2>/dev/null`).trim().split('\n').filter(Boolean) +if (taskFiles.length === 0) { + console.log('ERROR: No task JSONs found in .task/') + return +} + +const taskJsons = taskFiles.map(f => { + const content = Read(f) + const json = JSON.parse(content) + json._filePath = f + return json +}) + +// 3.2: Skip completed tasks (resume support) +const todoContent = Read(`${sessionFolder}/TODO_LIST.md`) +const completedIds = new Set() +const todoLines = todoContent.match(/^- \[x\] (IMPL-\d+(?:\.\d+)?)/gm) || [] +todoLines.forEach(line => { + const match = line.match(/IMPL-\d+(?:\.\d+)?/) + if (match) completedIds.add(match[0]) +}) + +// Also check task JSON status field +taskJsons.forEach(tj => { + if (tj.status === 'completed') completedIds.add(tj.id) +}) + +const pendingJsons = taskJsons.filter(tj => !completedIds.has(tj.id)) + +console.log(` Total tasks: ${taskJsons.length}`) +console.log(` Already completed: ${completedIds.size}`) +console.log(` Pending: ${pendingJsons.length}`) + +if (pendingJsons.length === 0) { + console.log(`\nAll tasks already completed. Proceeding to Phase 5.`) + // → Jump to Phase 5 +} + +// 3.3: Read plan.json for execution hints +const planJsonPath = `${sessionFolder}/plan.json` +const planJsonExists = Bash(`test -f "${planJsonPath}" && echo yes`).trim() === 'yes' +const planJson = planJsonExists ? JSON.parse(Read(planJsonPath) || '{}') : {} + +// 3.4: Extract fields from task JSONs (handles two schema variants) +function resolveAgent(tj) { + if (tj.meta?.agent) return tj.meta.agent + const typeMap = { + 'feature': 'code-developer', + 'test-gen': 'code-developer', + 'test-fix': 'test-fix-agent', + 'review': 'universal-executor', + 'docs': 'doc-generator' + } + return typeMap[tj.meta?.type] || 'code-developer' +} + +function extractDeps(tj) { + return tj.depends_on || tj.context?.depends_on || [] +} + +function buildHints(tj) { + const tips = [] + const files = [] + // Gather artifact references + if (tj.artifacts) { + tj.artifacts.forEach(a => { if (a.path) files.push(a.path) }) + } + // Gather pre_analysis Read references + if (tj.pre_analysis) { + tj.pre_analysis.forEach(step => { + if (step.tool === 'Read' && step.path) files.push(step.path) + }) + } + // Gather tips from meta or context + if (tj.meta?.hints) tips.push(tj.meta.hints) + if (tj.context?.tips) tips.push(tj.context.tips) + + const tipsStr = tips.join('; ') + const filesStr = files.join(';') + if (tipsStr && filesStr) return `${tipsStr} || ${filesStr}` + if (tipsStr) return tipsStr + if (filesStr) return `|| ${filesStr}` + return '' +} + +function extractDirectives(tj) { + if (tj.convergence?.verification) { + return Array.isArray(tj.convergence.verification) + ? tj.convergence.verification.join('; ') + : tj.convergence.verification + } + if (tj.execution_config?.verification_command) return tj.execution_config.verification_command + return '' +} + +function extractAcceptance(tj) { + if (tj.convergence?.criteria) { + return Array.isArray(tj.convergence.criteria) + ? tj.convergence.criteria.join('; ') + : tj.convergence.criteria + } + if (tj.context?.acceptance) { + return Array.isArray(tj.context.acceptance) + ? tj.context.acceptance.join('; ') + : tj.context.acceptance + } + return '' +} + +function extractScope(tj) { + if (tj.scope) return tj.scope + if (tj.focus_paths) { + return Array.isArray(tj.focus_paths) ? tj.focus_paths.join(';') : tj.focus_paths + } + return '' +} + +// Build task rows (all tasks — completed ones carry status forward) +const taskRows = taskJsons.map(tj => ({ + id: tj.id, + title: tj.title || '', + description: tj.description || '', + agent: resolveAgent(tj), + scope: extractScope(tj), + deps: extractDeps(tj).join(';'), + execution_group: tj.meta?.execution_group || '', + context_from: '', // computed after wave assignment + task_json_path: `.task/${tj.id}.json`, + hints: buildHints(tj), + execution_directives: extractDirectives(tj), + acceptance_criteria: extractAcceptance(tj), + prev_context: '', // computed per-wave in Phase 4 + status: completedIds.has(tj.id) ? 'completed' : 'pending', + findings: '', + files_modified: '', + tests_passed: '', + acceptance_met: '', + summary_path: `.summaries/${tj.id}-summary.md`, + error: '' +})) + +// 3.5: Compute waves via Kahn's BFS with plan.json hints +function computeWaves(rows, planJson) { + const taskMap = new Map(rows.map(r => [r.id, r])) + const inDegree = new Map(rows.map(r => [r.id, 0])) + const adjList = new Map(rows.map(r => [r.id, []])) + + for (const row of rows) { + const deps = row.deps.split(';').filter(Boolean) + for (const dep of deps) { + if (taskMap.has(dep)) { + adjList.get(dep).push(row.id) + inDegree.set(row.id, inDegree.get(row.id) + 1) + } + } + } + + // BFS + const queue = [] + const waveMap = new Map() + + for (const [id, deg] of inDegree) { + if (deg === 0) { + queue.push([id, 1]) + waveMap.set(id, 1) + } + } + + let maxWave = 1 + let idx = 0 + while (idx < queue.length) { + const [current, depth] = queue[idx++] + for (const next of adjList.get(current)) { + const newDeg = inDegree.get(next) - 1 + inDegree.set(next, newDeg) + const nextDepth = Math.max(waveMap.get(next) || 0, depth + 1) + waveMap.set(next, nextDepth) + if (newDeg === 0) { + queue.push([next, nextDepth]) + maxWave = Math.max(maxWave, nextDepth) + } + } + } + + // Check for unassigned (circular deps) + for (const row of rows) { + if (!waveMap.has(row.id)) { + console.log(`WARNING: Circular dependency involving ${row.id}, assigning to wave ${maxWave + 1}`) + waveMap.set(row.id, maxWave + 1) + maxWave = maxWave + 1 + } + } + + // Apply plan.json execution_graph hints if available + if (planJson.execution_graph?.phases) { + planJson.execution_graph.phases.forEach((phase, idx) => { + const phaseWave = idx + 1 + const taskIds = phase.tasks || phase.task_ids || [] + taskIds.forEach(id => { + if (waveMap.has(id)) { + // Only shift to later wave (never earlier — respect deps) + if (phaseWave > waveMap.get(id)) { + waveMap.set(id, phaseWave) + } + } + }) + }) + maxWave = Math.max(maxWave, ...waveMap.values()) + } + + return { waveMap, maxWave } +} + +const { waveMap, maxWave } = computeWaves(taskRows, planJson) + +// Assign wave + context_from +taskRows.forEach(row => { + row.wave = waveMap.get(row.id) || 1 + // context_from = deps + already-completed IDs for resume context + const depIds = row.deps.split(';').filter(Boolean) + const contextIds = [...new Set([...depIds, ...[...completedIds].filter(id => id !== row.id)])] + row.context_from = contextIds.join(';') +}) + +// 3.6: Write tasks.csv +function csvEscape(val) { + return `"${String(val).replace(/"/g, '""')}"` +} + +const tasksCsvHeader = 'id,title,description,agent,scope,deps,execution_group,context_from,wave,task_json_path,hints,execution_directives,acceptance_criteria,prev_context,status,findings,files_modified,tests_passed,acceptance_met,summary_path,error' +const tasksCsvRows = taskRows.map(r => + [r.id, r.title, r.description, r.agent, r.scope, r.deps, r.execution_group, + r.context_from, r.wave, r.task_json_path, r.hints, r.execution_directives, + r.acceptance_criteria, r.prev_context, r.status, r.findings, r.files_modified, + r.tests_passed, r.acceptance_met, r.summary_path, r.error] + .map(csvEscape).join(',') +) +Write(`${sessionFolder}/tasks.csv`, [tasksCsvHeader, ...tasksCsvRows].join('\n')) + +// 3.7: Write context.csv +const contextRows = ['key,type,value,source'] +if (planJson.tech_stack) { + const stack = Array.isArray(planJson.tech_stack) ? planJson.tech_stack.join(';') : planJson.tech_stack + contextRows.push(`"tech_stack","array","${stack}","plan.json"`) +} +if (planJson.conventions) { + const conv = Array.isArray(planJson.conventions) ? planJson.conventions.join(';') : planJson.conventions + contextRows.push(`"conventions","array","${conv}","plan.json"`) +} +const ctxPkgExists = Bash(`test -f "${sessionFolder}/.process/context-package.json" && echo yes`).trim() === 'yes' +if (ctxPkgExists) { + contextRows.push(`"context_package_path","path",".process/context-package.json","session"`) +} +contextRows.push(`"discoveries_path","path","discoveries.ndjson","session"`) +Write(`${sessionFolder}/context.csv`, contextRows.join('\n')) + +// 3.8: Initialize discoveries.ndjson +Bash(`touch "${sessionFolder}/discoveries.ndjson"`) + +// 3.9: User validation (skip if AUTO_YES) +if (!AUTO_YES) { + const pendingRows = taskRows.filter(r => r.status === 'pending') + console.log(`\n## Wave Execution Plan\n`) + console.log(` Tasks: ${pendingRows.length} pending across ${maxWave} waves\n`) + for (let w = 1; w <= maxWave; w++) { + const waveTasks = pendingRows.filter(r => r.wave === w) + if (waveTasks.length === 0) continue + console.log(` Wave ${w}: ${waveTasks.map(t => `${t.id}(${t.agent})`).join(', ')}`) + } + + const answer = AskUserQuestion({ + questions: [{ + question: `Proceed with ${pendingRows.length} tasks across ${maxWave} waves?`, + header: "Confirm", + multiSelect: false, + options: [ + { label: "Execute", description: "Proceed with wave execution" }, + { label: "Modify", description: `Edit ${sessionFolder}/tasks.csv then --resume-session` }, + { label: "Cancel", description: "Abort" } + ] + }] + }) + + if (answer.Confirm === "Modify") { + console.log(`Edit: ${sessionFolder}/tasks.csv\nResume: $workflow-execute --resume-session=${sessionId}`) + return + } else if (answer.Confirm === "Cancel") { + return + } +} + +console.log(`\n tasks.csv: ${taskRows.length} rows (${pendingJsons.length} pending)`) +console.log(` context.csv: ${contextRows.length - 1} entries`) +console.log(` Wave plan: ${maxWave} waves`) +``` + +--- + +### Phase 4: Wave Execute (spawn_agents_on_csv) + +**Objective**: Execute tasks wave-by-wave via `spawn_agents_on_csv`. Each wave builds `prev_context` from completed predecessors. + +```javascript +console.log(`\n## Phase 4: Wave Execute\n`) + +// Determine concurrency from plan.json or flag +let effectiveConcurrency = maxConcurrency +if (planJson.recommended_execution === 'Sequential') { + effectiveConcurrency = 1 + console.log(` Sequential mode (from plan.json), concurrency: 1`) +} else { + console.log(` Parallel mode, concurrency: ${effectiveConcurrency}`) +} + +// Read context.csv for instruction injection +const contextCsvContent = Read(`${sessionFolder}/context.csv`) +const contextEntries = parseCsv(contextCsvContent) +const contextBlock = contextEntries.map(e => `- **${e.key}** (${e.type}): ${e.value}`).join('\n') + +const failedIds = new Set() +const skippedIds = new Set() + +for (let wave = 1; wave <= maxWave; wave++) { + console.log(`\n### Wave ${wave}/${maxWave}\n`) + + // Re-read master CSV for current state + const masterCsv = parseCsv(Read(`${sessionFolder}/tasks.csv`)) + const waveTasks = masterCsv.filter(row => + parseInt(row.wave) === wave && row.status === 'pending' + ) + + if (waveTasks.length === 0) { + console.log(` No pending tasks in wave ${wave}`) + continue + } + + // Skip tasks whose deps failed/skipped + const executableTasks = [] + for (const task of waveTasks) { + const deps = (task.deps || '').split(';').filter(Boolean) + if (deps.some(d => failedIds.has(d) || skippedIds.has(d))) { + skippedIds.add(task.id) + updateMasterCsvRow(`${sessionFolder}/tasks.csv`, task.id, { + status: 'skipped', + error: 'Dependency failed or skipped' + }) + console.log(` [${task.id}] ${task.title} → SKIPPED (dependency failed)`) + continue + } + executableTasks.push(task) + } + + if (executableTasks.length === 0) { + console.log(` No executable tasks in wave ${wave}`) + continue + } + + // Build prev_context for each task + for (const task of executableTasks) { + task.prev_context = buildPrevContext(task.context_from, masterCsv) + } + + // Write wave CSV (input columns + prev_context) + const waveHeader = 'id,title,description,agent,scope,deps,execution_group,context_from,wave,task_json_path,hints,execution_directives,acceptance_criteria,prev_context' + const waveRows = executableTasks.map(t => + [t.id, t.title, t.description, t.agent, t.scope, t.deps, t.execution_group, + t.context_from, t.wave, t.task_json_path, t.hints, t.execution_directives, + t.acceptance_criteria, t.prev_context] + .map(cell => `"${String(cell).replace(/"/g, '""')}"`) + .join(',') + ) + Write(`${sessionFolder}/wave-${wave}.csv`, [waveHeader, ...waveRows].join('\n')) + + // Execute wave + console.log(` Executing ${executableTasks.length} tasks (concurrency: ${effectiveConcurrency})...`) + + spawn_agents_on_csv({ + csv_path: `${sessionFolder}/wave-${wave}.csv`, + id_column: "id", + instruction: buildExecuteInstruction(sessionFolder, contextBlock), + max_concurrency: effectiveConcurrency, + max_runtime_seconds: 600, + output_csv_path: `${sessionFolder}/wave-${wave}-results.csv`, + output_schema: { + type: "object", + properties: { + id: { type: "string" }, + status: { type: "string", enum: ["completed", "failed"] }, + findings: { type: "string" }, + files_modified: { type: "array", items: { type: "string" } }, + tests_passed: { type: "boolean" }, + acceptance_met: { type: "string" }, + error: { type: "string" } + }, + required: ["id", "status", "findings", "tests_passed"] + } + }) + + // Merge results into master CSV + update task JSONs + const waveResults = parseCsv(Read(`${sessionFolder}/wave-${wave}-results.csv`)) + for (const result of waveResults) { + const filesModified = Array.isArray(result.files_modified) + ? result.files_modified.join(';') + : (result.files_modified || '') + + updateMasterCsvRow(`${sessionFolder}/tasks.csv`, result.id, { + status: result.status, + findings: result.findings || '', + files_modified: filesModified, + tests_passed: String(result.tests_passed ?? ''), + acceptance_met: result.acceptance_met || '', + error: result.error || '' + }) + + // Update task JSON status + if (result.status === 'completed' || result.status === 'failed') { + Bash(`cd "${sessionFolder}/.task" && jq '.status="${result.status}" | .status_history=(.status_history // [])+[{"from":"in_progress","to":"${result.status}","changed_at":"'"$(date -Iseconds)"'"}]' "${result.id}.json" > tmp.json && mv tmp.json "${result.id}.json" 2>/dev/null || true`) + } + + if (result.status === 'failed') { + failedIds.add(result.id) + console.log(` [${result.id}] → FAILED: ${result.error}`) + } else { + console.log(` [${result.id}] → COMPLETED${result.tests_passed ? ' (tests passed)' : ''}`) + } + + // Auto-commit per completed task + if (withCommit && result.status === 'completed' && filesModified) { + const files = filesModified.split(';').filter(Boolean) + if (files.length > 0) { + const taskJson = JSON.parse(Read(`${sessionFolder}/.task/${result.id}.json`) || '{}') + const typeMap = { feature: 'feat', bugfix: 'fix', refactor: 'refactor', 'test-gen': 'test', docs: 'docs' } + const type = typeMap[taskJson.meta?.type] || 'chore' + const title = taskJson.title || result.id + const msg = `${type}: ${title}` + Bash(`git add ${files.map(f => '"' + f + '"').join(' ')} && git commit -m "${msg}" 2>/dev/null || true`) + console.log(` Committed: ${msg}`) + } + } + } + + // Cleanup temp wave CSVs + Bash(`rm -f "${sessionFolder}/wave-${wave}.csv" "${sessionFolder}/wave-${wave}-results.csv"`) + + const completedCount = waveResults.filter(r => r.status === 'completed').length + const failedCount = waveResults.filter(r => r.status === 'failed').length + console.log(` Wave ${wave} done: ${completedCount} completed, ${failedCount} failed`) +} +``` + +**prev_context Builder** + +```javascript +function buildPrevContext(contextFrom, masterCsv) { + if (!contextFrom) return 'No previous context available' + + const ids = contextFrom.split(';').filter(Boolean) + const entries = [] + + ids.forEach(id => { + const row = masterCsv.find(r => r.id === id) + if (row && row.status === 'completed' && row.findings) { + entries.push(`[${row.id}: ${row.title}] ${row.findings}`) + if (row.files_modified) entries.push(` Modified: ${row.files_modified}`) + } + }) + + return entries.length > 0 ? entries.join('\n') : 'No previous context available' +} +``` + +**Execute Instruction Template** + +```javascript +function buildExecuteInstruction(sessionFolder, contextBlock) { + return ` +## TASK ASSIGNMENT + +### MANDATORY FIRST STEPS +1. Read your FULL task JSON: ${sessionFolder}/{task_json_path} + - CSV row is a brief — task JSON has pre_analysis, flow_control, convergence, and full context +2. Read shared discoveries: ${sessionFolder}/discoveries.ndjson (if exists) +3. Read project context: .workflow/project-tech.json (if exists) + +--- + +## Your Task + +**Task ID**: {id} +**Title**: {title} +**Description**: {description} +**Agent Type**: {agent} +**Scope**: {scope} + +### Task JSON (full details) +Read: ${sessionFolder}/{task_json_path} + +### Implementation Hints & Reference Files +{hints} + +> Format: \`tips text || file1;file2\`. Read ALL reference files (after ||) before starting. Apply tips (before ||) as guidance. + +### Execution Directives +{execution_directives} + +> Commands to run for verification, tool restrictions, or environment requirements. + +### Acceptance Criteria +{acceptance_criteria} + +### Previous Context (from predecessor tasks) +{prev_context} + +### Project Context +${contextBlock} + +--- + +## Execution Protocol + +1. **Read task JSON**: Load ${sessionFolder}/{task_json_path} for full task details including pre_analysis steps and flow_control +2. **Check execution method**: If task JSON has \`execution_config.method\`, follow it (agent vs cli mode) +3. **Execute pre_analysis**: If task JSON has \`pre_analysis\` steps, run them first to gather context +4. **Read references**: Parse {hints} — read all files listed after \`||\` to understand existing patterns +5. **Read discoveries**: Load ${sessionFolder}/discoveries.ndjson for shared findings +6. **Use context**: Apply predecessor tasks' findings from prev_context above +7. **Stay in scope**: ONLY create/modify files within {scope} — do NOT touch files outside this boundary +8. **Apply hints**: Follow implementation tips from {hints} (before \`||\`) +9. **Execute**: Implement the task as described in the task JSON +10. **Generate summary**: Write execution summary to ${sessionFolder}/.summaries/{id}-summary.md with sections: + ## Summary, ## Files Modified (as \`- \\\`path\\\`\` list), ## Key Decisions, ## Tests +11. **Run directives**: Execute commands from {execution_directives} to verify your work +12. **Update TODO**: In ${sessionFolder}/TODO_LIST.md, change \`- [ ] {id}\` to \`- [x] {id}\` +13. **Share discoveries**: Append findings to shared board: + \`\`\`bash + echo '{"ts":"","worker":"{id}","type":"","data":{...}}' >> ${sessionFolder}/discoveries.ndjson + \`\`\` +14. **Report result**: Return JSON via report_agent_job_result + +### Discovery Types to Share +- \`code_pattern\`: {name, file, description} — reusable patterns found +- \`integration_point\`: {file, description, exports[]} — module connection points +- \`convention\`: {naming, imports, formatting} — code style conventions +- \`blocker\`: {issue, severity, impact} — blocking issues encountered + +--- + +## Output (report_agent_job_result) + +Return JSON: +{ + "id": "{id}", + "status": "completed" | "failed", + "findings": "Key discoveries and implementation notes (max 500 chars)", + "files_modified": ["path1", "path2"], + "tests_passed": true | false, + "acceptance_met": "Summary of which acceptance criteria were met/unmet", + "error": "" +} + +**IMPORTANT**: Set status to "completed" ONLY if: +- All acceptance criteria are met +- Verification directives pass (if any) +Otherwise set status to "failed" with details in error field. +` +} +``` + +--- + +### Phase 5: Results Sync + +**Objective**: Export results, reconcile TODO_LIST.md, update session status. + +```javascript +console.log(`\n## Phase 5: Results Sync\n`) + +// 5.1: Export results.csv (final copy of tasks.csv) +const finalCsvContent = Read(`${sessionFolder}/tasks.csv`) +Write(`${sessionFolder}/results.csv`, finalCsvContent) + +// 5.2: Reconcile TODO_LIST.md with tasks.csv status +const finalTasks = parseCsv(finalCsvContent) +let todoMd = Read(`${sessionFolder}/TODO_LIST.md`) + +for (const task of finalTasks) { + if (task.status === 'completed') { + // Ensure marked as [x] in TODO_LIST.md + const uncheckedPattern = new RegExp(`^(- \\[ \\] ${task.id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:.*)$`, 'm') + todoMd = todoMd.replace(uncheckedPattern, (match, line) => line.replace('- [ ]', '- [x]')) + } +} +Write(`${sessionFolder}/TODO_LIST.md`, todoMd) + +// 5.3: Summary +const completed = finalTasks.filter(t => t.status === 'completed') +const failed = finalTasks.filter(t => t.status === 'failed') +const skipped = finalTasks.filter(t => t.status === 'skipped') +const pending = finalTasks.filter(t => t.status === 'pending') + +console.log(` Results:`) +console.log(` Completed: ${completed.length}`) +console.log(` Failed: ${failed.length}`) +console.log(` Skipped: ${skipped.length}`) +console.log(` Pending: ${pending.length}`) + +// 5.4: Update session status +const allDone = failed.length === 0 && skipped.length === 0 && pending.length === 0 +const sessionStatus = allDone ? 'completed' : 'partial' +Bash(`cd "${sessionFolder}" && jq '.status = "${sessionStatus}" | .completed_at = "'"$(date -Iseconds)"'"' workflow-session.json > tmp.json && mv tmp.json workflow-session.json 2>/dev/null || true`) + +// 5.5: User next step +if (AUTO_YES) { + console.log(` [--yes] Session ${sessionId} ${sessionStatus}.`) +} else { + const nextStep = AskUserQuestion({ + questions: [{ + question: "Execution complete. What's next?", + header: "Next Step", + multiSelect: false, + options: [ + { label: "Enter Review", description: "Run post-implementation review (security/quality/architecture)" }, + { label: "Complete Session", description: "Archive session and finalize" } + ] + }] + }) + + if (nextStep['Next Step'] === 'Enter Review') { + // → Phase 6 + } else { + console.log(` Session ${sessionId} ${sessionStatus}.`) + } +} +``` + +--- + +### Phase 6: Post-Implementation Review (Optional) + +**Objective**: CLI-assisted specialized review of implemented code. + +```javascript +// Phase 6 entry (from Phase 5 "Enter Review" or direct invocation) +console.log(`\n## Phase 6: Post-Implementation Review\n`) + +const reviewType = AUTO_YES ? 'quality' : (() => { + const answer = AskUserQuestion({ + questions: [{ + question: "Select review type:", + header: "Review", + multiSelect: false, + options: [ + { label: "Quality", description: "Code quality, best practices, maintainability" }, + { label: "Security", description: "Security vulnerabilities, OWASP Top 10" }, + { label: "Architecture", description: "Architecture decisions, scalability, patterns" }, + { label: "Action Items", description: "TODO items, tech debt, follow-ups" } + ] + }] + }) + return answer.Review.toLowerCase() +})() + +// Get list of modified files from tasks.csv +const reviewTasks = parseCsv(Read(`${sessionFolder}/tasks.csv`)) +const allModifiedFiles = new Set() +reviewTasks.forEach(t => { + (t.files_modified || '').split(';').filter(Boolean).forEach(f => allModifiedFiles.add(f)) +}) + +const fileList = [...allModifiedFiles].join(', ') + +Bash({ + command: `ccw cli -p "PURPOSE: Post-implementation ${reviewType} review of modified files. Identify issues and generate actionable report. +TASK: + • Review all modified files for ${reviewType} concerns + • Assess overall ${reviewType} posture + • Generate prioritized issue list with severity + • Provide remediation recommendations +MODE: analysis +CONTEXT: @${[...allModifiedFiles].map(f => f).join(' @')} +EXPECTED: Structured ${reviewType} review report with: summary, issue list (severity, file, line, description, fix), overall score +CONSTRAINTS: Focus on ${reviewType} | Review only modified files: ${fileList}" --tool gemini --mode analysis --rule analysis-review-code-quality`, + run_in_background: true +}) +// Wait for CLI → review report + +Write(`${sessionFolder}/REVIEW-${reviewType}.md`, reviewReport) +console.log(` Review complete: ${sessionFolder}/REVIEW-${reviewType}.md`) + +// Post-review options +if (!AUTO_YES) { + const postReview = AskUserQuestion({ + questions: [{ + question: "Review complete. What's next?", + header: "Post-Review", + multiSelect: false, + options: [ + { label: "Another Review", description: "Run a different review type" }, + { label: "Complete Session", description: "Archive and finalize" } + ] + }] + }) + + if (postReview['Post-Review'] === 'Another Review') { + // Loop back to Phase 6 review type selection + } +} + +console.log(`\nSession ${sessionId} execution complete.`) +``` + +--- + +## CSV Helpers + +```javascript +function parseCsv(content) { + const lines = content.trim().split('\n') + if (lines.length < 2) return [] + const header = parseCsvLine(lines[0]) + return lines.slice(1).map(line => { + const cells = parseCsvLine(line) + const obj = {} + header.forEach((col, i) => { obj[col] = cells[i] || '' }) + return obj + }) +} + +function parseCsvLine(line) { + const cells = [] + let current = '' + let inQuotes = false + for (let i = 0; i < line.length; i++) { + const ch = line[i] + if (inQuotes) { + if (ch === '"' && line[i + 1] === '"') { + current += '"' + i++ + } else if (ch === '"') { + inQuotes = false + } else { + current += ch + } + } else { + if (ch === '"') { + inQuotes = true + } else if (ch === ',') { + cells.push(current) + current = '' + } else { + current += ch + } + } + } + cells.push(current) + return cells +} + +function updateMasterCsvRow(csvPath, taskId, updates) { + const content = Read(csvPath) + const lines = content.split('\n') + const header = parseCsvLine(lines[0]) + + for (let i = 1; i < lines.length; i++) { + const cells = parseCsvLine(lines[i]) + if (cells[0] === taskId) { + for (const [col, val] of Object.entries(updates)) { + const colIdx = header.indexOf(col) + if (colIdx >= 0) { + cells[colIdx] = String(val).replace(/"/g, '""') + } + } + lines[i] = cells.map(c => `"${c}"`).join(',') + break + } + } + + Write(csvPath, lines.join('\n')) +} + +function csvEscape(val) { + return `"${String(val).replace(/"/g, '""')}"` +} +``` + +--- + +## Agent Assignment Rules + +``` +meta.agent specified → Use specified agent file +meta.agent missing → Infer from meta.type: + feature → code-developer + test-gen → code-developer + test-fix → test-fix-agent + review → universal-executor + docs → doc-generator + default → code-developer +``` + +--- + +## Error Handling + +| Error | Recovery | +|-------|----------| +| No active sessions | Guide: run `$workflow-plan "description"` first | +| Missing planning docs | Guide: run `$workflow-plan --session ID` | +| Agent failure | Mark failed in tasks.csv, skip dependents, continue wave | +| Dependency cascade | Skip dependent tasks, report at Phase 5 | +| CSV parse error | Validate CSV format, report line number | +| Task JSON corruption | Skip task, mark failed in CSV | +| Commit failure | Log error, continue execution (non-blocking) | +| Circular dependency | Warn and assign to last wave | +| All wave tasks skipped | Log and continue to next wave | + +--- + +## Core Rules + +1. **Wave Order is Sacred**: Never execute wave N before wave N-1 completes and results merge +2. **CSV is Execution State**: tasks.csv holds all execution state — always re-read before each wave +3. **Task JSON is Rich Data**: agents read full task JSON via `task_json_path` — CSV is brief +4. **Skip on Failure**: If a dependency failed, skip the dependent task (cascade) +5. **Cleanup Temp Files**: Remove wave CSVs after results are merged +6. **TODO_LIST.md Sync**: Phase 5 reconciles TODO_LIST.md with tasks.csv final state +7. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson +8. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped +9. **Planning Artifacts Unchanged**: IMPL-*.json, plan.json, IMPL_PLAN.md formats are preserved + +--- + +## Compact Protection + +> **COMPACT DIRECTIVE**: If context compression occurs during execution: +> - Re-read `tasks.csv` for current execution state (source of truth) +> - Re-read `TODO_LIST.md` for progress display +> - Re-read `plan.json` for execution hints (concurrency, phases) +> - Task JSONs are read per-wave via `task_json_path`, compression has minimal impact +> - Wave loop state (`failedIds`, `skippedIds`, `wave`) can be reconstructed from tasks.csv status column diff --git a/.codex/skills/wave-plan-pipeline/SKILL.md b/.codex/skills/workflow-lite-planex/SKILL.md similarity index 100% rename from .codex/skills/wave-plan-pipeline/SKILL.md rename to .codex/skills/workflow-lite-planex/SKILL.md diff --git a/.codex/skills/workflow-plan/SKILL.md b/.codex/skills/workflow-plan/SKILL.md new file mode 100644 index 00000000..3f7830fa --- /dev/null +++ b/.codex/skills/workflow-plan/SKILL.md @@ -0,0 +1,636 @@ +--- +name: workflow-plan +description: | + Planning pipeline with multi-mode routing (plan/verify/replan). Session discovery → + context gathering (spawn_agent) → conditional conflict resolution → task generation + (spawn_agent or N+1 parallel agents) → plan verification → interactive replan. + Produces IMPL_PLAN.md, task JSONs, TODO_LIST.md. +argument-hint: "[-y|--yes] [--session ID] \"task description\" | verify [--session ID] | replan [--session ID] [IMPL-N] \"changes\"" +allowed-tools: spawn_agent, wait, send_input, close_agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep +--- + +## Auto Mode + +When `--yes` or `-y`: Skip all confirmations, use defaults, auto-verify, auto-continue to execute if PROCEED. + +# Workflow Plan + +## Usage + +```bash +# Plan mode (default) +$workflow-plan "Build authentication system with JWT and OAuth" +$workflow-plan -y "Add rate limiting to API endpoints" +$workflow-plan --session WFS-auth "Extend with 2FA support" + +# Verify mode +$workflow-plan verify --session WFS-auth +$workflow-plan verify + +# Replan mode +$workflow-plan replan --session WFS-auth "Change from JWT to session-based auth" +$workflow-plan replan --session WFS-auth IMPL-3 "Split into two smaller tasks" +``` + +**Flags**: +- `-y, --yes`: Skip all confirmations (auto mode) +- `--session ID`: Use specific session + +--- + +## Overview + +Multi-mode planning pipeline using subagent coordination. Plan mode runs 4 sequential phases with conditional branching; verify and replan modes operate on existing plans. + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ WORKFLOW PLAN PIPELINE │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ Mode Detection: plan | verify | replan │ +│ │ +│ ═══ Plan Mode (default) ═══ │ +│ │ +│ Phase 1: Session Discovery │ +│ ├─ Create or find workflow session │ +│ └─ Initialize planning-notes.md │ +│ │ +│ Phase 2: Context Gathering (spawn_agent: context-search-agent) │ +│ ├─ Codebase analysis → context-package.json │ +│ └─ Conflict risk assessment │ +│ │ +│ Phase 3: Conflict Resolution (conditional: risk ≥ medium) │ +│ ├─ CLI-driven conflict analysis │ +│ └─ User-selected resolution strategies │ +│ │ +│ Phase 4: Task Generation (spawn_agent: action-planning-agent) │ +│ ├─ Single module → 1 agent │ +│ ├─ Multi-module → N+1 parallel agents │ +│ └─ Output: IMPL_PLAN.md + task JSONs + TODO_LIST.md │ +│ │ +│ Plan Confirmation Gate │ +│ ├─ "Verify Plan" → Phase 5 │ +│ ├─ "Start Execution" → workflow-execute │ +│ └─ "Review Status" → Display inline │ +│ │ +│ ═══ Verify Mode ═══ │ +│ Phase 5: Plan Verification (spawn_agent: cli-explore-agent) │ +│ └─ 10-dimension analysis → PLAN_VERIFICATION.md │ +│ │ +│ ═══ Replan Mode ═══ │ +│ Phase 6: Interactive Replan │ +│ └─ Clarification → Impact → Backup → Apply → Verify │ +│ │ +└──────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Data Flow + +``` +User Input (task description) + │ + ↓ [Convert to GOAL/SCOPE/CONTEXT] + │ +Phase 1 ──→ sessionId, planning-notes.md + │ +Phase 2 ──→ context-package.json, conflictRisk + │ + ├── conflictRisk ≥ medium ──→ Phase 3 ──→ modified artifacts + └── conflictRisk < medium ──→ skip Phase 3 + │ +Phase 4 ──→ IMPL_PLAN.md, plan.json, task JSONs, TODO_LIST.md + │ + ├── Verify → Phase 5 → PLAN_VERIFICATION.md + ├── Execute → workflow-execute skill + └── Review → inline display +``` + +--- + +## Session Structure + +``` +.workflow/active/WFS-{session}/ +├── workflow-session.json # Session metadata +├── planning-notes.md # Accumulated context across phases +├── IMPL_PLAN.md # Implementation plan (human-readable) +├── plan.json # Structured plan overview (machine-readable) +├── TODO_LIST.md # Task checklist +├── .task/ # Task definitions +│ ├── IMPL-1.json +│ └── IMPL-N.json +└── .process/ + ├── context-package.json # Phase 2 output + ├── conflict-resolution.json # Phase 3 output (conditional) + ├── PLAN_VERIFICATION.md # Phase 5 output + └── backup/ # Phase 6 backups +``` + +--- + +## Implementation + +### Session Initialization + +```javascript +const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() + +// Parse flags +const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') +const sessionMatch = $ARGUMENTS.match(/--session\s+(\S+)/) +const existingSessionId = sessionMatch ? sessionMatch[1] : null + +// Mode detection +const cleanArgs = $ARGUMENTS + .replace(/--yes|-y|--session\s+\S+/g, '').trim() + +let mode = 'plan' +if (cleanArgs.startsWith('verify')) mode = 'verify' +else if (cleanArgs.startsWith('replan')) mode = 'replan' + +const taskDescription = cleanArgs + .replace(/^(verify|replan)\s*/, '') + .replace(/^["']|["']$/g, '') + .trim() + +// Extract replan task ID if present +const replanTaskMatch = taskDescription.match(/^(IMPL-\d+(?:\.\d+)?)\s+(.+)/) +const replanTaskId = replanTaskMatch ? replanTaskMatch[1] : null +const replanDescription = replanTaskMatch ? replanTaskMatch[2] : taskDescription +``` + +--- + +### Phase 1: Session Discovery (Plan Mode) + +**Objective**: Create or find workflow session, initialize planning notes. + +```javascript +if (mode !== 'plan') { + // verify/replan: locate existing session + // → Jump to Phase 5 or Phase 6 +} + +let sessionId, sessionFolder + +if (existingSessionId) { + sessionId = existingSessionId + sessionFolder = `.workflow/active/${sessionId}` + if (!Bash(`test -d "${sessionFolder}" && echo yes`).trim()) { + console.log(`ERROR: Session ${sessionId} not found`) + return + } +} else { + // Auto-detect from .workflow/active/ or create new + const sessions = Bash(`ls -d .workflow/active/WFS-* 2>/dev/null`).trim().split('\n').filter(Boolean) + + if (sessions.length === 0 || taskDescription) { + // Create new session + const slug = taskDescription.toLowerCase() + .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-').substring(0, 40) + sessionId = `WFS-${slug}` + sessionFolder = `.workflow/active/${sessionId}` + Bash(`mkdir -p "${sessionFolder}/.task" "${sessionFolder}/.process" "${sessionFolder}/.summaries"`) + + Write(`${sessionFolder}/workflow-session.json`, JSON.stringify({ + session_id: sessionId, + status: 'planning', + created_at: getUtc8ISOString(), + task_description: taskDescription + }, null, 2)) + } else if (sessions.length === 1) { + sessionId = sessions[0].split('/').pop() + sessionFolder = sessions[0] + } else { + // Multiple sessions — ask user + if (AUTO_YES) { + sessionFolder = sessions[0] + sessionId = sessions[0].split('/').pop() + } else { + const answer = AskUserQuestion({ + questions: [{ + question: "Multiple sessions found. Select one:", + header: "Session", + multiSelect: false, + options: sessions.slice(0, 4).map(s => ({ + label: s.split('/').pop(), + description: s + })) + }] + }) + sessionId = answer.Session + sessionFolder = `.workflow/active/${sessionId}` + } + } +} + +// Initialize planning-notes.md +const structuredDesc = `GOAL: ${taskDescription}\nSCOPE: Core implementation\nCONTEXT: New development` +Write(`${sessionFolder}/planning-notes.md`, `# Planning Notes\n\n## User Intent\n${structuredDesc}\n`) + +console.log(`Session: ${sessionId}`) +``` + +--- + +### Phase 2: Context Gathering (spawn_agent) + +**Objective**: Gather project context, assess conflict risk. + +```javascript +console.log(`\n## Phase 2: Context Gathering\n`) + +const ctxAgent = spawn_agent({ + agent: `~/.codex/agents/context-search-agent.md`, + instruction: ` +Gather implementation context for planning. + +**Session**: ${sessionFolder} +**Task**: ${taskDescription} +**Mode**: PLAN + +### Steps +1. Analyze project structure (package.json, tsconfig, etc.) +2. Search for existing similar implementations +3. Identify integration points and dependencies +4. Assess conflict risk with existing code +5. Generate context package + +### Output +Write context package to: ${sessionFolder}/.process/context-package.json +Format: { + "critical_files": [...], + "patterns": [...], + "dependencies": [...], + "integration_points": [...], + "conflict_risk": "none" | "low" | "medium" | "high", + "conflict_areas": [...], + "constraints": [...] +} +` +}) + +wait({ id: ctxAgent }) +close_agent({ id: ctxAgent }) + +// Parse outputs +const contextPkg = JSON.parse(Read(`${sessionFolder}/.process/context-package.json`) || '{}') +const conflictRisk = contextPkg.conflict_risk || 'none' +const contextPath = `${sessionFolder}/.process/context-package.json` + +// Update planning-notes.md +Edit(`${sessionFolder}/planning-notes.md`, { + oldText: '## User Intent', + newText: `## Context Findings +- Critical files: ${(contextPkg.critical_files || []).join(', ')} +- Conflict risk: ${conflictRisk} +- Constraints: ${(contextPkg.constraints || []).join('; ')} + +## User Intent` +}) + +console.log(` Context gathered. Conflict risk: ${conflictRisk}`) +``` + +--- + +### Phase 3: Conflict Resolution (Conditional) + +**Objective**: Detect and resolve conflicts when risk ≥ medium. + +```javascript +if (['medium', 'high'].includes(conflictRisk)) { + console.log(`\n## Phase 3: Conflict Resolution (risk: ${conflictRisk})\n`) + + Bash({ + command: `ccw cli -p "PURPOSE: Analyze and resolve conflicts between planned changes and existing codebase. +TASK: + • Read context package for conflict areas + • Analyze each conflict area in detail + • Propose resolution strategies (refactor, adapt, isolate, defer) + • For each conflict: assess impact and recommend approach +MODE: analysis +CONTEXT: @**/* +EXPECTED: JSON: {conflicts: [{area, severity, description, strategy, impact}], summary: string} +CONSTRAINTS: Focus on ${(contextPkg.conflict_areas || []).join(', ')} + +TASK DESCRIPTION: ${taskDescription}" --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause`, + run_in_background: true + }) + // Wait for CLI → conflicts[] + + if (!AUTO_YES && conflicts.length > 0) { + // Present conflicts and let user select strategies + console.log(`\n### Conflicts Found: ${conflicts.length}\n`) + conflicts.forEach((c, i) => { + console.log(`${i + 1}. [${c.severity}] ${c.area}: ${c.description}`) + console.log(` Strategy: ${c.strategy} | Impact: ${c.impact}`) + }) + + const answer = AskUserQuestion({ + questions: [{ + question: "Accept conflict resolution strategies?", + header: "Conflicts", + multiSelect: false, + options: [ + { label: "Accept All", description: "Apply all recommended strategies" }, + { label: "Review Each", description: "Approve strategies individually" }, + { label: "Skip", description: "Proceed without resolving" } + ] + }] + }) + } + + // Write resolution + Write(`${sessionFolder}/.process/conflict-resolution.json`, + JSON.stringify({ conflicts, resolved_at: getUtc8ISOString() }, null, 2)) + + // Update planning-notes + // Append conflict decisions to planning-notes.md +} else { + console.log(` Conflict risk: ${conflictRisk} — skipping Phase 3`) +} +``` + +--- + +### Phase 4: Task Generation (spawn_agent) + +**Objective**: Generate IMPL_PLAN.md, task JSONs, TODO_LIST.md. + +**Steps**: + +1. **Determine Planning Strategy** + + ```javascript + console.log(`\n## Phase 4: Task Generation\n`) + + // Detect module count from context + const modules = contextPkg.integration_points?.map(p => p.module).filter(Boolean) || [] + const uniqueModules = [...new Set(modules)] + const isMultiModule = uniqueModules.length >= 2 + ``` + +2. **Single Module → One Agent** + + ```javascript + if (!isMultiModule) { + const planAgent = spawn_agent({ + agent: `~/.codex/agents/action-planning-agent.md`, + instruction: ` +Generate implementation plan and task JSONs. + +**Session**: ${sessionFolder} +**Task**: ${taskDescription} +**Context**: ${contextPath} +**Planning Notes**: ${sessionFolder}/planning-notes.md +${contextPkg.conflict_risk === 'medium' || contextPkg.conflict_risk === 'high' + ? `**Conflict Resolution**: ${sessionFolder}/.process/conflict-resolution.json` : ''} + +### Output Requirements +1. **IMPL_PLAN.md** at ${sessionFolder}/IMPL_PLAN.md + - Section 1: Requirements Summary + - Section 2: Architecture Decisions + - Section 3: Task Breakdown (with dependencies) + - Section 4: Implementation Strategy (Sequential/Parallel/Phased) + - Section 5: Risk Assessment +2. **plan.json** at ${sessionFolder}/plan.json + - {task_ids[], recommended_execution, complexity, shared_context} +3. **Task JSONs** at ${sessionFolder}/.task/IMPL-{N}.json + - {id, title, description, depends_on[], convergence, meta: {type, agent}} +4. **TODO_LIST.md** at ${sessionFolder}/TODO_LIST.md + - Checkbox format: - [ ] IMPL-{N}: {title} +` + }) + + wait({ id: planAgent }) + close_agent({ id: planAgent }) + } + ``` + +3. **Multi-Module → N+1 Parallel Agents** + + ```javascript + if (isMultiModule) { + const prefixes = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' + const moduleAgents = [] + + // Spawn N module planners in parallel + for (let i = 0; i < uniqueModules.length; i++) { + const prefix = prefixes[i] + const mod = uniqueModules[i] + + const agentId = spawn_agent({ + agent: `~/.codex/agents/action-planning-agent.md`, + instruction: ` +Plan module: ${mod} (prefix: ${prefix}) + +**Session**: ${sessionFolder} +**Module**: ${mod} +**Context**: ${contextPath} +**Task ID prefix**: ${prefix} (e.g., ${prefix}1, ${prefix}2, ...) + +Generate task JSONs for this module only. +Output to: ${sessionFolder}/.task/${prefix}{N}.json +Mark cross-module dependencies as CROSS::${'{module}'}::${'{task}'} +` + }) + moduleAgents.push({ id: agentId, module: mod, prefix }) + } + + // Wait for all module planners + wait({ ids: moduleAgents.map(a => a.id) }) + moduleAgents.forEach(a => close_agent({ id: a.id })) + + // +1 Coordinator: integrate all modules + const coordAgent = spawn_agent({ + agent: `~/.codex/agents/action-planning-agent.md`, + instruction: ` +Integrate ${uniqueModules.length} module plans into unified IMPL_PLAN.md. + +**Session**: ${sessionFolder} +**Modules**: ${uniqueModules.join(', ')} +**Task Directory**: ${sessionFolder}/.task/ + +### Steps +1. Read all module task JSONs from .task/ +2. Resolve CROSS:: dependencies (replace with actual task IDs) +3. Generate unified IMPL_PLAN.md, plan.json, TODO_LIST.md +4. Renumber task IDs to sequential IMPL-1, IMPL-2, ... +` + }) + + wait({ id: coordAgent }) + close_agent({ id: coordAgent }) + } + ``` + +4. **Plan Confirmation Gate** + + ```javascript + // Validate outputs exist + const planExists = Bash(`test -f "${sessionFolder}/IMPL_PLAN.md" && echo yes`).trim() === 'yes' + const taskCount = parseInt(Bash(`ls ${sessionFolder}/.task/IMPL-*.json 2>/dev/null | wc -l`).trim()) || 0 + + console.log(`\n## Plan Generated\n`) + console.log(` Tasks: ${taskCount}`) + console.log(` Plan: ${sessionFolder}/IMPL_PLAN.md`) + + if (AUTO_YES) { + // Auto-verify then auto-execute if PROCEED + console.log(` [--yes] Auto-verifying plan...`) + // → Fall through to Phase 5, then Phase 5 result determines next step + } else { + const nextStep = AskUserQuestion({ + questions: [{ + question: "Plan generated. What's next?", + header: "Next Step", + multiSelect: false, + options: [ + { label: "Verify Plan (Recommended)", description: "Run quality verification before execution" }, + { label: "Start Execution", description: "Proceed to workflow-execute" }, + { label: "Review Status", description: "Display plan summary inline" } + ] + }] + }) + + if (nextStep['Next Step'] === 'Start Execution') { + console.log(`\nReady to execute. Run: $workflow-execute --session ${sessionId}`) + return + } + if (nextStep['Next Step'] === 'Review Status') { + const plan = Read(`${sessionFolder}/IMPL_PLAN.md`) + console.log(plan) + return + } + // Verify → continue to Phase 5 + } + ``` + +--- + +### Phase 5: Plan Verification (Verify Mode) + +**Objective**: Read-only multi-dimensional plan analysis. + +```javascript +if (mode === 'verify' || /* auto-verify from Phase 4 */) { + console.log(`\n## Phase 5: Plan Verification\n`) + + // Find session if in verify mode entry + if (mode === 'verify' && !sessionFolder) { + // Session discovery (same logic as Phase 1) + } + + Bash({ + command: `ccw cli -p "PURPOSE: Verify implementation plan quality across 10 dimensions. Read-only analysis. Success = actionable quality gate recommendation. +TASK: + • A: User Intent Alignment — does plan match original goal? + • B: Requirements Coverage — are all requirements addressed? + • C: Consistency Validation — internal consistency of plan + • D: Dependency Integrity — valid dependency chain + • E: Synthesis Alignment — matches brainstorm artifacts (if exist) + • F: Task Specification Quality — clear, actionable, testable + • G: Duplication Detection — no overlapping tasks + • H: Feasibility Assessment — realistic scope and effort + • I: Constraints Compliance — respects stated constraints + • J: Context Validation — planning-notes consistent with plan +MODE: analysis +CONTEXT: @${sessionFolder}/IMPL_PLAN.md @${sessionFolder}/.task/**/*.json @${sessionFolder}/planning-notes.md @${sessionFolder}/TODO_LIST.md +EXPECTED: Structured report with: per-dimension score (PASS/WARN/FAIL), issues list, quality gate (BLOCK_EXECUTION/PROCEED_WITH_FIXES/PROCEED_WITH_CAUTION/PROCEED) +CONSTRAINTS: Read-only | No file modifications | Be specific about issues" --tool gemini --mode analysis --rule analysis-review-architecture --cd "${sessionFolder}"`, + run_in_background: true + }) + // Wait for CLI → verification report + + Write(`${sessionFolder}/.process/PLAN_VERIFICATION.md`, verificationReport) + + console.log(` Quality gate: ${qualityGate}`) + console.log(` Report: ${sessionFolder}/.process/PLAN_VERIFICATION.md`) + + if (AUTO_YES && qualityGate === 'PROCEED') { + console.log(` [--yes] Plan verified. Ready for execution.`) + console.log(` Run: $workflow-execute --session ${sessionId}`) + } +} +``` + +--- + +### Phase 6: Interactive Replan (Replan Mode) + +**Objective**: Modify existing plan based on new requirements. + +```javascript +if (mode === 'replan') { + console.log(`\n## Phase 6: Interactive Replan\n`) + + // Find session + if (!sessionFolder) { + // Session discovery logic + } + + const scope = replanTaskId ? 'task' : 'session' + console.log(` Scope: ${scope}${replanTaskId ? ` (${replanTaskId})` : ''}`) + console.log(` Changes: ${replanDescription}`) + + // 1. Backup current plan + Bash(`mkdir -p "${sessionFolder}/.process/backup" && cp "${sessionFolder}/IMPL_PLAN.md" "${sessionFolder}/.process/backup/IMPL_PLAN-$(date +%Y%m%d%H%M%S).md"`) + + // 2. Replan via agent + const replanAgent = spawn_agent({ + agent: `~/.codex/agents/action-planning-agent.md`, + instruction: ` +Replan ${scope === 'task' ? `task ${replanTaskId}` : 'entire session'}. + +**Session**: ${sessionFolder} +**Current Plan**: ${sessionFolder}/IMPL_PLAN.md +**Current Tasks**: ${sessionFolder}/.task/ +**Changes Requested**: ${replanDescription} +${replanTaskId ? `**Target Task**: ${sessionFolder}/.task/${replanTaskId}.json` : ''} + +### Steps +1. Read current plan and task JSONs +2. Analyze impact of requested changes +3. Modify affected tasks (update/add/remove) +4. Update IMPL_PLAN.md with change annotations +5. Update TODO_LIST.md +6. Generate change summary + +### Constraints +- Preserve completed tasks +- Minimize changes to unaffected tasks +- Maintain dependency integrity +` + }) + + wait({ id: replanAgent }) + close_agent({ id: replanAgent }) + + console.log(` Replan complete. Review: ${sessionFolder}/IMPL_PLAN.md`) +} +``` + +--- + +## Error Handling + +| Error | Recovery | +|-------|----------| +| No active session | Guide: run `$workflow-plan "description"` first | +| Context gathering timeout | Retry with reduced scope | +| Conflict analysis failure | Skip Phase 3, proceed with warning | +| Task generation failure | Retry agent with simplified context | +| Plan verification failure | Display partial results | +| Session not found (verify/replan) | List available sessions | + +--- + +## Compact Protection + +> **COMPACT DIRECTIVE**: If context compression occurs: +> - Re-read `planning-notes.md` for accumulated context +> - Re-read `workflow-session.json` for session state +> - Phase 4 is the most token-intensive — if compressed, re-read task JSONs on demand