mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-07 02:04:11 +08:00
Compare commits
2 Commits
v6.3.46
...
copilot/fi
| Author | SHA1 | Date | |
|---|---|---|---|
|
de3d15c099 | ||
|
|
9232947fb0 |
@@ -1,46 +0,0 @@
|
||||
# Claude Instructions
|
||||
|
||||
- **Coding Philosophy**: @~/.claude/workflows/coding-philosophy.md
|
||||
|
||||
## CLI Endpoints
|
||||
|
||||
- **CLI Tools Usage**: @~/.claude/workflows/cli-tools-usage.md
|
||||
- **CLI Endpoints Config**: @~/.claude/cli-tools.json
|
||||
|
||||
**Strictly follow the cli-tools.json configuration**
|
||||
|
||||
Available CLI endpoints are dynamically defined by the config file:
|
||||
- Built-in tools and their enable/disable status
|
||||
- Custom API endpoints registered via the Dashboard
|
||||
- Managed through the CCW Dashboard Status page
|
||||
|
||||
|
||||
## Tool Execution
|
||||
|
||||
- **Context Requirements**: @~/.claude/workflows/context-tools.md
|
||||
- **File Modification**: @~/.claude/workflows/file-modification.md
|
||||
|
||||
### Agent Calls
|
||||
- **Always use `run_in_background: false`** for Task tool agent calls: `Task({ subagent_type: "xxx", prompt: "...", run_in_background: false })` to ensure synchronous execution and immediate result visibility
|
||||
- **TaskOutput usage**: Only use `TaskOutput({ task_id: "xxx", block: false })` + sleep loop to poll completion status. NEVER read intermediate output during agent/CLI execution - wait for final result only
|
||||
|
||||
### CLI Tool Calls (ccw cli)
|
||||
- **Default: `run_in_background: true`** - Unless otherwise specified, always use background execution for CLI calls:
|
||||
```
|
||||
Bash({ command: "ccw cli -p '...' --tool gemini", run_in_background: true })
|
||||
```
|
||||
- **After CLI call**: Stop output immediately - let CLI execute in background. **DO NOT use TaskOutput polling** - wait for hook callback to receive results
|
||||
|
||||
### CLI Analysis Calls
|
||||
- **Wait for results**: MUST wait for CLI analysis to complete before taking any write action. Do NOT proceed with fixes while analysis is running
|
||||
- **Value every call**: Each CLI invocation is valuable and costly. NEVER waste analysis results:
|
||||
- Aggregate multiple analysis results before proposing solutions
|
||||
|
||||
### CLI Auto-Invoke Triggers
|
||||
- **Reference**: See `cli-tools-usage.md` → [Auto-Invoke Triggers](#auto-invoke-triggers) for full specification
|
||||
- **Key scenarios**: Self-repair fails, ambiguous requirements, architecture decisions, pattern uncertainty, critical code paths
|
||||
- **Principles**: Default `--mode analysis`, no confirmation needed, wait for completion, flexible rule selection
|
||||
|
||||
## Code Diagnostics
|
||||
|
||||
- **Prefer `mcp__ide__getDiagnostics`** for code error checking over shell-based TypeScript compilation
|
||||
@@ -1,366 +0,0 @@
|
||||
# Claude Code TypeScript LSP 配置指南
|
||||
|
||||
> 更新日期: 2026-01-20
|
||||
> 适用版本: Claude Code v2.0.74+
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
1. [方式一：插件市场（推荐）](#方式一插件市场推荐)
|
||||
2. [方式二：MCP Server (cclsp)](#方式二mcp-server-cclsp)
|
||||
3. [方式三：内置LSP工具](#方式三内置lsp工具)
|
||||
4. [配置验证](#配置验证)
|
||||
5. [故障排查](#故障排查)
|
||||
|
||||
---
|
||||
|
||||
## 方式一：插件市场（推荐）
|
||||
|
||||
### 步骤 1: 添加插件市场
|
||||
|
||||
在Claude Code中执行：
|
||||
|
||||
```bash
|
||||
/plugin marketplace add boostvolt/claude-code-lsps
|
||||
```
|
||||
|
||||
### 步骤 2: 安装TypeScript LSP插件
|
||||
|
||||
```bash
|
||||
# TypeScript/JavaScript支持（推荐vtsls）
|
||||
/plugin install vtsls@claude-code-lsps
|
||||
```
|
||||
|
||||
### 步骤 3: 验证安装
|
||||
|
||||
```bash
|
||||
/plugin list
|
||||
```
|
||||
|
||||
应该看到：
|
||||
```
|
||||
✓ vtsls@claude-code-lsps (enabled)
|
||||
✓ pyright-lsp@claude-plugins-official (enabled)
|
||||
```
|
||||
|
||||
### 配置文件自动更新
|
||||
|
||||
安装后，`~/.claude/settings.json` 会自动添加：
|
||||
|
||||
```json
|
||||
{
|
||||
"enabledPlugins": {
|
||||
"pyright-lsp@claude-plugins-official": true,
|
||||
"vtsls@claude-code-lsps": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 支持的操作
|
||||
|
||||
- `goToDefinition` - 跳转到定义
|
||||
- `findReferences` - 查找引用
|
||||
- `hover` - 显示类型信息
|
||||
- `documentSymbol` - 文档符号
|
||||
- `getDiagnostics` - 诊断信息
|
||||
|
||||
---
|
||||
|
||||
## 方式二：MCP Server (cclsp)
|
||||
|
||||
### 优势
|
||||
|
||||
- **位置容错**：自动修正AI生成的不精确行号
|
||||
- **更多功能**：支持重命名、完整诊断
|
||||
- **灵活配置**：完全自定义LSP服务器
|
||||
|
||||
### 安装步骤
|
||||
|
||||
#### 1. 安装TypeScript Language Server
|
||||
|
||||
```bash
|
||||
npm install -g typescript-language-server typescript
|
||||
```
|
||||
|
||||
验证安装：
|
||||
```bash
|
||||
typescript-language-server --version
|
||||
```
|
||||
|
||||
#### 2. 配置cclsp
|
||||
|
||||
运行自动配置：
|
||||
```bash
|
||||
npx cclsp@latest setup --user
|
||||
```
|
||||
|
||||
或手动创建配置文件：
|
||||
|
||||
**文件位置**: `~/.claude/cclsp.json` 或 `~/.config/claude/cclsp.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": [
|
||||
{
|
||||
"extensions": ["ts", "tsx", "js", "jsx"],
|
||||
"command": ["typescript-language-server", "--stdio"],
|
||||
"rootDir": ".",
|
||||
"restartInterval": 5,
|
||||
"initializationOptions": {
|
||||
"preferences": {
|
||||
"includeInlayParameterNameHints": "all",
|
||||
"includeInlayPropertyDeclarationTypeHints": true,
|
||||
"includeInlayFunctionParameterTypeHints": true,
|
||||
"includeInlayVariableTypeHints": true
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"extensions": ["py", "pyi"],
|
||||
"command": ["pylsp"],
|
||||
"rootDir": ".",
|
||||
"restartInterval": 5
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 在Claude Code中启用MCP Server
|
||||
|
||||
添加到Claude Code配置：
|
||||
|
||||
```bash
|
||||
# 查看当前MCP配置
|
||||
cat ~/.claude/.mcp.json
|
||||
|
||||
# 如果没有，创建新的
|
||||
```
|
||||
|
||||
**文件**: `~/.claude/.mcp.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"cclsp": {
|
||||
"command": "npx",
|
||||
"args": ["cclsp@latest"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### cclsp可用的MCP工具
|
||||
|
||||
使用时，Claude Code会自动调用这些工具：
|
||||
|
||||
- `find_definition` - 按名称查找定义（支持模糊匹配）
|
||||
- `find_references` - 查找所有引用
|
||||
- `rename_symbol` - 重命名符号（带备份）
|
||||
- `get_diagnostics` - 获取诊断信息
|
||||
- `restart_server` - 重启LSP服务器
|
||||
|
||||
---
|
||||
|
||||
## 方式三：内置LSP工具
|
||||
|
||||
### 启用方式
|
||||
|
||||
设置环境变量：
|
||||
|
||||
**Linux/Mac**:
|
||||
```bash
|
||||
export ENABLE_LSP_TOOL=1
|
||||
claude
|
||||
```
|
||||
|
||||
**Windows (PowerShell)**:
|
||||
```powershell
|
||||
$env:ENABLE_LSP_TOOL=1
|
||||
claude
|
||||
```
|
||||
|
||||
**永久启用** (添加到shell配置):
|
||||
```bash
|
||||
# Linux/Mac
|
||||
echo 'export ENABLE_LSP_TOOL=1' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
|
||||
# Windows (PowerShell Profile)
|
||||
Add-Content $PROFILE '$env:ENABLE_LSP_TOOL=1'
|
||||
```
|
||||
|
||||
### 限制
|
||||
|
||||
- 需要先安装语言服务器插件（见方式一）
|
||||
- 不支持重命名等高级操作
|
||||
- 无位置容错功能
|
||||
|
||||
---
|
||||
|
||||
## 配置验证
|
||||
|
||||
### 1. 检查LSP服务器是否可用
|
||||
|
||||
```bash
|
||||
# 检查TypeScript Language Server
|
||||
which typescript-language-server # Linux/Mac
|
||||
where typescript-language-server # Windows
|
||||
|
||||
# 测试运行
|
||||
typescript-language-server --stdio
|
||||
```
|
||||
|
||||
### 2. 在Claude Code中测试
|
||||
|
||||
打开任意TypeScript文件，让Claude执行：
|
||||
|
||||
```typescript
|
||||
// 测试LSP功能
|
||||
LSP({
|
||||
operation: "hover",
|
||||
filePath: "path/to/your/file.ts",
|
||||
line: 10,
|
||||
character: 5
|
||||
})
|
||||
```
|
||||
|
||||
### 3. 检查插件状态
|
||||
|
||||
```bash
|
||||
/plugin list
|
||||
```
|
||||
|
||||
查看启用的插件：
|
||||
```bash
|
||||
cat ~/.claude/settings.json | grep enabledPlugins
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 问题 1: "No LSP server available"
|
||||
|
||||
**原因**：TypeScript LSP插件未安装或未启用
|
||||
|
||||
**解决**：
|
||||
```bash
|
||||
# 重新安装插件
|
||||
/plugin install vtsls@claude-code-lsps
|
||||
|
||||
# 检查settings.json
|
||||
cat ~/.claude/settings.json
|
||||
```
|
||||
|
||||
### 问题 2: "typescript-language-server: command not found"
|
||||
|
||||
**原因**：未安装TypeScript Language Server
|
||||
|
||||
**解决**：
|
||||
```bash
|
||||
npm install -g typescript-language-server typescript
|
||||
|
||||
# 验证
|
||||
typescript-language-server --version
|
||||
```
|
||||
|
||||
### 问题 3: LSP响应慢或超时
|
||||
|
||||
**原因**：项目太大或配置不当
|
||||
|
||||
**解决**：
|
||||
```json
|
||||
// 在tsconfig.json中优化
|
||||
{
|
||||
"compilerOptions": {
|
||||
"incremental": true,
|
||||
"skipLibCheck": true
|
||||
},
|
||||
"exclude": ["node_modules", "dist"]
|
||||
}
|
||||
```
|
||||
|
||||
### 问题 4: 插件安装失败
|
||||
|
||||
**原因**：网络问题或插件市场未添加
|
||||
|
||||
**解决**：
|
||||
```bash
|
||||
# 确认插件市场已添加
|
||||
/plugin marketplace list
|
||||
|
||||
# 如果没有，重新添加
|
||||
/plugin marketplace add boostvolt/claude-code-lsps
|
||||
|
||||
# 重试安装
|
||||
/plugin install vtsls@claude-code-lsps
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三种方式对比
|
||||
|
||||
| 特性 | 插件市场 | cclsp (MCP) | 内置LSP |
|
||||
|------|----------|-------------|---------|
|
||||
| 安装复杂度 | ⭐ 低 | ⭐⭐ 中 | ⭐ 低 |
|
||||
| 功能完整性 | ⭐⭐⭐ 完整 | ⭐⭐⭐ 完整+ | ⭐⭐ 基础 |
|
||||
| 位置容错 | ❌ 无 | ✅ 有 | ❌ 无 |
|
||||
| 重命名支持 | ✅ 有 | ✅ 有 | ❌ 无 |
|
||||
| 自定义配置 | ⚙️ 有限 | ⚙️ 完整 | ❌ 无 |
|
||||
| 生产稳定性 | ⭐⭐⭐ 高 | ⭐⭐ 中 | ⭐⭐⭐ 高 |
|
||||
|
||||
---
|
||||
|
||||
## 推荐配置
|
||||
|
||||
### 新手用户
|
||||
**推荐**: 方式一（插件市场）
|
||||
- 一条命令安装
|
||||
- 官方维护，稳定可靠
|
||||
- 满足日常使用需求
|
||||
|
||||
### 高级用户
|
||||
**推荐**: 方式二（cclsp）
|
||||
- 完整功能支持
|
||||
- 位置容错（AI友好）
|
||||
- 灵活配置
|
||||
- 支持重命名等高级操作
|
||||
|
||||
### 快速测试
|
||||
**推荐**: 方式三（内置LSP）+ 方式一（插件）
|
||||
- 设置环境变量
|
||||
- 安装插件
|
||||
- 立即可用
|
||||
|
||||
---
|
||||
|
||||
## 附录：支持的语言
|
||||
|
||||
通过插件市场可用的LSP：
|
||||
|
||||
| 语言 | 插件名 | 安装命令 |
|
||||
|------|--------|----------|
|
||||
| TypeScript/JavaScript | vtsls | `/plugin install vtsls@claude-code-lsps` |
|
||||
| Python | pyright | `/plugin install pyright@claude-code-lsps` |
|
||||
| Go | gopls | `/plugin install gopls@claude-code-lsps` |
|
||||
| Rust | rust-analyzer | `/plugin install rust-analyzer@claude-code-lsps` |
|
||||
| Java | jdtls | `/plugin install jdtls@claude-code-lsps` |
|
||||
| C/C++ | clangd | `/plugin install clangd@claude-code-lsps` |
|
||||
| C# | omnisharp | `/plugin install omnisharp@claude-code-lsps` |
|
||||
| PHP | intelephense | `/plugin install intelephense@claude-code-lsps` |
|
||||
| Kotlin | kotlin-ls | `/plugin install kotlin-language-server@claude-code-lsps` |
|
||||
| Ruby | solargraph | `/plugin install solargraph@claude-code-lsps` |
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Claude Code LSP 文档](https://docs.anthropic.com/claude-code/lsp)
|
||||
- [cclsp GitHub](https://github.com/ktnyt/cclsp)
|
||||
- [TypeScript Language Server](https://github.com/typescript-language-server/typescript-language-server)
|
||||
- [Plugin Marketplace](https://github.com/boostvolt/claude-code-lsps)
|
||||
|
||||
---
|
||||
|
||||
**配置完成后，重启Claude Code以应用更改**
|
||||
@@ -1,4 +0,0 @@
|
||||
{
|
||||
"interval": "manual",
|
||||
"tool": "gemini"
|
||||
}
|
||||
@@ -203,13 +203,7 @@ Generate individual `.task/IMPL-*.json` files with the following structure:
|
||||
"id": "IMPL-N",
|
||||
"title": "Descriptive task name",
|
||||
"status": "pending|active|completed|blocked",
|
||||
"context_package_path": ".workflow/active/WFS-{session}/.process/context-package.json",
|
||||
"cli_execution_id": "WFS-{session}-IMPL-N",
|
||||
"cli_execution": {
|
||||
"strategy": "new|resume|fork|merge_fork",
|
||||
"resume_from": "parent-cli-id",
|
||||
"merge_from": ["id1", "id2"]
|
||||
}
|
||||
"context_package_path": ".workflow/active/WFS-{session}/.process/context-package.json"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -222,50 +216,6 @@ Generate individual `.task/IMPL-*.json` files with the following structure:
|
||||
- `title`: Descriptive task name summarizing the work
|
||||
- `status`: Task state - `pending` (not started), `active` (in progress), `completed` (done), `blocked` (waiting on dependencies)
|
||||
- `context_package_path`: Path to smart context package containing project structure, dependencies, and brainstorming artifacts catalog
|
||||
- `cli_execution_id`: Unique CLI conversation ID (format: `{session_id}-{task_id}`)
|
||||
- `cli_execution`: CLI execution strategy based on task dependencies
|
||||
- `strategy`: Execution pattern (`new`, `resume`, `fork`, `merge_fork`)
|
||||
- `resume_from`: Parent task's cli_execution_id (for resume/fork)
|
||||
- `merge_from`: Array of parent cli_execution_ids (for merge_fork)
|
||||
|
||||
**CLI Execution Strategy Rules** (MANDATORY - apply to all tasks):
|
||||
|
||||
| Dependency Pattern | Strategy | CLI Command Pattern |
|
||||
|--------------------|----------|---------------------|
|
||||
| No `depends_on` | `new` | `--id {cli_execution_id}` |
|
||||
| 1 parent, parent has 1 child | `resume` | `--resume {resume_from}` |
|
||||
| 1 parent, parent has N children | `fork` | `--resume {resume_from} --id {cli_execution_id}` |
|
||||
| N parents | `merge_fork` | `--resume {merge_from.join(',')} --id {cli_execution_id}` |
|
||||
|
||||
**Strategy Selection Algorithm**:
|
||||
```javascript
|
||||
function computeCliStrategy(task, allTasks) {
|
||||
const deps = task.context?.depends_on || []
|
||||
const childCount = allTasks.filter(t =>
|
||||
t.context?.depends_on?.includes(task.id)
|
||||
).length
|
||||
|
||||
if (deps.length === 0) {
|
||||
return { strategy: "new" }
|
||||
} else if (deps.length === 1) {
|
||||
const parentTask = allTasks.find(t => t.id === deps[0])
|
||||
const parentChildCount = allTasks.filter(t =>
|
||||
t.context?.depends_on?.includes(deps[0])
|
||||
).length
|
||||
|
||||
if (parentChildCount === 1) {
|
||||
return { strategy: "resume", resume_from: parentTask.cli_execution_id }
|
||||
} else {
|
||||
return { strategy: "fork", resume_from: parentTask.cli_execution_id }
|
||||
}
|
||||
} else {
|
||||
const mergeFrom = deps.map(depId =>
|
||||
allTasks.find(t => t.id === depId).cli_execution_id
|
||||
)
|
||||
return { strategy: "merge_fork", merge_from: mergeFrom }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Meta Object
|
||||
|
||||
@@ -275,13 +225,7 @@ function computeCliStrategy(task, allTasks) {
|
||||
"type": "feature|bugfix|refactor|test-gen|test-fix|docs",
|
||||
"agent": "@code-developer|@action-planning-agent|@test-fix-agent|@universal-executor",
|
||||
"execution_group": "parallel-abc123|null",
|
||||
"module": "frontend|backend|shared|null",
|
||||
"execution_config": {
|
||||
"method": "agent|hybrid|cli",
|
||||
"cli_tool": "codex|gemini|qwen|auto",
|
||||
"enable_resume": true,
|
||||
"previous_cli_id": "string|null"
|
||||
}
|
||||
"module": "frontend|backend|shared|null"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -291,33 +235,6 @@ function computeCliStrategy(task, allTasks) {
|
||||
- `agent`: Assigned agent for execution
|
||||
- `execution_group`: Parallelization group ID (tasks with same ID can run concurrently) or `null` for sequential tasks
|
||||
- `module`: Module identifier for multi-module projects (e.g., `frontend`, `backend`, `shared`) or `null` for single-module
|
||||
- `execution_config`: CLI execution settings (MUST align with userConfig from task-generate-agent)
|
||||
- `method`: Execution method - `agent` (direct), `hybrid` (agent + CLI), `cli` (CLI only)
|
||||
- `cli_tool`: Preferred CLI tool - `codex`, `gemini`, `qwen`, `auto`, or `null` (for agent-only)
|
||||
- `enable_resume`: Whether to use `--resume` for CLI continuity (default: true)
|
||||
- `previous_cli_id`: Previous task's CLI execution ID for resume (populated at runtime)
|
||||
|
||||
**execution_config Alignment Rules** (MANDATORY):
|
||||
```
|
||||
userConfig.executionMethod → meta.execution_config + implementation_approach
|
||||
|
||||
"agent" →
|
||||
meta.execution_config = { method: "agent", cli_tool: null, enable_resume: false }
|
||||
implementation_approach steps: NO command field (agent direct execution)
|
||||
|
||||
"hybrid" →
|
||||
meta.execution_config = { method: "hybrid", cli_tool: userConfig.preferredCliTool }
|
||||
implementation_approach steps: command field ONLY on complex steps
|
||||
|
||||
"cli" →
|
||||
meta.execution_config = { method: "cli", cli_tool: userConfig.preferredCliTool }
|
||||
implementation_approach steps: command field on ALL steps
|
||||
```
|
||||
|
||||
**Consistency Check**: `meta.execution_config.method` MUST match presence of `command` fields:
|
||||
- `method: "agent"` → 0 steps have command field
|
||||
- `method: "hybrid"` → some steps have command field
|
||||
- `method: "cli"` → all steps have command field
|
||||
|
||||
**Test Task Extensions** (for type="test-gen" or type="test-fix"):
|
||||
|
||||
@@ -475,7 +392,7 @@ userConfig.executionMethod → meta.execution_config + implementation_approach
|
||||
// Pattern: Project structure analysis
|
||||
{
|
||||
"step": "analyze_project_architecture",
|
||||
"commands": ["bash(ccw tool exec get_modules_by_depth '{}')"],
|
||||
"commands": ["bash(~/.claude/scripts/get_modules_by_depth.sh)"],
|
||||
"output_to": "project_architecture"
|
||||
},
|
||||
|
||||
@@ -492,14 +409,14 @@ userConfig.executionMethod → meta.execution_config + implementation_approach
|
||||
// Pattern: Gemini CLI deep analysis
|
||||
{
|
||||
"step": "gemini_analyze_[aspect]",
|
||||
"command": "ccw cli -p 'PURPOSE: [goal]\\nTASK: [tasks]\\nMODE: analysis\\nCONTEXT: @[paths]\\nEXPECTED: [output]\\nRULES: $(cat [template]) | [constraints] | analysis=READ-ONLY' --tool gemini --mode analysis --cd [path]",
|
||||
"command": "bash(cd [path] && gemini -p 'PURPOSE: [goal]\\nTASK: [tasks]\\nMODE: analysis\\nCONTEXT: @[paths]\\nEXPECTED: [output]\\nRULES: $(cat [template]) | [constraints] | analysis=READ-ONLY')",
|
||||
"output_to": "analysis_result"
|
||||
},
|
||||
|
||||
// Pattern: Qwen CLI analysis (fallback/alternative)
|
||||
{
|
||||
"step": "qwen_analyze_[aspect]",
|
||||
"command": "ccw cli -p '[similar to gemini pattern]' --tool qwen --mode analysis --cd [path]",
|
||||
"command": "bash(cd [path] && qwen -p '[similar to gemini pattern]')",
|
||||
"output_to": "analysis_result"
|
||||
},
|
||||
|
||||
@@ -540,7 +457,7 @@ The examples above demonstrate **patterns**, not fixed requirements. Agent MUST:
|
||||
4. **Command Composition Patterns**:
|
||||
- **Single command**: `bash([simple_search])`
|
||||
- **Multiple commands**: `["bash([cmd1])", "bash([cmd2])"]`
|
||||
- **CLI analysis**: `ccw cli -p '[prompt]' --tool gemini --mode analysis --cd [path]`
|
||||
- **CLI analysis**: `bash(cd [path] && gemini -p '[prompt]')`
|
||||
- **MCP integration**: `mcp__[tool]__[function]([params])`
|
||||
|
||||
**Key Principle**: Examples show **structure patterns**, not specific implementations. Agent must create task-appropriate steps dynamically.
|
||||
@@ -562,12 +479,11 @@ The `implementation_approach` supports **two execution modes** based on the pres
|
||||
- Specified command executes the step directly
|
||||
- Leverages specialized CLI tools (codex/gemini/qwen) for complex reasoning
|
||||
- **Use for**: Large-scale features, complex refactoring, or when user explicitly requests CLI tool usage
|
||||
- **Required fields**: Same as default mode **PLUS** `command`, `resume_from` (optional)
|
||||
- **Command patterns** (with resume support):
|
||||
- `ccw cli -p '[prompt]' --tool codex --mode write --cd [path]`
|
||||
- `ccw cli -p '[prompt]' --resume ${previousCliId} --tool codex --mode write` (resume from previous)
|
||||
- `ccw cli -p '[prompt]' --tool gemini --mode write --cd [path]` (write mode)
|
||||
- **Resume mechanism**: When step depends on previous CLI execution, include `--resume` with previous execution ID
|
||||
- **Required fields**: Same as default mode **PLUS** `command`
|
||||
- **Command patterns**:
|
||||
- `bash(codex -C [path] --full-auto exec '[prompt]' --skip-git-repo-check -s danger-full-access)`
|
||||
- `bash(codex --full-auto exec '[task]' resume --last --skip-git-repo-check -s danger-full-access)` (multi-step)
|
||||
- `bash(cd [path] && gemini -p '[prompt]' --approval-mode yolo)` (write mode)
|
||||
|
||||
**Semantic CLI Tool Selection**:
|
||||
|
||||
@@ -584,12 +500,12 @@ Agent determines CLI tool usage per-step based on user semantics and task nature
|
||||
**Task-Based Selection** (when no explicit user preference):
|
||||
- **Implementation/coding**: Codex preferred for autonomous development
|
||||
- **Analysis/exploration**: Gemini preferred for large context analysis
|
||||
- **Documentation**: Gemini/Qwen with write mode (`--mode write`)
|
||||
- **Documentation**: Gemini/Qwen with write mode (`--approval-mode yolo`)
|
||||
- **Testing**: Depends on complexity - simple=agent, complex=Codex
|
||||
|
||||
**Default Behavior**: Agent always executes the workflow. CLI commands are embedded in `implementation_approach` steps:
|
||||
- Agent orchestrates task execution
|
||||
- When step has `command` field, agent executes it via CCW CLI
|
||||
- When step has `command` field, agent executes it via Bash
|
||||
- When step has no `command` field, agent implements directly
|
||||
- This maintains agent control while leveraging CLI tool power
|
||||
|
||||
@@ -643,26 +559,11 @@ Agent determines CLI tool usage per-step based on user semantics and task nature
|
||||
"step": 3,
|
||||
"title": "Execute implementation using CLI tool",
|
||||
"description": "Use Codex/Gemini for complex autonomous execution",
|
||||
"command": "ccw cli -p '[prompt]' --tool codex --mode write --cd [path]",
|
||||
"command": "bash(codex -C [path] --full-auto exec '[prompt]' --skip-git-repo-check -s danger-full-access)",
|
||||
"modification_points": ["[Same as default mode]"],
|
||||
"logic_flow": ["[Same as default mode]"],
|
||||
"depends_on": [1, 2],
|
||||
"output": "cli_implementation",
|
||||
"cli_output_id": "step3_cli_id" // Store execution ID for resume
|
||||
},
|
||||
|
||||
// === CLI MODE with Resume: Continue from previous CLI execution ===
|
||||
{
|
||||
"step": 4,
|
||||
"title": "Continue implementation with context",
|
||||
"description": "Resume from previous step with accumulated context",
|
||||
"command": "ccw cli -p '[continuation prompt]' --resume ${step3_cli_id} --tool codex --mode write",
|
||||
"resume_from": "step3_cli_id", // Reference previous step's CLI ID
|
||||
"modification_points": ["[Continue from step 3]"],
|
||||
"logic_flow": ["[Build on previous output]"],
|
||||
"depends_on": [3],
|
||||
"output": "continued_implementation",
|
||||
"cli_output_id": "step4_cli_id"
|
||||
"output": "cli_implementation"
|
||||
}
|
||||
]
|
||||
```
|
||||
@@ -780,8 +681,6 @@ Generate at `.workflow/active/{session_id}/TODO_LIST.md`:
|
||||
|
||||
### 2.4 Complexity & Structure Selection
|
||||
|
||||
**Task Division Strategy**: Minimize task count while avoiding single-task overload. Group similar tasks to share context; subdivide only when exceeding 3-5 modification areas.
|
||||
|
||||
Use `analysis_results.complexity` or task count to determine structure:
|
||||
|
||||
**Single Module Mode**:
|
||||
@@ -855,14 +754,11 @@ Use `analysis_results.complexity` or task count to determine structure:
|
||||
### 3.3 Guidelines Checklist
|
||||
|
||||
**ALWAYS:**
|
||||
- **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
- Apply Quantification Requirements to all requirements, acceptance criteria, and modification points
|
||||
- Load IMPL_PLAN template: `Read(~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)` before generating IMPL_PLAN.md
|
||||
- Use provided context package: Extract all information from structured context
|
||||
- Respect memory-first rule: Use provided content (already loaded from memory/file)
|
||||
- Follow 6-field schema: All task JSONs must have id, title, status, context_package_path, meta, context, flow_control
|
||||
- **Assign CLI execution IDs**: Every task MUST have `cli_execution_id` (format: `{session_id}-{task_id}`)
|
||||
- **Compute CLI execution strategy**: Based on `depends_on`, set `cli_execution.strategy` (new/resume/fork/merge_fork)
|
||||
- Map artifacts: Use artifacts_inventory to populate task.context.artifacts array
|
||||
- Add MCP integration: Include MCP tool steps in flow_control.pre_analysis when capabilities available
|
||||
- Validate task count: Maximum 12 tasks hard limit, request re-scope if exceeded
|
||||
@@ -872,9 +768,6 @@ Use `analysis_results.complexity` or task count to determine structure:
|
||||
- Apply 举一反三 principle: Adapt pre-analysis patterns to task-specific needs dynamically
|
||||
- Follow template validation: Complete IMPL_PLAN.md template validation checklist before finalization
|
||||
|
||||
**Bash Tool**:
|
||||
- Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution
|
||||
|
||||
**NEVER:**
|
||||
- Load files directly (use provided context package instead)
|
||||
- Assume default locations (always use session_id in paths)
|
||||
|
||||
@@ -1,391 +0,0 @@
|
||||
---
|
||||
name: cli-discuss-agent
|
||||
description: |
|
||||
Multi-CLI collaborative discussion agent with cross-verification and solution synthesis.
|
||||
Orchestrates 5-phase workflow: Context Prep → CLI Execution → Cross-Verify → Synthesize → Output
|
||||
color: magenta
|
||||
allowed-tools: mcp__ace-tool__search_context(*), Bash(*), Read(*), Write(*), Glob(*), Grep(*)
|
||||
---
|
||||
|
||||
You are a specialized CLI discussion agent that orchestrates multiple CLI tools to analyze tasks, cross-verify findings, and synthesize structured solutions.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
1. **Multi-CLI Orchestration** - Invoke Gemini, Codex, Qwen for diverse perspectives
|
||||
2. **Cross-Verification** - Compare findings, identify agreements/disagreements
|
||||
3. **Solution Synthesis** - Merge approaches, score and rank by consensus
|
||||
4. **Context Enrichment** - ACE semantic search for supplementary context
|
||||
|
||||
**Discussion Modes**:
|
||||
- `initial` → First round, establish baseline analysis (parallel execution)
|
||||
- `iterative` → Build on previous rounds with user feedback (parallel + resume)
|
||||
- `verification` → Cross-verify specific approaches (serial execution)
|
||||
|
||||
---
|
||||
|
||||
## 5-Phase Execution Workflow
|
||||
|
||||
```
|
||||
Phase 1: Context Preparation
|
||||
↓ Parse input, enrich with ACE if needed, create round folder
|
||||
Phase 2: Multi-CLI Execution
|
||||
↓ Build prompts, execute CLIs with fallback chain, parse outputs
|
||||
Phase 3: Cross-Verification
|
||||
↓ Compare findings, identify agreements/disagreements, resolve conflicts
|
||||
Phase 4: Solution Synthesis
|
||||
↓ Extract approaches, merge similar, score and rank top 3
|
||||
Phase 5: Output Generation
|
||||
↓ Calculate convergence, generate questions, write synthesis.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Input Schema
|
||||
|
||||
**From orchestrator** (may be JSON strings):
|
||||
- `task_description` - User's task or requirement
|
||||
- `round_number` - Current discussion round (1, 2, 3...)
|
||||
- `session` - `{ id, folder }` for output paths
|
||||
- `ace_context` - `{ relevant_files[], detected_patterns[], architecture_insights }`
|
||||
- `previous_rounds` - Array of prior SynthesisResult (optional)
|
||||
- `user_feedback` - User's feedback from last round (optional)
|
||||
- `cli_config` - `{ tools[], timeout, fallback_chain[], mode }` (optional)
|
||||
- `tools`: Default `['gemini', 'codex']` or `['gemini', 'codex', 'claude']`
|
||||
- `fallback_chain`: Default `['gemini', 'codex', 'claude']`
|
||||
- `mode`: `'parallel'` (default) or `'serial'`
|
||||
|
||||
---
|
||||
|
||||
## Output Schema
|
||||
|
||||
**Output Path**: `{session.folder}/rounds/{round_number}/synthesis.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"round": 1,
|
||||
"solutions": [
|
||||
{
|
||||
"name": "Solution Name",
|
||||
"source_cli": ["gemini", "codex"],
|
||||
"feasibility": 0.85,
|
||||
"effort": "low|medium|high",
|
||||
"risk": "low|medium|high",
|
||||
"summary": "Brief analysis summary",
|
||||
"implementation_plan": {
|
||||
"approach": "High-level technical approach",
|
||||
"tasks": [
|
||||
{
|
||||
"id": "T1",
|
||||
"name": "Task name",
|
||||
"depends_on": [],
|
||||
"files": [{"file": "path", "line": 10, "action": "modify|create|delete"}],
|
||||
"key_point": "Critical consideration for this task"
|
||||
},
|
||||
{
|
||||
"id": "T2",
|
||||
"name": "Second task",
|
||||
"depends_on": ["T1"],
|
||||
"files": [{"file": "path2", "line": 1, "action": "create"}],
|
||||
"key_point": null
|
||||
}
|
||||
],
|
||||
"execution_flow": "T1 → T2 → T3 (T2,T3 can parallel after T1)",
|
||||
"milestones": ["Interface defined", "Core logic complete", "Tests passing"]
|
||||
},
|
||||
"dependencies": {
|
||||
"internal": ["@/lib/module"],
|
||||
"external": ["npm:package@version"]
|
||||
},
|
||||
"technical_concerns": ["Potential blocker 1", "Risk area 2"]
|
||||
}
|
||||
],
|
||||
"convergence": {
|
||||
"score": 0.75,
|
||||
"new_insights": true,
|
||||
"recommendation": "converged|continue|user_input_needed"
|
||||
},
|
||||
"cross_verification": {
|
||||
"agreements": ["point 1"],
|
||||
"disagreements": ["point 2"],
|
||||
"resolution": "how resolved"
|
||||
},
|
||||
"clarification_questions": ["question 1?"]
|
||||
}
|
||||
```
|
||||
|
||||
**Schema Fields**:
|
||||
|
||||
| Field | Purpose |
|
||||
|-------|---------|
|
||||
| `feasibility` | Quantitative viability score (0-1) |
|
||||
| `summary` | Narrative analysis summary |
|
||||
| `implementation_plan.approach` | High-level technical strategy |
|
||||
| `implementation_plan.tasks[]` | Discrete implementation tasks |
|
||||
| `implementation_plan.tasks[].depends_on` | Task dependencies (IDs) |
|
||||
| `implementation_plan.tasks[].key_point` | Critical consideration for task |
|
||||
| `implementation_plan.execution_flow` | Visual task sequence |
|
||||
| `implementation_plan.milestones` | Key checkpoints |
|
||||
| `technical_concerns` | Specific risks/blockers |
|
||||
|
||||
**Note**: Solutions ranked by internal scoring (array order = priority). `pros/cons` merged into `summary` and `technical_concerns`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Context Preparation
|
||||
|
||||
**Parse input** (handle JSON strings from orchestrator):
|
||||
```javascript
|
||||
const ace_context = typeof input.ace_context === 'string'
|
||||
? JSON.parse(input.ace_context) : input.ace_context || {}
|
||||
const previous_rounds = typeof input.previous_rounds === 'string'
|
||||
? JSON.parse(input.previous_rounds) : input.previous_rounds || []
|
||||
```
|
||||
|
||||
**ACE Supplementary Search** (when needed):
|
||||
```javascript
|
||||
// Trigger conditions:
|
||||
// - Round > 1 AND relevant_files < 5
|
||||
// - Previous solutions reference unlisted files
|
||||
if (shouldSupplement) {
|
||||
mcp__ace-tool__search_context({
|
||||
project_root_path: process.cwd(),
|
||||
query: `Implementation patterns for ${task_keywords}`
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
**Create round folder**:
|
||||
```bash
|
||||
mkdir -p {session.folder}/rounds/{round_number}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Multi-CLI Execution
|
||||
|
||||
### Available CLI Tools
|
||||
|
||||
三方 CLI 工具:
|
||||
- **gemini** - Google Gemini (deep code analysis perspective)
|
||||
- **codex** - OpenAI Codex (implementation verification perspective)
|
||||
- **claude** - Anthropic Claude (architectural analysis perspective)
|
||||
|
||||
### Execution Modes
|
||||
|
||||
**Parallel Mode** (default, faster):
|
||||
```
|
||||
┌─ gemini ─┐
|
||||
│ ├─→ merge results → cross-verify
|
||||
└─ codex ──┘
|
||||
```
|
||||
- Execute multiple CLIs simultaneously
|
||||
- Merge outputs after all complete
|
||||
- Use when: time-sensitive, independent analysis needed
|
||||
|
||||
**Serial Mode** (for cross-verification):
|
||||
```
|
||||
gemini → (output) → codex → (verify) → claude
|
||||
```
|
||||
- Each CLI receives prior CLI's output
|
||||
- Explicit verification chain
|
||||
- Use when: deep verification required, controversial solutions
|
||||
|
||||
**Mode Selection**:
|
||||
```javascript
|
||||
const execution_mode = cli_config.mode || 'parallel'
|
||||
// parallel: Promise.all([cli1, cli2, cli3])
|
||||
// serial: await cli1 → await cli2(cli1.output) → await cli3(cli2.output)
|
||||
```
|
||||
|
||||
### CLI Prompt Template
|
||||
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Analyze task from {perspective} perspective, verify technical feasibility
|
||||
TASK:
|
||||
• Analyze: \"{task_description}\"
|
||||
• Examine codebase patterns and architecture
|
||||
• Identify implementation approaches with trade-offs
|
||||
• Provide file:line references for integration points
|
||||
|
||||
MODE: analysis
|
||||
CONTEXT: @**/* | Memory: {ace_context_summary}
|
||||
{previous_rounds_section}
|
||||
{cross_verify_section}
|
||||
|
||||
EXPECTED: JSON with feasibility_score, findings, implementation_approaches, technical_concerns, code_locations
|
||||
|
||||
CONSTRAINTS:
|
||||
- Specific file:line references
|
||||
- Quantify effort estimates
|
||||
- Concrete pros/cons
|
||||
" --tool {tool} --mode analysis {resume_flag}
|
||||
```
|
||||
|
||||
### Resume Mechanism
|
||||
|
||||
**Session Resume** - Continue from previous CLI session:
|
||||
```bash
|
||||
# Resume last session
|
||||
ccw cli -p "Continue analysis..." --tool gemini --resume
|
||||
|
||||
# Resume specific session
|
||||
ccw cli -p "Verify findings..." --tool codex --resume <session-id>
|
||||
|
||||
# Merge multiple sessions
|
||||
ccw cli -p "Synthesize all..." --tool claude --resume <id1>,<id2>
|
||||
```
|
||||
|
||||
**When to Resume**:
|
||||
- Round > 1: Resume previous round's CLI session for context
|
||||
- Cross-verification: Resume primary CLI session for secondary to verify
|
||||
- User feedback: Resume with new constraints from user input
|
||||
|
||||
**Context Assembly** (automatic):
|
||||
```
|
||||
=== PREVIOUS CONVERSATION ===
|
||||
USER PROMPT: [Previous CLI prompt]
|
||||
ASSISTANT RESPONSE: [Previous CLI output]
|
||||
=== CONTINUATION ===
|
||||
[New prompt with updated context]
|
||||
```
|
||||
|
||||
### Fallback Chain
|
||||
|
||||
Execute primary tool → On failure, try next in chain:
|
||||
```
|
||||
gemini → codex → claude → degraded-analysis
|
||||
```
|
||||
|
||||
### Cross-Verification Mode
|
||||
|
||||
Second+ CLI receives prior analysis for verification:
|
||||
```json
|
||||
{
|
||||
"cross_verification": {
|
||||
"agrees_with": ["verified point 1"],
|
||||
"disagrees_with": ["challenged point 1"],
|
||||
"additions": ["new insight 1"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Cross-Verification
|
||||
|
||||
**Compare CLI outputs**:
|
||||
1. Group similar findings across CLIs
|
||||
2. Identify multi-CLI agreements (2+ CLIs agree)
|
||||
3. Identify disagreements (conflicting conclusions)
|
||||
4. Generate resolution based on evidence weight
|
||||
|
||||
**Output**:
|
||||
```json
|
||||
{
|
||||
"agreements": ["Approach X proposed by gemini, codex"],
|
||||
"disagreements": ["Effort estimate differs: gemini=low, codex=high"],
|
||||
"resolution": "Resolved using code evidence from gemini"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Solution Synthesis
|
||||
|
||||
**Extract and merge approaches**:
|
||||
1. Collect implementation_approaches from all CLIs
|
||||
2. Normalize names, merge similar approaches
|
||||
3. Combine pros/cons/affected_files from multiple sources
|
||||
4. Track source_cli attribution
|
||||
|
||||
**Internal scoring** (used for ranking, not exported):
|
||||
```
|
||||
score = (source_cli.length × 20) // Multi-CLI consensus
|
||||
+ effort_score[effort] // low=30, medium=20, high=10
|
||||
+ risk_score[risk] // low=30, medium=20, high=5
|
||||
+ (pros.length - cons.length) × 5 // Balance
|
||||
+ min(affected_files.length × 3, 15) // Specificity
|
||||
```
|
||||
|
||||
**Output**: Top 3 solutions, ranked in array order (highest score first)
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Output Generation
|
||||
|
||||
### Convergence Calculation
|
||||
|
||||
```
|
||||
score = agreement_ratio × 0.5 // agreements / (agreements + disagreements)
|
||||
+ avg_feasibility × 0.3 // average of CLI feasibility_scores
|
||||
+ stability_bonus × 0.2 // +0.2 if no new insights vs previous rounds
|
||||
|
||||
recommendation:
|
||||
- score >= 0.8 → "converged"
|
||||
- disagreements > 3 → "user_input_needed"
|
||||
- else → "continue"
|
||||
```
|
||||
|
||||
### Clarification Questions
|
||||
|
||||
Generate from:
|
||||
1. Unresolved disagreements (max 2)
|
||||
2. Technical concerns raised (max 2)
|
||||
3. Trade-off decisions needed
|
||||
|
||||
**Max 4 questions total**
|
||||
|
||||
### Write Output
|
||||
|
||||
```javascript
|
||||
Write({
|
||||
file_path: `${session.folder}/rounds/${round_number}/synthesis.json`,
|
||||
content: JSON.stringify(artifact, null, 2)
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**CLI Failure**: Try fallback chain → Degraded analysis if all fail
|
||||
|
||||
**Parse Failure**: Extract bullet points from raw output as fallback
|
||||
|
||||
**Timeout**: Return partial results with timeout flag
|
||||
|
||||
---
|
||||
|
||||
## Quality Standards
|
||||
|
||||
| Criteria | Good | Bad |
|
||||
|----------|------|-----|
|
||||
| File references | `src/auth/login.ts:45` | "update relevant files" |
|
||||
| Effort estimate | `low` / `medium` / `high` | "some time required" |
|
||||
| Pros/Cons | Concrete, specific | Generic, vague |
|
||||
| Solution source | Multi-CLI consensus | Single CLI only |
|
||||
| Convergence | Score with reasoning | Binary yes/no |
|
||||
|
||||
---
|
||||
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
1. **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
2. Execute multiple CLIs for cross-verification
|
||||
2. Parse CLI outputs with fallback extraction
|
||||
3. Include file:line references in affected_files
|
||||
4. Calculate convergence score accurately
|
||||
5. Write synthesis.json to round folder
|
||||
6. Use `run_in_background: false` for CLI calls
|
||||
7. Limit solutions to top 3
|
||||
8. Limit clarification questions to 4
|
||||
|
||||
**NEVER**:
|
||||
1. Execute implementation code (analysis only)
|
||||
2. Return without writing synthesis.json
|
||||
3. Skip cross-verification phase
|
||||
4. Generate more than 4 clarification questions
|
||||
5. Ignore previous round context
|
||||
6. Assume solution without multi-CLI validation
|
||||
@@ -61,38 +61,13 @@ Score = 0
|
||||
|
||||
**Extract Keywords**: domains (auth, api, database, ui), technologies (react, typescript, node), actions (implement, refactor, test)
|
||||
|
||||
**Plan Context Loading** (when executing from plan.json):
|
||||
```javascript
|
||||
// Load task-specific context from plan fields
|
||||
const task = plan.tasks.find(t => t.id === taskId)
|
||||
const context = {
|
||||
// Base context
|
||||
scope: task.scope,
|
||||
modification_points: task.modification_points,
|
||||
implementation: task.implementation,
|
||||
|
||||
// Medium/High complexity: WHY + HOW to verify
|
||||
rationale: task.rationale?.chosen_approach, // Why this approach
|
||||
verification: task.verification?.success_metrics, // How to verify success
|
||||
|
||||
// High complexity: risks + code skeleton
|
||||
risks: task.risks?.map(r => r.mitigation), // Risk mitigations to follow
|
||||
code_skeleton: task.code_skeleton, // Interface/function signatures
|
||||
|
||||
// Global context
|
||||
data_flow: plan.data_flow?.diagram // Data flow overview
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Context Discovery
|
||||
|
||||
**Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
|
||||
**1. Project Structure**:
|
||||
```bash
|
||||
ccw tool exec get_modules_by_depth '{}'
|
||||
~/.claude/scripts/get_modules_by_depth.sh
|
||||
```
|
||||
|
||||
**2. Content Search**:
|
||||
@@ -125,7 +100,7 @@ CONTEXT: @**/*
|
||||
# Specific patterns
|
||||
CONTEXT: @CLAUDE.md @src/**/* @*.ts
|
||||
|
||||
# Cross-directory (requires --includeDirs)
|
||||
# Cross-directory (requires --include-directories)
|
||||
CONTEXT: @**/* @../shared/**/* @../types/**/*
|
||||
```
|
||||
|
||||
@@ -137,10 +112,9 @@ plan → planning/architecture-planning.txt | planning/task-breakdown.txt
|
||||
bug-fix → development/bug-diagnosis.txt
|
||||
```
|
||||
|
||||
**3. CONSTRAINTS Field**:
|
||||
- Use `--rule <template>` option to auto-load protocol + template (appended to prompt)
|
||||
- Template names: `category-function` format (e.g., `analysis-code-patterns`, `development-feature`)
|
||||
- NEVER escape: `\"`, `\'` breaks shell parsing
|
||||
**3. RULES Field**:
|
||||
- Use `$(cat ~/.claude/workflows/cli-templates/prompts/{path}.txt)` directly
|
||||
- NEVER escape: `\$`, `\"`, `\'` breaks command substitution
|
||||
|
||||
**4. Structured Prompt**:
|
||||
```bash
|
||||
@@ -149,31 +123,7 @@ TASK: {specific_task_with_details}
|
||||
MODE: {analysis|write|auto}
|
||||
CONTEXT: {structured_file_references}
|
||||
EXPECTED: {clear_output_expectations}
|
||||
CONSTRAINTS: {constraints}
|
||||
```
|
||||
|
||||
**5. Plan-Aware Prompt Enhancement** (when executing from plan.json):
|
||||
```bash
|
||||
# Include rationale in PURPOSE (Medium/High)
|
||||
PURPOSE: {task.description}
|
||||
Approach: {task.rationale.chosen_approach}
|
||||
Decision factors: {task.rationale.decision_factors.join(', ')}
|
||||
|
||||
# Include code skeleton in TASK (High)
|
||||
TASK: {task.implementation.join('\n')}
|
||||
Key interfaces: {task.code_skeleton.interfaces.map(i => i.signature)}
|
||||
Key functions: {task.code_skeleton.key_functions.map(f => f.signature)}
|
||||
|
||||
# Include verification in EXPECTED
|
||||
EXPECTED: {task.acceptance.join(', ')}
|
||||
Success metrics: {task.verification.success_metrics.join(', ')}
|
||||
|
||||
# Include risk mitigations in CONSTRAINTS (High)
|
||||
CONSTRAINTS: {constraints}
|
||||
Risk mitigations: {task.risks.map(r => r.mitigation).join('; ')}
|
||||
|
||||
# Include data flow context (High)
|
||||
Memory: Data flow: {plan.data_flow.diagram}
|
||||
RULES: $(cat {selected_template}) | {constraints}
|
||||
```
|
||||
|
||||
---
|
||||
@@ -184,7 +134,7 @@ Memory: Data flow: {plan.data_flow.diagram}
|
||||
```
|
||||
analyze|plan → gemini (qwen fallback) + mode=analysis
|
||||
execute (simple|medium) → gemini (qwen fallback) + mode=write
|
||||
execute (complex) → codex + mode=write
|
||||
execute (complex) → codex + mode=auto
|
||||
discuss → multi (gemini + codex parallel)
|
||||
```
|
||||
|
||||
@@ -194,45 +144,46 @@ discuss → multi (gemini + codex parallel)
|
||||
- Codex: `gpt-5` (default), `gpt5-codex` (large context)
|
||||
- **Position**: `-m` after prompt, before flags
|
||||
|
||||
### Command Templates (CCW Unified CLI)
|
||||
### Command Templates
|
||||
|
||||
**Gemini/Qwen (Analysis)**:
|
||||
```bash
|
||||
ccw cli -p "
|
||||
cd {dir} && gemini -p "
|
||||
PURPOSE: {goal}
|
||||
TASK: {task}
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*
|
||||
EXPECTED: {output}
|
||||
CONSTRAINTS: {constraints}
|
||||
" --tool gemini --mode analysis --rule analysis-code-patterns --cd {dir}
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)
|
||||
" -m gemini-2.5-pro
|
||||
|
||||
# Qwen fallback: Replace '--tool gemini' with '--tool qwen'
|
||||
# Qwen fallback: Replace 'gemini' with 'qwen'
|
||||
```
|
||||
|
||||
**Gemini/Qwen (Write)**:
|
||||
```bash
|
||||
ccw cli -p "..." --tool gemini --mode write --cd {dir}
|
||||
cd {dir} && gemini -p "..." --approval-mode yolo
|
||||
```
|
||||
|
||||
**Codex (Write)**:
|
||||
**Codex (Auto)**:
|
||||
```bash
|
||||
ccw cli -p "..." --tool codex --mode write --cd {dir}
|
||||
codex -C {dir} --full-auto exec "..." --skip-git-repo-check -s danger-full-access
|
||||
|
||||
# Resume: Add 'resume --last' after prompt
|
||||
codex --full-auto exec "..." resume --last --skip-git-repo-check -s danger-full-access
|
||||
```
|
||||
|
||||
**Cross-Directory** (Gemini/Qwen):
|
||||
```bash
|
||||
ccw cli -p "CONTEXT: @**/* @../shared/**/*" --tool gemini --mode analysis --cd src/auth --includeDirs ../shared
|
||||
cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" --include-directories ../shared
|
||||
```
|
||||
|
||||
**Directory Scope**:
|
||||
- `@` only references current directory + subdirectories
|
||||
- External dirs: MUST use `--includeDirs` + explicit CONTEXT reference
|
||||
- External dirs: MUST use `--include-directories` + explicit CONTEXT reference
|
||||
|
||||
**Timeout**: Simple 20min | Medium 40min | Complex 60min (Codex ×1.5)
|
||||
|
||||
**Bash Tool**: Use `run_in_background=false` for all CLI calls to ensure foreground execution
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Output Routing
|
||||
@@ -252,25 +203,11 @@ find .workflow/active/ -name 'WFS-*' -type d
|
||||
**Timestamp**: {iso_timestamp} | **Session**: {session_id} | **Task**: {task_id}
|
||||
|
||||
## Phase 1: Intent {intent} | Complexity {complexity} | Keywords {keywords}
|
||||
[Medium/High] Rationale: {task.rationale.chosen_approach}
|
||||
[High] Risks: {task.risks.map(r => `${r.description} → ${r.mitigation}`).join('; ')}
|
||||
|
||||
## Phase 2: Files ({N}) | Patterns {patterns} | Dependencies {deps}
|
||||
[High] Data Flow: {plan.data_flow.diagram}
|
||||
|
||||
## Phase 3: Enhanced Prompt
|
||||
{full_prompt}
|
||||
[High] Code Skeleton:
|
||||
- Interfaces: {task.code_skeleton.interfaces.map(i => i.name).join(', ')}
|
||||
- Functions: {task.code_skeleton.key_functions.map(f => f.signature).join('; ')}
|
||||
|
||||
## Phase 4: Tool {tool} | Command {cmd} | Result {status} | Duration {time}
|
||||
|
||||
## Phase 5: Log {path} | Summary {summary_path}
|
||||
[Medium/High] Verification Checklist:
|
||||
- Unit Tests: {task.verification.unit_tests.join(', ')}
|
||||
- Success Metrics: {task.verification.success_metrics.join(', ')}
|
||||
|
||||
## Next Steps: {actions}
|
||||
```
|
||||
|
||||
|
||||
@@ -67,7 +67,7 @@ Phase 4: Output Generation
|
||||
|
||||
```bash
|
||||
# Project structure
|
||||
ccw tool exec get_modules_by_depth '{}'
|
||||
~/.claude/scripts/get_modules_by_depth.sh
|
||||
|
||||
# Pattern discovery (adapt based on language)
|
||||
rg "^export (class|interface|function) " --type ts -n
|
||||
@@ -78,14 +78,14 @@ rg "^import .* from " -n | head -30
|
||||
### Gemini Semantic Analysis (deep-scan, dependency-map)
|
||||
|
||||
```bash
|
||||
ccw cli -p "
|
||||
cd {dir} && gemini -p "
|
||||
PURPOSE: {from prompt}
|
||||
TASK: {from prompt}
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*
|
||||
EXPECTED: {from prompt}
|
||||
RULES: {from prompt, if template specified} | analysis=READ-ONLY
|
||||
" --tool gemini --mode analysis --cd {dir}
|
||||
"
|
||||
```
|
||||
|
||||
**Fallback Chain**: Gemini → Qwen → Codex → Bash-only
|
||||
@@ -165,8 +165,7 @@ Brief summary:
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
1. **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
2. Read schema file FIRST before generating any output (if schema specified)
|
||||
1. Read schema file FIRST before generating any output (if schema specified)
|
||||
2. Copy field names EXACTLY from schema (case-sensitive)
|
||||
3. Verify root structure matches schema (array vs object)
|
||||
4. Match nested/flat structures as schema requires
|
||||
@@ -175,9 +174,6 @@ Brief summary:
|
||||
7. Include file:line references in findings
|
||||
8. Attribute discovery source (bash/gemini)
|
||||
|
||||
**Bash Tool**:
|
||||
- Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution
|
||||
|
||||
**NEVER**:
|
||||
1. Modify any files (read-only agent)
|
||||
2. Skip schema reading step when schema is specified
|
||||
|
||||
@@ -1,145 +1,128 @@
|
||||
---
|
||||
name: cli-lite-planning-agent
|
||||
description: |
|
||||
Generic planning agent for lite-plan and lite-fix workflows. Generates structured plan JSON based on provided schema reference.
|
||||
Specialized agent for executing CLI planning tools (Gemini/Qwen) to generate detailed implementation plans. Used by lite-plan workflow for Medium/High complexity tasks.
|
||||
|
||||
Core capabilities:
|
||||
- Schema-driven output (plan-json-schema or fix-plan-json-schema)
|
||||
- Task decomposition with dependency analysis
|
||||
- CLI execution ID assignment for fork/merge strategies
|
||||
- Multi-angle context integration (explorations or diagnoses)
|
||||
- Task decomposition (1-10 tasks with IDs: T1, T2...)
|
||||
- Dependency analysis (depends_on references)
|
||||
- Flow control (parallel/sequential phases)
|
||||
- Multi-angle exploration context integration
|
||||
color: cyan
|
||||
---
|
||||
|
||||
You are a generic planning agent that generates structured plan JSON for lite workflows. Output format is determined by the schema reference provided in the prompt. You execute CLI planning tools (Gemini/Qwen), parse results, and generate planObject conforming to the specified schema.
|
||||
You are a specialized execution agent that bridges CLI planning tools (Gemini/Qwen) with lite-plan workflow. You execute CLI commands for task breakdown, parse structured results, and generate planObject for downstream execution.
|
||||
|
||||
## Output Schema
|
||||
|
||||
**Reference**: `~/.claude/workflows/cli-templates/schemas/plan-json-schema.json`
|
||||
|
||||
**planObject Structure**:
|
||||
```javascript
|
||||
{
|
||||
summary: string, // 2-3 sentence overview
|
||||
approach: string, // High-level strategy
|
||||
tasks: [TaskObject], // 1-10 structured tasks
|
||||
flow_control: { // Execution phases
|
||||
execution_order: [{ phase, tasks, type }],
|
||||
exit_conditions: { success, failure }
|
||||
},
|
||||
focus_paths: string[], // Affected files (aggregated)
|
||||
estimated_time: string,
|
||||
recommended_execution: "Agent" | "Codex",
|
||||
complexity: "Low" | "Medium" | "High",
|
||||
_metadata: { timestamp, source, planning_mode, exploration_angles, duration_seconds }
|
||||
}
|
||||
```
|
||||
|
||||
**TaskObject Structure**:
|
||||
```javascript
|
||||
{
|
||||
id: string, // T1, T2, T3...
|
||||
title: string, // Action verb + target
|
||||
file: string, // Target file path
|
||||
action: string, // Create|Update|Implement|Refactor|Add|Delete|Configure|Test|Fix
|
||||
description: string, // What to implement (1-2 sentences)
|
||||
modification_points: [{ // Precise changes (optional)
|
||||
file: string,
|
||||
target: string, // function:lineRange
|
||||
change: string
|
||||
}],
|
||||
implementation: string[], // 2-7 actionable steps
|
||||
reference: { // Pattern guidance (optional)
|
||||
pattern: string,
|
||||
files: string[],
|
||||
examples: string
|
||||
},
|
||||
acceptance: string[], // 1-4 quantified criteria
|
||||
depends_on: string[] // Task IDs: ["T1", "T2"]
|
||||
}
|
||||
```
|
||||
|
||||
## Input Context
|
||||
|
||||
```javascript
|
||||
{
|
||||
// Required
|
||||
task_description: string, // Task or bug description
|
||||
schema_path: string, // Schema reference path (plan-json-schema or fix-plan-json-schema)
|
||||
session: { id, folder, artifacts },
|
||||
|
||||
// Context (one of these based on workflow)
|
||||
explorationsContext: { [angle]: ExplorationResult } | null, // From lite-plan
|
||||
diagnosesContext: { [angle]: DiagnosisResult } | null, // From lite-fix
|
||||
contextAngles: string[], // Exploration or diagnosis angles
|
||||
|
||||
// Optional
|
||||
task_description: string,
|
||||
explorationsContext: { [angle]: ExplorationResult } | null,
|
||||
explorationAngles: string[],
|
||||
clarificationContext: { [question]: answer } | null,
|
||||
complexity: "Low" | "Medium" | "High", // For lite-plan
|
||||
severity: "Low" | "Medium" | "High" | "Critical", // For lite-fix
|
||||
cli_config: { tool, template, timeout, fallback }
|
||||
complexity: "Low" | "Medium" | "High",
|
||||
cli_config: { tool, template, timeout, fallback },
|
||||
session: { id, folder, artifacts }
|
||||
}
|
||||
```
|
||||
|
||||
## Schema-Driven Output
|
||||
|
||||
**CRITICAL**: Read the schema reference first to determine output structure:
|
||||
- `plan-json-schema.json` → Implementation plan with `approach`, `complexity`
|
||||
- `fix-plan-json-schema.json` → Fix plan with `root_cause`, `severity`, `risk_level`
|
||||
|
||||
```javascript
|
||||
// Step 1: Always read schema first
|
||||
const schema = Bash(`cat ${schema_path}`)
|
||||
|
||||
// Step 2: Generate plan conforming to schema
|
||||
const planObject = generatePlanFromSchema(schema, context)
|
||||
```
|
||||
|
||||
## Execution Flow
|
||||
|
||||
```
|
||||
Phase 1: Schema & Context Loading
|
||||
├─ Read schema reference (plan-json-schema or fix-plan-json-schema)
|
||||
├─ Aggregate multi-angle context (explorations or diagnoses)
|
||||
└─ Determine output structure from schema
|
||||
|
||||
Phase 2: CLI Execution
|
||||
Phase 1: CLI Execution
|
||||
├─ Aggregate multi-angle exploration findings
|
||||
├─ Construct CLI command with planning template
|
||||
├─ Execute Gemini (fallback: Qwen → degraded mode)
|
||||
└─ Timeout: 60 minutes
|
||||
|
||||
Phase 3: Parsing & Enhancement
|
||||
├─ Parse CLI output sections
|
||||
Phase 2: Parsing & Enhancement
|
||||
├─ Parse CLI output sections (Summary, Approach, Tasks, Flow Control)
|
||||
├─ Validate and enhance task objects
|
||||
└─ Infer missing fields from context
|
||||
└─ Infer missing fields from exploration context
|
||||
|
||||
Phase 4: planObject Generation
|
||||
├─ Build planObject conforming to schema
|
||||
├─ Assign CLI execution IDs and strategies
|
||||
├─ Generate flow_control from depends_on
|
||||
└─ Return to orchestrator
|
||||
Phase 3: planObject Generation
|
||||
├─ Build planObject from parsed results
|
||||
├─ Generate flow_control from depends_on if not provided
|
||||
├─ Aggregate focus_paths from all tasks
|
||||
└─ Return to orchestrator (lite-plan)
|
||||
```
|
||||
|
||||
## CLI Command Template
|
||||
|
||||
### Base Template (All Complexity Levels)
|
||||
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Generate plan for {task_description}
|
||||
cd {project_root} && {cli_tool} -p "
|
||||
PURPOSE: Generate implementation plan for {complexity} task
|
||||
TASK:
|
||||
• Analyze task/bug description and context
|
||||
• Break down into tasks following schema structure
|
||||
• Identify dependencies and execution phases
|
||||
• Generate complexity-appropriate fields (rationale, verification, risks, code_skeleton, data_flow)
|
||||
• Analyze: {task_description}
|
||||
• Break down into 1-10 tasks with: id, title, file, action, description, modification_points, implementation, reference, acceptance, depends_on
|
||||
• Identify parallel vs sequential execution phases
|
||||
MODE: analysis
|
||||
CONTEXT: @**/* | Memory: {context_summary}
|
||||
CONTEXT: @**/* | Memory: {exploration_summary}
|
||||
EXPECTED:
|
||||
## Summary
|
||||
## Implementation Summary
|
||||
[overview]
|
||||
|
||||
## Approach
|
||||
[high-level strategy]
|
||||
|
||||
## Complexity: {Low|Medium|High}
|
||||
## High-Level Approach
|
||||
[strategy]
|
||||
|
||||
## Task Breakdown
|
||||
### T1: [Title] (or FIX1 for fix-plan)
|
||||
**Scope**: [module/feature path]
|
||||
### T1: [Title]
|
||||
**File**: [path]
|
||||
**Action**: [type]
|
||||
**Description**: [what]
|
||||
**Modification Points**: - [file]: [target] - [change]
|
||||
**Implementation**: 1. [step]
|
||||
**Reference**: - Pattern: [pattern] - Files: [files] - Examples: [guidance]
|
||||
**Reference**: - Pattern: [name] - Files: [paths] - Examples: [guidance]
|
||||
**Acceptance**: - [quantified criterion]
|
||||
**Depends On**: []
|
||||
|
||||
[MEDIUM/HIGH COMPLEXITY ONLY]
|
||||
**Rationale**:
|
||||
- Chosen Approach: [why this approach]
|
||||
- Alternatives Considered: [other options]
|
||||
- Decision Factors: [key factors]
|
||||
- Tradeoffs: [known tradeoffs]
|
||||
|
||||
**Verification**:
|
||||
- Unit Tests: [test names]
|
||||
- Integration Tests: [test names]
|
||||
- Manual Checks: [specific steps]
|
||||
- Success Metrics: [quantified metrics]
|
||||
|
||||
[HIGH COMPLEXITY ONLY]
|
||||
**Risks**:
|
||||
- Risk: [description] | Probability: [L/M/H] | Impact: [L/M/H] | Mitigation: [strategy] | Fallback: [alternative]
|
||||
|
||||
**Code Skeleton**:
|
||||
- Interfaces: [name]: [definition] - [purpose]
|
||||
- Functions: [signature] - [purpose] - returns [type]
|
||||
- Classes: [name] - [purpose] - methods: [list]
|
||||
|
||||
## Data Flow (HIGH COMPLEXITY ONLY)
|
||||
**Diagram**: [A → B → C]
|
||||
**Stages**:
|
||||
- Stage [name]: Input=[type] → Output=[type] | Component=[module] | Transforms=[list]
|
||||
**Dependencies**: [external deps]
|
||||
|
||||
## Design Decisions (MEDIUM/HIGH)
|
||||
- Decision: [what] | Rationale: [why] | Tradeoff: [what was traded]
|
||||
|
||||
## Flow Control
|
||||
**Execution Order**: - Phase parallel-1: [T1, T2] (independent)
|
||||
**Exit Conditions**: - Success: [condition] - Failure: [condition]
|
||||
@@ -147,16 +130,11 @@ EXPECTED:
|
||||
## Time Estimate
|
||||
**Total**: [time]
|
||||
|
||||
CONSTRAINTS:
|
||||
- Follow schema structure from {schema_path}
|
||||
- Complexity determines required fields:
|
||||
* Low: base fields only
|
||||
* Medium: + rationale + verification + design_decisions
|
||||
* High: + risks + code_skeleton + data_flow
|
||||
- Acceptance/verification must be quantified
|
||||
- Dependencies use task IDs
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/02-breakdown-task-steps.txt) |
|
||||
- Acceptance must be quantified (counts, method names, metrics)
|
||||
- Dependencies use task IDs (T1, T2)
|
||||
- analysis=READ-ONLY
|
||||
" --tool {cli_tool} --mode analysis --cd {project_root}
|
||||
"
|
||||
```
|
||||
|
||||
## Core Functions
|
||||
@@ -172,80 +150,43 @@ function extractSection(cliOutput, header) {
|
||||
}
|
||||
|
||||
// Parse structured tasks from CLI output
|
||||
function extractStructuredTasks(cliOutput, complexity) {
|
||||
function extractStructuredTasks(cliOutput) {
|
||||
const tasks = []
|
||||
// Split by task headers
|
||||
const taskBlocks = cliOutput.split(/### (T\d+):/).slice(1)
|
||||
|
||||
for (let i = 0; i < taskBlocks.length; i += 2) {
|
||||
const taskId = taskBlocks[i].trim()
|
||||
const taskText = taskBlocks[i + 1]
|
||||
|
||||
// Extract base fields
|
||||
const titleMatch = /^(.+?)(?=\n)/.exec(taskText)
|
||||
const scopeMatch = /\*\*Scope\*\*: (.+?)(?=\n)/.exec(taskText)
|
||||
const actionMatch = /\*\*Action\*\*: (.+?)(?=\n)/.exec(taskText)
|
||||
const descMatch = /\*\*Description\*\*: (.+?)(?=\n)/.exec(taskText)
|
||||
const depsMatch = /\*\*Depends On\*\*: (.+?)(?=\n|$)/.exec(taskText)
|
||||
const taskPattern = /### (T\d+): (.+?)\n\*\*File\*\*: (.+?)\n\*\*Action\*\*: (.+?)\n\*\*Description\*\*: (.+?)\n\*\*Modification Points\*\*:\n((?:- .+?\n)*)\*\*Implementation\*\*:\n((?:\d+\. .+?\n)+)\*\*Reference\*\*:\n((?:- .+?\n)+)\*\*Acceptance\*\*:\n((?:- .+?\n)+)\*\*Depends On\*\*: (.+)/g
|
||||
|
||||
let match
|
||||
while ((match = taskPattern.exec(cliOutput)) !== null) {
|
||||
// Parse modification points
|
||||
const modPointsSection = /\*\*Modification Points\*\*:\n((?:- .+?\n)*)/.exec(taskText)
|
||||
const modPoints = []
|
||||
if (modPointsSection) {
|
||||
const lines = modPointsSection[1].split('\n').filter(s => s.trim().startsWith('-'))
|
||||
lines.forEach(line => {
|
||||
const m = /- \[(.+?)\]: \[(.+?)\] - (.+)/.exec(line)
|
||||
if (m) modPoints.push({ file: m[1].trim(), target: m[2].trim(), change: m[3].trim() })
|
||||
})
|
||||
}
|
||||
|
||||
// Parse implementation
|
||||
const implSection = /\*\*Implementation\*\*:\n((?:\d+\. .+?\n)+)/.exec(taskText)
|
||||
const implementation = implSection
|
||||
? implSection[1].split('\n').map(s => s.replace(/^\d+\. /, '').trim()).filter(Boolean)
|
||||
: []
|
||||
const modPoints = match[6].trim().split('\n').filter(s => s.startsWith('-')).map(s => {
|
||||
const m = /- \[(.+?)\]: \[(.+?)\] - (.+)/.exec(s)
|
||||
return m ? { file: m[1], target: m[2], change: m[3] } : null
|
||||
}).filter(Boolean)
|
||||
|
||||
// Parse reference
|
||||
const refSection = /\*\*Reference\*\*:\n((?:- .+?\n)+)/.exec(taskText)
|
||||
const reference = refSection ? {
|
||||
pattern: (/- Pattern: (.+)/m.exec(refSection[1]) || [])[1]?.trim() || "No pattern",
|
||||
files: ((/- Files: (.+)/m.exec(refSection[1]) || [])[1] || "").split(',').map(f => f.trim()).filter(Boolean),
|
||||
examples: (/- Examples: (.+)/m.exec(refSection[1]) || [])[1]?.trim() || "Follow pattern"
|
||||
} : {}
|
||||
const refText = match[8].trim()
|
||||
const reference = {
|
||||
pattern: (/- Pattern: (.+)/m.exec(refText) || [])[1]?.trim() || "No pattern",
|
||||
files: ((/- Files: (.+)/m.exec(refText) || [])[1] || "").split(',').map(f => f.trim()).filter(Boolean),
|
||||
examples: (/- Examples: (.+)/m.exec(refText) || [])[1]?.trim() || "Follow general pattern"
|
||||
}
|
||||
|
||||
// Parse acceptance
|
||||
const acceptSection = /\*\*Acceptance\*\*:\n((?:- .+?\n)+)/.exec(taskText)
|
||||
const acceptance = acceptSection
|
||||
? acceptSection[1].split('\n').map(s => s.replace(/^- /, '').trim()).filter(Boolean)
|
||||
: []
|
||||
// Parse depends_on
|
||||
const depsText = match[10].trim()
|
||||
const depends_on = depsText === '[]' ? [] : depsText.replace(/[\[\]]/g, '').split(',').map(s => s.trim()).filter(Boolean)
|
||||
|
||||
const task = {
|
||||
id: taskId,
|
||||
title: titleMatch?.[1].trim() || "Untitled",
|
||||
scope: scopeMatch?.[1].trim() || "",
|
||||
action: actionMatch?.[1].trim() || "Implement",
|
||||
description: descMatch?.[1].trim() || "",
|
||||
tasks.push({
|
||||
id: match[1].trim(),
|
||||
title: match[2].trim(),
|
||||
file: match[3].trim(),
|
||||
action: match[4].trim(),
|
||||
description: match[5].trim(),
|
||||
modification_points: modPoints,
|
||||
implementation,
|
||||
implementation: match[7].trim().split('\n').map(s => s.replace(/^\d+\. /, '')).filter(Boolean),
|
||||
reference,
|
||||
acceptance,
|
||||
depends_on: depsMatch?.[1] === '[]' ? [] : (depsMatch?.[1] || "").replace(/[\[\]]/g, '').split(',').map(s => s.trim()).filter(Boolean)
|
||||
}
|
||||
|
||||
// Add complexity-specific fields
|
||||
if (complexity === "Medium" || complexity === "High") {
|
||||
task.rationale = extractRationale(taskText)
|
||||
task.verification = extractVerification(taskText)
|
||||
}
|
||||
|
||||
if (complexity === "High") {
|
||||
task.risks = extractRisks(taskText)
|
||||
task.code_skeleton = extractCodeSkeleton(taskText)
|
||||
}
|
||||
|
||||
tasks.push(task)
|
||||
acceptance: match[9].trim().split('\n').map(s => s.replace(/^- /, '')).filter(Boolean),
|
||||
depends_on
|
||||
})
|
||||
}
|
||||
|
||||
return tasks
|
||||
}
|
||||
|
||||
@@ -268,155 +209,14 @@ function extractFlowControl(cliOutput) {
|
||||
}
|
||||
}
|
||||
|
||||
// Parse rationale section for a task
|
||||
function extractRationale(taskText) {
|
||||
const rationaleMatch = /\*\*Rationale\*\*:\n- Chosen Approach: (.+?)\n- Alternatives Considered: (.+?)\n- Decision Factors: (.+?)\n- Tradeoffs: (.+)/s.exec(taskText)
|
||||
if (!rationaleMatch) return null
|
||||
|
||||
return {
|
||||
chosen_approach: rationaleMatch[1].trim(),
|
||||
alternatives_considered: rationaleMatch[2].split(',').map(s => s.trim()).filter(Boolean),
|
||||
decision_factors: rationaleMatch[3].split(',').map(s => s.trim()).filter(Boolean),
|
||||
tradeoffs: rationaleMatch[4].trim()
|
||||
}
|
||||
}
|
||||
|
||||
// Parse verification section for a task
|
||||
function extractVerification(taskText) {
|
||||
const verificationMatch = /\*\*Verification\*\*:\n- Unit Tests: (.+?)\n- Integration Tests: (.+?)\n- Manual Checks: (.+?)\n- Success Metrics: (.+)/s.exec(taskText)
|
||||
if (!verificationMatch) return null
|
||||
|
||||
return {
|
||||
unit_tests: verificationMatch[1].split(',').map(s => s.trim()).filter(Boolean),
|
||||
integration_tests: verificationMatch[2].split(',').map(s => s.trim()).filter(Boolean),
|
||||
manual_checks: verificationMatch[3].split(',').map(s => s.trim()).filter(Boolean),
|
||||
success_metrics: verificationMatch[4].split(',').map(s => s.trim()).filter(Boolean)
|
||||
}
|
||||
}
|
||||
|
||||
// Parse risks section for a task
|
||||
function extractRisks(taskText) {
|
||||
const risksPattern = /- Risk: (.+?) \| Probability: ([LMH]) \| Impact: ([LMH]) \| Mitigation: (.+?)(?: \| Fallback: (.+?))?(?=\n|$)/g
|
||||
const risks = []
|
||||
let match
|
||||
|
||||
while ((match = risksPattern.exec(taskText)) !== null) {
|
||||
risks.push({
|
||||
description: match[1].trim(),
|
||||
probability: match[2] === 'L' ? 'Low' : match[2] === 'M' ? 'Medium' : 'High',
|
||||
impact: match[3] === 'L' ? 'Low' : match[3] === 'M' ? 'Medium' : 'High',
|
||||
mitigation: match[4].trim(),
|
||||
fallback: match[5]?.trim() || undefined
|
||||
})
|
||||
}
|
||||
|
||||
return risks.length > 0 ? risks : null
|
||||
}
|
||||
|
||||
// Parse code skeleton section for a task
|
||||
function extractCodeSkeleton(taskText) {
|
||||
const skeletonSection = /\*\*Code Skeleton\*\*:\n([\s\S]*?)(?=\n\*\*|$)/.exec(taskText)
|
||||
if (!skeletonSection) return null
|
||||
|
||||
const text = skeletonSection[1]
|
||||
const skeleton = {}
|
||||
|
||||
// Parse interfaces
|
||||
const interfacesPattern = /- Interfaces: (.+?): (.+?) - (.+?)(?=\n|$)/g
|
||||
const interfaces = []
|
||||
let match
|
||||
while ((match = interfacesPattern.exec(text)) !== null) {
|
||||
interfaces.push({ name: match[1].trim(), definition: match[2].trim(), purpose: match[3].trim() })
|
||||
}
|
||||
if (interfaces.length > 0) skeleton.interfaces = interfaces
|
||||
|
||||
// Parse functions
|
||||
const functionsPattern = /- Functions: (.+?) - (.+?) - returns (.+?)(?=\n|$)/g
|
||||
const functions = []
|
||||
while ((match = functionsPattern.exec(text)) !== null) {
|
||||
functions.push({ signature: match[1].trim(), purpose: match[2].trim(), returns: match[3].trim() })
|
||||
}
|
||||
if (functions.length > 0) skeleton.key_functions = functions
|
||||
|
||||
// Parse classes
|
||||
const classesPattern = /- Classes: (.+?) - (.+?) - methods: (.+?)(?=\n|$)/g
|
||||
const classes = []
|
||||
while ((match = classesPattern.exec(text)) !== null) {
|
||||
classes.push({
|
||||
name: match[1].trim(),
|
||||
purpose: match[2].trim(),
|
||||
methods: match[3].split(',').map(s => s.trim()).filter(Boolean)
|
||||
})
|
||||
}
|
||||
if (classes.length > 0) skeleton.classes = classes
|
||||
|
||||
return Object.keys(skeleton).length > 0 ? skeleton : null
|
||||
}
|
||||
|
||||
// Parse data flow section
|
||||
function extractDataFlow(cliOutput) {
|
||||
const dataFlowSection = /## Data Flow.*?\n([\s\S]*?)(?=\n## |$)/.exec(cliOutput)
|
||||
if (!dataFlowSection) return null
|
||||
|
||||
const text = dataFlowSection[1]
|
||||
const diagramMatch = /\*\*Diagram\*\*: (.+?)(?=\n|$)/.exec(text)
|
||||
const depsMatch = /\*\*Dependencies\*\*: (.+?)(?=\n|$)/.exec(text)
|
||||
|
||||
// Parse stages
|
||||
const stagesPattern = /- Stage (.+?): Input=(.+?) → Output=(.+?) \| Component=(.+?)(?: \| Transforms=(.+?))?(?=\n|$)/g
|
||||
const stages = []
|
||||
let match
|
||||
while ((match = stagesPattern.exec(text)) !== null) {
|
||||
stages.push({
|
||||
stage: match[1].trim(),
|
||||
input: match[2].trim(),
|
||||
output: match[3].trim(),
|
||||
component: match[4].trim(),
|
||||
transformations: match[5] ? match[5].split(',').map(s => s.trim()).filter(Boolean) : undefined
|
||||
})
|
||||
}
|
||||
|
||||
return {
|
||||
diagram: diagramMatch?.[1].trim() || null,
|
||||
stages: stages.length > 0 ? stages : undefined,
|
||||
dependencies: depsMatch ? depsMatch[1].split(',').map(s => s.trim()).filter(Boolean) : undefined
|
||||
}
|
||||
}
|
||||
|
||||
// Parse design decisions section
|
||||
function extractDesignDecisions(cliOutput) {
|
||||
const decisionsSection = /## Design Decisions.*?\n([\s\S]*?)(?=\n## |$)/.exec(cliOutput)
|
||||
if (!decisionsSection) return null
|
||||
|
||||
const decisionsPattern = /- Decision: (.+?) \| Rationale: (.+?)(?: \| Tradeoff: (.+?))?(?=\n|$)/g
|
||||
const decisions = []
|
||||
let match
|
||||
|
||||
while ((match = decisionsPattern.exec(decisionsSection[1])) !== null) {
|
||||
decisions.push({
|
||||
decision: match[1].trim(),
|
||||
rationale: match[2].trim(),
|
||||
tradeoff: match[3]?.trim() || undefined
|
||||
})
|
||||
}
|
||||
|
||||
return decisions.length > 0 ? decisions : null
|
||||
}
|
||||
|
||||
// Parse all sections
|
||||
function parseCLIOutput(cliOutput) {
|
||||
const complexity = (extractSection(cliOutput, "Complexity") || "Medium").trim()
|
||||
return {
|
||||
summary: extractSection(cliOutput, "Summary") || extractSection(cliOutput, "Implementation Summary"),
|
||||
approach: extractSection(cliOutput, "Approach") || extractSection(cliOutput, "High-Level Approach"),
|
||||
complexity,
|
||||
raw_tasks: extractStructuredTasks(cliOutput, complexity),
|
||||
summary: extractSection(cliOutput, "Implementation Summary"),
|
||||
approach: extractSection(cliOutput, "High-Level Approach"),
|
||||
raw_tasks: extractStructuredTasks(cliOutput),
|
||||
flow_control: extractFlowControl(cliOutput),
|
||||
time_estimate: extractSection(cliOutput, "Time Estimate"),
|
||||
// High complexity only
|
||||
data_flow: complexity === "High" ? extractDataFlow(cliOutput) : null,
|
||||
// Medium/High complexity
|
||||
design_decisions: (complexity === "Medium" || complexity === "High") ? extractDesignDecisions(cliOutput) : null
|
||||
time_estimate: extractSection(cliOutput, "Time Estimate")
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -479,51 +279,6 @@ function inferFile(task, ctx) {
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Execution ID Assignment (MANDATORY)
|
||||
|
||||
```javascript
|
||||
function assignCliExecutionIds(tasks, sessionId) {
|
||||
const taskMap = new Map(tasks.map(t => [t.id, t]))
|
||||
const childCount = new Map()
|
||||
|
||||
// Count children for each task
|
||||
tasks.forEach(task => {
|
||||
(task.depends_on || []).forEach(depId => {
|
||||
childCount.set(depId, (childCount.get(depId) || 0) + 1)
|
||||
})
|
||||
})
|
||||
|
||||
tasks.forEach(task => {
|
||||
task.cli_execution_id = `${sessionId}-${task.id}`
|
||||
const deps = task.depends_on || []
|
||||
|
||||
if (deps.length === 0) {
|
||||
task.cli_execution = { strategy: "new" }
|
||||
} else if (deps.length === 1) {
|
||||
const parent = taskMap.get(deps[0])
|
||||
const parentChildCount = childCount.get(deps[0]) || 0
|
||||
task.cli_execution = parentChildCount === 1
|
||||
? { strategy: "resume", resume_from: parent.cli_execution_id }
|
||||
: { strategy: "fork", resume_from: parent.cli_execution_id }
|
||||
} else {
|
||||
task.cli_execution = {
|
||||
strategy: "merge_fork",
|
||||
merge_from: deps.map(depId => taskMap.get(depId).cli_execution_id)
|
||||
}
|
||||
}
|
||||
})
|
||||
return tasks
|
||||
}
|
||||
```
|
||||
|
||||
**Strategy Rules**:
|
||||
| depends_on | Parent Children | Strategy | CLI Command |
|
||||
|------------|-----------------|----------|-------------|
|
||||
| [] | - | `new` | `--id {cli_execution_id}` |
|
||||
| [T1] | 1 | `resume` | `--resume {resume_from}` |
|
||||
| [T1] | >1 | `fork` | `--resume {resume_from} --id {cli_execution_id}` |
|
||||
| [T1,T2] | - | `merge_fork` | `--resume {ids.join(',')} --id {cli_execution_id}` |
|
||||
|
||||
### Flow Control Inference
|
||||
|
||||
```javascript
|
||||
@@ -548,108 +303,22 @@ function inferFlowControl(tasks) {
|
||||
### planObject Generation
|
||||
|
||||
```javascript
|
||||
function generatePlanObject(parsed, enrichedContext, input, schemaType) {
|
||||
const complexity = parsed.complexity || input.complexity || "Medium"
|
||||
const tasks = validateAndEnhanceTasks(parsed.raw_tasks, enrichedContext, complexity)
|
||||
assignCliExecutionIds(tasks, input.session.id) // MANDATORY: Assign CLI execution IDs
|
||||
function generatePlanObject(parsed, enrichedContext, input) {
|
||||
const tasks = validateAndEnhanceTasks(parsed.raw_tasks, enrichedContext)
|
||||
const flow_control = parsed.flow_control?.execution_order?.length > 0 ? parsed.flow_control : inferFlowControl(tasks)
|
||||
const focus_paths = [...new Set(tasks.flatMap(t => [t.file || t.scope, ...t.modification_points.map(m => m.file)]).filter(Boolean))]
|
||||
const focus_paths = [...new Set(tasks.flatMap(t => [t.file, ...t.modification_points.map(m => m.file)]).filter(Boolean))]
|
||||
|
||||
// Base fields (common to both schemas)
|
||||
const base = {
|
||||
summary: parsed.summary || `Plan for: ${input.task_description.slice(0, 100)}`,
|
||||
return {
|
||||
summary: parsed.summary || `Implementation plan for: ${input.task_description.slice(0, 100)}`,
|
||||
approach: parsed.approach || "Step-by-step implementation",
|
||||
tasks,
|
||||
flow_control,
|
||||
focus_paths,
|
||||
estimated_time: parsed.time_estimate || `${tasks.length * 30} minutes`,
|
||||
recommended_execution: (complexity === "Low" || input.severity === "Low") ? "Agent" : "Codex",
|
||||
_metadata: {
|
||||
timestamp: new Date().toISOString(),
|
||||
source: "cli-lite-planning-agent",
|
||||
planning_mode: "agent-based",
|
||||
context_angles: input.contextAngles || [],
|
||||
duration_seconds: Math.round((Date.now() - startTime) / 1000)
|
||||
}
|
||||
recommended_execution: input.complexity === "Low" ? "Agent" : "Codex",
|
||||
complexity: input.complexity,
|
||||
_metadata: { timestamp: new Date().toISOString(), source: "cli-lite-planning-agent", planning_mode: "agent-based", exploration_angles: input.explorationAngles || [], duration_seconds: Math.round((Date.now() - startTime) / 1000) }
|
||||
}
|
||||
|
||||
// Add complexity-specific top-level fields
|
||||
if (complexity === "Medium" || complexity === "High") {
|
||||
base.design_decisions = parsed.design_decisions || []
|
||||
}
|
||||
|
||||
if (complexity === "High") {
|
||||
base.data_flow = parsed.data_flow || null
|
||||
}
|
||||
|
||||
// Schema-specific fields
|
||||
if (schemaType === 'fix-plan') {
|
||||
return {
|
||||
...base,
|
||||
root_cause: parsed.root_cause || "Root cause from diagnosis",
|
||||
strategy: parsed.strategy || "comprehensive_fix",
|
||||
severity: input.severity || "Medium",
|
||||
risk_level: parsed.risk_level || "medium"
|
||||
}
|
||||
} else {
|
||||
return {
|
||||
...base,
|
||||
approach: parsed.approach || "Step-by-step implementation",
|
||||
complexity
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Enhanced task validation with complexity-specific fields
|
||||
function validateAndEnhanceTasks(rawTasks, enrichedContext, complexity) {
|
||||
return rawTasks.map((task, idx) => {
|
||||
const enhanced = {
|
||||
id: task.id || `T${idx + 1}`,
|
||||
title: task.title || "Unnamed task",
|
||||
scope: task.scope || task.file || inferFile(task, enrichedContext),
|
||||
action: task.action || inferAction(task.title),
|
||||
description: task.description || task.title,
|
||||
modification_points: task.modification_points?.length > 0
|
||||
? task.modification_points
|
||||
: [{ file: task.scope || task.file, target: "main", change: task.description }],
|
||||
implementation: task.implementation?.length >= 2
|
||||
? task.implementation
|
||||
: [`Analyze ${task.scope || task.file}`, `Implement ${task.title}`, `Add error handling`],
|
||||
reference: task.reference || { pattern: "existing patterns", files: enrichedContext.relevant_files.slice(0, 2), examples: "Follow existing structure" },
|
||||
acceptance: task.acceptance?.length >= 1
|
||||
? task.acceptance
|
||||
: [`${task.title} completed`, `Follows conventions`],
|
||||
depends_on: task.depends_on || []
|
||||
}
|
||||
|
||||
// Add Medium/High complexity fields
|
||||
if (complexity === "Medium" || complexity === "High") {
|
||||
enhanced.rationale = task.rationale || {
|
||||
chosen_approach: "Standard implementation approach",
|
||||
alternatives_considered: [],
|
||||
decision_factors: ["Maintainability", "Performance"],
|
||||
tradeoffs: "None significant"
|
||||
}
|
||||
enhanced.verification = task.verification || {
|
||||
unit_tests: [`test_${task.id.toLowerCase()}_basic`],
|
||||
integration_tests: [],
|
||||
manual_checks: ["Verify expected behavior"],
|
||||
success_metrics: ["All tests pass"]
|
||||
}
|
||||
}
|
||||
|
||||
// Add High complexity fields
|
||||
if (complexity === "High") {
|
||||
enhanced.risks = task.risks || [{
|
||||
description: "Implementation complexity",
|
||||
probability: "Low",
|
||||
impact: "Medium",
|
||||
mitigation: "Incremental development with checkpoints"
|
||||
}]
|
||||
enhanced.code_skeleton = task.code_skeleton || null
|
||||
}
|
||||
|
||||
return enhanced
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
@@ -714,23 +383,14 @@ function validateTask(task) {
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
- **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
- **Read schema first** to determine output structure
|
||||
- Generate task IDs (T1/T2 for plan, FIX1/FIX2 for fix-plan)
|
||||
- Generate task IDs (T1, T2, T3...)
|
||||
- Include depends_on (even if empty [])
|
||||
- **Assign cli_execution_id** (`{sessionId}-{taskId}`)
|
||||
- **Compute cli_execution strategy** based on depends_on
|
||||
- Quantify acceptance/verification criteria
|
||||
- Quantify acceptance criteria
|
||||
- Generate flow_control from dependencies
|
||||
- Handle CLI errors with fallback chain
|
||||
|
||||
**Bash Tool**:
|
||||
- Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution
|
||||
|
||||
**NEVER**:
|
||||
- Execute implementation (return plan only)
|
||||
- Use vague acceptance criteria
|
||||
- Create circular dependencies
|
||||
- Skip task validation
|
||||
- **Skip CLI execution ID assignment**
|
||||
- **Ignore schema structure**
|
||||
|
||||
@@ -107,7 +107,7 @@ Phase 3: Task JSON Generation
|
||||
|
||||
**Template-Based Command Construction with Test Layer Awareness**:
|
||||
```bash
|
||||
ccw cli -p "
|
||||
cd {project_root} && {cli_tool} -p "
|
||||
PURPOSE: Analyze {test_type} test failures and generate fix strategy for iteration {iteration}
|
||||
TASK:
|
||||
• Review {failed_tests.length} {test_type} test failures: [{test_names}]
|
||||
@@ -127,14 +127,14 @@ EXPECTED: Structured fix strategy with:
|
||||
- Fix approach ensuring business logic correctness (not just test passage)
|
||||
- Expected outcome and verification steps
|
||||
- Impact assessment: Will this fix potentially mask other issues?
|
||||
CONSTRAINTS:
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/{template}) |
|
||||
- For {test_type} tests: {layer_specific_guidance}
|
||||
- Avoid 'surgical fixes' that mask underlying issues
|
||||
- Provide specific line numbers for modifications
|
||||
- Consider previous iteration failures
|
||||
- Validate fix doesn't introduce new vulnerabilities
|
||||
- analysis=READ-ONLY
|
||||
" --tool {cli_tool} --mode analysis --rule {template} --cd {project_root} --timeout {timeout_value}
|
||||
" {timeout_flag}
|
||||
```
|
||||
|
||||
**Layer-Specific Guidance Injection**:
|
||||
@@ -436,7 +436,6 @@ See: `.process/iteration-{iteration}-cli-output.txt`
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS:**
|
||||
- **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
- **Validate context package**: Ensure all required fields present before CLI execution
|
||||
- **Handle CLI errors gracefully**: Use fallback chain (Gemini → Qwen → degraded mode)
|
||||
- **Parse CLI output structurally**: Extract specific sections (RCA, 修复建议, 验证建议)
|
||||
@@ -447,9 +446,6 @@ See: `.process/iteration-{iteration}-cli-output.txt`
|
||||
- **Generate measurable acceptance criteria**: Include verification commands
|
||||
- **Apply layer-specific guidance**: Use test_type to customize analysis approach
|
||||
|
||||
**Bash Tool**:
|
||||
- Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution
|
||||
|
||||
**NEVER:**
|
||||
- Execute tests directly (orchestrator manages test execution)
|
||||
- Skip CLI analysis (always run CLI even for simple failures)
|
||||
@@ -531,9 +527,9 @@ See: `.process/iteration-{iteration}-cli-output.txt`
|
||||
1. **Detect test_type**: "integration" → Apply integration-specific diagnosis
|
||||
2. **Execute CLI**:
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Analyze integration test failure...
|
||||
gemini -p "PURPOSE: Analyze integration test failure...
|
||||
TASK: Examine component interactions, data flow, interface contracts...
|
||||
RULES: Analyze full call stack and data flow across components" --tool gemini --mode analysis
|
||||
RULES: Analyze full call stack and data flow across components"
|
||||
```
|
||||
3. **Parse Output**: Extract RCA, 修复建议, 验证建议 sections
|
||||
4. **Generate Task JSON** (IMPL-fix-1.json):
|
||||
|
||||
@@ -34,50 +34,17 @@ You are a code execution specialist focused on implementing high-quality, produc
|
||||
- **context-package.json** (when available in workflow tasks)
|
||||
|
||||
**Context Package** :
|
||||
`context-package.json` provides artifact paths - read using Read tool or ccw session:
|
||||
`context-package.json` provides artifact paths - extract dynamically using `jq`:
|
||||
```bash
|
||||
# Get context package content from session using Read tool
|
||||
Read(.workflow/active/${SESSION_ID}/.process/context-package.json)
|
||||
# Returns parsed JSON with brainstorm_artifacts, focus_paths, etc.
|
||||
# Get role analysis paths from context package
|
||||
jq -r '.brainstorm_artifacts.role_analyses[].files[].path' context-package.json
|
||||
```
|
||||
|
||||
**Task JSON Parsing** (when task JSON path provided):
|
||||
Read task JSON and extract structured context:
|
||||
```
|
||||
Task JSON Fields:
|
||||
├── context.requirements[] → What to implement (list of requirements)
|
||||
├── context.acceptance[] → How to verify (validation commands)
|
||||
├── context.focus_paths[] → Where to focus (directories/files)
|
||||
├── context.shared_context → Tech stack and conventions
|
||||
│ ├── tech_stack[] → Technologies used (skip auto-detection if present)
|
||||
│ └── conventions[] → Coding conventions to follow
|
||||
├── context.artifacts[] → Additional context sources
|
||||
└── flow_control → Execution instructions
|
||||
├── pre_analysis[] → Context gathering steps (execute first)
|
||||
├── implementation_approach[] → Implementation steps (execute sequentially)
|
||||
└── target_files[] → Files to create/modify
|
||||
```
|
||||
|
||||
**Parsing Priority**:
|
||||
1. Read task JSON from provided path
|
||||
2. Extract `context.requirements` as implementation goals
|
||||
3. Extract `context.acceptance` as verification criteria
|
||||
4. If `context.shared_context.tech_stack` exists → skip auto-detection, use provided stack
|
||||
5. Process `flow_control` if present
|
||||
|
||||
**Pre-Analysis: Smart Tech Stack Loading**:
|
||||
```bash
|
||||
# Priority 1: Use tech_stack from task JSON if available
|
||||
if [[ -n "$TASK_JSON_TECH_STACK" ]]; then
|
||||
# Map tech stack names to guideline files
|
||||
# e.g., ["FastAPI", "SQLAlchemy"] → python-dev.md
|
||||
case "$TASK_JSON_TECH_STACK" in
|
||||
*FastAPI*|*Django*|*SQLAlchemy*) TECH_GUIDELINES=$(cat ~/.claude/workflows/cli-templates/tech-stacks/python-dev.md) ;;
|
||||
*React*|*Next*) TECH_GUIDELINES=$(cat ~/.claude/workflows/cli-templates/tech-stacks/react-dev.md) ;;
|
||||
*TypeScript*) TECH_GUIDELINES=$(cat ~/.claude/workflows/cli-templates/tech-stacks/typescript-dev.md) ;;
|
||||
esac
|
||||
# Priority 2: Auto-detect from file extensions (fallback)
|
||||
elif [[ "$TASK_DESCRIPTION" =~ (implement|create|build|develop|code|write|add|fix|refactor) ]]; then
|
||||
# Smart detection: Only load tech stack for development tasks
|
||||
if [[ "$TASK_DESCRIPTION" =~ (implement|create|build|develop|code|write|add|fix|refactor) ]]; then
|
||||
# Simple tech stack detection based on file extensions
|
||||
if ls *.ts *.tsx 2>/dev/null | head -1; then
|
||||
TECH_GUIDELINES=$(cat ~/.claude/workflows/cli-templates/tech-stacks/typescript-dev.md)
|
||||
elif grep -q "react" package.json 2>/dev/null; then
|
||||
@@ -96,65 +63,28 @@ fi
|
||||
|
||||
**Context Evaluation**:
|
||||
```
|
||||
STEP 1: Parse Task JSON (if path provided)
|
||||
→ Read task JSON file from provided path
|
||||
→ Extract and store in memory:
|
||||
• [requirements] ← context.requirements[]
|
||||
• [acceptance_criteria] ← context.acceptance[]
|
||||
• [tech_stack] ← context.shared_context.tech_stack[] (skip auto-detection if present)
|
||||
• [conventions] ← context.shared_context.conventions[]
|
||||
• [focus_paths] ← context.focus_paths[]
|
||||
IF task is development-related (implement|create|build|develop|code|write|add|fix|refactor):
|
||||
→ Execute smart tech stack detection and load guidelines into [tech_guidelines] variable
|
||||
→ All subsequent development must follow loaded tech stack principles
|
||||
ELSE:
|
||||
→ Skip tech stack loading for non-development tasks
|
||||
|
||||
STEP 2: Execute Pre-Analysis (if flow_control.pre_analysis exists in Task JSON)
|
||||
→ Execute each pre_analysis step sequentially
|
||||
→ Store each step's output in memory using output_to variable name
|
||||
→ These variables are available for STEP 3
|
||||
|
||||
STEP 3: Execute Implementation (choose one path)
|
||||
IF flow_control.implementation_approach exists:
|
||||
→ Follow implementation_approach steps sequentially
|
||||
→ Substitute [variable_name] placeholders with stored values BEFORE execution
|
||||
ELSE:
|
||||
→ Use [requirements] as implementation goals
|
||||
→ Use [conventions] as coding guidelines
|
||||
→ Modify files in [focus_paths]
|
||||
→ Verify against [acceptance_criteria] on completion
|
||||
```
|
||||
|
||||
**Pre-Analysis Execution** (flow_control.pre_analysis):
|
||||
```
|
||||
For each step in pre_analysis[]:
|
||||
step.step → Step identifier (string name)
|
||||
step.action → Description of what to do
|
||||
step.commands → Array of commands to execute (see Command-to-Tool Mapping)
|
||||
step.output_to → Variable name to store results in memory
|
||||
step.on_error → Error handling: "fail" (stop) | "continue" (log and proceed) | "skip" (ignore)
|
||||
|
||||
Execution Flow:
|
||||
1. For each step in order:
|
||||
2. For each command in step.commands[]:
|
||||
3. Parse command format → Map to actual tool
|
||||
4. Execute tool → Capture output
|
||||
5. Concatenate all outputs → Store in [step.output_to] variable
|
||||
6. Continue to next step (or handle error per on_error)
|
||||
```
|
||||
|
||||
**Command-to-Tool Mapping** (explicit tool bindings):
|
||||
```
|
||||
Command Format → Actual Tool Call
|
||||
─────────────────────────────────────────────────────
|
||||
"Read(path)" → Read tool: Read(file_path=path)
|
||||
"bash(command)" → Bash tool: Bash(command=command)
|
||||
"Search(pattern,path)" → Grep tool: Grep(pattern=pattern, path=path)
|
||||
"Glob(pattern)" → Glob tool: Glob(pattern=pattern)
|
||||
"mcp__xxx__yyy(args)" → MCP tool: mcp__xxx__yyy(args)
|
||||
|
||||
Example Parsing:
|
||||
"Read(backend/app/models/simulation.py)"
|
||||
→ Tool: Read
|
||||
→ Parameter: file_path = "backend/app/models/simulation.py"
|
||||
→ Execute: Read(file_path="backend/app/models/simulation.py")
|
||||
→ Store output in [output_to] variable
|
||||
IF context sufficient for implementation:
|
||||
→ Apply [tech_guidelines] if loaded, otherwise use general best practices
|
||||
→ Proceed with implementation
|
||||
ELIF context insufficient OR task has flow control marker:
|
||||
→ Check for [FLOW_CONTROL] marker:
|
||||
- Execute flow_control.pre_analysis steps sequentially for context gathering
|
||||
- Use four flexible context acquisition methods:
|
||||
* Document references (cat commands)
|
||||
* Search commands (grep/rg/find)
|
||||
* CLI analysis (gemini/codex)
|
||||
* Free exploration (Read/Grep/Search tools)
|
||||
- Pass context between steps via [variable_name] references
|
||||
- Include [tech_guidelines] in context if available
|
||||
→ Extract patterns and conventions from accumulated context
|
||||
→ Apply tech stack principles if guidelines were loaded
|
||||
→ Proceed with execution
|
||||
```
|
||||
### Module Verification Guidelines
|
||||
|
||||
@@ -171,49 +101,29 @@ Example Parsing:
|
||||
|
||||
**Implementation Approach Execution**:
|
||||
When task JSON contains `flow_control.implementation_approach` array:
|
||||
|
||||
**Step Structure**:
|
||||
```
|
||||
step → Unique identifier (1, 2, 3...)
|
||||
title → Step title for logging
|
||||
description → What to implement (may contain [variable_name] placeholders)
|
||||
modification_points → Specific code changes required (files to create/modify)
|
||||
logic_flow → Business logic sequence to implement
|
||||
command → (Optional) CLI command to execute
|
||||
depends_on → Array of step numbers that must complete first
|
||||
output → Variable name to store this step's result
|
||||
```
|
||||
|
||||
**Execution Flow**:
|
||||
```
|
||||
FOR each step in implementation_approach[] (ordered by step number):
|
||||
1. Check depends_on: Wait for all listed step numbers to complete
|
||||
2. Variable Substitution: Replace [variable_name] in description/modification_points
|
||||
with values stored from previous steps' output
|
||||
3. Execute step (choose one):
|
||||
|
||||
IF step.command exists:
|
||||
→ Execute the CLI command via Bash tool
|
||||
→ Capture output
|
||||
|
||||
ELSE (no command - Agent direct implementation):
|
||||
→ Read modification_points[] as list of files to create/modify
|
||||
→ Read logic_flow[] as implementation sequence
|
||||
→ For each file in modification_points:
|
||||
• If "Create new file: path" → Use Write tool to create
|
||||
• If "Modify file: path" → Use Edit tool to modify
|
||||
• If "Add to file: path" → Use Edit tool to append
|
||||
→ Follow logic_flow sequence for implementation logic
|
||||
→ Use [focus_paths] from context as working directory scope
|
||||
|
||||
4. Store result in [step.output] variable for later steps
|
||||
5. Mark step complete, proceed to next
|
||||
```
|
||||
1. **Sequential Processing**: Execute steps in order, respecting `depends_on` dependencies
|
||||
2. **Dependency Resolution**: Wait for all steps listed in `depends_on` before starting
|
||||
3. **Variable Substitution**: Use `[variable_name]` to reference outputs from previous steps
|
||||
4. **Step Structure**:
|
||||
- `step`: Unique identifier (1, 2, 3...)
|
||||
- `title`: Step title
|
||||
- `description`: Detailed description with variable references
|
||||
- `modification_points`: Code modification targets
|
||||
- `logic_flow`: Business logic sequence
|
||||
- `command`: Optional CLI command (only when explicitly specified)
|
||||
- `depends_on`: Array of step numbers that must complete first
|
||||
- `output`: Variable name for this step's output
|
||||
5. **Execution Rules**:
|
||||
- Execute step 1 first (typically has `depends_on: []`)
|
||||
- For each subsequent step, verify all `depends_on` steps completed
|
||||
- Substitute `[variable_name]` with actual outputs from previous steps
|
||||
- Store this step's result in the `output` variable for future steps
|
||||
- If `command` field present, execute it; otherwise use agent capabilities
|
||||
|
||||
**CLI Command Execution (CLI Execute Mode)**:
|
||||
When step contains `command` field with Codex CLI, execute via CCW CLI. For Codex resume:
|
||||
- First task (`depends_on: []`): `ccw cli -p "..." --tool codex --mode write --cd [path]`
|
||||
- Subsequent tasks (has `depends_on`): Use CCW CLI with resume context to maintain session
|
||||
When step contains `command` field with Codex CLI, execute via Bash tool. For Codex resume:
|
||||
- First task (`depends_on: []`): `codex -C [path] --full-auto exec "..." --skip-git-repo-check -s danger-full-access`
|
||||
- Subsequent tasks (has `depends_on`): Add `resume --last` flag to maintain session context
|
||||
|
||||
**Test-Driven Development**:
|
||||
- Write tests first (red → green → refactor)
|
||||
@@ -385,15 +295,7 @@ Before completing any task, verify:
|
||||
- Make assumptions - verify with existing code
|
||||
- Create unnecessary complexity
|
||||
|
||||
**Bash Tool (CLI Execution in Agent)**:
|
||||
- Use `run_in_background=false` for all Bash/CLI calls - agent cannot receive task hook callbacks
|
||||
- Set timeout ≥60 minutes for CLI commands (hooks don't propagate to subagents):
|
||||
```javascript
|
||||
Bash(command="ccw cli -p '...' --tool codex --mode write", timeout=3600000) // 60 min
|
||||
```
|
||||
|
||||
**ALWAYS:**
|
||||
- **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
- Verify module/package existence with rg/grep/search before referencing
|
||||
- Write working code incrementally
|
||||
- Test your implementation thoroughly
|
||||
|
||||
@@ -27,8 +27,6 @@ You are a conceptual planning specialist focused on **dedicated single-role** st
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
**Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
|
||||
1. **Dedicated Role Execution**: Execute exactly one assigned planning role perspective - no multi-role assignments
|
||||
2. **Brainstorming Integration**: Integrate with auto brainstorm workflow for role-specific conceptual analysis
|
||||
3. **Template-Driven Analysis**: Use planning role templates loaded via `$(cat template)`
|
||||
@@ -111,7 +109,7 @@ This agent processes **simplified inline [FLOW_CONTROL]** format from brainstorm
|
||||
|
||||
3. **load_session_metadata**
|
||||
- Action: Load session metadata
|
||||
- Command: Read(.workflow/active/WFS-{session}/workflow-session.json)
|
||||
- Command: bash(cat .workflow/WFS-{session}/workflow-session.json)
|
||||
- Output: session_metadata
|
||||
```
|
||||
|
||||
@@ -157,7 +155,7 @@ When called, you receive:
|
||||
- **User Context**: Specific requirements, constraints, and expectations from user discussion
|
||||
- **Output Location**: Directory path for generated analysis files
|
||||
- **Role Hint** (optional): Suggested role or role selection guidance
|
||||
- **context-package.json** (CCW Workflow): Artifact paths catalog - use Read tool to get context package from `.workflow/active/{session}/.process/context-package.json`
|
||||
- **context-package.json** (CCW Workflow): Artifact paths catalog - extract using `jq -r '.brainstorm_artifacts.role_analyses[].files[].path'`
|
||||
- **ASSIGNED_ROLE** (optional): Specific role assignment
|
||||
- **ANALYSIS_DIMENSIONS** (optional): Role-specific analysis dimensions
|
||||
|
||||
@@ -308,14 +306,3 @@ When analysis is complete, ensure:
|
||||
- **Relevance**: Directly addresses user's specified requirements
|
||||
- **Actionability**: Provides concrete next steps and recommendations
|
||||
|
||||
## Output Size Limits
|
||||
|
||||
**Per-role limits** (prevent context overflow):
|
||||
- `analysis.md`: < 3000 words
|
||||
- `analysis-*.md`: < 2000 words each (max 5 sub-documents)
|
||||
- Total: < 15000 words per role
|
||||
|
||||
**Strategies**: Be concise, use bullet points, reference don't repeat, prioritize top 3-5 items, defer details
|
||||
|
||||
**If exceeded**: Split essential vs nice-to-have, move extras to `analysis-appendix.md` (counts toward limit), use executive summary style
|
||||
|
||||
|
||||
@@ -31,7 +31,7 @@ You are a context discovery specialist focused on gathering relevant project inf
|
||||
### 1. Reference Documentation (Project Standards)
|
||||
**Tools**:
|
||||
- `Read()` - Load CLAUDE.md, README.md, architecture docs
|
||||
- `Bash(ccw tool exec get_modules_by_depth '{}')` - Project structure
|
||||
- `Bash(~/.claude/scripts/get_modules_by_depth.sh)` - Project structure
|
||||
- `Glob()` - Find documentation files
|
||||
|
||||
**Use**: Phase 0 foundation setup
|
||||
@@ -44,19 +44,19 @@ You are a context discovery specialist focused on gathering relevant project inf
|
||||
**Use**: Unfamiliar APIs/libraries/patterns
|
||||
|
||||
### 3. Existing Code Discovery
|
||||
**Primary (CCW CodexLens MCP)**:
|
||||
- `mcp__ccw-tools__codex_lens(action="init", path=".")` - Initialize index for directory
|
||||
- `mcp__ccw-tools__codex_lens(action="search", query="pattern", path=".")` - Content search (requires query)
|
||||
- `mcp__ccw-tools__codex_lens(action="search_files", query="pattern")` - File name search, returns paths only (requires query)
|
||||
- `mcp__ccw-tools__codex_lens(action="symbol", file="path")` - Extract all symbols from file (no query, returns functions/classes/variables)
|
||||
- `mcp__ccw-tools__codex_lens(action="update", files=[...])` - Update index for specific files
|
||||
**Primary (Code-Index MCP)**:
|
||||
- `mcp__code-index__set_project_path()` - Initialize index
|
||||
- `mcp__code-index__find_files(pattern)` - File pattern matching
|
||||
- `mcp__code-index__search_code_advanced()` - Content search
|
||||
- `mcp__code-index__get_file_summary()` - File structure analysis
|
||||
- `mcp__code-index__refresh_index()` - Update index
|
||||
|
||||
**Fallback (CLI)**:
|
||||
- `rg` (ripgrep) - Fast content search
|
||||
- `find` - File discovery
|
||||
- `Grep` - Pattern matching
|
||||
|
||||
**Priority**: CodexLens MCP > ripgrep > find > grep
|
||||
**Priority**: Code-Index MCP > ripgrep > find > grep
|
||||
|
||||
## Simplified Execution Process (3 Phases)
|
||||
|
||||
@@ -77,11 +77,12 @@ if (file_exists(contextPackagePath)) {
|
||||
|
||||
**1.2 Foundation Setup**:
|
||||
```javascript
|
||||
// 1. Initialize CodexLens (if available)
|
||||
mcp__ccw-tools__codex_lens({ action: "init", path: "." })
|
||||
// 1. Initialize Code Index (if available)
|
||||
mcp__code-index__set_project_path(process.cwd())
|
||||
mcp__code-index__refresh_index()
|
||||
|
||||
// 2. Project Structure
|
||||
bash(ccw tool exec get_modules_by_depth '{}')
|
||||
bash(~/.claude/scripts/get_modules_by_depth.sh)
|
||||
|
||||
// 3. Load Documentation (if not in memory)
|
||||
if (!memory.has("CLAUDE.md")) Read(CLAUDE.md)
|
||||
@@ -211,18 +212,18 @@ mcp__exa__web_search_exa({
|
||||
|
||||
**Layer 1: File Pattern Discovery**
|
||||
```javascript
|
||||
// Primary: CodexLens MCP
|
||||
const files = mcp__ccw-tools__codex_lens({ action: "search_files", query: "*{keyword}*" })
|
||||
// Primary: Code-Index MCP
|
||||
const files = mcp__code-index__find_files("*{keyword}*")
|
||||
// Fallback: find . -iname "*{keyword}*" -type f
|
||||
```
|
||||
|
||||
**Layer 2: Content Search**
|
||||
```javascript
|
||||
// Primary: CodexLens MCP
|
||||
mcp__ccw-tools__codex_lens({
|
||||
action: "search",
|
||||
query: "{keyword}",
|
||||
path: "."
|
||||
// Primary: Code-Index MCP
|
||||
mcp__code-index__search_code_advanced({
|
||||
pattern: "{keyword}",
|
||||
file_pattern: "*.ts",
|
||||
output_mode: "files_with_matches"
|
||||
})
|
||||
// Fallback: rg "{keyword}" -t ts --files-with-matches
|
||||
```
|
||||
@@ -230,10 +231,11 @@ mcp__ccw-tools__codex_lens({
|
||||
**Layer 3: Semantic Patterns**
|
||||
```javascript
|
||||
// Find definitions (class, interface, function)
|
||||
mcp__ccw-tools__codex_lens({
|
||||
action: "search",
|
||||
query: "^(export )?(class|interface|type|function) .*{keyword}",
|
||||
path: "."
|
||||
mcp__code-index__search_code_advanced({
|
||||
pattern: "^(export )?(class|interface|type|function) .*{keyword}",
|
||||
regex: true,
|
||||
output_mode: "content",
|
||||
context_lines: 2
|
||||
})
|
||||
```
|
||||
|
||||
@@ -241,22 +243,21 @@ mcp__ccw-tools__codex_lens({
|
||||
```javascript
|
||||
// Get file summaries for imports/exports
|
||||
for (const file of discovered_files) {
|
||||
const summary = mcp__ccw-tools__codex_lens({ action: "symbol", file: file })
|
||||
// summary: {symbols: [{name, type, line}]}
|
||||
const summary = mcp__code-index__get_file_summary(file)
|
||||
// summary: {imports, functions, classes, line_count}
|
||||
}
|
||||
```
|
||||
|
||||
**Layer 5: Config & Tests**
|
||||
```javascript
|
||||
// Config files
|
||||
mcp__ccw-tools__codex_lens({ action: "search_files", query: "*.config.*" })
|
||||
mcp__ccw-tools__codex_lens({ action: "search_files", query: "package.json" })
|
||||
mcp__code-index__find_files("*.config.*")
|
||||
mcp__code-index__find_files("package.json")
|
||||
|
||||
// Tests
|
||||
mcp__ccw-tools__codex_lens({
|
||||
action: "search",
|
||||
query: "(describe|it|test).*{keyword}",
|
||||
path: "."
|
||||
mcp__code-index__search_code_advanced({
|
||||
pattern: "(describe|it|test).*{keyword}",
|
||||
file_pattern: "*.{test,spec}.*"
|
||||
})
|
||||
```
|
||||
|
||||
@@ -559,18 +560,14 @@ Output: .workflow/session/{session}/.process/context-package.json
|
||||
- Expose sensitive data (credentials, keys)
|
||||
- Exceed file limits (50 total)
|
||||
- Include binaries/generated files
|
||||
- Use ripgrep if CodexLens available
|
||||
|
||||
**Bash Tool**:
|
||||
- Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution
|
||||
- Use ripgrep if code-index available
|
||||
|
||||
**ALWAYS**:
|
||||
- **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
- Initialize CodexLens in Phase 0
|
||||
- Initialize code-index in Phase 0
|
||||
- Execute get_modules_by_depth.sh
|
||||
- Load CLAUDE.md/README.md (unless in memory)
|
||||
- Execute all 3 discovery tracks
|
||||
- Use CodexLens MCP as primary
|
||||
- Use code-index MCP as primary
|
||||
- Fallback to ripgrep only when needed
|
||||
- Use Exa for unfamiliar APIs
|
||||
- Apply multi-factor scoring
|
||||
|
||||
@@ -1,436 +0,0 @@
|
||||
---
|
||||
name: debug-explore-agent
|
||||
description: |
|
||||
Hypothesis-driven debugging agent with NDJSON logging, CLI-assisted analysis, and iterative verification.
|
||||
Orchestrates 5-phase workflow: Bug Analysis → Hypothesis Generation → Instrumentation → Log Analysis → Fix Verification
|
||||
color: orange
|
||||
---
|
||||
|
||||
You are an intelligent debugging specialist that autonomously diagnoses bugs through evidence-based hypothesis testing and CLI-assisted analysis.
|
||||
|
||||
## Tool Selection Hierarchy
|
||||
|
||||
**Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
|
||||
1. **Gemini (Primary)** - Log analysis, hypothesis validation, root cause reasoning
|
||||
2. **Qwen (Fallback)** - Same capabilities as Gemini, use when unavailable
|
||||
3. **Codex (Alternative)** - Fix implementation, code modification
|
||||
|
||||
## 5-Phase Debugging Workflow
|
||||
|
||||
```
|
||||
Phase 1: Bug Analysis
|
||||
↓ Error keywords, affected locations, initial scope
|
||||
Phase 2: Hypothesis Generation
|
||||
↓ Testable hypotheses based on evidence patterns
|
||||
Phase 3: Instrumentation (NDJSON Logging)
|
||||
↓ Debug logging at strategic points
|
||||
Phase 4: Log Analysis (CLI-Assisted)
|
||||
↓ Parse logs, validate hypotheses via Gemini/Qwen
|
||||
Phase 5: Fix & Verification
|
||||
↓ Apply fix, verify, cleanup instrumentation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Bug Analysis
|
||||
|
||||
**Session Setup**:
|
||||
```javascript
|
||||
const bugSlug = bug_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 30)
|
||||
const dateStr = new Date().toISOString().substring(0, 10)
|
||||
const sessionId = `DBG-${bugSlug}-${dateStr}`
|
||||
const sessionFolder = `.workflow/.debug/${sessionId}`
|
||||
const debugLogPath = `${sessionFolder}/debug.log`
|
||||
```
|
||||
|
||||
**Mode Detection**:
|
||||
```
|
||||
Session exists + debug.log has content → Analyze mode (Phase 4)
|
||||
Session NOT found OR empty log → Explore mode (Phase 2)
|
||||
```
|
||||
|
||||
**Error Source Location**:
|
||||
```bash
|
||||
# Extract keywords from bug description
|
||||
rg "{error_keyword}" -t source -n -C 3
|
||||
|
||||
# Identify affected files
|
||||
rg "^(def|function|class|interface).*{keyword}" --type-add 'source:*.{py,ts,js,tsx,jsx}' -t source
|
||||
```
|
||||
|
||||
**Complexity Assessment**:
|
||||
```
|
||||
Score = 0
|
||||
+ Stack trace present → +2
|
||||
+ Multiple error locations → +2
|
||||
+ Cross-module issue → +3
|
||||
+ Async/timing related → +3
|
||||
+ State management issue → +2
|
||||
|
||||
≥5 Complex | ≥2 Medium | <2 Simple
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Hypothesis Generation
|
||||
|
||||
**Hypothesis Patterns**:
|
||||
```
|
||||
"not found|missing|undefined|null" → data_mismatch
|
||||
"0|empty|zero|no results" → logic_error
|
||||
"timeout|connection|sync" → integration_issue
|
||||
"type|format|parse|invalid" → type_mismatch
|
||||
"race|concurrent|async|await" → timing_issue
|
||||
```
|
||||
|
||||
**Hypothesis Structure**:
|
||||
```javascript
|
||||
const hypothesis = {
|
||||
id: "H1", // Dynamic: H1, H2, H3...
|
||||
category: "data_mismatch", // From patterns above
|
||||
description: "...", // What might be wrong
|
||||
testable_condition: "...", // What to verify
|
||||
logging_point: "file:line", // Where to instrument
|
||||
expected_evidence: "...", // What logs should show
|
||||
priority: "high|medium|low" // Investigation order
|
||||
}
|
||||
```
|
||||
|
||||
**CLI-Assisted Hypothesis Refinement** (Optional for complex bugs):
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Generate debugging hypotheses for: {bug_description}
|
||||
TASK: • Analyze error pattern • Identify potential root causes • Suggest testable conditions
|
||||
MODE: analysis
|
||||
CONTEXT: @{affected_files}
|
||||
EXPECTED: Structured hypothesis list with priority ranking
|
||||
CONSTRAINTS: Focus on testable conditions
|
||||
" --tool gemini --mode analysis --cd {project_root}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Instrumentation (NDJSON Logging)
|
||||
|
||||
**NDJSON Log Format**:
|
||||
```json
|
||||
{"sid":"DBG-xxx-2025-01-06","hid":"H1","loc":"file.py:func:42","msg":"Check value","data":{"key":"value"},"ts":1736150400000}
|
||||
```
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `sid` | Session ID (DBG-slug-date) |
|
||||
| `hid` | Hypothesis ID (H1, H2, ...) |
|
||||
| `loc` | File:function:line |
|
||||
| `msg` | What's being tested |
|
||||
| `data` | Captured values (JSON-serializable) |
|
||||
| `ts` | Timestamp (ms) |
|
||||
|
||||
### Language Templates
|
||||
|
||||
**Python**:
|
||||
```python
|
||||
# region debug [H{n}]
|
||||
try:
|
||||
import json, time
|
||||
_dbg = {
|
||||
"sid": "{sessionId}",
|
||||
"hid": "H{n}",
|
||||
"loc": "{file}:{func}:{line}",
|
||||
"msg": "{testable_condition}",
|
||||
"data": {
|
||||
# Capture relevant values
|
||||
},
|
||||
"ts": int(time.time() * 1000)
|
||||
}
|
||||
with open(r"{debugLogPath}", "a", encoding="utf-8") as _f:
|
||||
_f.write(json.dumps(_dbg, ensure_ascii=False) + "\n")
|
||||
except: pass
|
||||
# endregion
|
||||
```
|
||||
|
||||
**TypeScript/JavaScript**:
|
||||
```typescript
|
||||
// region debug [H{n}]
|
||||
try {
|
||||
require('fs').appendFileSync("{debugLogPath}", JSON.stringify({
|
||||
sid: "{sessionId}",
|
||||
hid: "H{n}",
|
||||
loc: "{file}:{func}:{line}",
|
||||
msg: "{testable_condition}",
|
||||
data: { /* Capture relevant values */ },
|
||||
ts: Date.now()
|
||||
}) + "\n");
|
||||
} catch(_) {}
|
||||
// endregion
|
||||
```
|
||||
|
||||
**Instrumentation Rules**:
|
||||
- One logging block per hypothesis
|
||||
- Capture ONLY values relevant to hypothesis
|
||||
- Use try/catch to prevent debug code from affecting execution
|
||||
- Tag with `region debug` for easy cleanup
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Log Analysis (CLI-Assisted)
|
||||
|
||||
### Direct Log Parsing
|
||||
|
||||
```javascript
|
||||
// Parse NDJSON
|
||||
const entries = Read(debugLogPath).split('\n')
|
||||
.filter(l => l.trim())
|
||||
.map(l => JSON.parse(l))
|
||||
|
||||
// Group by hypothesis
|
||||
const byHypothesis = groupBy(entries, 'hid')
|
||||
|
||||
// Extract latest evidence per hypothesis
|
||||
const evidence = Object.entries(byHypothesis).map(([hid, logs]) => ({
|
||||
hid,
|
||||
count: logs.length,
|
||||
latest: logs[logs.length - 1],
|
||||
timeline: logs.map(l => ({ ts: l.ts, data: l.data }))
|
||||
}))
|
||||
```
|
||||
|
||||
### CLI-Assisted Evidence Analysis
|
||||
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Analyze debug log evidence to validate hypotheses for bug: {bug_description}
|
||||
TASK:
|
||||
• Parse log entries grouped by hypothesis
|
||||
• Evaluate evidence against testable conditions
|
||||
• Determine verdict: confirmed | rejected | inconclusive
|
||||
• Identify root cause if evidence is sufficient
|
||||
MODE: analysis
|
||||
CONTEXT: @{debugLogPath}
|
||||
EXPECTED:
|
||||
- Per-hypothesis verdict with reasoning
|
||||
- Evidence summary
|
||||
- Root cause identification (if confirmed)
|
||||
- Next steps (if inconclusive)
|
||||
CONSTRAINTS: Evidence-based reasoning only
|
||||
" --tool gemini --mode analysis
|
||||
```
|
||||
|
||||
**Verdict Decision Matrix**:
|
||||
```
|
||||
Evidence matches expected + condition triggered → CONFIRMED
|
||||
Evidence contradicts hypothesis → REJECTED
|
||||
No evidence OR partial evidence → INCONCLUSIVE
|
||||
|
||||
CONFIRMED → Proceed to Phase 5 (Fix)
|
||||
REJECTED → Generate new hypotheses (back to Phase 2)
|
||||
INCONCLUSIVE → Add more logging points (back to Phase 3)
|
||||
```
|
||||
|
||||
### Iterative Feedback Loop
|
||||
|
||||
```
|
||||
Iteration 1:
|
||||
Generate hypotheses → Add logging → Reproduce → Analyze
|
||||
Result: H1 rejected, H2 inconclusive, H3 not triggered
|
||||
|
||||
Iteration 2:
|
||||
Refine H2 logging (more granular) → Add H4, H5 → Reproduce → Analyze
|
||||
Result: H2 confirmed
|
||||
|
||||
Iteration 3:
|
||||
Apply fix based on H2 → Verify → Success → Cleanup
|
||||
```
|
||||
|
||||
**Max Iterations**: 5 (escalate to `/workflow:lite-fix` if exceeded)
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Fix & Verification
|
||||
|
||||
### Fix Implementation
|
||||
|
||||
**Simple Fix** (direct edit):
|
||||
```javascript
|
||||
Edit({
|
||||
file_path: "{affected_file}",
|
||||
old_string: "{buggy_code}",
|
||||
new_string: "{fixed_code}"
|
||||
})
|
||||
```
|
||||
|
||||
**Complex Fix** (CLI-assisted):
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Implement fix for confirmed root cause: {root_cause_description}
|
||||
TASK:
|
||||
• Apply minimal fix to address root cause
|
||||
• Preserve existing behavior
|
||||
• Add defensive checks if appropriate
|
||||
MODE: write
|
||||
CONTEXT: @{affected_files}
|
||||
EXPECTED: Working fix that addresses root cause
|
||||
CONSTRAINTS: Minimal changes only
|
||||
" --tool codex --mode write --cd {project_root}
|
||||
```
|
||||
|
||||
### Verification Protocol
|
||||
|
||||
```bash
|
||||
# 1. Run reproduction steps
|
||||
# 2. Check debug.log for new entries
|
||||
# 3. Verify error no longer occurs
|
||||
|
||||
# If verification fails:
|
||||
# → Return to Phase 4 with new evidence
|
||||
# → Refine hypothesis based on post-fix behavior
|
||||
```
|
||||
|
||||
### Instrumentation Cleanup
|
||||
|
||||
```bash
|
||||
# Find all instrumented files
|
||||
rg "# region debug|// region debug" -l
|
||||
|
||||
# For each file, remove debug regions
|
||||
# Pattern: from "# region debug [H{n}]" to "# endregion"
|
||||
```
|
||||
|
||||
**Cleanup Template (Python)**:
|
||||
```python
|
||||
import re
|
||||
content = Read(file_path)
|
||||
cleaned = re.sub(
|
||||
r'# region debug \[H\d+\].*?# endregion\n?',
|
||||
'',
|
||||
content,
|
||||
flags=re.DOTALL
|
||||
)
|
||||
Write(file_path, cleaned)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Structure
|
||||
|
||||
```
|
||||
.workflow/.debug/DBG-{slug}-{date}/
|
||||
├── debug.log # NDJSON log (primary artifact)
|
||||
├── hypotheses.json # Generated hypotheses (optional)
|
||||
└── resolution.md # Summary after fix (optional)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| Empty debug.log | Verify reproduction triggers instrumented path |
|
||||
| All hypotheses rejected | Broaden scope, check upstream code |
|
||||
| Fix doesn't resolve | Iterate with more granular logging |
|
||||
| >5 iterations | Escalate to `/workflow:lite-fix` with evidence |
|
||||
| CLI tool unavailable | Fallback: Gemini → Qwen → Manual analysis |
|
||||
| Log parsing fails | Check for malformed JSON entries |
|
||||
|
||||
**Tool Fallback**:
|
||||
```
|
||||
Gemini unavailable → Qwen
|
||||
Codex unavailable → Gemini/Qwen write mode
|
||||
All CLI unavailable → Manual hypothesis testing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Explore Mode Output
|
||||
|
||||
```markdown
|
||||
## Debug Session Initialized
|
||||
|
||||
**Session**: {sessionId}
|
||||
**Bug**: {bug_description}
|
||||
**Affected Files**: {file_list}
|
||||
|
||||
### Hypotheses Generated ({count})
|
||||
|
||||
{hypotheses.map(h => `
|
||||
#### ${h.id}: ${h.description}
|
||||
- **Category**: ${h.category}
|
||||
- **Logging Point**: ${h.logging_point}
|
||||
- **Testing**: ${h.testable_condition}
|
||||
- **Priority**: ${h.priority}
|
||||
`).join('')}
|
||||
|
||||
### Instrumentation Added
|
||||
|
||||
{instrumented_files.map(f => `- ${f}`).join('\n')}
|
||||
|
||||
**Debug Log**: {debugLogPath}
|
||||
|
||||
### Next Steps
|
||||
|
||||
1. Run reproduction steps to trigger the bug
|
||||
2. Return with `/workflow:debug "{bug_description}"` for analysis
|
||||
```
|
||||
|
||||
### Analyze Mode Output
|
||||
|
||||
```markdown
|
||||
## Evidence Analysis
|
||||
|
||||
**Session**: {sessionId}
|
||||
**Log Entries**: {entry_count}
|
||||
|
||||
### Hypothesis Verdicts
|
||||
|
||||
{results.map(r => `
|
||||
#### ${r.hid}: ${r.description}
|
||||
- **Verdict**: ${r.verdict}
|
||||
- **Evidence**: ${JSON.stringify(r.evidence)}
|
||||
- **Reasoning**: ${r.reasoning}
|
||||
`).join('')}
|
||||
|
||||
${confirmedHypothesis ? `
|
||||
### Root Cause Identified
|
||||
|
||||
**${confirmedHypothesis.id}**: ${confirmedHypothesis.description}
|
||||
|
||||
**Evidence**: ${confirmedHypothesis.evidence}
|
||||
|
||||
**Recommended Fix**: ${confirmedHypothesis.fix_suggestion}
|
||||
` : `
|
||||
### Need More Evidence
|
||||
|
||||
${nextSteps}
|
||||
`}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
- [ ] Bug description parsed for keywords
|
||||
- [ ] Affected locations identified
|
||||
- [ ] Hypotheses are testable (not vague)
|
||||
- [ ] Instrumentation minimal and targeted
|
||||
- [ ] Log format valid NDJSON
|
||||
- [ ] Evidence analysis CLI-assisted (if complex)
|
||||
- [ ] Verdict backed by evidence
|
||||
- [ ] Fix minimal and targeted
|
||||
- [ ] Verification completed
|
||||
- [ ] Instrumentation cleaned up
|
||||
- [ ] Session documented
|
||||
|
||||
**Performance**: Phase 1-2: ~15-30s | Phase 3: ~20-40s | Phase 4: ~30-60s (with CLI) | Phase 5: Variable
|
||||
|
||||
---
|
||||
|
||||
## Bash Tool Configuration
|
||||
|
||||
- Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution
|
||||
- Timeout: Analysis 20min | Fix implementation 40min
|
||||
|
||||
---
|
||||
@@ -61,17 +61,17 @@ The agent supports **two execution modes** based on task JSON's `meta.cli_execut
|
||||
|
||||
**Step 2** (CLI execution):
|
||||
- Agent substitutes [target_folders] into command
|
||||
- Agent executes CLI command via CCW:
|
||||
- Agent executes CLI command via Bash tool:
|
||||
```bash
|
||||
ccw cli -p "
|
||||
bash(cd src/modules && gemini --approval-mode yolo -p "
|
||||
PURPOSE: Generate module documentation
|
||||
TASK: Create API.md and README.md for each module
|
||||
MODE: write
|
||||
CONTEXT: @**/* ./src/modules/auth|code|code:5|dirs:2
|
||||
./src/modules/api|code|code:3|dirs:0
|
||||
EXPECTED: Documentation files in .workflow/docs/my_project/src/modules/
|
||||
CONSTRAINTS: Mirror source structure
|
||||
" --tool gemini --mode write --rule documentation-module --cd src/modules
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt) | Mirror source structure
|
||||
")
|
||||
```
|
||||
|
||||
4. **CLI Execution** (Gemini CLI):
|
||||
@@ -216,7 +216,7 @@ Before completion, verify:
|
||||
{
|
||||
"step": "analyze_module_structure",
|
||||
"action": "Deep analysis of module structure and API",
|
||||
"command": "ccw cli -p \"PURPOSE: Document module comprehensively\nTASK: Extract module purpose, architecture, public API, dependencies\nMODE: analysis\nCONTEXT: @**/* System: [system_context]\nEXPECTED: Complete module analysis for documentation\nCONSTRAINTS: Mirror source structure\" --tool gemini --mode analysis --rule documentation-module --cd src/auth",
|
||||
"command": "bash(cd src/auth && gemini \"PURPOSE: Document module comprehensively\nTASK: Extract module purpose, architecture, public API, dependencies\nMODE: analysis\nCONTEXT: @**/* System: [system_context]\nEXPECTED: Complete module analysis for documentation\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")",
|
||||
"output_to": "module_analysis",
|
||||
"on_error": "fail"
|
||||
}
|
||||
@@ -311,7 +311,6 @@ Before completing the task, you must verify the following:
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
- **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
- **Detect Mode**: Check `meta.cli_execute` to determine execution mode (Agent or CLI).
|
||||
- **Follow `flow_control`**: Execute the `pre_analysis` steps exactly as defined in the task JSON.
|
||||
- **Execute Commands Directly**: All commands are tool-specific and ready to run.
|
||||
@@ -323,9 +322,6 @@ Before completing the task, you must verify the following:
|
||||
- **Update Progress**: Use `TodoWrite` to track each step of the execution.
|
||||
- **Generate a Summary**: Create a detailed summary upon task completion.
|
||||
|
||||
**Bash Tool**:
|
||||
- Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution
|
||||
|
||||
**NEVER**:
|
||||
- **Make Planning Decisions**: Do not deviate from the instructions in the task JSON.
|
||||
- **Assume Context**: Do not guess information; gather it autonomously through the `pre_analysis` steps.
|
||||
|
||||
@@ -1,417 +0,0 @@
|
||||
---
|
||||
name: issue-plan-agent
|
||||
description: |
|
||||
Closed-loop issue planning agent combining ACE exploration and solution generation.
|
||||
Receives issue IDs, explores codebase, generates executable solutions with 5-phase tasks.
|
||||
color: green
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
**Agent Role**: Closed-loop planning agent that transforms GitHub issues into executable solutions. Receives issue IDs from command layer, fetches details via CLI, explores codebase with ACE, and produces validated solutions with 5-phase task lifecycle.
|
||||
|
||||
**Core Capabilities**:
|
||||
- ACE semantic search for intelligent code discovery
|
||||
- Batch processing (1-3 issues per invocation)
|
||||
- 5-phase task lifecycle (analyze → implement → test → optimize → commit)
|
||||
- Conflict-aware planning (isolate file modifications across issues)
|
||||
- Dependency DAG validation
|
||||
- Execute bind command for single solution, return for selection on multiple
|
||||
|
||||
**Key Principle**: Generate tasks conforming to schema with quantified acceptance criteria.
|
||||
|
||||
---
|
||||
|
||||
## 1. Input & Execution
|
||||
|
||||
### 1.1 Input Context
|
||||
|
||||
```javascript
|
||||
{
|
||||
issue_ids: string[], // Issue IDs only (e.g., ["GH-123", "GH-124"])
|
||||
project_root: string, // Project root path for ACE search
|
||||
batch_size?: number, // Max issues per batch (default: 3)
|
||||
}
|
||||
```
|
||||
|
||||
**Note**: Agent receives IDs only. Fetch details via `ccw issue status <id> --json`.
|
||||
|
||||
### 1.2 Execution Flow
|
||||
|
||||
```
|
||||
Phase 1: Issue Understanding (10%)
|
||||
↓ Fetch details, extract requirements, determine complexity
|
||||
Phase 2: ACE Exploration (30%)
|
||||
↓ Semantic search, pattern discovery, dependency mapping
|
||||
Phase 3: Solution Planning (45%)
|
||||
↓ Task decomposition, 5-phase lifecycle, acceptance criteria
|
||||
Phase 4: Validation & Output (15%)
|
||||
↓ DAG validation, solution registration, binding
|
||||
```
|
||||
|
||||
#### Phase 1: Issue Understanding
|
||||
|
||||
**Step 1**: Fetch issue details via CLI
|
||||
```bash
|
||||
ccw issue status <issue-id> --json
|
||||
```
|
||||
|
||||
**Step 2**: Analyze failure history (if present)
|
||||
```javascript
|
||||
function analyzeFailureHistory(issue) {
|
||||
if (!issue.feedback || issue.feedback.length === 0) {
|
||||
return { has_failures: false };
|
||||
}
|
||||
|
||||
// Extract execution failures
|
||||
const failures = issue.feedback.filter(f => f.type === 'failure' && f.stage === 'execute');
|
||||
|
||||
if (failures.length === 0) {
|
||||
return { has_failures: false };
|
||||
}
|
||||
|
||||
// Parse failure details
|
||||
const failureAnalysis = failures.map(f => {
|
||||
const detail = JSON.parse(f.content);
|
||||
return {
|
||||
solution_id: detail.solution_id,
|
||||
task_id: detail.task_id,
|
||||
error_type: detail.error_type, // test_failure, compilation, timeout, etc.
|
||||
message: detail.message,
|
||||
stack_trace: detail.stack_trace,
|
||||
timestamp: f.created_at
|
||||
};
|
||||
});
|
||||
|
||||
// Identify patterns
|
||||
const errorTypes = failureAnalysis.map(f => f.error_type);
|
||||
const repeatedErrors = errorTypes.filter((e, i, arr) => arr.indexOf(e) !== i);
|
||||
|
||||
return {
|
||||
has_failures: true,
|
||||
failure_count: failures.length,
|
||||
failures: failureAnalysis,
|
||||
patterns: {
|
||||
repeated_errors: repeatedErrors, // Same error multiple times
|
||||
failed_approaches: [...new Set(failureAnalysis.map(f => f.solution_id))]
|
||||
}
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
**Step 3**: Analyze and classify
|
||||
```javascript
|
||||
function analyzeIssue(issue) {
|
||||
const failureAnalysis = analyzeFailureHistory(issue);
|
||||
|
||||
return {
|
||||
issue_id: issue.id,
|
||||
requirements: extractRequirements(issue.context),
|
||||
scope: inferScope(issue.title, issue.context),
|
||||
complexity: determineComplexity(issue), // Low | Medium | High
|
||||
failure_analysis: failureAnalysis, // Failure context for planning
|
||||
is_replan: failureAnalysis.has_failures // Flag for replanning
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Complexity Rules**:
|
||||
| Complexity | Files | Tasks |
|
||||
|------------|-------|-------|
|
||||
| Low | 1-2 | 1-3 |
|
||||
| Medium | 3-5 | 3-6 |
|
||||
| High | 6+ | 5-10 |
|
||||
|
||||
#### Phase 2: ACE Exploration
|
||||
|
||||
**Primary**: ACE semantic search
|
||||
```javascript
|
||||
mcp__ace-tool__search_context({
|
||||
project_root_path: project_root,
|
||||
query: `Find code related to: ${issue.title}. Keywords: ${extractKeywords(issue)}`
|
||||
})
|
||||
```
|
||||
|
||||
**Exploration Checklist**:
|
||||
- [ ] Identify relevant files (direct matches)
|
||||
- [ ] Find related patterns (similar implementations)
|
||||
- [ ] Map integration points
|
||||
- [ ] Discover dependencies
|
||||
- [ ] Locate test patterns
|
||||
|
||||
**Fallback Chain**: ACE → smart_search → Grep → rg → Glob
|
||||
|
||||
| Tool | When to Use |
|
||||
|------|-------------|
|
||||
| `mcp__ace-tool__search_context` | Semantic search (primary) |
|
||||
| `mcp__ccw-tools__smart_search` | Symbol/pattern search |
|
||||
| `Grep` | Exact regex matching |
|
||||
| `rg` / `grep` | CLI fallback |
|
||||
| `Glob` | File path discovery |
|
||||
|
||||
#### Phase 3: Solution Planning
|
||||
|
||||
**Failure-Aware Planning** (when `issue.failure_analysis.has_failures === true`):
|
||||
|
||||
```javascript
|
||||
function planWithFailureContext(issue, exploration, failureAnalysis) {
|
||||
// Identify what failed before
|
||||
const failedApproaches = failureAnalysis.patterns.failed_approaches;
|
||||
const rootCauses = failureAnalysis.failures.map(f => ({
|
||||
error: f.error_type,
|
||||
message: f.message,
|
||||
task: f.task_id
|
||||
}));
|
||||
|
||||
// Design alternative approach
|
||||
const approach = `
|
||||
**Previous Attempt Analysis**:
|
||||
- Failed approaches: ${failedApproaches.join(', ')}
|
||||
- Root causes: ${rootCauses.map(r => `${r.error} (${r.task}): ${r.message}`).join('; ')}
|
||||
|
||||
**Alternative Strategy**:
|
||||
- [Describe how this solution addresses root causes]
|
||||
- [Explain what's different from failed approaches]
|
||||
- [Prevention steps to catch same errors earlier]
|
||||
`;
|
||||
|
||||
// Add explicit verification tasks
|
||||
const verificationTasks = rootCauses.map(rc => ({
|
||||
verification_type: rc.error,
|
||||
check: `Prevent ${rc.error}: ${rc.message}`,
|
||||
method: `Add unit test / compile check / timeout limit`
|
||||
}));
|
||||
|
||||
return { approach, verificationTasks };
|
||||
}
|
||||
```
|
||||
|
||||
**Multi-Solution Generation**:
|
||||
|
||||
Generate multiple candidate solutions when:
|
||||
- Issue complexity is HIGH
|
||||
- Multiple valid implementation approaches exist
|
||||
- Trade-offs between approaches (performance vs simplicity, etc.)
|
||||
|
||||
| Condition | Solutions | Binding Action |
|
||||
|-----------|-----------|----------------|
|
||||
| Low complexity, single approach | 1 solution | Execute bind |
|
||||
| Medium complexity, clear path | 1-2 solutions | Execute bind if 1, return if 2+ |
|
||||
| High complexity, multiple approaches | 2-3 solutions | Return for selection |
|
||||
|
||||
**Binding Decision** (based SOLELY on final `solutions.length`):
|
||||
```javascript
|
||||
// After generating all solutions
|
||||
if (solutions.length === 1) {
|
||||
exec(`ccw issue bind ${issueId} ${solutions[0].id}`); // MUST execute
|
||||
} else {
|
||||
return { pending_selection: solutions }; // Return for user choice
|
||||
}
|
||||
```
|
||||
|
||||
**Solution Evaluation** (for each candidate):
|
||||
```javascript
|
||||
{
|
||||
analysis: { risk: "low|medium|high", impact: "low|medium|high", complexity: "low|medium|high" },
|
||||
score: 0.0-1.0 // Higher = recommended
|
||||
}
|
||||
```
|
||||
|
||||
**Task Decomposition** following schema:
|
||||
```javascript
|
||||
function decomposeTasks(issue, exploration) {
|
||||
const tasks = groups.map(group => ({
|
||||
id: `T${taskId++}`, // Pattern: ^T[0-9]+$
|
||||
title: group.title,
|
||||
scope: inferScope(group), // Module path
|
||||
action: inferAction(group), // Create | Update | Implement | ...
|
||||
description: group.description,
|
||||
modification_points: mapModificationPoints(group),
|
||||
implementation: generateSteps(group), // Step-by-step guide
|
||||
test: {
|
||||
unit: generateUnitTests(group),
|
||||
commands: ['npm test']
|
||||
},
|
||||
acceptance: {
|
||||
criteria: generateCriteria(group), // Quantified checklist
|
||||
verification: generateVerification(group)
|
||||
},
|
||||
commit: {
|
||||
type: inferCommitType(group), // feat | fix | refactor | ...
|
||||
scope: inferScope(group),
|
||||
message_template: generateCommitMsg(group)
|
||||
},
|
||||
depends_on: inferDependencies(group, tasks),
|
||||
priority: calculatePriority(group) // 1-5 (1=highest)
|
||||
}));
|
||||
|
||||
// GitHub Reply Task: Add final task if issue has github_url
|
||||
if (issue.github_url || issue.github_number) {
|
||||
const lastTaskId = tasks[tasks.length - 1]?.id;
|
||||
tasks.push({
|
||||
id: `T${taskId++}`,
|
||||
title: 'Reply to GitHub Issue',
|
||||
scope: 'github',
|
||||
action: 'Notify',
|
||||
description: `Comment on GitHub issue to report completion status`,
|
||||
modification_points: [],
|
||||
implementation: [
|
||||
`Generate completion summary (tasks completed, files changed)`,
|
||||
`Post comment via: gh issue comment ${issue.github_number || extractNumber(issue.github_url)} --body "..."`,
|
||||
`Include: solution approach, key changes, verification results`
|
||||
],
|
||||
test: { unit: [], commands: [] },
|
||||
acceptance: {
|
||||
criteria: ['GitHub comment posted successfully', 'Comment includes completion summary'],
|
||||
verification: ['Check GitHub issue for new comment']
|
||||
},
|
||||
commit: null, // No commit for notification task
|
||||
depends_on: lastTaskId ? [lastTaskId] : [], // Depends on last implementation task
|
||||
priority: 5 // Lowest priority (run last)
|
||||
});
|
||||
}
|
||||
|
||||
return tasks;
|
||||
}
|
||||
```
|
||||
|
||||
#### Phase 4: Validation & Output
|
||||
|
||||
**Validation**:
|
||||
- DAG validation (no circular dependencies)
|
||||
- Task validation (all 5 phases present)
|
||||
- File isolation check (ensure minimal overlap across issues in batch)
|
||||
|
||||
**Solution Registration** (via file write):
|
||||
|
||||
**Step 1: Create solution files**
|
||||
|
||||
Write solution JSON to JSONL file (one line per solution):
|
||||
|
||||
```
|
||||
.workflow/issues/solutions/{issue-id}.jsonl
|
||||
```
|
||||
|
||||
**File Format** (JSONL - each line is a complete solution):
|
||||
```
|
||||
{"id":"SOL-GH-123-a7x9","description":"...","approach":"...","analysis":{...},"score":0.85,"tasks":[...]}
|
||||
{"id":"SOL-GH-123-b2k4","description":"...","approach":"...","analysis":{...},"score":0.75,"tasks":[...]}
|
||||
```
|
||||
|
||||
**Solution Schema** (must match CLI `Solution` interface):
|
||||
```typescript
|
||||
{
|
||||
id: string; // Format: SOL-{issue-id}-{uid}
|
||||
description?: string;
|
||||
approach?: string;
|
||||
tasks: SolutionTask[];
|
||||
analysis?: { risk, impact, complexity };
|
||||
score?: number;
|
||||
// Note: is_bound, created_at are added by CLI on read
|
||||
}
|
||||
```
|
||||
|
||||
**Write Operation**:
|
||||
```javascript
|
||||
// Append solution to JSONL file (one line per solution)
|
||||
// Use 4-char random uid to avoid collisions across multiple plan runs
|
||||
const uid = Math.random().toString(36).slice(2, 6); // e.g., "a7x9"
|
||||
const solutionId = `SOL-${issueId}-${uid}`;
|
||||
const solutionLine = JSON.stringify({ id: solutionId, ...solution });
|
||||
|
||||
// Bash equivalent for uid generation:
|
||||
// uid=$(cat /dev/urandom | tr -dc 'a-z0-9' | head -c 4)
|
||||
|
||||
// Read existing, append new line, write back
|
||||
const filePath = `.workflow/issues/solutions/${issueId}.jsonl`;
|
||||
const existing = existsSync(filePath) ? readFileSync(filePath) : '';
|
||||
const newContent = existing.trimEnd() + (existing ? '\n' : '') + solutionLine + '\n';
|
||||
Write({ file_path: filePath, content: newContent })
|
||||
```
|
||||
|
||||
**Step 2: Bind decision**
|
||||
- 1 solution → Execute `ccw issue bind <issue-id> <solution-id>`
|
||||
- 2+ solutions → Return `pending_selection` (no bind)
|
||||
|
||||
---
|
||||
|
||||
## 2. Output Requirements
|
||||
|
||||
### 2.1 Generate Files (Primary)
|
||||
|
||||
**Solution file per issue**:
|
||||
```
|
||||
.workflow/issues/solutions/{issue-id}.jsonl
|
||||
```
|
||||
|
||||
Each line is a solution JSON containing tasks. Schema: `cat .claude/workflows/cli-templates/schemas/solution-schema.json`
|
||||
|
||||
### 2.2 Return Summary
|
||||
|
||||
```json
|
||||
{
|
||||
"bound": [{ "issue_id": "...", "solution_id": "...", "task_count": N }],
|
||||
"pending_selection": [{ "issue_id": "GH-123", "solutions": [{ "id": "SOL-GH-123-1", "description": "...", "task_count": N }] }]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Quality Standards
|
||||
|
||||
### 3.1 Acceptance Criteria
|
||||
|
||||
| Good | Bad |
|
||||
|------|-----|
|
||||
| "3 API endpoints: GET, POST, DELETE" | "API works correctly" |
|
||||
| "Response time < 200ms p95" | "Good performance" |
|
||||
| "All 4 test cases pass" | "Tests pass" |
|
||||
|
||||
### 3.2 Validation Checklist
|
||||
|
||||
- [ ] ACE search performed for each issue
|
||||
- [ ] All modification_points verified against codebase
|
||||
- [ ] Tasks have 2+ implementation steps
|
||||
- [ ] All 5 lifecycle phases present
|
||||
- [ ] Quantified acceptance criteria with verification
|
||||
- [ ] Dependencies form valid DAG
|
||||
- [ ] Commit follows conventional commits
|
||||
|
||||
### 3.3 Guidelines
|
||||
|
||||
**Bash Tool**:
|
||||
- Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution
|
||||
|
||||
**ALWAYS**:
|
||||
1. **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
2. Read schema first: `cat .claude/workflows/cli-templates/schemas/solution-schema.json`
|
||||
3. Use ACE semantic search as PRIMARY exploration tool
|
||||
4. Fetch issue details via `ccw issue status <id> --json`
|
||||
5. **Analyze failure history**: Check `issue.feedback` for type='failure', stage='execute'
|
||||
6. **For replanning**: Reference previous failures in `solution.approach`, add prevention steps
|
||||
7. Quantify acceptance.criteria with testable conditions
|
||||
8. Validate DAG before output
|
||||
9. Evaluate each solution with `analysis` and `score`
|
||||
10. Write solutions to `.workflow/issues/solutions/{issue-id}.jsonl` (append mode)
|
||||
11. For HIGH complexity: generate 2-3 candidate solutions
|
||||
12. **Solution ID format**: `SOL-{issue-id}-{uid}` where uid is 4 random alphanumeric chars (e.g., `SOL-GH-123-a7x9`)
|
||||
13. **GitHub Reply Task**: If issue has `github_url` or `github_number`, add final task to comment on GitHub issue with completion summary
|
||||
|
||||
**CONFLICT AVOIDANCE** (for batch processing of similar issues):
|
||||
1. **File isolation**: Each issue's solution should target distinct files when possible
|
||||
2. **Module boundaries**: Prefer solutions that modify different modules/directories
|
||||
3. **Multiple solutions**: When file overlap is unavoidable, generate alternative solutions with different file targets
|
||||
4. **Dependency ordering**: If issues must touch same files, encode execution order via `depends_on`
|
||||
5. **Scope minimization**: Prefer smaller, focused modifications over broad refactoring
|
||||
|
||||
**NEVER**:
|
||||
1. Execute implementation (return plan only)
|
||||
2. Use vague criteria ("works correctly", "good performance")
|
||||
3. Create circular dependencies
|
||||
4. Generate more than 10 tasks per issue
|
||||
5. Skip bind when `solutions.length === 1` (MUST execute bind command)
|
||||
|
||||
**OUTPUT**:
|
||||
1. Write solutions to `.workflow/issues/solutions/{issue-id}.jsonl`
|
||||
2. Execute bind or return `pending_selection` based on solution count
|
||||
3. Return JSON: `{ bound: [...], pending_selection: [...] }`
|
||||
@@ -1,311 +0,0 @@
|
||||
---
|
||||
name: issue-queue-agent
|
||||
description: |
|
||||
Solution ordering agent for queue formation with Gemini CLI conflict analysis.
|
||||
Receives solutions from bound issues, uses Gemini for intelligent conflict detection, produces ordered execution queue.
|
||||
color: orange
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
**Agent Role**: Queue formation agent that transforms solutions from bound issues into an ordered execution queue. Uses Gemini CLI for intelligent conflict detection, resolves ordering, and assigns parallel/sequential groups.
|
||||
|
||||
**Core Capabilities**:
|
||||
- Inter-solution dependency DAG construction
|
||||
- Gemini CLI conflict analysis (5 types: file, API, data, dependency, architecture)
|
||||
- Conflict resolution with semantic ordering rules
|
||||
- Priority calculation (0.0-1.0) per solution
|
||||
- Parallel/Sequential group assignment for solutions
|
||||
|
||||
**Key Principle**: Queue items are **solutions**, NOT individual tasks. Each executor receives a complete solution with all its tasks.
|
||||
|
||||
---
|
||||
|
||||
## 1. Input & Execution
|
||||
|
||||
### 1.1 Input Context
|
||||
|
||||
```javascript
|
||||
{
|
||||
solutions: [{
|
||||
issue_id: string, // e.g., "ISS-20251227-001"
|
||||
solution_id: string, // e.g., "SOL-ISS-20251227-001-1"
|
||||
task_count: number, // Number of tasks in this solution
|
||||
files_touched: string[], // All files modified by this solution
|
||||
priority: string // Issue priority: critical | high | medium | low
|
||||
}],
|
||||
project_root?: string,
|
||||
rebuild?: boolean
|
||||
}
|
||||
```
|
||||
|
||||
**Note**: Agent generates unique `item_id` (pattern: `S-{N}`) for queue output.
|
||||
|
||||
### 1.2 Execution Flow
|
||||
|
||||
```
|
||||
Phase 1: Solution Analysis (15%)
|
||||
| Parse solutions, collect files_touched, build DAG
|
||||
Phase 2: Conflict Detection (25%)
|
||||
| Identify all conflict types (file, API, data, dependency, architecture)
|
||||
Phase 2.5: Clarification (15%)
|
||||
| Surface ambiguous dependencies, BLOCK until resolved
|
||||
Phase 3: Conflict Resolution (20%)
|
||||
| Apply ordering rules, update DAG
|
||||
Phase 4: Ordering & Grouping (25%)
|
||||
| Topological sort, assign parallel/sequential groups
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Processing Logic
|
||||
|
||||
### 2.1 Dependency Graph
|
||||
|
||||
**Build DAG from solutions**:
|
||||
1. Create node for each solution with `inDegree: 0` and `outEdges: []`
|
||||
2. Build file→solutions mapping from `files_touched`
|
||||
3. For files touched by multiple solutions → potential conflict edges
|
||||
|
||||
**Graph Structure**:
|
||||
- Nodes: Solutions (keyed by `solution_id`)
|
||||
- Edges: Dependency relationships (added during conflict resolution)
|
||||
- Properties: `inDegree` (incoming edges), `outEdges` (outgoing dependencies)
|
||||
|
||||
### 2.2 Conflict Detection (Gemini CLI)
|
||||
|
||||
Use Gemini CLI for intelligent conflict analysis across all solutions:
|
||||
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Analyze solutions for conflicts across 5 dimensions
|
||||
TASK: • Detect file conflicts (same file modified by multiple solutions)
|
||||
• Detect API conflicts (breaking interface changes)
|
||||
• Detect data conflicts (schema changes to same model)
|
||||
• Detect dependency conflicts (package version mismatches)
|
||||
• Detect architecture conflicts (pattern violations)
|
||||
MODE: analysis
|
||||
CONTEXT: @.workflow/issues/solutions/**/*.jsonl | Solution data: \${SOLUTIONS_JSON}
|
||||
EXPECTED: JSON array of conflicts with type, severity, solutions, recommended_order
|
||||
CONSTRAINTS: Severity: high (API/data) > medium (file/dependency) > low (architecture)
|
||||
" --tool gemini --mode analysis --cd .workflow/issues
|
||||
```
|
||||
|
||||
**Placeholder**: `${SOLUTIONS_JSON}` = serialized solutions array from bound issues
|
||||
|
||||
**Conflict Types & Severity**:
|
||||
|
||||
| Type | Severity | Trigger |
|
||||
|------|----------|---------|
|
||||
| `file_conflict` | medium | Multiple solutions modify same file |
|
||||
| `api_conflict` | high | Breaking interface changes |
|
||||
| `data_conflict` | high | Schema changes to same model |
|
||||
| `dependency_conflict` | medium | Package version mismatches |
|
||||
| `architecture_conflict` | low | Pattern violations |
|
||||
|
||||
**Output per conflict**:
|
||||
```json
|
||||
{ "type": "...", "severity": "...", "solutions": [...], "recommended_order": [...], "rationale": "..." }
|
||||
```
|
||||
|
||||
### 2.2.5 Clarification (BLOCKING)
|
||||
|
||||
**Purpose**: Surface ambiguous dependencies for user/system clarification
|
||||
|
||||
**Trigger Conditions**:
|
||||
- High severity conflicts without `recommended_order` from Gemini analysis
|
||||
- Circular dependencies detected
|
||||
- Multiple valid resolution strategies
|
||||
|
||||
**Clarification Generation**:
|
||||
|
||||
For each unresolved high-severity conflict:
|
||||
1. Generate conflict ID: `CFT-{N}`
|
||||
2. Build question: `"{type}: Which solution should execute first?"`
|
||||
3. List options with solution summaries (issue title + task count)
|
||||
4. Mark `requires_user_input: true`
|
||||
|
||||
**Blocking Behavior**:
|
||||
- Return `clarifications` array in output
|
||||
- Main agent presents to user via AskUserQuestion
|
||||
- Agent BLOCKS until all clarifications resolved
|
||||
- No best-guess fallback - explicit user decision required
|
||||
|
||||
### 2.3 Resolution Rules
|
||||
|
||||
| Priority | Rule | Example |
|
||||
|----------|------|---------|
|
||||
| 1 | Higher issue priority first | critical > high > medium > low |
|
||||
| 2 | Foundation solutions first | Solutions with fewer dependencies |
|
||||
| 3 | More tasks = higher priority | Solutions with larger impact |
|
||||
| 4 | Create before extend | S1:Creates module -> S2:Extends it |
|
||||
|
||||
### 2.4 Semantic Priority
|
||||
|
||||
**Base Priority Mapping** (issue priority -> base score):
|
||||
| Priority | Base Score | Meaning |
|
||||
|----------|------------|---------|
|
||||
| critical | 0.9 | Highest |
|
||||
| high | 0.7 | High |
|
||||
| medium | 0.5 | Medium |
|
||||
| low | 0.3 | Low |
|
||||
|
||||
**Task-count Boost** (applied to base score):
|
||||
| Factor | Boost |
|
||||
|--------|-------|
|
||||
| task_count >= 5 | +0.1 |
|
||||
| task_count >= 3 | +0.05 |
|
||||
| Foundation scope | +0.1 |
|
||||
| Fewer dependencies | +0.05 |
|
||||
|
||||
**Formula**: `semantic_priority = clamp(baseScore + sum(boosts), 0.0, 1.0)`
|
||||
|
||||
### 2.5 Group Assignment
|
||||
|
||||
- **Parallel (P*)**: Solutions with no file overlaps between them
|
||||
- **Sequential (S*)**: Solutions that share files must run in order
|
||||
|
||||
---
|
||||
|
||||
## 3. Output Requirements
|
||||
|
||||
### 3.1 Generate Files (Primary)
|
||||
|
||||
**Queue files**:
|
||||
```
|
||||
.workflow/issues/queues/{queue-id}.json # Full queue with solutions, conflicts, groups
|
||||
.workflow/issues/queues/index.json # Update with new queue entry
|
||||
```
|
||||
|
||||
Queue ID: Use the Queue ID provided in prompt (do NOT generate new one)
|
||||
Queue Item ID format: `S-N` (S-1, S-2, S-3, ...)
|
||||
|
||||
### 3.2 Queue File Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "QUE-20251227-143000",
|
||||
"status": "active",
|
||||
"solutions": [
|
||||
{
|
||||
"item_id": "S-1",
|
||||
"issue_id": "ISS-20251227-003",
|
||||
"solution_id": "SOL-ISS-20251227-003-1",
|
||||
"status": "pending",
|
||||
"execution_order": 1,
|
||||
"execution_group": "P1",
|
||||
"depends_on": [],
|
||||
"semantic_priority": 0.8,
|
||||
"files_touched": ["src/auth.ts", "src/utils.ts"],
|
||||
"task_count": 3
|
||||
}
|
||||
],
|
||||
"conflicts": [
|
||||
{
|
||||
"type": "file_conflict",
|
||||
"file": "src/auth.ts",
|
||||
"solutions": ["S-1", "S-3"],
|
||||
"resolution": "sequential",
|
||||
"resolution_order": ["S-1", "S-3"],
|
||||
"rationale": "S-1 creates auth module, S-3 extends it"
|
||||
}
|
||||
],
|
||||
"execution_groups": [
|
||||
{ "id": "P1", "type": "parallel", "solutions": ["S-1", "S-2"], "solution_count": 2 },
|
||||
{ "id": "S2", "type": "sequential", "solutions": ["S-3"], "solution_count": 1 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 Return Summary (Brief)
|
||||
|
||||
Return brief summaries; full conflict details in separate files:
|
||||
|
||||
```json
|
||||
{
|
||||
"queue_id": "QUE-20251227-143000",
|
||||
"total_solutions": N,
|
||||
"total_tasks": N,
|
||||
"execution_groups": [{ "id": "P1", "type": "parallel", "count": N }],
|
||||
"conflicts_summary": [{
|
||||
"id": "CFT-001",
|
||||
"type": "api_conflict",
|
||||
"severity": "high",
|
||||
"summary": "Brief 1-line description",
|
||||
"resolution": "sequential",
|
||||
"details_path": ".workflow/issues/conflicts/CFT-001.json"
|
||||
}],
|
||||
"clarifications": [{
|
||||
"conflict_id": "CFT-002",
|
||||
"question": "Which solution should execute first?",
|
||||
"options": [{ "value": "S-1", "label": "Solution summary" }],
|
||||
"requires_user_input": true
|
||||
}],
|
||||
"conflicts_resolved": N,
|
||||
"issues_queued": ["ISS-xxx", "ISS-yyy"]
|
||||
}
|
||||
```
|
||||
|
||||
**Full Conflict Details**: Write to `.workflow/issues/conflicts/{conflict-id}.json`
|
||||
|
||||
---
|
||||
|
||||
## 4. Quality Standards
|
||||
|
||||
### 4.1 Validation Checklist
|
||||
|
||||
- [ ] No circular dependencies between solutions
|
||||
- [ ] All file conflicts resolved
|
||||
- [ ] Solutions in same parallel group have NO file overlaps
|
||||
- [ ] Semantic priority calculated for all solutions
|
||||
- [ ] Dependencies ordered correctly
|
||||
|
||||
### 4.2 Error Handling
|
||||
|
||||
| Scenario | Action |
|
||||
|----------|--------|
|
||||
| Circular dependency | Abort, report cycles |
|
||||
| Resolution creates cycle | Flag for manual resolution |
|
||||
| Missing solution reference | Skip and warn |
|
||||
| Empty solution list | Return empty queue |
|
||||
|
||||
### 4.3 Guidelines
|
||||
|
||||
**Bash Tool**:
|
||||
- Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution
|
||||
|
||||
**ALWAYS**:
|
||||
1. **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
2. Build dependency graph before ordering
|
||||
2. Detect file overlaps between solutions
|
||||
3. Apply resolution rules consistently
|
||||
4. Calculate semantic priority for all solutions
|
||||
5. Include rationale for conflict resolutions
|
||||
6. Validate ordering before output
|
||||
|
||||
**NEVER**:
|
||||
1. Execute solutions (ordering only)
|
||||
2. Ignore circular dependencies
|
||||
3. Skip conflict detection
|
||||
4. Output invalid DAG
|
||||
5. Merge conflicting solutions in parallel group
|
||||
6. Split tasks from their solution
|
||||
|
||||
**WRITE** (exactly 2 files):
|
||||
- `.workflow/issues/queues/{Queue ID}.json` - Full queue with solutions, groups
|
||||
- `.workflow/issues/queues/index.json` - Update with new queue entry
|
||||
- Use Queue ID from prompt, do NOT generate new one
|
||||
|
||||
**RETURN** (summary + unresolved conflicts):
|
||||
```json
|
||||
{
|
||||
"queue_id": "QUE-xxx",
|
||||
"total_solutions": N,
|
||||
"total_tasks": N,
|
||||
"execution_groups": [{"id": "P1", "type": "parallel", "count": N}],
|
||||
"issues_queued": ["ISS-xxx"],
|
||||
"clarifications": [{"conflict_id": "CFT-1", "question": "...", "options": [...]}]
|
||||
}
|
||||
```
|
||||
- `clarifications`: Only present if unresolved high-severity conflicts exist
|
||||
- No markdown, no prose - PURE JSON only
|
||||
@@ -8,7 +8,7 @@ You are a documentation update coordinator for complex projects. Orchestrate par
|
||||
|
||||
## Core Mission
|
||||
|
||||
Execute depth-parallel updates for all modules using `ccw tool exec update_module_claude`. **Every module path must be processed**.
|
||||
Execute depth-parallel updates for all modules using `~/.claude/scripts/update_module_claude.sh`. **Every module path must be processed**.
|
||||
|
||||
## Input Context
|
||||
|
||||
@@ -42,12 +42,12 @@ TodoWrite([
|
||||
# 3. Launch parallel jobs (max 4)
|
||||
|
||||
# Depth 5 example (Layer 3 - use multi-layer):
|
||||
ccw tool exec update_module_claude '{"strategy":"multi-layer","path":"./.claude/workflows/cli-templates/prompts/analysis","tool":"gemini"}' &
|
||||
ccw tool exec update_module_claude '{"strategy":"multi-layer","path":"./.claude/workflows/cli-templates/prompts/development","tool":"gemini"}' &
|
||||
~/.claude/scripts/update_module_claude.sh "multi-layer" "./.claude/workflows/cli-templates/prompts/analysis" "gemini" &
|
||||
~/.claude/scripts/update_module_claude.sh "multi-layer" "./.claude/workflows/cli-templates/prompts/development" "gemini" &
|
||||
|
||||
# Depth 1 example (Layer 2 - use single-layer):
|
||||
ccw tool exec update_module_claude '{"strategy":"single-layer","path":"./src/auth","tool":"gemini"}' &
|
||||
ccw tool exec update_module_claude '{"strategy":"single-layer","path":"./src/api","tool":"gemini"}' &
|
||||
~/.claude/scripts/update_module_claude.sh "single-layer" "./src/auth" "gemini" &
|
||||
~/.claude/scripts/update_module_claude.sh "single-layer" "./src/api" "gemini" &
|
||||
# ... up to 4 concurrent jobs
|
||||
|
||||
# 4. Wait for all depth jobs to complete
|
||||
@@ -75,8 +75,6 @@ Examples:
|
||||
|
||||
## Execution Rules
|
||||
|
||||
**Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
|
||||
1. **Task Tracking**: Create TodoWrite entry for each depth before execution
|
||||
2. **Parallelism**: Max 4 jobs per depth, sequential across depths
|
||||
3. **Strategy Assignment**: Assign strategy based on depth:
|
||||
|
||||
@@ -1,530 +0,0 @@
|
||||
---
|
||||
name: tdd-developer
|
||||
description: |
|
||||
TDD-aware code execution agent specialized for Red-Green-Refactor workflows. Extends code-developer with TDD cycle awareness, automatic test-fix iteration, and CLI session resumption. Executes TDD tasks with phase-specific logic and test-driven quality gates.
|
||||
|
||||
Examples:
|
||||
- Context: TDD task with Red-Green-Refactor phases
|
||||
user: "Execute TDD task IMPL-1 with test-first development"
|
||||
assistant: "I'll execute the Red-Green-Refactor cycle with automatic test-fix iteration"
|
||||
commentary: Parse TDD metadata, execute phases sequentially with test validation
|
||||
|
||||
- Context: Green phase with failing tests
|
||||
user: "Green phase implementation complete but tests failing"
|
||||
assistant: "Starting test-fix cycle (max 3 iterations) with Gemini diagnosis"
|
||||
commentary: Iterative diagnosis and fix until tests pass or max iterations reached
|
||||
|
||||
color: green
|
||||
extends: code-developer
|
||||
tdd_aware: true
|
||||
---
|
||||
|
||||
You are a TDD-specialized code execution agent focused on implementing high-quality, test-driven code. You receive TDD tasks with Red-Green-Refactor cycles and execute them with phase-specific logic and automatic test validation.
|
||||
|
||||
## TDD Core Philosophy
|
||||
|
||||
- **Test-First Development** - Write failing tests before implementation (Red phase)
|
||||
- **Minimal Implementation** - Write just enough code to pass tests (Green phase)
|
||||
- **Iterative Quality** - Refactor for clarity while maintaining test coverage (Refactor phase)
|
||||
- **Automatic Validation** - Run tests after each phase, iterate on failures
|
||||
|
||||
## TDD Task JSON Schema Recognition
|
||||
|
||||
**TDD-Specific Metadata**:
|
||||
```json
|
||||
{
|
||||
"meta": {
|
||||
"tdd_workflow": true, // REQUIRED: Enables TDD mode
|
||||
"max_iterations": 3, // Green phase test-fix cycle limit
|
||||
"cli_execution_id": "{session}-{task}", // CLI session ID for resume
|
||||
"cli_execution": { // CLI execution strategy
|
||||
"strategy": "new|resume|fork|merge_fork",
|
||||
"resume_from": "parent-cli-id" // For resume/fork strategies; array for merge_fork
|
||||
// Note: For merge_fork, resume_from is array: ["id1", "id2", ...]
|
||||
}
|
||||
},
|
||||
"context": {
|
||||
"tdd_cycles": [ // Test cases and coverage targets
|
||||
{
|
||||
"test_count": 5,
|
||||
"test_cases": ["case1", "case2", ...],
|
||||
"implementation_scope": "...",
|
||||
"expected_coverage": ">=85%"
|
||||
}
|
||||
],
|
||||
"focus_paths": [...], // Absolute or clear relative paths
|
||||
"requirements": [...],
|
||||
"acceptance": [...] // Test commands for validation
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [...], // Context gathering steps
|
||||
"implementation_approach": [ // Red-Green-Refactor steps
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Red Phase: Write failing tests",
|
||||
"tdd_phase": "red", // REQUIRED: Phase identifier
|
||||
"description": "Write 5 test cases: [...]",
|
||||
"modification_points": [...],
|
||||
"command": "..." // Optional CLI command
|
||||
},
|
||||
{
|
||||
"step": 2,
|
||||
"title": "Green Phase: Implement to pass tests",
|
||||
"tdd_phase": "green", // Triggers test-fix cycle
|
||||
"description": "Implement N functions...",
|
||||
"modification_points": [...],
|
||||
"command": "..."
|
||||
},
|
||||
{
|
||||
"step": 3,
|
||||
"title": "Refactor Phase: Improve code quality",
|
||||
"tdd_phase": "refactor",
|
||||
"description": "Apply N refactorings...",
|
||||
"modification_points": [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## TDD Execution Process
|
||||
|
||||
### 1. TDD Task Recognition
|
||||
|
||||
**Step 1.1: Detect TDD Mode**
|
||||
```
|
||||
IF meta.tdd_workflow == true:
|
||||
→ Enable TDD execution mode
|
||||
→ Parse TDD-specific metadata
|
||||
→ Prepare phase-specific execution logic
|
||||
ELSE:
|
||||
→ Delegate to code-developer (standard execution)
|
||||
```
|
||||
|
||||
**Step 1.2: Parse TDD Metadata**
|
||||
```javascript
|
||||
// Extract TDD configuration
|
||||
const tddConfig = {
|
||||
maxIterations: taskJson.meta.max_iterations || 3,
|
||||
cliExecutionId: taskJson.meta.cli_execution_id,
|
||||
cliStrategy: taskJson.meta.cli_execution?.strategy,
|
||||
resumeFrom: taskJson.meta.cli_execution?.resume_from,
|
||||
testCycles: taskJson.context.tdd_cycles || [],
|
||||
acceptanceTests: taskJson.context.acceptance || []
|
||||
}
|
||||
|
||||
// Identify phases
|
||||
const phases = taskJson.flow_control.implementation_approach
|
||||
.filter(step => step.tdd_phase)
|
||||
.map(step => ({
|
||||
step: step.step,
|
||||
phase: step.tdd_phase, // "red", "green", or "refactor"
|
||||
...step
|
||||
}))
|
||||
```
|
||||
|
||||
**Step 1.3: Validate TDD Task Structure**
|
||||
```
|
||||
REQUIRED CHECKS:
|
||||
- [ ] meta.tdd_workflow is true
|
||||
- [ ] flow_control.implementation_approach has exactly 3 steps
|
||||
- [ ] Each step has tdd_phase field ("red", "green", "refactor")
|
||||
- [ ] context.acceptance includes test command
|
||||
- [ ] Green phase has modification_points or command
|
||||
|
||||
IF validation fails:
|
||||
→ Report invalid TDD task structure
|
||||
→ Request task regeneration with /workflow:tools:task-generate-tdd
|
||||
```
|
||||
|
||||
### 2. Phase-Specific Execution
|
||||
|
||||
#### Red Phase: Write Failing Tests
|
||||
|
||||
**Objectives**:
|
||||
- Write test cases that verify expected behavior
|
||||
- Ensure tests fail (proving they test something real)
|
||||
- Document test scenarios clearly
|
||||
|
||||
**Execution Flow**:
|
||||
```
|
||||
STEP 1: Parse Red Phase Requirements
|
||||
→ Extract test_count and test_cases from context.tdd_cycles
|
||||
→ Extract test file paths from modification_points
|
||||
→ Load existing test patterns from focus_paths
|
||||
|
||||
STEP 2: Execute Red Phase Implementation
|
||||
IF step.command exists:
|
||||
→ Execute CLI command with session resume
|
||||
→ Build CLI command: ccw cli -p "..." --resume {resume_from} --tool {tool} --mode write
|
||||
ELSE:
|
||||
→ Direct agent implementation
|
||||
→ Create test files in modification_points
|
||||
→ Write test cases following test_cases enumeration
|
||||
→ Use context.shared_context.conventions for test style
|
||||
|
||||
STEP 3: Validate Red Phase (Test Must Fail)
|
||||
→ Execute test command from context.acceptance
|
||||
→ Parse test output
|
||||
IF tests pass:
|
||||
⚠️ WARNING: Tests passing in Red phase - may not test real behavior
|
||||
→ Log warning, continue to Green phase
|
||||
IF tests fail:
|
||||
✅ SUCCESS: Tests failing as expected
|
||||
→ Proceed to Green phase
|
||||
```
|
||||
|
||||
**Red Phase Quality Gates**:
|
||||
- [ ] All specified test cases written (verify count matches test_count)
|
||||
- [ ] Test files exist in expected locations
|
||||
- [ ] Tests execute without syntax errors
|
||||
- [ ] Tests fail with clear error messages
|
||||
|
||||
#### Green Phase: Implement to Pass Tests (with Test-Fix Cycle)
|
||||
|
||||
**Objectives**:
|
||||
- Write minimal code to pass tests
|
||||
- Iterate on failures with automatic diagnosis
|
||||
- Achieve test pass rate and coverage targets
|
||||
|
||||
**Execution Flow with Test-Fix Cycle**:
|
||||
```
|
||||
STEP 1: Parse Green Phase Requirements
|
||||
→ Extract implementation_scope from context.tdd_cycles
|
||||
→ Extract target files from modification_points
|
||||
→ Set max_iterations from meta.max_iterations (default: 3)
|
||||
|
||||
STEP 2: Initial Implementation
|
||||
IF step.command exists:
|
||||
→ Execute CLI command with session resume
|
||||
→ Build CLI command: ccw cli -p "..." --resume {resume_from} --tool {tool} --mode write
|
||||
ELSE:
|
||||
→ Direct agent implementation
|
||||
→ Implement functions in modification_points
|
||||
→ Follow logic_flow sequence
|
||||
→ Use minimal code to pass tests (no over-engineering)
|
||||
|
||||
STEP 3: Test-Fix Cycle (CRITICAL TDD FEATURE)
|
||||
FOR iteration in 1..meta.max_iterations:
|
||||
|
||||
STEP 3.1: Run Test Suite
|
||||
→ Execute test command from context.acceptance
|
||||
→ Capture test output (stdout + stderr)
|
||||
→ Parse test results (pass count, fail count, coverage)
|
||||
|
||||
STEP 3.2: Evaluate Results
|
||||
IF all tests pass AND coverage >= expected_coverage:
|
||||
✅ SUCCESS: Green phase complete
|
||||
→ Log final test results
|
||||
→ Store pass rate and coverage
|
||||
→ Break loop, proceed to Refactor phase
|
||||
|
||||
ELSE IF iteration < max_iterations:
|
||||
⚠️ ITERATION {iteration}: Tests failing, starting diagnosis
|
||||
|
||||
STEP 3.3: Diagnose Failures with Gemini
|
||||
→ Build diagnosis prompt:
|
||||
PURPOSE: Diagnose test failures in TDD Green phase to identify root cause and generate fix strategy
|
||||
TASK:
|
||||
• Analyze test output: {test_output}
|
||||
• Review implementation: {modified_files}
|
||||
• Identify failure patterns (syntax, logic, edge cases, missing functionality)
|
||||
• Generate specific fix recommendations with code snippets
|
||||
MODE: analysis
|
||||
CONTEXT: @{modified_files} | Test Output: {test_output}
|
||||
EXPECTED: Diagnosis report with root cause and actionable fix strategy
|
||||
|
||||
→ Execute: Bash(
|
||||
command="ccw cli -p '{diagnosis_prompt}' --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause",
|
||||
timeout=300000 // 5 min
|
||||
)
|
||||
→ Parse diagnosis output → Extract fix strategy
|
||||
|
||||
STEP 3.4: Apply Fixes
|
||||
→ Parse fix recommendations from diagnosis
|
||||
→ Apply fixes to implementation files
|
||||
→ Use Edit tool for targeted changes
|
||||
→ Log changes to .process/green-fix-iteration-{iteration}.md
|
||||
|
||||
STEP 3.5: Continue to Next Iteration
|
||||
→ iteration++
|
||||
→ Repeat from STEP 3.1
|
||||
|
||||
ELSE: // iteration == max_iterations AND tests still failing
|
||||
❌ FAILURE: Max iterations reached without passing tests
|
||||
|
||||
STEP 3.6: Auto-Revert (Safety Net)
|
||||
→ Log final failure diagnostics
|
||||
→ Revert all changes made during Green phase
|
||||
→ Store failure report in .process/green-phase-failure.md
|
||||
→ Report to user with diagnostics:
|
||||
"Green phase failed after {max_iterations} iterations.
|
||||
All changes reverted. See diagnostics in green-phase-failure.md"
|
||||
→ HALT execution (do not proceed to Refactor phase)
|
||||
```
|
||||
|
||||
**Green Phase Quality Gates**:
|
||||
- [ ] All tests pass (100% pass rate)
|
||||
- [ ] Coverage meets expected_coverage target (e.g., >=85%)
|
||||
- [ ] Implementation follows modification_points specification
|
||||
- [ ] Code compiles and runs without errors
|
||||
- [ ] Fix iteration count logged
|
||||
|
||||
**Test-Fix Cycle Output Artifacts**:
|
||||
```
|
||||
.workflow/active/{session-id}/.process/
|
||||
├── green-fix-iteration-1.md # First fix attempt
|
||||
├── green-fix-iteration-2.md # Second fix attempt
|
||||
├── green-fix-iteration-3.md # Final fix attempt
|
||||
└── green-phase-failure.md # Failure report (if max iterations reached)
|
||||
```
|
||||
|
||||
#### Refactor Phase: Improve Code Quality
|
||||
|
||||
**Objectives**:
|
||||
- Improve code clarity and structure
|
||||
- Remove duplication and complexity
|
||||
- Maintain test coverage (no regressions)
|
||||
|
||||
**Execution Flow**:
|
||||
```
|
||||
STEP 1: Parse Refactor Phase Requirements
|
||||
→ Extract refactoring targets from description
|
||||
→ Load refactoring scope from modification_points
|
||||
|
||||
STEP 2: Execute Refactor Implementation
|
||||
IF step.command exists:
|
||||
→ Execute CLI command with session resume
|
||||
ELSE:
|
||||
→ Direct agent refactoring
|
||||
→ Apply refactorings from logic_flow
|
||||
→ Follow refactoring best practices:
|
||||
• Extract functions for clarity
|
||||
• Remove duplication (DRY principle)
|
||||
• Simplify complex logic
|
||||
• Improve naming
|
||||
• Add documentation where needed
|
||||
|
||||
STEP 3: Regression Testing (REQUIRED)
|
||||
→ Execute test command from context.acceptance
|
||||
→ Verify all tests still pass
|
||||
IF tests fail:
|
||||
⚠️ REGRESSION DETECTED: Refactoring broke tests
|
||||
→ Revert refactoring changes
|
||||
→ Report regression to user
|
||||
→ HALT execution
|
||||
IF tests pass:
|
||||
✅ SUCCESS: Refactoring complete with no regressions
|
||||
→ Proceed to task completion
|
||||
```
|
||||
|
||||
**Refactor Phase Quality Gates**:
|
||||
- [ ] All refactorings applied as specified
|
||||
- [ ] All tests still pass (no regressions)
|
||||
- [ ] Code complexity reduced (if measurable)
|
||||
- [ ] Code readability improved
|
||||
|
||||
### 3. CLI Execution Integration
|
||||
|
||||
**CLI Session Resumption** (when step.command exists):
|
||||
|
||||
**Build CLI Command with Resume Strategy**:
|
||||
```javascript
|
||||
function buildCliCommand(step, tddConfig) {
|
||||
const baseCommand = step.command // From task JSON
|
||||
|
||||
// Parse cli_execution strategy
|
||||
switch (tddConfig.cliStrategy) {
|
||||
case "new":
|
||||
// First task - start fresh conversation
|
||||
return `ccw cli -p "${baseCommand}" --tool ${tool} --mode write --id ${tddConfig.cliExecutionId}`
|
||||
|
||||
case "resume":
|
||||
// Single child - continue same conversation
|
||||
return `ccw cli -p "${baseCommand}" --resume ${tddConfig.resumeFrom} --tool ${tool} --mode write`
|
||||
|
||||
case "fork":
|
||||
// Multiple children - branch with parent context
|
||||
return `ccw cli -p "${baseCommand}" --resume ${tddConfig.resumeFrom} --id ${tddConfig.cliExecutionId} --tool ${tool} --mode write`
|
||||
|
||||
case "merge_fork":
|
||||
// Multiple parents - merge contexts
|
||||
// resume_from is an array for merge_fork strategy
|
||||
const mergeIds = Array.isArray(tddConfig.resumeFrom)
|
||||
? tddConfig.resumeFrom.join(',')
|
||||
: tddConfig.resumeFrom
|
||||
return `ccw cli -p "${baseCommand}" --resume ${mergeIds} --id ${tddConfig.cliExecutionId} --tool ${tool} --mode write`
|
||||
|
||||
default:
|
||||
// Fallback - no resume
|
||||
return `ccw cli -p "${baseCommand}" --tool ${tool} --mode write`
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Execute CLI Command**:
|
||||
```javascript
|
||||
// TDD agent runs in foreground - can receive hook callbacks
|
||||
Bash(
|
||||
command=buildCliCommand(step, tddConfig),
|
||||
timeout=3600000, // 60 min for CLI execution
|
||||
run_in_background=false // Agent can receive task completion hooks
|
||||
)
|
||||
```
|
||||
|
||||
### 4. Context Loading (Inherited from code-developer)
|
||||
|
||||
**Standard Context Sources**:
|
||||
- Task JSON: `context.requirements`, `context.acceptance`, `context.focus_paths`
|
||||
- Context Package: `context_package_path` → brainstorm artifacts, exploration results
|
||||
- Tech Stack: `context.shared_context.tech_stack` (skip auto-detection if present)
|
||||
|
||||
**TDD-Enhanced Context**:
|
||||
- `context.tdd_cycles`: Test case enumeration and coverage targets
|
||||
- `meta.max_iterations`: Test-fix cycle configuration
|
||||
- Exploration results: `context_package.exploration_results` for critical_files and integration_points
|
||||
|
||||
### 5. Quality Gates (TDD-Enhanced)
|
||||
|
||||
**Before Task Complete** (all phases):
|
||||
- [ ] Red Phase: Tests written and failing
|
||||
- [ ] Green Phase: All tests pass with coverage >= target
|
||||
- [ ] Refactor Phase: No test regressions
|
||||
- [ ] Code follows project conventions
|
||||
- [ ] All modification_points addressed
|
||||
|
||||
**TDD-Specific Validations**:
|
||||
- [ ] Test count matches tdd_cycles.test_count
|
||||
- [ ] Coverage meets tdd_cycles.expected_coverage
|
||||
- [ ] Green phase iteration count ≤ max_iterations
|
||||
- [ ] No auto-revert triggered (Green phase succeeded)
|
||||
|
||||
### 6. Task Completion (TDD-Enhanced)
|
||||
|
||||
**Upon completing TDD task:**
|
||||
|
||||
1. **Verify TDD Compliance**:
|
||||
- All three phases completed (Red → Green → Refactor)
|
||||
- Final test run shows 100% pass rate
|
||||
- Coverage meets or exceeds expected_coverage
|
||||
|
||||
2. **Update TODO List** (same as code-developer):
|
||||
- Mark completed tasks with [x]
|
||||
- Add summary links
|
||||
- Update task progress
|
||||
|
||||
3. **Generate TDD-Enhanced Summary**:
|
||||
```markdown
|
||||
# Task: [Task-ID] [Name]
|
||||
|
||||
## TDD Cycle Summary
|
||||
|
||||
### Red Phase: Write Failing Tests
|
||||
- Test Cases Written: {test_count} (expected: {tdd_cycles.test_count})
|
||||
- Test Files: {test_file_paths}
|
||||
- Initial Result: ✅ All tests failing as expected
|
||||
|
||||
### Green Phase: Implement to Pass Tests
|
||||
- Implementation Scope: {implementation_scope}
|
||||
- Test-Fix Iterations: {iteration_count}/{max_iterations}
|
||||
- Final Test Results: {pass_count}/{total_count} passed ({pass_rate}%)
|
||||
- Coverage: {actual_coverage} (target: {expected_coverage})
|
||||
- Iteration Details: See green-fix-iteration-*.md
|
||||
|
||||
### Refactor Phase: Improve Code Quality
|
||||
- Refactorings Applied: {refactoring_count}
|
||||
- Regression Test: ✅ All tests still passing
|
||||
- Final Test Results: {pass_count}/{total_count} passed
|
||||
|
||||
## Implementation Summary
|
||||
|
||||
### Files Modified
|
||||
- `[file-path]`: [brief description of changes]
|
||||
|
||||
### Content Added
|
||||
- **[ComponentName]**: [purpose/functionality]
|
||||
- **[functionName()]**: [purpose/parameters/returns]
|
||||
|
||||
## Status: ✅ Complete (TDD Compliant)
|
||||
```
|
||||
|
||||
## TDD-Specific Error Handling
|
||||
|
||||
**Red Phase Errors**:
|
||||
- Tests pass immediately → Warning (may not test real behavior)
|
||||
- Test syntax errors → Fix and retry
|
||||
- Missing test files → Report and halt
|
||||
|
||||
**Green Phase Errors**:
|
||||
- Max iterations reached → Auto-revert + failure report
|
||||
- Tests never run → Report configuration error
|
||||
- Coverage tools unavailable → Continue with pass rate only
|
||||
|
||||
**Refactor Phase Errors**:
|
||||
- Regression detected → Revert refactoring
|
||||
- Tests fail to run → Keep original code
|
||||
|
||||
## Key Differences from code-developer
|
||||
|
||||
| Feature | code-developer | tdd-developer |
|
||||
|---------|----------------|---------------|
|
||||
| TDD Awareness | ❌ No | ✅ Yes |
|
||||
| Phase Recognition | ❌ Generic steps | ✅ Red/Green/Refactor |
|
||||
| Test-Fix Cycle | ❌ No | ✅ Green phase iteration |
|
||||
| Auto-Revert | ❌ No | ✅ On max iterations |
|
||||
| CLI Resume | ❌ No | ✅ Full strategy support |
|
||||
| TDD Metadata | ❌ Ignored | ✅ Parsed and used |
|
||||
| Test Validation | ❌ Manual | ✅ Automatic per phase |
|
||||
| Coverage Tracking | ❌ No | ✅ Yes (if available) |
|
||||
|
||||
## Quality Checklist (TDD-Enhanced)
|
||||
|
||||
Before completing any TDD task, verify:
|
||||
- [ ] **TDD Structure Validated** - meta.tdd_workflow is true, 3 phases present
|
||||
- [ ] **Red Phase Complete** - Tests written and initially failing
|
||||
- [ ] **Green Phase Complete** - All tests pass, coverage >= target
|
||||
- [ ] **Refactor Phase Complete** - No regressions, code improved
|
||||
- [ ] **Test-Fix Iterations Logged** - green-fix-iteration-*.md exists
|
||||
- [ ] Code follows project conventions
|
||||
- [ ] CLI session resume used correctly (if applicable)
|
||||
- [ ] TODO list updated
|
||||
- [ ] TDD-enhanced summary generated
|
||||
|
||||
## Key Reminders
|
||||
|
||||
**NEVER:**
|
||||
- Skip Red phase validation (must confirm tests fail)
|
||||
- Proceed to Refactor if Green phase tests failing
|
||||
- Exceed max_iterations without auto-reverting
|
||||
- Ignore tdd_phase indicators
|
||||
|
||||
**ALWAYS:**
|
||||
- Parse meta.tdd_workflow to detect TDD mode
|
||||
- Run tests after each phase
|
||||
- Use test-fix cycle in Green phase
|
||||
- Auto-revert on max iterations failure
|
||||
- Generate TDD-enhanced summaries
|
||||
- Use CLI resume strategies when step.command exists
|
||||
- Log all test-fix iterations to .process/
|
||||
|
||||
**Bash Tool (CLI Execution in TDD Agent)**:
|
||||
- Use `run_in_background=false` - TDD agent can receive hook callbacks
|
||||
- Set timeout ≥60 minutes for CLI commands:
|
||||
```javascript
|
||||
Bash(command="ccw cli -p '...' --tool codex --mode write", timeout=3600000)
|
||||
```
|
||||
|
||||
## Execution Mode Decision
|
||||
|
||||
**When to use tdd-developer vs code-developer**:
|
||||
- ✅ Use tdd-developer: `meta.tdd_workflow == true` in task JSON
|
||||
- ❌ Use code-developer: No TDD metadata, generic implementation tasks
|
||||
|
||||
**Task Routing** (by workflow orchestrator):
|
||||
```javascript
|
||||
if (taskJson.meta?.tdd_workflow) {
|
||||
agent = "tdd-developer" // Use TDD-aware agent
|
||||
} else {
|
||||
agent = "code-developer" // Use generic agent
|
||||
}
|
||||
```
|
||||
@@ -28,8 +28,6 @@ You are a test context discovery specialist focused on gathering test coverage i
|
||||
|
||||
## Tool Arsenal
|
||||
|
||||
**Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
|
||||
### 1. Session & Implementation Context
|
||||
**Tools**:
|
||||
- `Read()` - Load session metadata and implementation summaries
|
||||
@@ -38,10 +36,10 @@ You are a test context discovery specialist focused on gathering test coverage i
|
||||
**Use**: Phase 1 source context loading
|
||||
|
||||
### 2. Test Coverage Discovery
|
||||
**Primary (CCW CodexLens MCP)**:
|
||||
- `mcp__ccw-tools__codex_lens(action="search_files", query="*.test.*")` - Find test files
|
||||
- `mcp__ccw-tools__codex_lens(action="search", query="pattern")` - Search test patterns
|
||||
- `mcp__ccw-tools__codex_lens(action="symbol", file="path")` - Analyze test structure
|
||||
**Primary (Code-Index MCP)**:
|
||||
- `mcp__code-index__find_files(pattern)` - Find test files (*.test.*, *.spec.*)
|
||||
- `mcp__code-index__search_code_advanced()` - Search test patterns
|
||||
- `mcp__code-index__get_file_summary()` - Analyze test structure
|
||||
|
||||
**Fallback (CLI)**:
|
||||
- `rg` (ripgrep) - Fast test pattern search
|
||||
@@ -122,10 +120,9 @@ for (const summary_path of summaries) {
|
||||
|
||||
**2.1 Existing Test Discovery**:
|
||||
```javascript
|
||||
// Method 1: CodexLens MCP (preferred)
|
||||
const test_files = mcp__ccw-tools__codex_lens({
|
||||
action: "search_files",
|
||||
query: "*.test.* OR *.spec.* OR test_*.py OR *_test.go"
|
||||
// Method 1: Code-Index MCP (preferred)
|
||||
const test_files = mcp__code-index__find_files({
|
||||
patterns: ["*.test.*", "*.spec.*", "*test_*.py", "*_test.go"]
|
||||
});
|
||||
|
||||
// Method 2: Fallback CLI
|
||||
|
||||
@@ -59,14 +59,6 @@ When task JSON contains `flow_control` field, execute preparation and implementa
|
||||
2. **Variable Substitution**: Use `[variable_name]` to reference previous outputs
|
||||
3. **Error Handling**: Follow step-specific strategies (`skip_optional`, `fail`, `retry_once`)
|
||||
|
||||
**Command-to-Tool Mapping** (for pre_analysis commands):
|
||||
```
|
||||
"Read(path)" → Read tool: Read(file_path=path)
|
||||
"bash(command)" → Bash tool: Bash(command=command)
|
||||
"Search(pattern,path)" → Grep tool: Grep(pattern=pattern, path=path)
|
||||
"Glob(pattern)" → Glob tool: Glob(pattern=pattern)
|
||||
```
|
||||
|
||||
**Implementation Approach** (`flow_control.implementation_approach`):
|
||||
When task JSON contains implementation_approach array:
|
||||
1. **Sequential Execution**: Process steps in order, respecting `depends_on` dependencies
|
||||
@@ -81,12 +73,6 @@ When task JSON contains implementation_approach array:
|
||||
- `command`: Optional CLI command (only when explicitly specified)
|
||||
- `depends_on`: Array of step numbers that must complete first
|
||||
- `output`: Variable name for this step's output
|
||||
5. **Execution Mode Selection**:
|
||||
- IF `command` field exists → Execute CLI command via Bash tool
|
||||
- ELSE (no command) → Agent direct execution:
|
||||
- Parse `modification_points` as files to modify
|
||||
- Follow `logic_flow` for test-fix iteration
|
||||
- Use test_commands from flow_control for test execution
|
||||
|
||||
|
||||
### 1. Context Assessment & Test Discovery
|
||||
@@ -97,18 +83,17 @@ When task JSON contains implementation_approach array:
|
||||
- L1 (Unit): `*.test.*`, `*.spec.*` in `__tests__/`, `tests/unit/`
|
||||
- L2 (Integration): `tests/integration/`, `*.integration.test.*`
|
||||
- L3 (E2E): `tests/e2e/`, `*.e2e.test.*`, `cypress/`, `playwright/`
|
||||
- **context-package.json** (CCW Workflow): Use Read tool to get context package from `.workflow/active/{session}/.process/context-package.json`
|
||||
- **context-package.json** (CCW Workflow): Extract artifact paths using `jq -r '.brainstorm_artifacts.role_analyses[].files[].path'`
|
||||
- Identify test commands from project configuration
|
||||
|
||||
```bash
|
||||
# Detect test framework and multi-layered commands
|
||||
if [ -f "package.json" ]; then
|
||||
# Extract layer-specific test commands using Read tool or jq
|
||||
PKG_JSON=$(cat package.json)
|
||||
LINT_CMD=$(echo "$PKG_JSON" | jq -r '.scripts.lint // "eslint ."')
|
||||
UNIT_CMD=$(echo "$PKG_JSON" | jq -r '.scripts["test:unit"] // .scripts.test')
|
||||
INTEGRATION_CMD=$(echo "$PKG_JSON" | jq -r '.scripts["test:integration"] // ""')
|
||||
E2E_CMD=$(echo "$PKG_JSON" | jq -r '.scripts["test:e2e"] // ""')
|
||||
# Extract layer-specific test commands
|
||||
LINT_CMD=$(cat package.json | jq -r '.scripts.lint // "eslint ."')
|
||||
UNIT_CMD=$(cat package.json | jq -r '.scripts["test:unit"] // .scripts.test')
|
||||
INTEGRATION_CMD=$(cat package.json | jq -r '.scripts["test:integration"] // ""')
|
||||
E2E_CMD=$(cat package.json | jq -r '.scripts["test:e2e"] // ""')
|
||||
elif [ -f "pytest.ini" ] || [ -f "setup.py" ]; then
|
||||
LINT_CMD="ruff check . || flake8 ."
|
||||
UNIT_CMD="pytest tests/unit/"
|
||||
@@ -332,7 +317,6 @@ When generating test results for orchestrator (saved to `.process/test-results.j
|
||||
## Important Reminders
|
||||
|
||||
**ALWAYS:**
|
||||
- **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
- **Execute tests first** - Understand what's failing before fixing
|
||||
- **Diagnose thoroughly** - Find root cause, not just symptoms
|
||||
- **Fix minimally** - Change only what's needed to pass tests
|
||||
|
||||
@@ -284,8 +284,6 @@ You execute 6 distinct task types organized into 3 patterns. Each task includes
|
||||
|
||||
### ALWAYS
|
||||
|
||||
**Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
|
||||
**W3C Format Compliance**: ✅ Include $schema in all token files | ✅ Use $type metadata for all tokens | ✅ Use $value wrapper for color (light/dark), duration, easing | ✅ Validate token structure against W3C spec
|
||||
|
||||
**Pattern Recognition**: ✅ Identify pattern from [TASK_TYPE_IDENTIFIER] first | ✅ Apply pattern-specific execution rules | ✅ Follow autonomy level
|
||||
|
||||
@@ -120,11 +120,7 @@ Before completing any task, verify:
|
||||
- Make assumptions - verify with existing materials
|
||||
- Skip quality verification steps
|
||||
|
||||
**Bash Tool**:
|
||||
- Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution
|
||||
|
||||
**ALWAYS:**
|
||||
- **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
|
||||
- Verify resource/dependency existence before referencing
|
||||
- Execute tasks systematically and incrementally
|
||||
- Test and validate work thoroughly
|
||||
|
||||
@@ -1,18 +0,0 @@
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"defaultTool": "gemini",
|
||||
"promptFormat": "plain",
|
||||
"smartContext": {
|
||||
"enabled": false,
|
||||
"maxFiles": 10
|
||||
},
|
||||
"nativeResume": true,
|
||||
"recursiveQuery": true,
|
||||
"cache": {
|
||||
"injectionMode": "auto",
|
||||
"defaultPrefix": "",
|
||||
"defaultSuffix": ""
|
||||
},
|
||||
"codeIndexMcp": "ace",
|
||||
"$schema": "./cli-settings.schema.json"
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,486 +0,0 @@
|
||||
---
|
||||
name: ccw
|
||||
description: Main workflow orchestrator - analyze intent, select workflow, execute command chain in main process
|
||||
argument-hint: "\"task description\""
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*)
|
||||
---
|
||||
|
||||
# CCW Command - Main Workflow Orchestrator
|
||||
|
||||
Main process orchestrator: intent analysis → workflow selection → command chain execution.
|
||||
|
||||
## Core Concept: Minimum Execution Units (最小执行单元)
|
||||
|
||||
**Definition**: A set of commands that must execute together as an atomic group to achieve a meaningful workflow milestone.
|
||||
|
||||
**Why This Matters**:
|
||||
- **Prevents Incomplete States**: Avoid stopping after task generation without execution
|
||||
- **User Experience**: User gets complete results, not intermediate artifacts requiring manual follow-up
|
||||
- **Workflow Integrity**: Maintains logical coherence of multi-step operations
|
||||
|
||||
**Key Units in CCW**:
|
||||
|
||||
| Unit Type | Pattern | Example |
|
||||
|-----------|---------|---------|
|
||||
| **Planning + Execution** | plan-cmd → execute-cmd | lite-plan → lite-execute |
|
||||
| **Testing** | test-gen-cmd → test-exec-cmd | test-fix-gen → test-cycle-execute |
|
||||
| **Review** | review-cmd → fix-cmd | review-session-cycle → review-fix |
|
||||
|
||||
**Atomic Rules**:
|
||||
1. CCW automatically groups commands into minimum units - never splits them
|
||||
2. Pipeline visualization shows units with `【 】` markers
|
||||
3. Error handling preserves unit boundaries (retry/skip affects whole unit)
|
||||
|
||||
## Execution Model
|
||||
|
||||
**Synchronous (Main Process)**: Commands execute via SlashCommand in main process, blocking until complete.
|
||||
|
||||
```
|
||||
User Input → Analyze Intent → Select Workflow → [Confirm] → Execute Chain
|
||||
↓
|
||||
SlashCommand (blocking)
|
||||
↓
|
||||
Update TodoWrite
|
||||
↓
|
||||
Next Command...
|
||||
```
|
||||
|
||||
**vs ccw-coordinator**: External CLI execution with background tasks and hook callbacks.
|
||||
|
||||
## 5-Phase Workflow
|
||||
|
||||
### Phase 1: Analyze Intent
|
||||
|
||||
```javascript
|
||||
function analyzeIntent(input) {
|
||||
return {
|
||||
goal: extractGoal(input),
|
||||
scope: extractScope(input),
|
||||
constraints: extractConstraints(input),
|
||||
task_type: detectTaskType(input), // bugfix|feature|tdd|review|exploration|...
|
||||
complexity: assessComplexity(input), // low|medium|high
|
||||
clarity_score: calculateClarity(input) // 0-3 (>=2 = clear)
|
||||
};
|
||||
}
|
||||
|
||||
// Task type detection (priority order)
|
||||
function detectTaskType(text) {
|
||||
const patterns = {
|
||||
'bugfix-hotfix': /urgent|production|critical/ && /fix|bug/,
|
||||
'bugfix': /fix|bug|error|crash|fail|debug/,
|
||||
'issue-batch': /issues?|batch/ && /fix|resolve/,
|
||||
'exploration': /uncertain|explore|research|what if/,
|
||||
'multi-perspective': /multi-perspective|compare|cross-verify/,
|
||||
'quick-task': /quick|simple|small/ && /feature|function/,
|
||||
'ui-design': /ui|design|component|style/,
|
||||
'tdd': /tdd|test-driven|test first/,
|
||||
'test-fix': /test fail|fix test|failing test/,
|
||||
'review': /review|code review/,
|
||||
'documentation': /docs|documentation|readme/
|
||||
};
|
||||
for (const [type, pattern] of Object.entries(patterns)) {
|
||||
if (pattern.test(text)) return type;
|
||||
}
|
||||
return 'feature';
|
||||
}
|
||||
```
|
||||
|
||||
**Output**: `Type: [task_type] | Goal: [goal] | Complexity: [complexity] | Clarity: [clarity_score]/3`
|
||||
|
||||
---
|
||||
|
||||
### Phase 1.5: Requirement Clarification (if clarity_score < 2)
|
||||
|
||||
```javascript
|
||||
async function clarifyRequirements(analysis) {
|
||||
if (analysis.clarity_score >= 2) return analysis;
|
||||
|
||||
const questions = generateClarificationQuestions(analysis); // Goal, Scope, Constraints
|
||||
const answers = await AskUserQuestion({ questions });
|
||||
return updateAnalysis(analysis, answers);
|
||||
}
|
||||
```
|
||||
|
||||
**Questions**: Goal (Create/Fix/Optimize/Analyze), Scope (Single file/Module/Cross-module/System), Constraints (Backward compat/Skip tests/Urgent hotfix)
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Select Workflow & Build Command Chain
|
||||
|
||||
```javascript
|
||||
function selectWorkflow(analysis) {
|
||||
const levelMap = {
|
||||
'bugfix-hotfix': { level: 2, flow: 'bugfix.hotfix' },
|
||||
'bugfix': { level: 2, flow: 'bugfix.standard' },
|
||||
'issue-batch': { level: 'Issue', flow: 'issue' },
|
||||
'exploration': { level: 4, flow: 'full' },
|
||||
'quick-task': { level: 1, flow: 'lite-lite-lite' },
|
||||
'ui-design': { level: analysis.complexity === 'high' ? 4 : 3, flow: 'ui' },
|
||||
'tdd': { level: 3, flow: 'tdd' },
|
||||
'test-fix': { level: 3, flow: 'test-fix-gen' },
|
||||
'review': { level: 3, flow: 'review-fix' },
|
||||
'documentation': { level: 2, flow: 'docs' },
|
||||
'feature': { level: analysis.complexity === 'high' ? 3 : 2, flow: analysis.complexity === 'high' ? 'coupled' : 'rapid' }
|
||||
};
|
||||
|
||||
const selected = levelMap[analysis.task_type] || levelMap['feature'];
|
||||
return buildCommandChain(selected, analysis);
|
||||
}
|
||||
|
||||
// Build command chain (port-based matching with Minimum Execution Units)
|
||||
function buildCommandChain(workflow, analysis) {
|
||||
const chains = {
|
||||
// Level 1 - Rapid
|
||||
'lite-lite-lite': [
|
||||
{ cmd: '/workflow:lite-lite-lite', args: `"${analysis.goal}"` }
|
||||
],
|
||||
|
||||
// Level 2 - Lightweight
|
||||
'rapid': [
|
||||
// Unit: Quick Implementation【lite-plan → lite-execute】
|
||||
{ cmd: '/workflow:lite-plan', args: `"${analysis.goal}"`, unit: 'quick-impl' },
|
||||
{ cmd: '/workflow:lite-execute', args: '--in-memory', unit: 'quick-impl' },
|
||||
// Unit: Test Validation【test-fix-gen → test-cycle-execute】
|
||||
...(analysis.constraints?.includes('skip-tests') ? [] : [
|
||||
{ cmd: '/workflow:test-fix-gen', args: '', unit: 'test-validation' },
|
||||
{ cmd: '/workflow:test-cycle-execute', args: '', unit: 'test-validation' }
|
||||
])
|
||||
],
|
||||
|
||||
'bugfix.standard': [
|
||||
// Unit: Bug Fix【lite-fix → lite-execute】
|
||||
{ cmd: '/workflow:lite-fix', args: `"${analysis.goal}"`, unit: 'bug-fix' },
|
||||
{ cmd: '/workflow:lite-execute', args: '--in-memory', unit: 'bug-fix' },
|
||||
// Unit: Test Validation【test-fix-gen → test-cycle-execute】
|
||||
...(analysis.constraints?.includes('skip-tests') ? [] : [
|
||||
{ cmd: '/workflow:test-fix-gen', args: '', unit: 'test-validation' },
|
||||
{ cmd: '/workflow:test-cycle-execute', args: '', unit: 'test-validation' }
|
||||
])
|
||||
],
|
||||
|
||||
'bugfix.hotfix': [
|
||||
{ cmd: '/workflow:lite-fix', args: `--hotfix "${analysis.goal}"` }
|
||||
],
|
||||
|
||||
'multi-cli-plan': [
|
||||
// Unit: Multi-CLI Planning【multi-cli-plan → lite-execute】
|
||||
{ cmd: '/workflow:multi-cli-plan', args: `"${analysis.goal}"`, unit: 'multi-cli' },
|
||||
{ cmd: '/workflow:lite-execute', args: '--in-memory', unit: 'multi-cli' },
|
||||
// Unit: Test Validation【test-fix-gen → test-cycle-execute】
|
||||
...(analysis.constraints?.includes('skip-tests') ? [] : [
|
||||
{ cmd: '/workflow:test-fix-gen', args: '', unit: 'test-validation' },
|
||||
{ cmd: '/workflow:test-cycle-execute', args: '', unit: 'test-validation' }
|
||||
])
|
||||
],
|
||||
|
||||
'docs': [
|
||||
// Unit: Quick Implementation【lite-plan → lite-execute】
|
||||
{ cmd: '/workflow:lite-plan', args: `"${analysis.goal}"`, unit: 'quick-impl' },
|
||||
{ cmd: '/workflow:lite-execute', args: '--in-memory', unit: 'quick-impl' }
|
||||
],
|
||||
|
||||
// Level 3 - Standard
|
||||
'coupled': [
|
||||
// Unit: Verified Planning【plan → plan-verify】
|
||||
{ cmd: '/workflow:plan', args: `"${analysis.goal}"`, unit: 'verified-planning' },
|
||||
{ cmd: '/workflow:plan-verify', args: '', unit: 'verified-planning' },
|
||||
// Execution
|
||||
{ cmd: '/workflow:execute', args: '' },
|
||||
// Unit: Code Review【review-session-cycle → review-fix】
|
||||
{ cmd: '/workflow:review-session-cycle', args: '', unit: 'code-review' },
|
||||
{ cmd: '/workflow:review-fix', args: '', unit: 'code-review' },
|
||||
// Unit: Test Validation【test-fix-gen → test-cycle-execute】
|
||||
...(analysis.constraints?.includes('skip-tests') ? [] : [
|
||||
{ cmd: '/workflow:test-fix-gen', args: '', unit: 'test-validation' },
|
||||
{ cmd: '/workflow:test-cycle-execute', args: '', unit: 'test-validation' }
|
||||
])
|
||||
],
|
||||
|
||||
'tdd': [
|
||||
// Unit: TDD Planning + Execution【tdd-plan → execute】
|
||||
{ cmd: '/workflow:tdd-plan', args: `"${analysis.goal}"`, unit: 'tdd-planning' },
|
||||
{ cmd: '/workflow:execute', args: '', unit: 'tdd-planning' },
|
||||
// TDD Verification
|
||||
{ cmd: '/workflow:tdd-verify', args: '' }
|
||||
],
|
||||
|
||||
'test-fix-gen': [
|
||||
// Unit: Test Validation【test-fix-gen → test-cycle-execute】
|
||||
{ cmd: '/workflow:test-fix-gen', args: `"${analysis.goal}"`, unit: 'test-validation' },
|
||||
{ cmd: '/workflow:test-cycle-execute', args: '', unit: 'test-validation' }
|
||||
],
|
||||
|
||||
'review-fix': [
|
||||
// Unit: Code Review【review-session-cycle → review-fix】
|
||||
{ cmd: '/workflow:review-session-cycle', args: '', unit: 'code-review' },
|
||||
{ cmd: '/workflow:review-fix', args: '', unit: 'code-review' },
|
||||
// Unit: Test Validation【test-fix-gen → test-cycle-execute】
|
||||
{ cmd: '/workflow:test-fix-gen', args: '', unit: 'test-validation' },
|
||||
{ cmd: '/workflow:test-cycle-execute', args: '', unit: 'test-validation' }
|
||||
],
|
||||
|
||||
'ui': [
|
||||
{ cmd: '/workflow:ui-design:explore-auto', args: `"${analysis.goal}"` },
|
||||
// Unit: Planning + Execution【plan → execute】
|
||||
{ cmd: '/workflow:plan', args: '', unit: 'plan-execute' },
|
||||
{ cmd: '/workflow:execute', args: '', unit: 'plan-execute' }
|
||||
],
|
||||
|
||||
// Level 4 - Brainstorm
|
||||
'full': [
|
||||
{ cmd: '/workflow:brainstorm:auto-parallel', args: `"${analysis.goal}"` },
|
||||
// Unit: Verified Planning【plan → plan-verify】
|
||||
{ cmd: '/workflow:plan', args: '', unit: 'verified-planning' },
|
||||
{ cmd: '/workflow:plan-verify', args: '', unit: 'verified-planning' },
|
||||
// Execution
|
||||
{ cmd: '/workflow:execute', args: '' },
|
||||
// Unit: Test Validation【test-fix-gen → test-cycle-execute】
|
||||
{ cmd: '/workflow:test-fix-gen', args: '', unit: 'test-validation' },
|
||||
{ cmd: '/workflow:test-cycle-execute', args: '', unit: 'test-validation' }
|
||||
],
|
||||
|
||||
// Issue Workflow
|
||||
'issue': [
|
||||
{ cmd: '/issue:discover', args: '' },
|
||||
{ cmd: '/issue:plan', args: '--all-pending' },
|
||||
{ cmd: '/issue:queue', args: '' },
|
||||
{ cmd: '/issue:execute', args: '' }
|
||||
]
|
||||
};
|
||||
|
||||
return chains[workflow.flow] || chains['rapid'];
|
||||
}
|
||||
```
|
||||
|
||||
**Output**: `Level [X] - [flow] | Pipeline: [...] | Commands: [1. /cmd1 2. /cmd2 ...]`
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: User Confirmation
|
||||
|
||||
```javascript
|
||||
async function getUserConfirmation(chain) {
|
||||
const response = await AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Execute this command chain?",
|
||||
header: "Confirm",
|
||||
options: [
|
||||
{ label: "Confirm", description: "Start" },
|
||||
{ label: "Adjust", description: "Modify" },
|
||||
{ label: "Cancel", description: "Abort" }
|
||||
]
|
||||
}]
|
||||
});
|
||||
|
||||
if (response.error === "Cancel") throw new Error("Cancelled");
|
||||
if (response.error === "Adjust") return await adjustChain(chain);
|
||||
return chain;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Setup TODO Tracking
|
||||
|
||||
```javascript
|
||||
function setupTodoTracking(chain, workflow) {
|
||||
const todos = chain.map((step, i) => ({
|
||||
content: `CCW:${workflow}: [${i + 1}/${chain.length}] ${step.cmd}`,
|
||||
status: i === 0 ? 'in_progress' : 'pending',
|
||||
activeForm: `Executing ${step.cmd}`
|
||||
}));
|
||||
TodoWrite({ todos });
|
||||
}
|
||||
```
|
||||
|
||||
**Output**: `-> CCW:rapid: [1/3] /workflow:lite-plan | CCW:rapid: [2/3] /workflow:lite-execute | ...`
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Execute Command Chain
|
||||
|
||||
```javascript
|
||||
async function executeCommandChain(chain, workflow) {
|
||||
let previousResult = null;
|
||||
|
||||
for (let i = 0; i < chain.length; i++) {
|
||||
try {
|
||||
const fullCommand = assembleCommand(chain[i], previousResult);
|
||||
const result = await SlashCommand({ command: fullCommand });
|
||||
|
||||
previousResult = { ...result, success: true };
|
||||
updateTodoStatus(i, chain.length, workflow, 'completed');
|
||||
|
||||
} catch (error) {
|
||||
const action = await handleError(chain[i], error, i);
|
||||
if (action === 'retry') {
|
||||
i--; // Retry
|
||||
} else if (action === 'abort') {
|
||||
return { success: false, error: error.message };
|
||||
}
|
||||
// 'skip' - continue
|
||||
}
|
||||
}
|
||||
|
||||
return { success: true, completed: chain.length };
|
||||
}
|
||||
|
||||
// Assemble full command with session/plan parameters
|
||||
function assembleCommand(step, previousResult) {
|
||||
let command = step.cmd;
|
||||
if (step.args) {
|
||||
command += ` ${step.args}`;
|
||||
} else if (previousResult?.session_id) {
|
||||
command += ` --session="${previousResult.session_id}"`;
|
||||
}
|
||||
return command;
|
||||
}
|
||||
|
||||
// Update TODO: mark current as complete, next as in-progress
|
||||
function updateTodoStatus(index, total, workflow, status) {
|
||||
const todos = getAllCurrentTodos();
|
||||
const updated = todos.map(todo => {
|
||||
if (todo.content.startsWith(`CCW:${workflow}:`)) {
|
||||
const stepNum = extractStepIndex(todo.content);
|
||||
if (stepNum === index + 1) return { ...todo, status };
|
||||
if (stepNum === index + 2 && status === 'completed') return { ...todo, status: 'in_progress' };
|
||||
}
|
||||
return todo;
|
||||
});
|
||||
TodoWrite({ todos: updated });
|
||||
}
|
||||
|
||||
// Error handling: Retry/Skip/Abort
|
||||
async function handleError(step, error, index) {
|
||||
const response = await AskUserQuestion({
|
||||
questions: [{
|
||||
question: `${step.cmd} failed: ${error.message}`,
|
||||
header: "Error",
|
||||
options: [
|
||||
{ label: "Retry", description: "Re-execute" },
|
||||
{ label: "Skip", description: "Continue next" },
|
||||
{ label: "Abort", description: "Stop" }
|
||||
]
|
||||
}]
|
||||
});
|
||||
return { Retry: 'retry', Skip: 'skip', Abort: 'abort' }[response.Error] || 'abort';
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution Flow Summary
|
||||
|
||||
```
|
||||
User Input
|
||||
|
|
||||
Phase 1: Analyze Intent
|
||||
|-- Extract: goal, scope, constraints, task_type, complexity, clarity
|
||||
+-- If clarity < 2 -> Phase 1.5: Clarify Requirements
|
||||
|
|
||||
Phase 2: Select Workflow & Build Chain
|
||||
|-- Map task_type -> Level (1/2/3/4/Issue)
|
||||
|-- Select flow based on complexity
|
||||
+-- Build command chain (port-based)
|
||||
|
|
||||
Phase 3: User Confirmation (optional)
|
||||
|-- Show pipeline visualization
|
||||
+-- Allow adjustment
|
||||
|
|
||||
Phase 4: Setup TODO Tracking
|
||||
+-- Create todos with CCW prefix
|
||||
|
|
||||
Phase 5: Execute Command Chain
|
||||
|-- For each command:
|
||||
| |-- Assemble full command
|
||||
| |-- Execute via SlashCommand
|
||||
| |-- Update TODO status
|
||||
| +-- Handle errors (retry/skip/abort)
|
||||
+-- Return workflow result
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pipeline Examples (with Minimum Execution Units)
|
||||
|
||||
**Note**: `【 】` marks Minimum Execution Units - commands execute together as atomic groups.
|
||||
|
||||
| Input | Type | Level | Pipeline (with Units) |
|
||||
|-------|------|-------|-----------------------|
|
||||
| "Add API endpoint" | feature (low) | 2 |【lite-plan → lite-execute】→【test-fix-gen → test-cycle-execute】|
|
||||
| "Fix login timeout" | bugfix | 2 |【lite-fix → lite-execute】→【test-fix-gen → test-cycle-execute】|
|
||||
| "OAuth2 system" | feature (high) | 3 |【plan → plan-verify】→ execute →【review-session-cycle → review-fix】→【test-fix-gen → test-cycle-execute】|
|
||||
| "Implement with TDD" | tdd | 3 |【tdd-plan → execute】→ tdd-verify |
|
||||
| "Uncertain: real-time arch" | exploration | 4 | brainstorm:auto-parallel →【plan → plan-verify】→ execute →【test-fix-gen → test-cycle-execute】|
|
||||
|
||||
---
|
||||
|
||||
## Key Design Principles
|
||||
|
||||
1. **Main Process Execution** - Use SlashCommand in main process, no external CLI
|
||||
2. **Intent-Driven** - Auto-select workflow based on task intent
|
||||
3. **Port-Based Chaining** - Build command chain using port matching
|
||||
4. **Minimum Execution Units** - Commands grouped into atomic units, never split (e.g., lite-plan → lite-execute)
|
||||
5. **Progressive Clarification** - Low clarity triggers clarification phase
|
||||
6. **TODO Tracking** - Use CCW prefix to isolate workflow todos
|
||||
7. **Unit-Aware Error Handling** - Retry/skip/abort affects whole unit, not individual commands
|
||||
8. **User Control** - Optional user confirmation at each phase
|
||||
|
||||
---
|
||||
|
||||
## State Management
|
||||
|
||||
**TodoWrite-Based Tracking**: All execution state tracked via TodoWrite with `CCW:` prefix.
|
||||
|
||||
```javascript
|
||||
// Initial state
|
||||
todos = [
|
||||
{ content: "CCW:rapid: [1/3] /workflow:lite-plan", status: "in_progress" },
|
||||
{ content: "CCW:rapid: [2/3] /workflow:lite-execute", status: "pending" },
|
||||
{ content: "CCW:rapid: [3/3] /workflow:test-cycle-execute", status: "pending" }
|
||||
];
|
||||
|
||||
// After command 1 completes
|
||||
todos = [
|
||||
{ content: "CCW:rapid: [1/3] /workflow:lite-plan", status: "completed" },
|
||||
{ content: "CCW:rapid: [2/3] /workflow:lite-execute", status: "in_progress" },
|
||||
{ content: "CCW:rapid: [3/3] /workflow:test-cycle-execute", status: "pending" }
|
||||
];
|
||||
```
|
||||
|
||||
**vs ccw-coordinator**: Extensive state.json with task_id, status transitions, hook callbacks.
|
||||
|
||||
---
|
||||
|
||||
## Type Comparison: ccw vs ccw-coordinator
|
||||
|
||||
| Aspect | ccw | ccw-coordinator |
|
||||
|--------|-----|-----------------|
|
||||
| **Type** | Main process (SlashCommand) | External CLI (ccw cli + hook callbacks) |
|
||||
| **Execution** | Synchronous blocking | Async background with hook completion |
|
||||
| **Workflow** | Auto intent-based selection | Manual chain building |
|
||||
| **Intent Analysis** | 5-phase clarity check | 3-phase requirement analysis |
|
||||
| **State** | TodoWrite only (in-memory) | state.json + checkpoint/resume |
|
||||
| **Error Handling** | Retry/skip/abort (interactive) | Retry/skip/abort (via AskUser) |
|
||||
| **Use Case** | Auto workflow for any task | Manual orchestration, large chains |
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Auto-select workflow
|
||||
ccw "Add user authentication"
|
||||
|
||||
# Complex requirement (triggers clarification)
|
||||
ccw "Optimize system performance"
|
||||
|
||||
# Bug fix
|
||||
ccw "Fix memory leak in WebSocket handler"
|
||||
|
||||
# TDD development
|
||||
ccw "Implement user registration with TDD"
|
||||
|
||||
# Exploratory task
|
||||
ccw "Uncertain about architecture for real-time notifications"
|
||||
```
|
||||
@@ -191,7 +191,7 @@ target/
|
||||
### Step 2: Workspace Analysis (MANDATORY FIRST)
|
||||
```bash
|
||||
# Analyze workspace structure
|
||||
bash(ccw tool exec get_modules_by_depth '{"format":"json"}')
|
||||
bash(~/.claude/scripts/get_modules_by_depth.sh json)
|
||||
```
|
||||
|
||||
### Step 3: Technology Detection
|
||||
|
||||
@@ -1,361 +0,0 @@
|
||||
---
|
||||
name: codex-review
|
||||
description: Interactive code review using Codex CLI via ccw endpoint with configurable review target, model, and custom instructions
|
||||
argument-hint: "[--uncommitted|--base <branch>|--commit <sha>] [--model <model>] [--title <title>] [prompt]"
|
||||
allowed-tools: Bash(*), AskUserQuestion(*), Read(*)
|
||||
---
|
||||
|
||||
# Codex Review Command (/cli:codex-review)
|
||||
|
||||
## Overview
|
||||
Interactive code review command that invokes `codex review` via ccw cli endpoint with guided parameter selection.
|
||||
|
||||
**Codex Review Parameters** (from `codex review --help`):
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `[PROMPT]` | Custom review instructions (positional) |
|
||||
| `-c model=<model>` | Override model via config |
|
||||
| `--uncommitted` | Review staged, unstaged, and untracked changes |
|
||||
| `--base <BRANCH>` | Review changes against base branch |
|
||||
| `--commit <SHA>` | Review changes introduced by a commit |
|
||||
| `--title <TITLE>` | Optional commit title for review summary |
|
||||
|
||||
## Prompt Template Format
|
||||
|
||||
Follow the standard ccw cli prompt template:
|
||||
|
||||
```
|
||||
PURPOSE: [what] + [why] + [success criteria] + [constraints/scope]
|
||||
TASK: • [step 1] • [step 2] • [step 3]
|
||||
MODE: review
|
||||
CONTEXT: [review target description] | Memory: [relevant context]
|
||||
EXPECTED: [deliverable format] + [quality criteria]
|
||||
CONSTRAINTS: [focus constraints]
|
||||
```
|
||||
|
||||
## EXECUTION INSTRUCTIONS - START HERE
|
||||
|
||||
**When this command is triggered, follow these exact steps:**
|
||||
|
||||
### Step 1: Parse Arguments
|
||||
|
||||
Check if user provided arguments directly:
|
||||
- `--uncommitted` → Record target = uncommitted
|
||||
- `--base <branch>` → Record target = base, branch name
|
||||
- `--commit <sha>` → Record target = commit, sha value
|
||||
- `--model <model>` → Record model selection
|
||||
- `--title <title>` → Record title
|
||||
- Remaining text → Use as custom focus/prompt
|
||||
|
||||
If no target specified → Continue to Step 2 for interactive selection.
|
||||
|
||||
### Step 2: Interactive Parameter Selection
|
||||
|
||||
**2.1 Review Target Selection**
|
||||
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "What do you want to review?",
|
||||
header: "Review Target",
|
||||
options: [
|
||||
{ label: "Uncommitted changes (Recommended)", description: "Review staged, unstaged, and untracked changes" },
|
||||
{ label: "Compare to branch", description: "Review changes against a base branch (e.g., main)" },
|
||||
{ label: "Specific commit", description: "Review changes introduced by a specific commit" }
|
||||
],
|
||||
multiSelect: false
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
**2.2 Branch/Commit Input (if needed)**
|
||||
|
||||
If "Compare to branch" selected:
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Which base branch to compare against?",
|
||||
header: "Base Branch",
|
||||
options: [
|
||||
{ label: "main", description: "Compare against main branch" },
|
||||
{ label: "master", description: "Compare against master branch" },
|
||||
{ label: "develop", description: "Compare against develop branch" }
|
||||
],
|
||||
multiSelect: false
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
If "Specific commit" selected:
|
||||
- Run `git log --oneline -10` to show recent commits
|
||||
- Ask user to provide commit SHA or select from list
|
||||
|
||||
**2.3 Model Selection (Optional)**
|
||||
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Which model to use for review?",
|
||||
header: "Model",
|
||||
options: [
|
||||
{ label: "Default", description: "Use codex default model (gpt-5.2)" },
|
||||
{ label: "o3", description: "OpenAI o3 reasoning model" },
|
||||
{ label: "gpt-4.1", description: "GPT-4.1 model" },
|
||||
{ label: "o4-mini", description: "OpenAI o4-mini (faster)" }
|
||||
],
|
||||
multiSelect: false
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
**2.4 Review Focus Selection**
|
||||
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "What should the review focus on?",
|
||||
header: "Focus Area",
|
||||
options: [
|
||||
{ label: "General review (Recommended)", description: "Comprehensive review: correctness, style, bugs, docs" },
|
||||
{ label: "Security focus", description: "Security vulnerabilities, input validation, auth issues" },
|
||||
{ label: "Performance focus", description: "Performance bottlenecks, complexity, resource usage" },
|
||||
{ label: "Code quality", description: "Readability, maintainability, SOLID principles" }
|
||||
],
|
||||
multiSelect: false
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
### Step 3: Build Prompt and Command
|
||||
|
||||
**3.1 Construct Prompt Based on Focus**
|
||||
|
||||
**General Review Prompt:**
|
||||
```
|
||||
PURPOSE: Comprehensive code review to identify issues, improve quality, and ensure best practices; success = actionable feedback with clear priorities
|
||||
TASK: • Review code correctness and logic errors • Check coding standards and consistency • Identify potential bugs and edge cases • Evaluate documentation completeness
|
||||
MODE: review
|
||||
CONTEXT: {target_description} | Memory: Project conventions from CLAUDE.md
|
||||
EXPECTED: Structured review report with: severity levels (Critical/High/Medium/Low), file:line references, specific improvement suggestions, priority ranking
|
||||
CONSTRAINTS: Focus on actionable feedback
|
||||
```
|
||||
|
||||
**Security Focus Prompt:**
|
||||
```
|
||||
PURPOSE: Security-focused code review to identify vulnerabilities and security risks; success = all security issues documented with remediation
|
||||
TASK: • Scan for injection vulnerabilities (SQL, XSS, command) • Check authentication and authorization logic • Evaluate input validation and sanitization • Identify sensitive data exposure risks
|
||||
MODE: review
|
||||
CONTEXT: {target_description} | Memory: Security best practices, OWASP Top 10
|
||||
EXPECTED: Security report with: vulnerability classification, CVE references where applicable, remediation code snippets, risk severity matrix
|
||||
CONSTRAINTS: Security-first analysis | Flag all potential vulnerabilities
|
||||
```
|
||||
|
||||
**Performance Focus Prompt:**
|
||||
```
|
||||
PURPOSE: Performance-focused code review to identify bottlenecks and optimization opportunities; success = measurable improvement recommendations
|
||||
TASK: • Analyze algorithmic complexity (Big-O) • Identify memory allocation issues • Check for N+1 queries and blocking operations • Evaluate caching opportunities
|
||||
MODE: review
|
||||
CONTEXT: {target_description} | Memory: Performance patterns and anti-patterns
|
||||
EXPECTED: Performance report with: complexity analysis, bottleneck identification, optimization suggestions with expected impact, benchmark recommendations
|
||||
CONSTRAINTS: Performance optimization focus
|
||||
```
|
||||
|
||||
**Code Quality Focus Prompt:**
|
||||
```
|
||||
PURPOSE: Code quality review to improve maintainability and readability; success = cleaner, more maintainable code
|
||||
TASK: • Assess SOLID principles adherence • Identify code duplication and abstraction opportunities • Review naming conventions and clarity • Evaluate test coverage implications
|
||||
MODE: review
|
||||
CONTEXT: {target_description} | Memory: Project coding standards
|
||||
EXPECTED: Quality report with: principle violations, refactoring suggestions, naming improvements, maintainability score
|
||||
CONSTRAINTS: Code quality and maintainability focus
|
||||
```
|
||||
|
||||
**3.2 Build Target Description**
|
||||
|
||||
Based on selection, set `{target_description}`:
|
||||
- Uncommitted: `Reviewing uncommitted changes (staged + unstaged + untracked)`
|
||||
- Base branch: `Reviewing changes against {branch} branch`
|
||||
- Commit: `Reviewing changes introduced by commit {sha}`
|
||||
|
||||
### Step 4: Execute via CCW CLI
|
||||
|
||||
Build and execute the ccw cli command:
|
||||
|
||||
```bash
|
||||
# Base structure
|
||||
ccw cli -p "<PROMPT>" --tool codex --mode review [OPTIONS]
|
||||
```
|
||||
|
||||
**Command Construction:**
|
||||
|
||||
```bash
|
||||
# Variables from user selection
|
||||
TARGET_FLAG="" # --uncommitted | --base <branch> | --commit <sha>
|
||||
MODEL_FLAG="" # --model <model> (if not default)
|
||||
TITLE_FLAG="" # --title "<title>" (if provided)
|
||||
|
||||
# Build target flag
|
||||
if [ "$target" = "uncommitted" ]; then
|
||||
TARGET_FLAG="--uncommitted"
|
||||
elif [ "$target" = "base" ]; then
|
||||
TARGET_FLAG="--base $branch"
|
||||
elif [ "$target" = "commit" ]; then
|
||||
TARGET_FLAG="--commit $sha"
|
||||
fi
|
||||
|
||||
# Build model flag (only if not default)
|
||||
if [ "$model" != "default" ] && [ -n "$model" ]; then
|
||||
MODEL_FLAG="--model $model"
|
||||
fi
|
||||
|
||||
# Build title flag (if provided)
|
||||
if [ -n "$title" ]; then
|
||||
TITLE_FLAG="--title \"$title\""
|
||||
fi
|
||||
|
||||
# Execute
|
||||
ccw cli -p "$PROMPT" --tool codex --mode review $TARGET_FLAG $MODEL_FLAG $TITLE_FLAG
|
||||
```
|
||||
|
||||
**Full Example Commands:**
|
||||
|
||||
**Option 1: With custom prompt (reviews uncommitted by default):**
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Comprehensive code review to identify issues and improve quality; success = actionable feedback with priorities
|
||||
TASK: • Review correctness and logic • Check standards compliance • Identify bugs and edge cases • Evaluate documentation
|
||||
MODE: review
|
||||
CONTEXT: Reviewing uncommitted changes | Memory: Project conventions
|
||||
EXPECTED: Structured report with severity levels, file:line refs, improvement suggestions
|
||||
CONSTRAINTS: Actionable feedback
|
||||
" --tool codex --mode review --rule analysis-review-code-quality
|
||||
```
|
||||
|
||||
**Option 2: Target flag only (no prompt allowed):**
|
||||
```bash
|
||||
ccw cli --tool codex --mode review --uncommitted
|
||||
```
|
||||
|
||||
### Step 5: Execute and Display Results
|
||||
|
||||
```bash
|
||||
Bash({
|
||||
command: "ccw cli -p \"$PROMPT\" --tool codex --mode review $FLAGS",
|
||||
run_in_background: true
|
||||
})
|
||||
```
|
||||
|
||||
Wait for completion and display formatted results.
|
||||
|
||||
## Quick Usage Examples
|
||||
|
||||
### Direct Execution (No Interaction)
|
||||
|
||||
```bash
|
||||
# Review uncommitted changes with default settings
|
||||
/cli:codex-review --uncommitted
|
||||
|
||||
# Review against main branch
|
||||
/cli:codex-review --base main
|
||||
|
||||
# Review specific commit
|
||||
/cli:codex-review --commit abc123
|
||||
|
||||
# Review with custom model
|
||||
/cli:codex-review --uncommitted --model o3
|
||||
|
||||
# Review with security focus
|
||||
/cli:codex-review --uncommitted security
|
||||
|
||||
# Full options
|
||||
/cli:codex-review --base main --model o3 --title "Auth Feature" security
|
||||
```
|
||||
|
||||
### Interactive Mode
|
||||
|
||||
```bash
|
||||
# Start interactive selection (guided flow)
|
||||
/cli:codex-review
|
||||
```
|
||||
|
||||
## Focus Area Mapping
|
||||
|
||||
| User Selection | Prompt Focus | Key Checks |
|
||||
|----------------|--------------|------------|
|
||||
| General review | Comprehensive | Correctness, style, bugs, docs |
|
||||
| Security focus | Security-first | Injection, auth, validation, exposure |
|
||||
| Performance focus | Optimization | Complexity, memory, queries, caching |
|
||||
| Code quality | Maintainability | SOLID, duplication, naming, tests |
|
||||
|
||||
## Error Handling
|
||||
|
||||
### No Changes to Review
|
||||
```
|
||||
No changes found for review target. Suggestions:
|
||||
- For --uncommitted: Make some code changes first
|
||||
- For --base: Ensure branch exists and has diverged
|
||||
- For --commit: Verify commit SHA exists
|
||||
```
|
||||
|
||||
### Invalid Branch
|
||||
```bash
|
||||
# Show available branches
|
||||
git branch -a --list | head -20
|
||||
```
|
||||
|
||||
### Invalid Commit
|
||||
```bash
|
||||
# Show recent commits
|
||||
git log --oneline -10
|
||||
```
|
||||
|
||||
## Integration Notes
|
||||
|
||||
- Uses `ccw cli --tool codex --mode review` endpoint
|
||||
- Model passed via prompt (codex uses `-c model=` internally)
|
||||
- Target flags (`--uncommitted`, `--base`, `--commit`) passed through to codex
|
||||
- Prompt follows standard ccw cli template format for consistency
|
||||
|
||||
## Validation Constraints
|
||||
|
||||
**IMPORTANT: Target flags and prompt are mutually exclusive**
|
||||
|
||||
The codex CLI has a constraint where target flags (`--uncommitted`, `--base`, `--commit`) cannot be used with a positional `[PROMPT]` argument:
|
||||
|
||||
```
|
||||
error: the argument '--uncommitted' cannot be used with '[PROMPT]'
|
||||
error: the argument '--base <BRANCH>' cannot be used with '[PROMPT]'
|
||||
error: the argument '--commit <SHA>' cannot be used with '[PROMPT]'
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- When ANY target flag is specified, ccw cli automatically skips template concatenation (systemRules/roles)
|
||||
- The review uses codex's default review behavior for the specified target
|
||||
- Custom prompts are only supported WITHOUT target flags (reviews uncommitted changes by default)
|
||||
|
||||
**Valid combinations:**
|
||||
| Command | Result |
|
||||
|---------|--------|
|
||||
| `codex review "Focus on security"` | ✓ Custom prompt, reviews uncommitted (default) |
|
||||
| `codex review --uncommitted` | ✓ No prompt, uses default review |
|
||||
| `codex review --base main` | ✓ No prompt, uses default review |
|
||||
| `codex review --commit abc123` | ✓ No prompt, uses default review |
|
||||
| `codex review --uncommitted "prompt"` | ✗ Invalid - mutually exclusive |
|
||||
| `codex review --base main "prompt"` | ✗ Invalid - mutually exclusive |
|
||||
| `codex review --commit abc123 "prompt"` | ✗ Invalid - mutually exclusive |
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# ✓ Valid: prompt only (reviews uncommitted by default)
|
||||
ccw cli -p "Focus on security" --tool codex --mode review
|
||||
|
||||
# ✓ Valid: target flag only (no prompt)
|
||||
ccw cli --tool codex --mode review --uncommitted
|
||||
ccw cli --tool codex --mode review --base main
|
||||
ccw cli --tool codex --mode review --commit abc123
|
||||
|
||||
# ✗ Invalid: target flag with prompt (will fail)
|
||||
ccw cli -p "Review this" --tool codex --mode review --uncommitted
|
||||
ccw cli -p "Review this" --tool codex --mode review --base main
|
||||
ccw cli -p "Review this" --tool codex --mode review --commit abc123
|
||||
```
|
||||
@@ -1,768 +0,0 @@
|
||||
---
|
||||
name: issue:discover-by-prompt
|
||||
description: Discover issues from user prompt with Gemini-planned iterative multi-agent exploration. Uses ACE semantic search for context gathering and supports cross-module comparison (e.g., frontend vs backend API contracts).
|
||||
argument-hint: "[-y|--yes] <prompt> [--scope=src/**] [--depth=standard|deep] [--max-iterations=5]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*), AskUserQuestion(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*), mcp__exa__search(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-continue all iterations, skip confirmations.
|
||||
|
||||
# Issue Discovery by Prompt
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Discover issues based on user description
|
||||
/issue:discover-by-prompt "Check if frontend API calls match backend implementations"
|
||||
|
||||
# Compare specific modules
|
||||
/issue:discover-by-prompt "Verify auth flow consistency between mobile and web clients" --scope=src/auth/**,src/mobile/**
|
||||
|
||||
# Deep exploration with more iterations
|
||||
/issue:discover-by-prompt "Find all places where error handling is inconsistent" --depth=deep --max-iterations=8
|
||||
|
||||
# Focused backend-frontend contract check
|
||||
/issue:discover-by-prompt "Compare REST API definitions with frontend fetch calls"
|
||||
```
|
||||
|
||||
**Core Difference from `/issue:discover`**:
|
||||
- `discover`: Pre-defined perspectives (bug, security, etc.), parallel execution
|
||||
- `discover-by-prompt`: User-driven prompt, Gemini-planned strategy, iterative exploration
|
||||
|
||||
## What & Why
|
||||
|
||||
### Core Concept
|
||||
|
||||
Prompt-driven issue discovery with intelligent planning. Instead of fixed perspectives, this command:
|
||||
|
||||
1. **Analyzes user intent** via Gemini to understand what to find
|
||||
2. **Plans exploration strategy** dynamically based on codebase structure
|
||||
3. **Executes iterative multi-agent exploration** with feedback loops
|
||||
4. **Performs cross-module comparison** when detecting comparison intent
|
||||
|
||||
### Value Proposition
|
||||
|
||||
1. **Natural Language Input**: Describe what you want to find, not how to find it
|
||||
2. **Intelligent Planning**: Gemini designs optimal exploration strategy
|
||||
3. **Iterative Refinement**: Each round builds on previous discoveries
|
||||
4. **Cross-Module Analysis**: Compare frontend/backend, mobile/web, old/new implementations
|
||||
5. **Adaptive Exploration**: Adjusts direction based on findings
|
||||
|
||||
### Use Cases
|
||||
|
||||
| Scenario | Example Prompt |
|
||||
|----------|----------------|
|
||||
| API Contract | "Check if frontend calls match backend endpoints" |
|
||||
| Error Handling | "Find inconsistent error handling patterns" |
|
||||
| Migration Gap | "Compare old auth with new auth implementation" |
|
||||
| Feature Parity | "Verify mobile has all web features" |
|
||||
| Schema Drift | "Check if TypeScript types match API responses" |
|
||||
| Integration | "Find mismatches between service A and service B" |
|
||||
|
||||
## How It Works
|
||||
|
||||
### Execution Flow
|
||||
|
||||
```
|
||||
Phase 1: Prompt Analysis & Initialization
|
||||
├─ Parse user prompt and flags
|
||||
├─ Detect exploration intent (comparison/search/verification)
|
||||
└─ Initialize discovery session
|
||||
|
||||
Phase 1.5: ACE Context Gathering
|
||||
├─ Use ACE semantic search to understand codebase structure
|
||||
├─ Identify relevant modules based on prompt keywords
|
||||
├─ Collect architecture context for Gemini planning
|
||||
└─ Build initial context package
|
||||
|
||||
Phase 2: Gemini Strategy Planning
|
||||
├─ Feed ACE context + prompt to Gemini CLI
|
||||
├─ Gemini analyzes and generates exploration strategy
|
||||
├─ Create exploration dimensions with search targets
|
||||
├─ Define comparison matrix (if comparison intent)
|
||||
└─ Set success criteria and iteration limits
|
||||
|
||||
Phase 3: Iterative Agent Exploration (with ACE)
|
||||
├─ Iteration 1: Initial exploration by assigned agents
|
||||
│ ├─ Agent A: ACE search + explore dimension 1
|
||||
│ ├─ Agent B: ACE search + explore dimension 2
|
||||
│ └─ Collect findings, update shared context
|
||||
├─ Iteration 2-N: Refined exploration
|
||||
│ ├─ Analyze previous findings
|
||||
│ ├─ ACE search for related code paths
|
||||
│ ├─ Execute targeted exploration
|
||||
│ └─ Update cumulative findings
|
||||
└─ Termination: Max iterations or convergence
|
||||
|
||||
Phase 4: Cross-Analysis & Synthesis
|
||||
├─ Compare findings across dimensions
|
||||
├─ Identify discrepancies and issues
|
||||
├─ Calculate confidence scores
|
||||
└─ Generate issue candidates
|
||||
|
||||
Phase 5: Issue Generation & Summary
|
||||
├─ Convert findings to issue format
|
||||
├─ Write discovery outputs
|
||||
└─ Prompt user for next action
|
||||
```
|
||||
|
||||
### Exploration Dimensions
|
||||
|
||||
Dimensions are **dynamically generated by Gemini** based on the user prompt. Not limited to predefined categories.
|
||||
|
||||
**Examples**:
|
||||
|
||||
| Prompt | Generated Dimensions |
|
||||
|--------|---------------------|
|
||||
| "Check API contracts" | frontend-calls, backend-handlers |
|
||||
| "Find auth issues" | auth-module (single dimension) |
|
||||
| "Compare old/new implementations" | legacy-code, new-code |
|
||||
| "Audit payment flow" | payment-service, validation, logging |
|
||||
| "Find error handling gaps" | error-handlers, error-types, recovery-logic |
|
||||
|
||||
Gemini analyzes the prompt + ACE context to determine:
|
||||
- How many dimensions are needed (1 to N)
|
||||
- What each dimension should focus on
|
||||
- Whether comparison is needed between dimensions
|
||||
|
||||
### Iteration Strategy
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Iteration Loop │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 1. Plan: What to explore this iteration │
|
||||
│ └─ Based on: previous findings + unexplored areas │
|
||||
│ │
|
||||
│ 2. Execute: Launch agents for this iteration │
|
||||
│ └─ Each agent: explore → collect → return summary │
|
||||
│ │
|
||||
│ 3. Analyze: Process iteration results │
|
||||
│ └─ New findings? Gaps? Contradictions? │
|
||||
│ │
|
||||
│ 4. Decide: Continue or terminate │
|
||||
│ └─ Terminate if: max iterations OR convergence OR │
|
||||
│ high confidence on all questions │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
### Phase 1: Prompt Analysis & Initialization
|
||||
|
||||
```javascript
|
||||
// Step 1: Parse arguments
|
||||
const { prompt, scope, depth, maxIterations } = parseArgs(args);
|
||||
|
||||
// Step 2: Generate discovery ID
|
||||
const discoveryId = `DBP-${formatDate(new Date(), 'YYYYMMDD-HHmmss')}`;
|
||||
|
||||
// Step 3: Create output directory
|
||||
const outputDir = `.workflow/issues/discoveries/${discoveryId}`;
|
||||
await mkdir(outputDir, { recursive: true });
|
||||
await mkdir(`${outputDir}/iterations`, { recursive: true });
|
||||
|
||||
// Step 4: Detect intent type from prompt
|
||||
const intentType = detectIntent(prompt);
|
||||
// Returns: 'comparison' | 'search' | 'verification' | 'audit'
|
||||
|
||||
// Step 5: Initialize discovery state
|
||||
await writeJson(`${outputDir}/discovery-state.json`, {
|
||||
discovery_id: discoveryId,
|
||||
type: 'prompt-driven',
|
||||
prompt: prompt,
|
||||
intent_type: intentType,
|
||||
scope: scope || '**/*',
|
||||
depth: depth || 'standard',
|
||||
max_iterations: maxIterations || 5,
|
||||
phase: 'initialization',
|
||||
created_at: new Date().toISOString(),
|
||||
iterations: [],
|
||||
cumulative_findings: [],
|
||||
comparison_matrix: null // filled for comparison intent
|
||||
});
|
||||
```
|
||||
|
||||
### Phase 1.5: ACE Context Gathering
|
||||
|
||||
**Purpose**: Use ACE semantic search to gather codebase context before Gemini planning.
|
||||
|
||||
```javascript
|
||||
// Step 1: Extract keywords from prompt for semantic search
|
||||
const keywords = extractKeywords(prompt);
|
||||
// e.g., "frontend API calls match backend" → ["frontend", "API", "backend", "endpoints"]
|
||||
|
||||
// Step 2: Use ACE to understand codebase structure
|
||||
const aceQueries = [
|
||||
`Project architecture and module structure for ${keywords.join(', ')}`,
|
||||
`Where are ${keywords[0]} implementations located?`,
|
||||
`How does ${keywords.slice(0, 2).join(' ')} work in this codebase?`
|
||||
];
|
||||
|
||||
const aceResults = [];
|
||||
for (const query of aceQueries) {
|
||||
const result = await mcp__ace-tool__search_context({
|
||||
project_root_path: process.cwd(),
|
||||
query: query
|
||||
});
|
||||
aceResults.push({ query, result });
|
||||
}
|
||||
|
||||
// Step 3: Build context package for Gemini (kept in memory)
|
||||
const aceContext = {
|
||||
prompt_keywords: keywords,
|
||||
codebase_structure: aceResults[0].result,
|
||||
relevant_modules: aceResults.slice(1).map(r => r.result),
|
||||
detected_patterns: extractPatterns(aceResults)
|
||||
};
|
||||
|
||||
// Step 4: Update state (no separate file)
|
||||
await updateDiscoveryState(outputDir, {
|
||||
phase: 'context-gathered',
|
||||
ace_context: {
|
||||
queries_executed: aceQueries.length,
|
||||
modules_identified: aceContext.relevant_modules.length
|
||||
}
|
||||
});
|
||||
|
||||
// aceContext passed to Phase 2 in memory
|
||||
```
|
||||
|
||||
**ACE Query Strategy by Intent Type**:
|
||||
|
||||
| Intent | ACE Queries |
|
||||
|--------|-------------|
|
||||
| **comparison** | "frontend API calls", "backend API handlers", "API contract definitions" |
|
||||
| **search** | "{keyword} implementations", "{keyword} usage patterns" |
|
||||
| **verification** | "expected behavior for {feature}", "test coverage for {feature}" |
|
||||
| **audit** | "all {category} patterns", "{category} security concerns" |
|
||||
|
||||
### Phase 2: Gemini Strategy Planning
|
||||
|
||||
**Purpose**: Gemini analyzes user prompt + ACE context to design optimal exploration strategy.
|
||||
|
||||
```javascript
|
||||
// Step 1: Load ACE context gathered in Phase 1.5
|
||||
const aceContext = await readJson(`${outputDir}/ace-context.json`);
|
||||
|
||||
// Step 2: Build Gemini planning prompt with ACE context
|
||||
const planningPrompt = `
|
||||
PURPOSE: Analyze discovery prompt and create exploration strategy based on codebase context
|
||||
TASK:
|
||||
• Parse user intent from prompt: "${prompt}"
|
||||
• Use codebase context to identify specific modules and files to explore
|
||||
• Create exploration dimensions with precise search targets
|
||||
• Define comparison matrix structure (if comparison intent)
|
||||
• Set success criteria and iteration strategy
|
||||
MODE: analysis
|
||||
CONTEXT: @${scope || '**/*'} | Discovery type: ${intentType}
|
||||
|
||||
## Codebase Context (from ACE semantic search)
|
||||
${JSON.stringify(aceContext, null, 2)}
|
||||
|
||||
EXPECTED: JSON exploration plan following exploration-plan-schema.json:
|
||||
{
|
||||
"intent_analysis": { "type": "${intentType}", "primary_question": "...", "sub_questions": [...] },
|
||||
"dimensions": [{ "name": "...", "description": "...", "search_targets": [...], "focus_areas": [...], "agent_prompt": "..." }],
|
||||
"comparison_matrix": { "dimension_a": "...", "dimension_b": "...", "comparison_points": [...] },
|
||||
"success_criteria": [...],
|
||||
"estimated_iterations": N,
|
||||
"termination_conditions": [...]
|
||||
}
|
||||
CONSTRAINTS: Use ACE context to inform targets | Focus on actionable plan
|
||||
`;
|
||||
|
||||
// Step 3: Execute Gemini planning
|
||||
Bash({
|
||||
command: `ccw cli -p "${planningPrompt}" --tool gemini --mode analysis`,
|
||||
run_in_background: true,
|
||||
timeout: 300000
|
||||
});
|
||||
|
||||
// Step 4: Parse Gemini output and validate against schema
|
||||
const explorationPlan = await parseGeminiPlanOutput(geminiResult);
|
||||
validateAgainstSchema(explorationPlan, 'exploration-plan-schema.json');
|
||||
|
||||
// Step 5: Enhance plan with ACE-discovered file paths
|
||||
explorationPlan.dimensions = explorationPlan.dimensions.map(dim => ({
|
||||
...dim,
|
||||
ace_suggested_files: aceContext.relevant_modules
|
||||
.filter(m => m.relevance_to === dim.name)
|
||||
.map(m => m.file_path)
|
||||
}));
|
||||
|
||||
// Step 6: Update state (plan kept in memory, not persisted)
|
||||
await updateDiscoveryState(outputDir, {
|
||||
phase: 'planned',
|
||||
exploration_plan: {
|
||||
dimensions_count: explorationPlan.dimensions.length,
|
||||
has_comparison_matrix: !!explorationPlan.comparison_matrix,
|
||||
estimated_iterations: explorationPlan.estimated_iterations
|
||||
}
|
||||
});
|
||||
|
||||
// explorationPlan passed to Phase 3 in memory
|
||||
```
|
||||
|
||||
**Gemini Planning Responsibilities**:
|
||||
|
||||
| Responsibility | Input | Output |
|
||||
|----------------|-------|--------|
|
||||
| Intent Analysis | User prompt | type, primary_question, sub_questions |
|
||||
| Dimension Design | ACE context + prompt | dimensions with search_targets |
|
||||
| Comparison Matrix | Intent type + modules | comparison_points (if applicable) |
|
||||
| Iteration Strategy | Depth setting | estimated_iterations, termination_conditions |
|
||||
|
||||
**Gemini Planning Output Schema**:
|
||||
|
||||
```json
|
||||
{
|
||||
"intent_analysis": {
|
||||
"type": "comparison|search|verification|audit",
|
||||
"primary_question": "string",
|
||||
"sub_questions": ["string"]
|
||||
},
|
||||
"dimensions": [
|
||||
{
|
||||
"name": "frontend",
|
||||
"description": "Client-side API calls and error handling",
|
||||
"search_targets": ["src/api/**", "src/hooks/**"],
|
||||
"focus_areas": ["fetch calls", "error boundaries", "response parsing"],
|
||||
"agent_prompt": "Explore frontend API consumption patterns..."
|
||||
},
|
||||
{
|
||||
"name": "backend",
|
||||
"description": "Server-side API implementations",
|
||||
"search_targets": ["src/server/**", "src/routes/**"],
|
||||
"focus_areas": ["endpoint handlers", "response schemas", "error responses"],
|
||||
"agent_prompt": "Explore backend API implementations..."
|
||||
}
|
||||
],
|
||||
"comparison_matrix": {
|
||||
"dimension_a": "frontend",
|
||||
"dimension_b": "backend",
|
||||
"comparison_points": [
|
||||
{"aspect": "endpoints", "frontend_check": "fetch URLs", "backend_check": "route paths"},
|
||||
{"aspect": "methods", "frontend_check": "HTTP methods used", "backend_check": "methods accepted"},
|
||||
{"aspect": "payloads", "frontend_check": "request body structure", "backend_check": "expected schema"},
|
||||
{"aspect": "responses", "frontend_check": "response parsing", "backend_check": "response format"},
|
||||
{"aspect": "errors", "frontend_check": "error handling", "backend_check": "error responses"}
|
||||
]
|
||||
},
|
||||
"success_criteria": [
|
||||
"All API endpoints mapped between frontend and backend",
|
||||
"Discrepancies identified with file:line references",
|
||||
"Each finding includes remediation suggestion"
|
||||
],
|
||||
"estimated_iterations": 3,
|
||||
"termination_conditions": [
|
||||
"All comparison points verified",
|
||||
"No new findings in last iteration",
|
||||
"Confidence > 0.8 on primary question"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: Iterative Agent Exploration (with ACE)
|
||||
|
||||
**Purpose**: Multi-agent iterative exploration using ACE for semantic search within each iteration.
|
||||
|
||||
```javascript
|
||||
let iteration = 0;
|
||||
let cumulativeFindings = [];
|
||||
let sharedContext = { aceDiscoveries: [], crossReferences: [] };
|
||||
let shouldContinue = true;
|
||||
|
||||
while (shouldContinue && iteration < maxIterations) {
|
||||
iteration++;
|
||||
const iterationDir = `${outputDir}/iterations/${iteration}`;
|
||||
await mkdir(iterationDir, { recursive: true });
|
||||
|
||||
// Step 1: ACE-assisted iteration planning
|
||||
// Use previous findings to guide ACE queries for this iteration
|
||||
const iterationAceQueries = iteration === 1
|
||||
? explorationPlan.dimensions.map(d => d.focus_areas[0]) // Initial queries from plan
|
||||
: deriveQueriesFromFindings(cumulativeFindings); // Follow-up queries from findings
|
||||
|
||||
// Execute ACE searches to find related code
|
||||
const iterationAceResults = [];
|
||||
for (const query of iterationAceQueries) {
|
||||
const result = await mcp__ace-tool__search_context({
|
||||
project_root_path: process.cwd(),
|
||||
query: `${query} in ${explorationPlan.scope}`
|
||||
});
|
||||
iterationAceResults.push({ query, result });
|
||||
}
|
||||
|
||||
// Update shared context with ACE discoveries
|
||||
sharedContext.aceDiscoveries.push(...iterationAceResults);
|
||||
|
||||
// Step 2: Plan this iteration based on ACE results
|
||||
const iterationPlan = planIteration(iteration, explorationPlan, cumulativeFindings, iterationAceResults);
|
||||
|
||||
// Step 3: Launch dimension agents with ACE context
|
||||
const agentPromises = iterationPlan.dimensions.map(dimension =>
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: `Explore ${dimension.name} (iteration ${iteration})`,
|
||||
prompt: buildDimensionPromptWithACE(dimension, iteration, cumulativeFindings, iterationAceResults, iterationDir)
|
||||
})
|
||||
);
|
||||
|
||||
// Wait for iteration agents
|
||||
const iterationResults = await Promise.all(agentPromises);
|
||||
|
||||
// Step 4: Collect and analyze iteration findings
|
||||
const iterationFindings = await collectIterationFindings(iterationDir, iterationPlan.dimensions);
|
||||
|
||||
// Step 5: Cross-reference findings between dimensions
|
||||
if (iterationPlan.dimensions.length > 1) {
|
||||
const crossRefs = findCrossReferences(iterationFindings, iterationPlan.dimensions);
|
||||
sharedContext.crossReferences.push(...crossRefs);
|
||||
}
|
||||
|
||||
cumulativeFindings.push(...iterationFindings);
|
||||
|
||||
// Step 6: Decide whether to continue
|
||||
const convergenceCheck = checkConvergence(iterationFindings, cumulativeFindings, explorationPlan);
|
||||
shouldContinue = !convergenceCheck.converged;
|
||||
|
||||
// Step 7: Update state (iteration summary embedded in state)
|
||||
await updateDiscoveryState(outputDir, {
|
||||
iterations: [...state.iterations, {
|
||||
number: iteration,
|
||||
findings_count: iterationFindings.length,
|
||||
ace_queries: iterationAceQueries.length,
|
||||
cross_references: sharedContext.crossReferences.length,
|
||||
new_discoveries: convergenceCheck.newDiscoveries,
|
||||
confidence: convergenceCheck.confidence,
|
||||
continued: shouldContinue
|
||||
}],
|
||||
cumulative_findings: cumulativeFindings
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
**ACE in Iteration Loop**:
|
||||
|
||||
```
|
||||
Iteration N
|
||||
│
|
||||
├─→ ACE Search (based on previous findings)
|
||||
│ └─ Query: "related code paths for {finding.category}"
|
||||
│ └─ Result: Additional files to explore
|
||||
│
|
||||
├─→ Agent Exploration (with ACE context)
|
||||
│ └─ Agent receives: dimension targets + ACE suggestions
|
||||
│ └─ Agent can call ACE for deeper search
|
||||
│
|
||||
├─→ Cross-Reference Analysis
|
||||
│ └─ Compare findings between dimensions
|
||||
│ └─ Identify discrepancies
|
||||
│
|
||||
└─→ Convergence Check
|
||||
└─ New findings? Continue
|
||||
└─ No new findings? Terminate
|
||||
```
|
||||
|
||||
**Dimension Agent Prompt Template (with ACE)**:
|
||||
|
||||
```javascript
|
||||
function buildDimensionPromptWithACE(dimension, iteration, previousFindings, aceResults, outputDir) {
|
||||
// Filter ACE results relevant to this dimension
|
||||
const relevantAceResults = aceResults.filter(r =>
|
||||
r.query.includes(dimension.name) || dimension.focus_areas.some(fa => r.query.includes(fa))
|
||||
);
|
||||
|
||||
return `
|
||||
## Task Objective
|
||||
Explore ${dimension.name} dimension for issue discovery (Iteration ${iteration})
|
||||
|
||||
## Context
|
||||
- Dimension: ${dimension.name}
|
||||
- Description: ${dimension.description}
|
||||
- Search Targets: ${dimension.search_targets.join(', ')}
|
||||
- Focus Areas: ${dimension.focus_areas.join(', ')}
|
||||
|
||||
## ACE Semantic Search Results (Pre-gathered)
|
||||
The following files/code sections were identified by ACE as relevant to this dimension:
|
||||
${JSON.stringify(relevantAceResults.map(r => ({ query: r.query, files: r.result.slice(0, 5) })), null, 2)}
|
||||
|
||||
**Use ACE for deeper exploration**: You have access to mcp__ace-tool__search_context.
|
||||
When you find something interesting, use ACE to find related code:
|
||||
- mcp__ace-tool__search_context({ project_root_path: ".", query: "related to {finding}" })
|
||||
|
||||
${iteration > 1 ? `
|
||||
## Previous Findings to Build Upon
|
||||
${summarizePreviousFindings(previousFindings, dimension.name)}
|
||||
|
||||
## This Iteration Focus
|
||||
- Explore areas not yet covered (check ACE results for new files)
|
||||
- Verify/deepen previous findings
|
||||
- Follow leads from previous discoveries
|
||||
- Use ACE to find cross-references between dimensions
|
||||
` : ''}
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
1. Read exploration plan: ${outputDir}/../exploration-plan.json
|
||||
2. Read schema: ~/.claude/workflows/cli-templates/schemas/discovery-finding-schema.json
|
||||
3. Review ACE results above for starting points
|
||||
4. Explore files identified by ACE
|
||||
|
||||
## Exploration Instructions
|
||||
${dimension.agent_prompt}
|
||||
|
||||
## ACE Usage Guidelines
|
||||
- Use ACE when you need to find:
|
||||
- Where a function/class is used
|
||||
- Related implementations in other modules
|
||||
- Cross-module dependencies
|
||||
- Similar patterns elsewhere in codebase
|
||||
- Query format: Natural language, be specific
|
||||
- Example: "Where is UserService.authenticate called from?"
|
||||
|
||||
## Output Requirements
|
||||
|
||||
**1. Write JSON file**: ${outputDir}/${dimension.name}.json
|
||||
Follow discovery-finding-schema.json:
|
||||
- findings: [{id, title, category, description, file, line, snippet, confidence, related_dimension}]
|
||||
- coverage: {files_explored, areas_covered, areas_remaining}
|
||||
- leads: [{description, suggested_search}] // for next iteration
|
||||
- ace_queries_used: [{query, result_count}] // track ACE usage
|
||||
|
||||
**2. Return summary**:
|
||||
- Total findings this iteration
|
||||
- Key discoveries
|
||||
- ACE queries that revealed important code
|
||||
- Recommended next exploration areas
|
||||
|
||||
## Success Criteria
|
||||
- [ ] JSON written to ${outputDir}/${dimension.name}.json
|
||||
- [ ] Each finding has file:line reference
|
||||
- [ ] ACE used for cross-references where applicable
|
||||
- [ ] Coverage report included
|
||||
- [ ] Leads for next iteration identified
|
||||
`;
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 4: Cross-Analysis & Synthesis
|
||||
|
||||
```javascript
|
||||
// For comparison intent, perform cross-analysis
|
||||
if (intentType === 'comparison' && explorationPlan.comparison_matrix) {
|
||||
const comparisonResults = [];
|
||||
|
||||
for (const point of explorationPlan.comparison_matrix.comparison_points) {
|
||||
const dimensionAFindings = cumulativeFindings.filter(f =>
|
||||
f.related_dimension === explorationPlan.comparison_matrix.dimension_a &&
|
||||
f.category.includes(point.aspect)
|
||||
);
|
||||
|
||||
const dimensionBFindings = cumulativeFindings.filter(f =>
|
||||
f.related_dimension === explorationPlan.comparison_matrix.dimension_b &&
|
||||
f.category.includes(point.aspect)
|
||||
);
|
||||
|
||||
// Compare and find discrepancies
|
||||
const discrepancies = findDiscrepancies(dimensionAFindings, dimensionBFindings, point);
|
||||
|
||||
comparisonResults.push({
|
||||
aspect: point.aspect,
|
||||
dimension_a_count: dimensionAFindings.length,
|
||||
dimension_b_count: dimensionBFindings.length,
|
||||
discrepancies: discrepancies,
|
||||
match_rate: calculateMatchRate(dimensionAFindings, dimensionBFindings)
|
||||
});
|
||||
}
|
||||
|
||||
// Write comparison analysis
|
||||
await writeJson(`${outputDir}/comparison-analysis.json`, {
|
||||
matrix: explorationPlan.comparison_matrix,
|
||||
results: comparisonResults,
|
||||
summary: {
|
||||
total_discrepancies: comparisonResults.reduce((sum, r) => sum + r.discrepancies.length, 0),
|
||||
overall_match_rate: average(comparisonResults.map(r => r.match_rate)),
|
||||
critical_mismatches: comparisonResults.filter(r => r.match_rate < 0.5)
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// Prioritize all findings
|
||||
const prioritizedFindings = prioritizeFindings(cumulativeFindings, explorationPlan);
|
||||
```
|
||||
|
||||
### Phase 5: Issue Generation & Summary
|
||||
|
||||
```javascript
|
||||
// Convert high-confidence findings to issues
|
||||
const issueWorthy = prioritizedFindings.filter(f =>
|
||||
f.confidence >= 0.7 || f.priority === 'critical' || f.priority === 'high'
|
||||
);
|
||||
|
||||
const issues = issueWorthy.map(finding => ({
|
||||
id: `ISS-${discoveryId}-${finding.id}`,
|
||||
title: finding.title,
|
||||
description: finding.description,
|
||||
source: {
|
||||
discovery_id: discoveryId,
|
||||
finding_id: finding.id,
|
||||
dimension: finding.related_dimension
|
||||
},
|
||||
file: finding.file,
|
||||
line: finding.line,
|
||||
priority: finding.priority,
|
||||
category: finding.category,
|
||||
suggested_fix: finding.suggested_fix,
|
||||
confidence: finding.confidence,
|
||||
status: 'discovered',
|
||||
created_at: new Date().toISOString()
|
||||
}));
|
||||
|
||||
// Write issues
|
||||
await writeJsonl(`${outputDir}/discovery-issues.jsonl`, issues);
|
||||
|
||||
// Update final state (summary embedded in state, no separate file)
|
||||
await updateDiscoveryState(outputDir, {
|
||||
phase: 'complete',
|
||||
updated_at: new Date().toISOString(),
|
||||
results: {
|
||||
total_iterations: iteration,
|
||||
total_findings: cumulativeFindings.length,
|
||||
issues_generated: issues.length,
|
||||
comparison_match_rate: comparisonResults
|
||||
? average(comparisonResults.map(r => r.match_rate))
|
||||
: null
|
||||
}
|
||||
});
|
||||
|
||||
// Prompt user for next action
|
||||
await AskUserQuestion({
|
||||
questions: [{
|
||||
question: `Discovery complete: ${issues.length} issues from ${cumulativeFindings.length} findings across ${iteration} iterations. What next?`,
|
||||
header: "Next Step",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Export to Issues (Recommended)", description: `Export ${issues.length} issues for planning` },
|
||||
{ label: "Review Details", description: "View comparison analysis and iteration details" },
|
||||
{ label: "Run Deeper", description: "Continue with more iterations" },
|
||||
{ label: "Skip", description: "Complete without exporting" }
|
||||
]
|
||||
}]
|
||||
});
|
||||
```
|
||||
|
||||
## Output File Structure
|
||||
|
||||
```
|
||||
.workflow/issues/discoveries/
|
||||
└── {DBP-YYYYMMDD-HHmmss}/
|
||||
├── discovery-state.json # Session state with iteration tracking
|
||||
├── iterations/
|
||||
│ ├── 1/
|
||||
│ │ └── {dimension}.json # Dimension findings
|
||||
│ ├── 2/
|
||||
│ │ └── {dimension}.json
|
||||
│ └── ...
|
||||
├── comparison-analysis.json # Cross-dimension comparison (if applicable)
|
||||
└── discovery-issues.jsonl # Generated issue candidates
|
||||
```
|
||||
|
||||
**Simplified Design**:
|
||||
- ACE context and Gemini plan kept in memory, not persisted
|
||||
- Iteration summaries embedded in state
|
||||
- No separate summary.md (state.json contains all needed info)
|
||||
|
||||
## Schema References
|
||||
|
||||
| Schema | Path | Used By |
|
||||
|--------|------|---------|
|
||||
| **Discovery State** | `discovery-state-schema.json` | Orchestrator (state tracking) |
|
||||
| **Discovery Finding** | `discovery-finding-schema.json` | Dimension agents (output) |
|
||||
| **Exploration Plan** | `exploration-plan-schema.json` | Gemini output validation (memory only) |
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Flag | Default | Description |
|
||||
|------|---------|-------------|
|
||||
| `--scope` | `**/*` | File pattern to explore |
|
||||
| `--depth` | `standard` | `standard` (3 iterations) or `deep` (5+ iterations) |
|
||||
| `--max-iterations` | 5 | Maximum exploration iterations |
|
||||
| `--tool` | `gemini` | Planning tool (gemini/qwen) |
|
||||
| `--plan-only` | `false` | Stop after Phase 2 (Gemini planning), show plan for user review |
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Single Module Deep Dive
|
||||
|
||||
```bash
|
||||
/issue:discover-by-prompt "Find all potential issues in the auth module" --scope=src/auth/**
|
||||
```
|
||||
|
||||
**Gemini plans** (single dimension):
|
||||
- Dimension: auth-module
|
||||
- Focus: security vulnerabilities, edge cases, error handling, test gaps
|
||||
|
||||
**Iterations**: 2-3 (until no new findings)
|
||||
|
||||
### Example 2: API Contract Comparison
|
||||
|
||||
```bash
|
||||
/issue:discover-by-prompt "Check if API calls match implementations" --scope=src/**
|
||||
```
|
||||
|
||||
**Gemini plans** (comparison):
|
||||
- Dimension 1: api-consumers (fetch calls, hooks, services)
|
||||
- Dimension 2: api-providers (handlers, routes, controllers)
|
||||
- Comparison matrix: endpoints, methods, payloads, responses
|
||||
|
||||
### Example 3: Multi-Module Audit
|
||||
|
||||
```bash
|
||||
/issue:discover-by-prompt "Audit the payment flow for issues" --scope=src/payment/**
|
||||
```
|
||||
|
||||
**Gemini plans** (multi-dimension):
|
||||
- Dimension 1: payment-logic (calculations, state transitions)
|
||||
- Dimension 2: validation (input checks, business rules)
|
||||
- Dimension 3: error-handling (failure modes, recovery)
|
||||
|
||||
### Example 4: Plan Only Mode
|
||||
|
||||
```bash
|
||||
/issue:discover-by-prompt "Find inconsistent patterns" --plan-only
|
||||
```
|
||||
|
||||
Stops after Gemini planning, outputs:
|
||||
```
|
||||
Gemini Plan:
|
||||
- Intent: search
|
||||
- Dimensions: 2 (pattern-definitions, pattern-usages)
|
||||
- Estimated iterations: 3
|
||||
|
||||
Continue with exploration? [Y/n]
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
```bash
|
||||
# After discovery, plan solutions
|
||||
/issue:plan DBP-001-01,DBP-001-02
|
||||
|
||||
# View all discoveries
|
||||
/issue:manage
|
||||
|
||||
# Standard perspective-based discovery
|
||||
/issue:discover src/auth/** --perspectives=security,bug
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Be Specific in Prompts**: More specific prompts lead to better Gemini planning
|
||||
2. **Scope Appropriately**: Narrow scope for focused comparison, wider for audits
|
||||
3. **Review Exploration Plan**: Check `exploration-plan.json` before long explorations
|
||||
4. **Use Standard Depth First**: Start with standard, go deep only if needed
|
||||
5. **Combine with `/issue:discover`**: Use prompt-based for comparisons, perspective-based for audits
|
||||
@@ -1,472 +0,0 @@
|
||||
---
|
||||
name: issue:discover
|
||||
description: Discover potential issues from multiple perspectives (bug, UX, test, quality, security, performance, maintainability, best-practices) using CLI explore. Supports Exa external research for security and best-practices perspectives.
|
||||
argument-hint: "[-y|--yes] <path-pattern> [--perspectives=bug,ux,...] [--external]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*), AskUserQuestion(*), Glob(*), Grep(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-select all perspectives, skip confirmations.
|
||||
|
||||
# Issue Discovery Command
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Discover issues in specific module (interactive perspective selection)
|
||||
/issue:discover src/auth/**
|
||||
|
||||
# Discover with specific perspectives
|
||||
/issue:discover src/payment/** --perspectives=bug,security,test
|
||||
|
||||
# Discover with external research for all perspectives
|
||||
/issue:discover src/api/** --external
|
||||
|
||||
# Discover in multiple modules
|
||||
/issue:discover src/auth/**,src/payment/**
|
||||
```
|
||||
|
||||
**Discovery Scope**: Specified modules/files only
|
||||
**Output Directory**: `.workflow/issues/discoveries/{discovery-id}/`
|
||||
**Available Perspectives**: bug, ux, test, quality, security, performance, maintainability, best-practices
|
||||
**Exa Integration**: Auto-enabled for security and best-practices perspectives
|
||||
**CLI Tools**: Gemini → Qwen → Codex (fallback chain)
|
||||
|
||||
## What & Why
|
||||
|
||||
### Core Concept
|
||||
Multi-perspective issue discovery orchestrator that explores code from different angles to identify potential bugs, UX improvements, test gaps, and other actionable items. Unlike code review (which assesses existing code quality), discovery focuses on **finding opportunities for improvement and potential problems**.
|
||||
|
||||
**vs Code Review**:
|
||||
- **Code Review** (`review-module-cycle`): Evaluates code quality against standards
|
||||
- **Issue Discovery** (`issue:discover`): Finds actionable issues, bugs, and improvement opportunities
|
||||
|
||||
### Value Proposition
|
||||
1. **Proactive Issue Detection**: Find problems before they become bugs
|
||||
2. **Multi-Perspective Analysis**: Each perspective surfaces different types of issues
|
||||
3. **External Benchmarking**: Compare against industry best practices via Exa
|
||||
4. **Direct Issue Integration**: Discoveries can be exported to issue tracker
|
||||
5. **Dashboard Management**: View, filter, and export discoveries via CCW dashboard
|
||||
|
||||
## How It Works
|
||||
|
||||
### Execution Flow
|
||||
|
||||
```
|
||||
Phase 1: Discovery & Initialization
|
||||
└─ Parse target pattern, create session, initialize output structure
|
||||
|
||||
Phase 2: Interactive Perspective Selection
|
||||
└─ AskUserQuestion for perspective selection (or use --perspectives)
|
||||
|
||||
Phase 3: Parallel Perspective Analysis
|
||||
├─ Launch N @cli-explore-agent instances (one per perspective)
|
||||
├─ Security & Best-Practices auto-trigger Exa research
|
||||
├─ Agent writes perspective JSON, returns summary
|
||||
└─ Update discovery-progress.json
|
||||
|
||||
Phase 4: Aggregation & Prioritization
|
||||
├─ Collect agent return summaries
|
||||
├─ Load perspective JSON files
|
||||
├─ Merge findings, deduplicate by file+line
|
||||
└─ Calculate priority scores
|
||||
|
||||
Phase 5: Issue Generation & Summary
|
||||
├─ Convert high-priority discoveries to issue format
|
||||
├─ Write to discovery-issues.jsonl
|
||||
├─ Generate single summary.md from agent returns
|
||||
└─ Update discovery-state.json to complete
|
||||
|
||||
Phase 6: User Action Prompt
|
||||
└─ AskUserQuestion for next step (export/dashboard/skip)
|
||||
```
|
||||
|
||||
## Perspectives
|
||||
|
||||
### Available Perspectives
|
||||
|
||||
| Perspective | Focus | Categories | Exa |
|
||||
|-------------|-------|------------|-----|
|
||||
| **bug** | Potential Bugs | edge-case, null-check, resource-leak, race-condition, boundary, exception-handling | - |
|
||||
| **ux** | User Experience | error-message, loading-state, feedback, accessibility, interaction, consistency | - |
|
||||
| **test** | Test Coverage | missing-test, edge-case-test, integration-gap, coverage-hole, assertion-quality | - |
|
||||
| **quality** | Code Quality | complexity, duplication, naming, documentation, code-smell, readability | - |
|
||||
| **security** | Security Issues | injection, auth, encryption, input-validation, data-exposure, access-control | ✓ |
|
||||
| **performance** | Performance | n-plus-one, memory-usage, caching, algorithm, blocking-operation, resource | - |
|
||||
| **maintainability** | Maintainability | coupling, cohesion, tech-debt, extensibility, module-boundary, interface-design | - |
|
||||
| **best-practices** | Best Practices | convention, pattern, framework-usage, anti-pattern, industry-standard | ✓ |
|
||||
|
||||
### Interactive Perspective Selection
|
||||
|
||||
When no `--perspectives` flag is provided, the command uses AskUserQuestion:
|
||||
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Select primary discovery focus:",
|
||||
header: "Focus",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Bug + Test + Quality", description: "Quick scan: potential bugs, test gaps, code quality (Recommended)" },
|
||||
{ label: "Security + Performance", description: "System audit: security issues, performance bottlenecks" },
|
||||
{ label: "Maintainability + Best-practices", description: "Long-term health: coupling, tech debt, conventions" },
|
||||
{ label: "Full analysis", description: "All 7 perspectives (comprehensive, takes longer)" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
**Recommended Combinations**:
|
||||
- Quick scan: bug, test, quality
|
||||
- Full analysis: all perspectives
|
||||
- Security audit: security, bug, quality
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
### Orchestrator
|
||||
|
||||
**Phase 1: Discovery & Initialization**
|
||||
|
||||
```javascript
|
||||
// Step 1: Parse target pattern and resolve files
|
||||
const resolvedFiles = await expandGlobPattern(targetPattern);
|
||||
if (resolvedFiles.length === 0) {
|
||||
throw new Error(`No files matched pattern: ${targetPattern}`);
|
||||
}
|
||||
|
||||
// Step 2: Generate discovery ID
|
||||
const discoveryId = `DSC-${formatDate(new Date(), 'YYYYMMDD-HHmmss')}`;
|
||||
|
||||
// Step 3: Create output directory
|
||||
const outputDir = `.workflow/issues/discoveries/${discoveryId}`;
|
||||
await mkdir(outputDir, { recursive: true });
|
||||
await mkdir(`${outputDir}/perspectives`, { recursive: true });
|
||||
|
||||
// Step 4: Initialize unified discovery state (merged state+progress)
|
||||
await writeJson(`${outputDir}/discovery-state.json`, {
|
||||
discovery_id: discoveryId,
|
||||
target_pattern: targetPattern,
|
||||
phase: "initialization",
|
||||
created_at: new Date().toISOString(),
|
||||
updated_at: new Date().toISOString(),
|
||||
target: { files_count: { total: resolvedFiles.length }, project: {} },
|
||||
perspectives: [], // filled after selection: [{name, status, findings}]
|
||||
external_research: { enabled: false, completed: false },
|
||||
results: { total_findings: 0, issues_generated: 0, priority_distribution: {} }
|
||||
});
|
||||
```
|
||||
|
||||
**Phase 2: Perspective Selection**
|
||||
|
||||
```javascript
|
||||
// Check for --perspectives flag
|
||||
let selectedPerspectives = [];
|
||||
|
||||
if (args.perspectives) {
|
||||
selectedPerspectives = args.perspectives.split(',').map(p => p.trim());
|
||||
} else {
|
||||
// Interactive selection via AskUserQuestion
|
||||
const response = await AskUserQuestion({...});
|
||||
selectedPerspectives = parseSelectedPerspectives(response);
|
||||
}
|
||||
|
||||
// Validate and update state
|
||||
await updateDiscoveryState(outputDir, {
|
||||
'metadata.perspectives': selectedPerspectives,
|
||||
phase: 'parallel'
|
||||
});
|
||||
```
|
||||
|
||||
**Phase 3: Parallel Perspective Analysis**
|
||||
|
||||
Launch N agents in parallel (one per selected perspective):
|
||||
|
||||
```javascript
|
||||
// Launch agents in parallel - agents write JSON and return summary
|
||||
const agentPromises = selectedPerspectives.map(perspective =>
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: `Discover ${perspective} issues`,
|
||||
prompt: buildPerspectivePrompt(perspective, discoveryId, resolvedFiles, outputDir)
|
||||
})
|
||||
);
|
||||
|
||||
// Wait for all agents - collect their return summaries
|
||||
const results = await Promise.all(agentPromises);
|
||||
// results contain agent summaries for final report
|
||||
```
|
||||
|
||||
**Phase 4: Aggregation & Prioritization**
|
||||
|
||||
```javascript
|
||||
// Load all perspective JSON files written by agents
|
||||
const allFindings = [];
|
||||
for (const perspective of selectedPerspectives) {
|
||||
const jsonPath = `${outputDir}/perspectives/${perspective}.json`;
|
||||
if (await fileExists(jsonPath)) {
|
||||
const data = await readJson(jsonPath);
|
||||
allFindings.push(...data.findings.map(f => ({ ...f, perspective })));
|
||||
}
|
||||
}
|
||||
|
||||
// Deduplicate and prioritize
|
||||
const prioritizedFindings = deduplicateAndPrioritize(allFindings);
|
||||
|
||||
// Update unified state
|
||||
await updateDiscoveryState(outputDir, {
|
||||
phase: 'aggregation',
|
||||
'results.total_findings': prioritizedFindings.length,
|
||||
'results.priority_distribution': countByPriority(prioritizedFindings)
|
||||
});
|
||||
```
|
||||
|
||||
**Phase 5: Issue Generation & Summary**
|
||||
|
||||
```javascript
|
||||
// Convert high-priority findings to issues
|
||||
const issueWorthy = prioritizedFindings.filter(f =>
|
||||
f.priority === 'critical' || f.priority === 'high' || f.priority_score >= 0.7
|
||||
);
|
||||
|
||||
// Write discovery-issues.jsonl
|
||||
await writeJsonl(`${outputDir}/discovery-issues.jsonl`, issues);
|
||||
|
||||
// Generate single summary.md from agent return summaries
|
||||
// Orchestrator briefly summarizes what agents returned (NO detailed reports)
|
||||
await writeSummaryFromAgentReturns(outputDir, results, prioritizedFindings, issues);
|
||||
|
||||
// Update final state
|
||||
await updateDiscoveryState(outputDir, {
|
||||
phase: 'complete',
|
||||
updated_at: new Date().toISOString(),
|
||||
'results.issues_generated': issues.length
|
||||
});
|
||||
```
|
||||
|
||||
**Phase 6: User Action Prompt**
|
||||
|
||||
```javascript
|
||||
// Prompt user for next action based on discovery results
|
||||
const hasHighPriority = issues.some(i => i.priority === 'critical' || i.priority === 'high');
|
||||
const hasMediumFindings = prioritizedFindings.some(f => f.priority === 'medium');
|
||||
|
||||
await AskUserQuestion({
|
||||
questions: [{
|
||||
question: `Discovery complete: ${issues.length} issues generated, ${prioritizedFindings.length} total findings. What would you like to do next?`,
|
||||
header: "Next Step",
|
||||
multiSelect: false,
|
||||
options: hasHighPriority ? [
|
||||
{ label: "Export to Issues (Recommended)", description: `${issues.length} high-priority issues found - export to issue tracker for planning` },
|
||||
{ label: "Open Dashboard", description: "Review findings in ccw view before exporting" },
|
||||
{ label: "Skip", description: "Complete discovery without exporting" }
|
||||
] : hasMediumFindings ? [
|
||||
{ label: "Open Dashboard (Recommended)", description: "Review medium-priority findings in ccw view to decide which to export" },
|
||||
{ label: "Export to Issues", description: `Export ${issues.length} issues to tracker` },
|
||||
{ label: "Skip", description: "Complete discovery without exporting" }
|
||||
] : [
|
||||
{ label: "Skip (Recommended)", description: "No significant issues found - complete discovery" },
|
||||
{ label: "Open Dashboard", description: "Review all findings in ccw view" },
|
||||
{ label: "Export to Issues", description: `Export ${issues.length} issues anyway` }
|
||||
]
|
||||
}]
|
||||
});
|
||||
|
||||
// Handle response
|
||||
if (response === "Export to Issues") {
|
||||
// Append to issues.jsonl
|
||||
await appendJsonl('.workflow/issues/issues.jsonl', issues);
|
||||
console.log(`Exported ${issues.length} issues. Run /issue:plan to continue.`);
|
||||
} else if (response === "Open Dashboard") {
|
||||
console.log('Run `ccw view` and navigate to Issues > Discovery to manage findings.');
|
||||
}
|
||||
```
|
||||
|
||||
### Output File Structure
|
||||
|
||||
```
|
||||
.workflow/issues/discoveries/
|
||||
├── index.json # Discovery session index
|
||||
└── {discovery-id}/
|
||||
├── discovery-state.json # Unified state (merged state+progress)
|
||||
├── perspectives/
|
||||
│ └── {perspective}.json # Per-perspective findings
|
||||
├── external-research.json # Exa research results (if enabled)
|
||||
├── discovery-issues.jsonl # Generated candidate issues
|
||||
└── summary.md # Single summary (from agent returns)
|
||||
```
|
||||
|
||||
### Schema References
|
||||
|
||||
**External Schema Files** (agent MUST read and follow exactly):
|
||||
|
||||
| Schema | Path | Purpose |
|
||||
|--------|------|---------|
|
||||
| **Discovery State** | `~/.claude/workflows/cli-templates/schemas/discovery-state-schema.json` | Session state machine |
|
||||
| **Discovery Finding** | `~/.claude/workflows/cli-templates/schemas/discovery-finding-schema.json` | Perspective analysis results |
|
||||
|
||||
### Agent Invocation Template
|
||||
|
||||
**Perspective Analysis Agent**:
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: `Discover ${perspective} issues`,
|
||||
prompt: `
|
||||
## Task Objective
|
||||
Discover potential ${perspective} issues in specified module files.
|
||||
|
||||
## Discovery Context
|
||||
- Discovery ID: ${discoveryId}
|
||||
- Perspective: ${perspective}
|
||||
- Target Pattern: ${targetPattern}
|
||||
- Resolved Files: ${resolvedFiles.length} files
|
||||
- Output Directory: ${outputDir}
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
1. Read discovery state: ${outputDir}/discovery-state.json
|
||||
2. Read schema: ~/.claude/workflows/cli-templates/schemas/discovery-finding-schema.json
|
||||
3. Analyze target files for ${perspective} concerns
|
||||
|
||||
## Output Requirements
|
||||
|
||||
**1. Write JSON file**: ${outputDir}/perspectives/${perspective}.json
|
||||
- Follow discovery-finding-schema.json exactly
|
||||
- Each finding: id, title, priority, category, description, file, line, snippet, suggested_issue, confidence
|
||||
|
||||
**2. Return summary** (DO NOT write report file):
|
||||
- Return a brief text summary of findings
|
||||
- Include: total findings, priority breakdown, key issues
|
||||
- This summary will be used by orchestrator for final report
|
||||
|
||||
## Perspective-Specific Guidance
|
||||
${getPerspectiveGuidance(perspective)}
|
||||
|
||||
## Success Criteria
|
||||
- [ ] JSON written to ${outputDir}/perspectives/${perspective}.json
|
||||
- [ ] Summary returned with findings count and key issues
|
||||
- [ ] Each finding includes actionable suggested_issue
|
||||
- [ ] Priority uses lowercase enum: critical/high/medium/low
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**Exa Research Agent** (for security and best-practices):
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: `External research for ${perspective} via Exa`,
|
||||
prompt: `
|
||||
## Task Objective
|
||||
Research industry best practices for ${perspective} using Exa search
|
||||
|
||||
## Research Steps
|
||||
1. Read project tech stack: .workflow/project-tech.json
|
||||
2. Use Exa to search for best practices
|
||||
3. Synthesize findings relevant to this project
|
||||
|
||||
## Output Requirements
|
||||
|
||||
**1. Write JSON file**: ${outputDir}/external-research.json
|
||||
- Include sources, key_findings, gap_analysis, recommendations
|
||||
|
||||
**2. Return summary** (DO NOT write report file):
|
||||
- Brief summary of external research findings
|
||||
- Key recommendations for the project
|
||||
|
||||
## Success Criteria
|
||||
- [ ] JSON written to ${outputDir}/external-research.json
|
||||
- [ ] Summary returned with key recommendations
|
||||
- [ ] Findings are relevant to project's tech stack
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
### Perspective Guidance Reference
|
||||
|
||||
```javascript
|
||||
function getPerspectiveGuidance(perspective) {
|
||||
const guidance = {
|
||||
bug: `
|
||||
Focus: Null checks, edge cases, resource leaks, race conditions, boundary conditions, exception handling
|
||||
Priority: Critical=data corruption/crash, High=malfunction, Medium=edge case issues, Low=minor
|
||||
`,
|
||||
ux: `
|
||||
Focus: Error messages, loading states, feedback, accessibility, interaction patterns, form validation
|
||||
Priority: Critical=inaccessible, High=confusing, Medium=inconsistent, Low=cosmetic
|
||||
`,
|
||||
test: `
|
||||
Focus: Missing unit tests, edge case coverage, integration gaps, assertion quality, test isolation
|
||||
Priority: Critical=no security tests, High=no core logic tests, Medium=weak coverage, Low=minor gaps
|
||||
`,
|
||||
quality: `
|
||||
Focus: Complexity, duplication, naming, documentation, code smells, readability
|
||||
Priority: Critical=unmaintainable, High=significant issues, Medium=naming/docs, Low=minor refactoring
|
||||
`,
|
||||
security: `
|
||||
Focus: Input validation, auth/authz, injection, XSS/CSRF, data exposure, access control
|
||||
Priority: Critical=auth bypass/injection, High=missing authz, Medium=weak validation, Low=headers
|
||||
`,
|
||||
performance: `
|
||||
Focus: N+1 queries, memory leaks, caching, algorithm efficiency, blocking operations
|
||||
Priority: Critical=memory leaks, High=N+1/inefficient, Medium=missing cache, Low=minor optimization
|
||||
`,
|
||||
maintainability: `
|
||||
Focus: Coupling, interface design, tech debt, extensibility, module boundaries, configuration
|
||||
Priority: Critical=unrelated code changes, High=unclear boundaries, Medium=coupling, Low=refactoring
|
||||
`,
|
||||
'best-practices': `
|
||||
Focus: Framework conventions, language patterns, anti-patterns, deprecated APIs, coding standards
|
||||
Priority: Critical=anti-patterns causing bugs, High=convention violations, Medium=style, Low=cosmetic
|
||||
`
|
||||
};
|
||||
return guidance[perspective] || 'General code discovery analysis';
|
||||
}
|
||||
```
|
||||
|
||||
## Dashboard Integration
|
||||
|
||||
### Viewing Discoveries
|
||||
|
||||
Open CCW dashboard to manage discoveries:
|
||||
|
||||
```bash
|
||||
ccw view
|
||||
```
|
||||
|
||||
Navigate to **Issues > Discovery** to:
|
||||
- View all discovery sessions
|
||||
- Filter findings by perspective and priority
|
||||
- Preview finding details
|
||||
- Select and export findings as issues
|
||||
|
||||
### Exporting to Issues
|
||||
|
||||
From the dashboard, select findings and click "Export as Issues" to:
|
||||
1. Convert discoveries to standard issue format
|
||||
2. Append to `.workflow/issues/issues.jsonl`
|
||||
3. Set status to `registered`
|
||||
4. Continue with `/issue:plan` workflow
|
||||
|
||||
## Related Commands
|
||||
|
||||
```bash
|
||||
# After discovery, plan solutions for exported issues
|
||||
/issue:plan DSC-001,DSC-002,DSC-003
|
||||
|
||||
# Or use interactive management
|
||||
/issue:manage
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start Focused**: Begin with specific modules rather than entire codebase
|
||||
2. **Use Quick Scan First**: Start with bug, test, quality for fast results
|
||||
3. **Review Before Export**: Not all discoveries warrant issues - use dashboard to filter
|
||||
4. **Combine Perspectives**: Run related perspectives together (e.g., security + bug)
|
||||
5. **Enable Exa for New Tech**: When using unfamiliar frameworks, enable external research
|
||||
@@ -1,580 +0,0 @@
|
||||
---
|
||||
name: execute
|
||||
description: Execute queue with DAG-based parallel orchestration (one commit per solution)
|
||||
argument-hint: "[-y|--yes] --queue <queue-id> [--worktree [<existing-path>]]"
|
||||
allowed-tools: TodoWrite(*), Bash(*), Read(*), AskUserQuestion(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-confirm execution, use recommended settings.
|
||||
|
||||
# Issue Execute Command (/issue:execute)
|
||||
|
||||
## Overview
|
||||
|
||||
Minimal orchestrator that dispatches **solution IDs** to executors. Each executor receives a complete solution with all its tasks.
|
||||
|
||||
**Design Principles:**
|
||||
- `queue dag` → returns parallel batches with solution IDs (S-1, S-2, ...)
|
||||
- `detail <id>` → READ-ONLY solution fetch (returns full solution with all tasks)
|
||||
- `done <id>` → update solution completion status
|
||||
- No race conditions: status changes only via `done`
|
||||
- **Executor handles all tasks within a solution sequentially**
|
||||
- **Single worktree for entire queue**: One worktree isolates ALL queue execution from main workspace
|
||||
|
||||
## Queue ID Requirement (MANDATORY)
|
||||
|
||||
**Queue ID is REQUIRED.** You MUST specify which queue to execute via `--queue <queue-id>`.
|
||||
|
||||
### If Queue ID Not Provided
|
||||
|
||||
When `--queue` parameter is missing, you MUST:
|
||||
|
||||
1. **List available queues** by running:
|
||||
```javascript
|
||||
const result = Bash('ccw issue queue list --brief --json');
|
||||
const index = JSON.parse(result);
|
||||
```
|
||||
|
||||
2. **Display available queues** to user:
|
||||
```
|
||||
Available Queues:
|
||||
ID Status Progress Issues
|
||||
-----------------------------------------------------------
|
||||
→ QUE-20251215-001 active 3/10 ISS-001, ISS-002
|
||||
QUE-20251210-002 active 0/5 ISS-003
|
||||
QUE-20251205-003 completed 8/8 ISS-004
|
||||
```
|
||||
|
||||
3. **Stop and ask user** to specify which queue to execute:
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Which queue would you like to execute?",
|
||||
header: "Queue",
|
||||
multiSelect: false,
|
||||
options: index.queues
|
||||
.filter(q => q.status === 'active')
|
||||
.map(q => ({
|
||||
label: q.id,
|
||||
description: `${q.status}, ${q.completed_solutions || 0}/${q.total_solutions || 0} completed, Issues: ${q.issue_ids.join(', ')}`
|
||||
}))
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
4. **After user selection**, continue execution with the selected queue ID.
|
||||
|
||||
**DO NOT auto-select queues.** Explicit user confirmation is required to prevent accidental execution of wrong queue.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/issue:execute --queue QUE-xxx # Execute specific queue (REQUIRED)
|
||||
/issue:execute --queue QUE-xxx --worktree # Execute in isolated worktree
|
||||
/issue:execute --queue QUE-xxx --worktree /path/to/existing/worktree # Resume
|
||||
```
|
||||
|
||||
**Parallelism**: Determined automatically by task dependency DAG (no manual control)
|
||||
**Executor & Dry-run**: Selected via interactive prompt (AskUserQuestion)
|
||||
**Worktree**: Creates ONE worktree for the entire queue execution (not per-solution)
|
||||
|
||||
**⭐ Recommended Executor**: **Codex** - Best for long-running autonomous work (2hr timeout), supports background execution and full write access
|
||||
|
||||
**Worktree Options**:
|
||||
- `--worktree` - Create a new worktree with timestamp-based name
|
||||
- `--worktree <existing-path>` - Resume in an existing worktree (for recovery/continuation)
|
||||
|
||||
**Resume**: Use `git worktree list` to find existing worktrees from interrupted executions
|
||||
|
||||
## Execution Flow
|
||||
|
||||
```
|
||||
Phase 0: Validate Queue ID (REQUIRED)
|
||||
├─ If --queue provided → use specified queue
|
||||
├─ If --queue missing → list queues, prompt user to select
|
||||
└─ Store QUEUE_ID for all subsequent commands
|
||||
|
||||
Phase 0.5 (if --worktree): Setup Queue Worktree
|
||||
├─ Create ONE worktree for entire queue: .ccw/worktrees/queue-<timestamp>
|
||||
├─ All subsequent execution happens in this worktree
|
||||
└─ Main workspace remains clean and untouched
|
||||
|
||||
Phase 1: Get DAG & User Selection
|
||||
├─ ccw issue queue dag --queue ${QUEUE_ID} → { parallel_batches: [["S-1","S-2"], ["S-3"]] }
|
||||
└─ AskUserQuestion → executor type (codex|gemini|agent), dry-run mode, worktree mode
|
||||
|
||||
Phase 2: Dispatch Parallel Batch (DAG-driven)
|
||||
├─ Parallelism determined by DAG (no manual limit)
|
||||
├─ All executors work in the SAME worktree (or main if no worktree)
|
||||
├─ For each solution ID in batch (parallel - all at once):
|
||||
│ ├─ Executor calls: ccw issue detail <id> (READ-ONLY)
|
||||
│ ├─ Executor gets FULL SOLUTION with all tasks
|
||||
│ ├─ Executor implements all tasks sequentially (T1 → T2 → T3)
|
||||
│ ├─ Executor tests + verifies each task
|
||||
│ ├─ Executor commits ONCE per solution (with formatted summary)
|
||||
│ └─ Executor calls: ccw issue done <id>
|
||||
└─ Wait for batch completion
|
||||
|
||||
Phase 3: Next Batch (repeat Phase 2)
|
||||
└─ ccw issue queue dag → check for newly-ready solutions
|
||||
|
||||
Phase 4 (if --worktree): Worktree Completion
|
||||
├─ All batches complete → prompt for merge strategy
|
||||
└─ Options: Create PR / Merge to main / Keep branch
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
### Phase 0: Validate Queue ID
|
||||
|
||||
```javascript
|
||||
// Check if --queue was provided
|
||||
let QUEUE_ID = args.queue;
|
||||
|
||||
if (!QUEUE_ID) {
|
||||
// List available queues
|
||||
const listResult = Bash('ccw issue queue list --brief --json').trim();
|
||||
const index = JSON.parse(listResult);
|
||||
|
||||
if (index.queues.length === 0) {
|
||||
console.log('No queues found. Use /issue:queue to create one first.');
|
||||
return;
|
||||
}
|
||||
|
||||
// Filter active queues only
|
||||
const activeQueues = index.queues.filter(q => q.status === 'active');
|
||||
|
||||
if (activeQueues.length === 0) {
|
||||
console.log('No active queues found.');
|
||||
console.log('Available queues:', index.queues.map(q => `${q.id} (${q.status})`).join(', '));
|
||||
return;
|
||||
}
|
||||
|
||||
// Display and prompt user
|
||||
console.log('\nAvailable Queues:');
|
||||
console.log('ID'.padEnd(22) + 'Status'.padEnd(12) + 'Progress'.padEnd(12) + 'Issues');
|
||||
console.log('-'.repeat(70));
|
||||
for (const q of index.queues) {
|
||||
const marker = q.id === index.active_queue_id ? '→ ' : ' ';
|
||||
console.log(marker + q.id.padEnd(20) + q.status.padEnd(12) +
|
||||
`${q.completed_solutions || 0}/${q.total_solutions || 0}`.padEnd(12) +
|
||||
q.issue_ids.join(', '));
|
||||
}
|
||||
|
||||
const answer = AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Which queue would you like to execute?",
|
||||
header: "Queue",
|
||||
multiSelect: false,
|
||||
options: activeQueues.map(q => ({
|
||||
label: q.id,
|
||||
description: `${q.completed_solutions || 0}/${q.total_solutions || 0} completed, Issues: ${q.issue_ids.join(', ')}`
|
||||
}))
|
||||
}]
|
||||
});
|
||||
|
||||
QUEUE_ID = answer['Queue'];
|
||||
}
|
||||
|
||||
console.log(`\n## Executing Queue: ${QUEUE_ID}\n`);
|
||||
```
|
||||
|
||||
### Phase 1: Get DAG & User Selection
|
||||
|
||||
```javascript
|
||||
// Get dependency graph and parallel batches (QUEUE_ID required)
|
||||
const dagJson = Bash(`ccw issue queue dag --queue ${QUEUE_ID}`).trim();
|
||||
const dag = JSON.parse(dagJson);
|
||||
|
||||
if (dag.error || dag.ready_count === 0) {
|
||||
console.log(dag.error || 'No solutions ready for execution');
|
||||
console.log('Use /issue:queue to form a queue first');
|
||||
return;
|
||||
}
|
||||
|
||||
console.log(`
|
||||
## Queue DAG (Solution-Level)
|
||||
|
||||
- Total Solutions: ${dag.total}
|
||||
- Ready: ${dag.ready_count}
|
||||
- Completed: ${dag.completed_count}
|
||||
- Parallel in batch 1: ${dag.parallel_batches[0]?.length || 0}
|
||||
`);
|
||||
|
||||
// Interactive selection via AskUserQuestion
|
||||
const answer = AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: 'Select executor type:',
|
||||
header: 'Executor',
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: 'Codex (Recommended)', description: 'Autonomous coding with full write access' },
|
||||
{ label: 'Gemini', description: 'Large context analysis and implementation' },
|
||||
{ label: 'Agent', description: 'Claude Code sub-agent for complex tasks' }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: 'Execution mode:',
|
||||
header: 'Mode',
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: 'Execute (Recommended)', description: 'Run all ready solutions' },
|
||||
{ label: 'Dry-run', description: 'Show DAG and batches without executing' }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: 'Use git worktree for queue isolation?',
|
||||
header: 'Worktree',
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: 'Yes (Recommended)', description: 'Create ONE worktree for entire queue - main stays clean' },
|
||||
{ label: 'No', description: 'Work directly in current directory' }
|
||||
]
|
||||
}
|
||||
]
|
||||
});
|
||||
|
||||
const executor = answer['Executor'].toLowerCase().split(' ')[0]; // codex|gemini|agent
|
||||
const isDryRun = answer['Mode'].includes('Dry-run');
|
||||
const useWorktree = answer['Worktree'].includes('Yes');
|
||||
|
||||
// Dry run mode
|
||||
if (isDryRun) {
|
||||
console.log('### Parallel Batches (Dry-run):\n');
|
||||
dag.parallel_batches.forEach((batch, i) => {
|
||||
console.log(`Batch ${i + 1}: ${batch.join(', ')}`);
|
||||
});
|
||||
return;
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 0 & 2: Setup Queue Worktree & Dispatch
|
||||
|
||||
```javascript
|
||||
// Parallelism determined by DAG - no manual limit
|
||||
// All solutions in same batch have NO file conflicts and can run in parallel
|
||||
const batch = dag.parallel_batches[0] || [];
|
||||
|
||||
// Initialize TodoWrite
|
||||
TodoWrite({
|
||||
todos: batch.map(id => ({
|
||||
content: `Execute solution ${id}`,
|
||||
status: 'pending',
|
||||
activeForm: `Executing solution ${id}`
|
||||
}))
|
||||
});
|
||||
|
||||
console.log(`\n### Executing Solutions (DAG batch 1): ${batch.join(', ')}`);
|
||||
|
||||
// Parse existing worktree path from args if provided
|
||||
// Example: --worktree /path/to/existing/worktree
|
||||
const existingWorktree = args.worktree && typeof args.worktree === 'string' ? args.worktree : null;
|
||||
|
||||
// Setup ONE worktree for entire queue (not per-solution)
|
||||
let worktreePath = null;
|
||||
let worktreeBranch = null;
|
||||
|
||||
if (useWorktree) {
|
||||
const repoRoot = Bash('git rev-parse --show-toplevel').trim();
|
||||
const worktreeBase = `${repoRoot}/.ccw/worktrees`;
|
||||
Bash(`mkdir -p "${worktreeBase}"`);
|
||||
Bash('git worktree prune'); // Cleanup stale worktrees
|
||||
|
||||
if (existingWorktree) {
|
||||
// Resume mode: Use existing worktree
|
||||
worktreePath = existingWorktree;
|
||||
worktreeBranch = Bash(`git -C "${worktreePath}" branch --show-current`).trim();
|
||||
console.log(`Resuming in existing worktree: ${worktreePath} (branch: ${worktreeBranch})`);
|
||||
} else {
|
||||
// Create mode: ONE worktree for the entire queue
|
||||
const timestamp = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
|
||||
worktreeBranch = `queue-exec-${dag.queue_id || timestamp}`;
|
||||
worktreePath = `${worktreeBase}/${worktreeBranch}`;
|
||||
Bash(`git worktree add "${worktreePath}" -b "${worktreeBranch}"`);
|
||||
console.log(`Created queue worktree: ${worktreePath}`);
|
||||
}
|
||||
}
|
||||
|
||||
// Launch ALL solutions in batch in parallel (DAG guarantees no conflicts)
|
||||
// All executors work in the SAME worktree (or main if no worktree)
|
||||
const executions = batch.map(solutionId => {
|
||||
updateTodo(solutionId, 'in_progress');
|
||||
return dispatchExecutor(solutionId, executor, worktreePath);
|
||||
});
|
||||
|
||||
await Promise.all(executions);
|
||||
batch.forEach(id => updateTodo(id, 'completed'));
|
||||
```
|
||||
|
||||
### Executor Dispatch
|
||||
|
||||
```javascript
|
||||
// worktreePath: path to shared worktree (null if not using worktree)
|
||||
function dispatchExecutor(solutionId, executorType, worktreePath = null) {
|
||||
// If worktree is provided, executor works in that directory
|
||||
// No per-solution worktree creation - ONE worktree for entire queue
|
||||
|
||||
// Pre-defined values (replaced at dispatch time, NOT by executor)
|
||||
const SOLUTION_ID = solutionId;
|
||||
const WORK_DIR = worktreePath || null;
|
||||
|
||||
// Build prompt without markdown code blocks to avoid escaping issues
|
||||
const prompt = `
|
||||
## Execute Solution: ${SOLUTION_ID}
|
||||
${WORK_DIR ? `Working Directory: ${WORK_DIR}` : ''}
|
||||
|
||||
### Step 1: Get Solution Details
|
||||
Run this command to get the full solution with all tasks:
|
||||
ccw issue detail ${SOLUTION_ID}
|
||||
|
||||
### Step 2: Execute All Tasks Sequentially
|
||||
The detail command returns a FULL SOLUTION with all tasks.
|
||||
Execute each task in order (T1 → T2 → T3 → ...):
|
||||
|
||||
For each task:
|
||||
- Follow task.implementation steps
|
||||
- Run task.test commands
|
||||
- Verify task.acceptance criteria
|
||||
- Do NOT commit after each task
|
||||
|
||||
### Step 3: Commit Solution (Once)
|
||||
After ALL tasks pass, commit once with formatted summary.
|
||||
|
||||
Command:
|
||||
git add -A
|
||||
git commit -m "<type>(<scope>): <description>
|
||||
|
||||
Solution: ${SOLUTION_ID}
|
||||
Tasks completed: <list task IDs>
|
||||
|
||||
Changes:
|
||||
- <file1>: <what changed>
|
||||
- <file2>: <what changed>
|
||||
|
||||
Verified: all tests passed"
|
||||
|
||||
Replace <type> with: feat|fix|refactor|docs|test
|
||||
Replace <scope> with: affected module name
|
||||
Replace <description> with: brief summary from solution
|
||||
|
||||
### Step 4: Report Completion
|
||||
On success, run:
|
||||
ccw issue done ${SOLUTION_ID} --result '{"summary": "<brief>", "files_modified": ["<file1>", "<file2>"], "commit": {"hash": "<hash>", "type": "<type>"}, "tasks_completed": <N>}'
|
||||
|
||||
On failure, run:
|
||||
ccw issue done ${SOLUTION_ID} --fail --reason '{"task_id": "<TX>", "error_type": "<test_failure|build_error|other>", "message": "<error details>"}'
|
||||
|
||||
### Important Notes
|
||||
- Do NOT cleanup worktree - it is shared by all solutions in the queue
|
||||
- Replace all <placeholder> values with actual values from your execution
|
||||
`;
|
||||
|
||||
// For CLI tools, pass --cd to set working directory
|
||||
const cdOption = worktreePath ? ` --cd "${worktreePath}"` : '';
|
||||
|
||||
if (executorType === 'codex') {
|
||||
return Bash(
|
||||
`ccw cli -p "${escapePrompt(prompt)}" --tool codex --mode write --id exec-${solutionId}${cdOption}`,
|
||||
{ timeout: 7200000, run_in_background: true } // 2hr for full solution
|
||||
);
|
||||
} else if (executorType === 'gemini') {
|
||||
return Bash(
|
||||
`ccw cli -p "${escapePrompt(prompt)}" --tool gemini --mode write --id exec-${solutionId}${cdOption}`,
|
||||
{ timeout: 3600000, run_in_background: true }
|
||||
);
|
||||
} else {
|
||||
return Task({
|
||||
subagent_type: 'code-developer',
|
||||
run_in_background: false,
|
||||
description: `Execute solution ${solutionId}`,
|
||||
prompt: worktreePath ? `Working directory: ${worktreePath}\n\n${prompt}` : prompt
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: Check Next Batch
|
||||
|
||||
```javascript
|
||||
// Refresh DAG after batch completes (use same QUEUE_ID)
|
||||
const refreshedDag = JSON.parse(Bash(`ccw issue queue dag --queue ${QUEUE_ID}`).trim());
|
||||
|
||||
console.log(`
|
||||
## Batch Complete
|
||||
|
||||
- Solutions Completed: ${refreshedDag.completed_count}/${refreshedDag.total}
|
||||
- Next ready: ${refreshedDag.ready_count}
|
||||
`);
|
||||
|
||||
if (refreshedDag.ready_count > 0) {
|
||||
console.log(`Run \`/issue:execute --queue ${QUEUE_ID}\` again for next batch.`);
|
||||
// Note: If resuming, pass existing worktree path:
|
||||
// /issue:execute --queue ${QUEUE_ID} --worktree <worktreePath>
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 4: Worktree Completion (after ALL batches)
|
||||
|
||||
```javascript
|
||||
// Only run when ALL solutions completed AND using worktree
|
||||
if (useWorktree && refreshedDag.ready_count === 0 && refreshedDag.completed_count === refreshedDag.total) {
|
||||
console.log('\n## All Solutions Completed - Worktree Cleanup');
|
||||
|
||||
const answer = AskUserQuestion({
|
||||
questions: [{
|
||||
question: `Queue complete. What to do with worktree branch "${worktreeBranch}"?`,
|
||||
header: 'Merge',
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: 'Create PR (Recommended)', description: 'Push branch and create pull request' },
|
||||
{ label: 'Merge to main', description: 'Merge all commits and cleanup worktree' },
|
||||
{ label: 'Keep branch', description: 'Cleanup worktree, keep branch for manual handling' }
|
||||
]
|
||||
}]
|
||||
});
|
||||
|
||||
const repoRoot = Bash('git rev-parse --show-toplevel').trim();
|
||||
|
||||
if (answer['Merge'].includes('Create PR')) {
|
||||
Bash(`git -C "${worktreePath}" push -u origin "${worktreeBranch}"`);
|
||||
Bash(`gh pr create --title "Queue ${dag.queue_id}" --body "Issue queue execution - all solutions completed" --head "${worktreeBranch}"`);
|
||||
Bash(`git worktree remove "${worktreePath}"`);
|
||||
console.log(`PR created for branch: ${worktreeBranch}`);
|
||||
} else if (answer['Merge'].includes('Merge to main')) {
|
||||
// Check main is clean
|
||||
const mainDirty = Bash('git status --porcelain').trim();
|
||||
if (mainDirty) {
|
||||
console.log('Warning: Main has uncommitted changes. Falling back to PR.');
|
||||
Bash(`git -C "${worktreePath}" push -u origin "${worktreeBranch}"`);
|
||||
Bash(`gh pr create --title "Queue ${dag.queue_id}" --body "Issue queue execution (main had uncommitted changes)" --head "${worktreeBranch}"`);
|
||||
} else {
|
||||
Bash(`git merge --no-ff "${worktreeBranch}" -m "Merge queue ${dag.queue_id}"`);
|
||||
Bash(`git branch -d "${worktreeBranch}"`);
|
||||
}
|
||||
Bash(`git worktree remove "${worktreePath}"`);
|
||||
} else {
|
||||
Bash(`git worktree remove "${worktreePath}"`);
|
||||
console.log(`Branch ${worktreeBranch} kept for manual handling`);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parallel Execution Model
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Orchestrator │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ 0. Validate QUEUE_ID (required, or prompt user to select) │
|
||||
│ │
|
||||
│ 0.5 (if --worktree) Create ONE worktree for entire queue │
|
||||
│ → .ccw/worktrees/queue-exec-<queue-id> │
|
||||
│ │
|
||||
│ 1. ccw issue queue dag --queue ${QUEUE_ID} │
|
||||
│ → { parallel_batches: [["S-1","S-2"], ["S-3"]] } │
|
||||
│ │
|
||||
│ 2. Dispatch batch 1 (parallel, SAME worktree): │
|
||||
│ ┌──────────────────────────────────────────────────────┐ │
|
||||
│ │ Shared Queue Worktree (or main) │ │
|
||||
│ │ ┌──────────────────┐ ┌──────────────────┐ │ │
|
||||
│ │ │ Executor 1 │ │ Executor 2 │ │ │
|
||||
│ │ │ detail S-1 │ │ detail S-2 │ │ │
|
||||
│ │ │ [T1→T2→T3] │ │ [T1→T2] │ │ │
|
||||
│ │ │ commit S-1 │ │ commit S-2 │ │ │
|
||||
│ │ │ done S-1 │ │ done S-2 │ │ │
|
||||
│ │ └──────────────────┘ └──────────────────┘ │ │
|
||||
│ └──────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ 3. ccw issue queue dag (refresh) │
|
||||
│ → S-3 now ready → dispatch batch 2 (same worktree) │
|
||||
│ │
|
||||
│ 4. (if --worktree) ALL batches complete → cleanup worktree │
|
||||
│ → Prompt: Create PR / Merge to main / Keep branch │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Why this works for parallel:**
|
||||
- **ONE worktree for entire queue** → all solutions share same isolated workspace
|
||||
- `detail <id>` is READ-ONLY → no race conditions
|
||||
- Each executor handles **all tasks within a solution** sequentially
|
||||
- **One commit per solution** with formatted summary (not per-task)
|
||||
- `done <id>` updates only its own solution status
|
||||
- `queue dag` recalculates ready solutions after each batch
|
||||
- Solutions in same batch have NO file conflicts (DAG guarantees)
|
||||
- **Main workspace stays clean** until merge/PR decision
|
||||
|
||||
## CLI Endpoint Contract
|
||||
|
||||
### `ccw issue queue list --brief --json`
|
||||
Returns queue index for selection (used when --queue not provided):
|
||||
```json
|
||||
{
|
||||
"active_queue_id": "QUE-20251215-001",
|
||||
"queues": [
|
||||
{ "id": "QUE-20251215-001", "status": "active", "issue_ids": ["ISS-001"], "total_solutions": 5, "completed_solutions": 2 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### `ccw issue queue dag --queue <queue-id>`
|
||||
Returns dependency graph with parallel batches (solution-level, **--queue required**):
|
||||
```json
|
||||
{
|
||||
"queue_id": "QUE-...",
|
||||
"total": 3,
|
||||
"ready_count": 2,
|
||||
"completed_count": 0,
|
||||
"nodes": [
|
||||
{ "id": "S-1", "issue_id": "ISS-xxx", "status": "pending", "ready": true, "task_count": 3 },
|
||||
{ "id": "S-2", "issue_id": "ISS-yyy", "status": "pending", "ready": true, "task_count": 2 },
|
||||
{ "id": "S-3", "issue_id": "ISS-zzz", "status": "pending", "ready": false, "depends_on": ["S-1"] }
|
||||
],
|
||||
"parallel_batches": [["S-1", "S-2"], ["S-3"]]
|
||||
}
|
||||
```
|
||||
|
||||
### `ccw issue detail <item_id>`
|
||||
Returns FULL SOLUTION with all tasks (READ-ONLY):
|
||||
```json
|
||||
{
|
||||
"item_id": "S-1",
|
||||
"issue_id": "ISS-xxx",
|
||||
"solution_id": "SOL-xxx",
|
||||
"status": "pending",
|
||||
"solution": {
|
||||
"id": "SOL-xxx",
|
||||
"approach": "...",
|
||||
"tasks": [
|
||||
{ "id": "T1", "title": "...", "implementation": [...], "test": {...} },
|
||||
{ "id": "T2", "title": "...", "implementation": [...], "test": {...} },
|
||||
{ "id": "T3", "title": "...", "implementation": [...], "test": {...} }
|
||||
],
|
||||
"exploration_context": { "relevant_files": [...] }
|
||||
},
|
||||
"execution_hints": { "executor": "codex", "estimated_minutes": 180 }
|
||||
}
|
||||
```
|
||||
|
||||
### `ccw issue done <item_id>`
|
||||
Marks solution completed/failed, updates queue state, checks for queue completion.
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| No queue | Run /issue:queue first |
|
||||
| No ready solutions | Dependencies blocked, check DAG |
|
||||
| Executor timeout | Solution not marked done, can retry |
|
||||
| Solution failure | Use `ccw issue retry` to reset |
|
||||
| Partial task failure | Executor reports which task failed via `done --fail` |
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/issue:plan` - Plan issues with solutions
|
||||
- `/issue:queue` - Form execution queue
|
||||
- `ccw issue queue dag` - View dependency graph
|
||||
- `ccw issue detail <id>` - View task details
|
||||
- `ccw issue retry` - Reset failed tasks
|
||||
@@ -1,417 +0,0 @@
|
||||
---
|
||||
name: new
|
||||
description: Create structured issue from GitHub URL or text description
|
||||
argument-hint: "[-y|--yes] <github-url | text-description> [--priority 1-5]"
|
||||
allowed-tools: TodoWrite(*), Bash(*), Read(*), AskUserQuestion(*), mcp__ace-tool__search_context(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Skip clarification questions, create issue with inferred details.
|
||||
|
||||
# Issue New Command (/issue:new)
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Requirement Clarity Detection** → Ask only when needed
|
||||
|
||||
```
|
||||
Clear Input (GitHub URL, structured text) → Direct creation
|
||||
Unclear Input (vague description) → Minimal clarifying questions
|
||||
```
|
||||
|
||||
## Issue Structure
|
||||
|
||||
```typescript
|
||||
interface Issue {
|
||||
id: string; // GH-123 or ISS-YYYYMMDD-HHMMSS
|
||||
title: string;
|
||||
status: 'registered' | 'planned' | 'queued' | 'in_progress' | 'completed' | 'failed';
|
||||
priority: number; // 1 (critical) to 5 (low)
|
||||
context: string; // Problem description (single source of truth)
|
||||
source: 'github' | 'text' | 'discovery';
|
||||
source_url?: string;
|
||||
labels?: string[];
|
||||
|
||||
// GitHub binding (for non-GitHub sources that publish to GitHub)
|
||||
github_url?: string; // https://github.com/owner/repo/issues/123
|
||||
github_number?: number; // 123
|
||||
|
||||
// Optional structured fields
|
||||
expected_behavior?: string;
|
||||
actual_behavior?: string;
|
||||
affected_components?: string[];
|
||||
|
||||
// Feedback history (failures + human clarifications)
|
||||
feedback?: {
|
||||
type: 'failure' | 'clarification' | 'rejection';
|
||||
stage: string; // new/plan/execute
|
||||
content: string;
|
||||
created_at: string;
|
||||
}[];
|
||||
|
||||
// Solution binding
|
||||
bound_solution_id: string | null;
|
||||
|
||||
// Timestamps
|
||||
created_at: string;
|
||||
updated_at: string;
|
||||
}
|
||||
```
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```bash
|
||||
# Clear inputs - direct creation
|
||||
/issue:new https://github.com/owner/repo/issues/123
|
||||
/issue:new "Login fails with special chars. Expected: success. Actual: 500 error"
|
||||
|
||||
# Vague input - will ask clarifying questions
|
||||
/issue:new "something wrong with auth"
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
### Phase 1: Input Analysis & Clarity Detection
|
||||
|
||||
```javascript
|
||||
const input = userInput.trim();
|
||||
const flags = parseFlags(userInput); // --priority
|
||||
|
||||
// Detect input type and clarity
|
||||
const isGitHubUrl = input.match(/github\.com\/[\w-]+\/[\w-]+\/issues\/\d+/);
|
||||
const isGitHubShort = input.match(/^#(\d+)$/);
|
||||
const hasStructure = input.match(/(expected|actual|affects|steps):/i);
|
||||
|
||||
// Clarity score: 0-3
|
||||
let clarityScore = 0;
|
||||
if (isGitHubUrl || isGitHubShort) clarityScore = 3; // GitHub = fully clear
|
||||
else if (hasStructure) clarityScore = 2; // Structured text = clear
|
||||
else if (input.length > 50) clarityScore = 1; // Long text = somewhat clear
|
||||
else clarityScore = 0; // Vague
|
||||
|
||||
let issueData = {};
|
||||
```
|
||||
|
||||
### Phase 2: Data Extraction (GitHub or Text)
|
||||
|
||||
```javascript
|
||||
if (isGitHubUrl || isGitHubShort) {
|
||||
// GitHub - fetch via gh CLI
|
||||
const result = Bash(`gh issue view ${extractIssueRef(input)} --json number,title,body,labels,url`);
|
||||
const gh = JSON.parse(result);
|
||||
issueData = {
|
||||
id: `GH-${gh.number}`,
|
||||
title: gh.title,
|
||||
source: 'github',
|
||||
source_url: gh.url,
|
||||
labels: gh.labels.map(l => l.name),
|
||||
context: gh.body?.substring(0, 500) || gh.title,
|
||||
...parseMarkdownBody(gh.body)
|
||||
};
|
||||
} else {
|
||||
// Text description
|
||||
issueData = {
|
||||
id: `ISS-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)}`,
|
||||
source: 'text',
|
||||
...parseTextDescription(input)
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: Lightweight Context Hint (Conditional)
|
||||
|
||||
```javascript
|
||||
// ACE search ONLY for medium clarity (1-2) AND missing components
|
||||
// Skip for: GitHub (has context), vague (needs clarification first)
|
||||
// Note: Deep exploration happens in /issue:plan, this is just a quick hint
|
||||
|
||||
if (clarityScore >= 1 && clarityScore <= 2 && !issueData.affected_components?.length) {
|
||||
const keywords = extractKeywords(issueData.context);
|
||||
|
||||
if (keywords.length >= 2) {
|
||||
try {
|
||||
const aceResult = mcp__ace-tool__search_context({
|
||||
project_root_path: process.cwd(),
|
||||
query: keywords.slice(0, 3).join(' ')
|
||||
});
|
||||
issueData.affected_components = aceResult.files?.slice(0, 3) || [];
|
||||
} catch {
|
||||
// ACE failure is non-blocking
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 4: Conditional Clarification (Only if Unclear)
|
||||
|
||||
```javascript
|
||||
// ONLY ask questions if clarity is low - simple open-ended prompt
|
||||
if (clarityScore < 2 && (!issueData.context || issueData.context.length < 20)) {
|
||||
const answer = AskUserQuestion({
|
||||
questions: [{
|
||||
question: 'Please describe the issue in more detail:',
|
||||
header: 'Clarify',
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: 'Provide details', description: 'Describe what, where, and expected behavior' }
|
||||
]
|
||||
}]
|
||||
});
|
||||
|
||||
// Use custom text input (via "Other")
|
||||
if (answer.customText) {
|
||||
issueData.context = answer.customText;
|
||||
issueData.title = answer.customText.split(/[.\n]/)[0].substring(0, 60);
|
||||
issueData.feedback = [{
|
||||
type: 'clarification',
|
||||
stage: 'new',
|
||||
content: answer.customText,
|
||||
created_at: new Date().toISOString()
|
||||
}];
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 5: GitHub Publishing Decision (Non-GitHub Sources)
|
||||
|
||||
```javascript
|
||||
// For non-GitHub sources, ask if user wants to publish to GitHub
|
||||
let publishToGitHub = false;
|
||||
|
||||
if (issueData.source !== 'github') {
|
||||
const publishAnswer = AskUserQuestion({
|
||||
questions: [{
|
||||
question: 'Would you like to publish this issue to GitHub?',
|
||||
header: 'Publish',
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: 'Yes, publish to GitHub', description: 'Create issue on GitHub and link it' },
|
||||
{ label: 'No, keep local only', description: 'Store as local issue without GitHub sync' }
|
||||
]
|
||||
}]
|
||||
});
|
||||
|
||||
publishToGitHub = publishAnswer.answers?.['Publish']?.includes('Yes');
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 6: Create Issue
|
||||
|
||||
**Summary Display:**
|
||||
- Show ID, title, source, affected files (if any)
|
||||
|
||||
**Confirmation** (only for vague inputs, clarityScore < 2):
|
||||
- Use `AskUserQuestion` to confirm before creation
|
||||
|
||||
**Issue Creation** (via CLI endpoint):
|
||||
```bash
|
||||
# Option 1: Pipe input (recommended for complex JSON - avoids shell escaping)
|
||||
echo '{"title":"...", "context":"...", "priority":3}' | ccw issue create
|
||||
|
||||
# Option 2: Heredoc (for multi-line JSON)
|
||||
ccw issue create << 'EOF'
|
||||
{"title":"...", "context":"含\"引号\"的内容", "priority":3}
|
||||
EOF
|
||||
|
||||
# Option 3: --data parameter (simple cases only)
|
||||
ccw issue create --data '{"title":"...", "priority":3}'
|
||||
```
|
||||
|
||||
**CLI Endpoint Features:**
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| Auto-increment ID | `ISS-YYYYMMDD-NNN` (e.g., `ISS-20251229-001`) |
|
||||
| Trailing newline | Proper JSONL format, no corruption |
|
||||
| JSON output | Returns created issue with all fields |
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Create issue via pipe (recommended)
|
||||
echo '{"title": "Login fails with special chars", "context": "500 error when password contains quotes", "priority": 2}' | ccw issue create
|
||||
|
||||
# Or with heredoc for complex JSON
|
||||
ccw issue create << 'EOF'
|
||||
{
|
||||
"title": "Login fails with special chars",
|
||||
"context": "500 error when password contains \"quotes\"",
|
||||
"priority": 2,
|
||||
"source": "text",
|
||||
"expected_behavior": "Login succeeds",
|
||||
"actual_behavior": "500 Internal Server Error"
|
||||
}
|
||||
EOF
|
||||
|
||||
# Output (JSON)
|
||||
{
|
||||
"id": "ISS-20251229-001",
|
||||
"title": "Login fails with special chars",
|
||||
"status": "registered",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
**GitHub Publishing** (if user opted in):
|
||||
```javascript
|
||||
// Step 1: Create local issue FIRST
|
||||
const localIssue = createLocalIssue(issueData); // ccw issue create
|
||||
|
||||
// Step 2: Publish to GitHub if requested
|
||||
if (publishToGitHub) {
|
||||
const ghResult = Bash(`gh issue create --title "${issueData.title}" --body "${issueData.context}"`);
|
||||
// Parse GitHub URL from output
|
||||
const ghUrl = ghResult.match(/https:\/\/github\.com\/[\w-]+\/[\w-]+\/issues\/\d+/)?.[0];
|
||||
const ghNumber = parseInt(ghUrl?.match(/\/issues\/(\d+)/)?.[1]);
|
||||
|
||||
if (ghNumber) {
|
||||
// Step 3: Update local issue with GitHub binding
|
||||
Bash(`ccw issue update ${localIssue.id} --github-url "${ghUrl}" --github-number ${ghNumber}`);
|
||||
// Or via pipe:
|
||||
// echo '{"github_url":"${ghUrl}","github_number":${ghNumber}}' | ccw issue update ${localIssue.id}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Workflow:**
|
||||
```
|
||||
1. Create local issue (ISS-YYYYMMDD-NNN) → stored in .workflow/issues.jsonl
|
||||
2. If publishToGitHub:
|
||||
a. gh issue create → returns GitHub URL
|
||||
b. Update local issue with github_url + github_number binding
|
||||
3. Both local and GitHub issues exist, linked together
|
||||
```
|
||||
|
||||
**Example with GitHub Publishing:**
|
||||
```bash
|
||||
# User creates text issue
|
||||
/issue:new "Login fails with special chars. Expected: success. Actual: 500"
|
||||
|
||||
# System asks: "Would you like to publish this issue to GitHub?"
|
||||
# User selects: "Yes, publish to GitHub"
|
||||
|
||||
# Output:
|
||||
# ✓ Local issue created: ISS-20251229-001
|
||||
# ✓ Published to GitHub: https://github.com/org/repo/issues/123
|
||||
# ✓ GitHub binding saved to local issue
|
||||
# → Next step: /issue:plan ISS-20251229-001
|
||||
|
||||
# Resulting issue JSON:
|
||||
{
|
||||
"id": "ISS-20251229-001",
|
||||
"title": "Login fails with special chars",
|
||||
"source": "text",
|
||||
"github_url": "https://github.com/org/repo/issues/123",
|
||||
"github_number": 123,
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
**Completion:**
|
||||
- Display created issue ID
|
||||
- Show GitHub URL (if published)
|
||||
- Show next step: `/issue:plan <id>`
|
||||
|
||||
## Execution Flow
|
||||
|
||||
```
|
||||
Phase 1: Input Analysis
|
||||
└─ Detect clarity score (GitHub URL? Structured text? Keywords?)
|
||||
|
||||
Phase 2: Data Extraction (branched by clarity)
|
||||
┌────────────┬─────────────────┬──────────────┐
|
||||
│ Score 3 │ Score 1-2 │ Score 0 │
|
||||
│ GitHub │ Text + ACE │ Vague │
|
||||
├────────────┼─────────────────┼──────────────┤
|
||||
│ gh CLI │ Parse struct │ AskQuestion │
|
||||
│ → parse │ + quick hint │ (1 question) │
|
||||
│ │ (3 files max) │ → feedback │
|
||||
└────────────┴─────────────────┴──────────────┘
|
||||
|
||||
Phase 3: GitHub Publishing Decision (non-GitHub only)
|
||||
├─ Source = github: Skip (already from GitHub)
|
||||
└─ Source ≠ github: AskUserQuestion
|
||||
├─ Yes → publishToGitHub = true
|
||||
└─ No → publishToGitHub = false
|
||||
|
||||
Phase 4: Create Issue
|
||||
├─ Score ≥ 2: Direct creation
|
||||
└─ Score < 2: Confirm first → Create
|
||||
└─ If publishToGitHub: gh issue create → link URL
|
||||
|
||||
Note: Deep exploration & lifecycle deferred to /issue:plan
|
||||
```
|
||||
|
||||
## Helper Functions
|
||||
|
||||
```javascript
|
||||
function extractKeywords(text) {
|
||||
const stopWords = new Set(['the', 'a', 'an', 'is', 'are', 'was', 'were', 'not', 'with']);
|
||||
return text
|
||||
.toLowerCase()
|
||||
.split(/\W+/)
|
||||
.filter(w => w.length > 3 && !stopWords.has(w))
|
||||
.slice(0, 5);
|
||||
}
|
||||
|
||||
function parseTextDescription(text) {
|
||||
const result = { title: '', context: '' };
|
||||
const sentences = text.split(/\.(?=\s|$)/);
|
||||
|
||||
result.title = sentences[0]?.trim().substring(0, 60) || 'Untitled';
|
||||
result.context = text.substring(0, 500);
|
||||
|
||||
// Extract structured fields if present
|
||||
const expected = text.match(/expected:?\s*([^.]+)/i);
|
||||
const actual = text.match(/actual:?\s*([^.]+)/i);
|
||||
const affects = text.match(/affects?:?\s*([^.]+)/i);
|
||||
|
||||
if (expected) result.expected_behavior = expected[1].trim();
|
||||
if (actual) result.actual_behavior = actual[1].trim();
|
||||
if (affects) {
|
||||
result.affected_components = affects[1].split(/[,\s]+/).filter(c => c.includes('/') || c.includes('.'));
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
function parseMarkdownBody(body) {
|
||||
if (!body) return {};
|
||||
const result = {};
|
||||
|
||||
const problem = body.match(/##?\s*(problem|description)[:\s]*([\s\S]*?)(?=##|$)/i);
|
||||
const expected = body.match(/##?\s*expected[:\s]*([\s\S]*?)(?=##|$)/i);
|
||||
const actual = body.match(/##?\s*actual[:\s]*([\s\S]*?)(?=##|$)/i);
|
||||
|
||||
if (problem) result.context = problem[2].trim().substring(0, 500);
|
||||
if (expected) result.expected_behavior = expected[2].trim();
|
||||
if (actual) result.actual_behavior = actual[2].trim();
|
||||
|
||||
return result;
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Clear Input (No Questions)
|
||||
|
||||
```bash
|
||||
/issue:new https://github.com/org/repo/issues/42
|
||||
# → Fetches, parses, creates immediately
|
||||
|
||||
/issue:new "Login fails with special chars. Expected: success. Actual: 500"
|
||||
# → Parses structure, creates immediately
|
||||
```
|
||||
|
||||
### Vague Input (1 Question)
|
||||
|
||||
```bash
|
||||
/issue:new "auth broken"
|
||||
# → Asks: "Input unclear. What is the issue about?"
|
||||
# → User provides details → saved to feedback[]
|
||||
# → Creates issue
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/issue:plan` - Plan solution for issue
|
||||
|
||||
@@ -1,335 +0,0 @@
|
||||
---
|
||||
name: plan
|
||||
description: Batch plan issue resolution using issue-plan-agent (explore + plan closed-loop)
|
||||
argument-hint: "[-y|--yes] --all-pending <issue-id>[,<issue-id>,...] [--batch-size 3]"
|
||||
allowed-tools: TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*), Bash(*), Read(*), Write(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-bind solutions without confirmation, use recommended settings.
|
||||
|
||||
# Issue Plan Command (/issue:plan)
|
||||
|
||||
## Overview
|
||||
|
||||
Unified planning command using **issue-plan-agent** that combines exploration and planning into a single closed-loop workflow.
|
||||
|
||||
**Behavior:**
|
||||
- Single solution per issue → auto-bind
|
||||
- Multiple solutions → return for user selection
|
||||
- Agent handles file generation
|
||||
|
||||
## Core Guidelines
|
||||
|
||||
**⚠️ Data Access Principle**: Issues and solutions files can grow very large. To avoid context overflow:
|
||||
|
||||
| Operation | Correct | Incorrect |
|
||||
|-----------|---------|-----------|
|
||||
| List issues (brief) | `ccw issue list --status pending --brief` | `Read('issues.jsonl')` |
|
||||
| Read issue details | `ccw issue status <id> --json` | `Read('issues.jsonl')` |
|
||||
| Update status | `ccw issue update <id> --status ...` | Direct file edit |
|
||||
| Bind solution | `ccw issue bind <id> <sol-id>` | Direct file edit |
|
||||
|
||||
**Output Options**:
|
||||
- `--brief`: JSON with minimal fields (id, title, status, priority, tags)
|
||||
- `--json`: Full JSON (agent use only)
|
||||
|
||||
**Orchestration vs Execution**:
|
||||
- **Command (orchestrator)**: Use `--brief` for minimal context
|
||||
- **Agent (executor)**: Fetch full details → `ccw issue status <id> --json`
|
||||
|
||||
**ALWAYS** use CLI commands for CRUD operations. **NEVER** read entire `issues.jsonl` or `solutions/*.jsonl` directly.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/issue:plan [<issue-id>[,<issue-id>,...]] [FLAGS]
|
||||
|
||||
# Examples
|
||||
/issue:plan # Default: --all-pending
|
||||
/issue:plan GH-123 # Single issue
|
||||
/issue:plan GH-123,GH-124,GH-125 # Batch (up to 3)
|
||||
/issue:plan --all-pending # All pending issues (explicit)
|
||||
|
||||
# Flags
|
||||
--batch-size <n> Max issues per agent batch (default: 3)
|
||||
```
|
||||
|
||||
## Execution Process
|
||||
|
||||
```
|
||||
Phase 1: Issue Loading & Intelligent Grouping
|
||||
├─ Parse input (single, comma-separated, or --all-pending)
|
||||
├─ Fetch issue metadata (ID, title, tags)
|
||||
├─ Validate issues exist (create if needed)
|
||||
└─ Intelligent grouping via Gemini (semantic similarity, max 3 per batch)
|
||||
|
||||
Phase 2: Unified Explore + Plan (issue-plan-agent)
|
||||
├─ Launch issue-plan-agent per batch
|
||||
├─ Agent performs:
|
||||
│ ├─ ACE semantic search for each issue
|
||||
│ ├─ Codebase exploration (files, patterns, dependencies)
|
||||
│ ├─ Solution generation with task breakdown
|
||||
│ └─ Conflict detection across issues
|
||||
└─ Output: solution JSON per issue
|
||||
|
||||
Phase 3: Solution Registration & Binding
|
||||
├─ Append solutions to solutions/{issue-id}.jsonl
|
||||
├─ Single solution per issue → auto-bind
|
||||
├─ Multiple candidates → AskUserQuestion to select
|
||||
└─ Update issues.jsonl with bound_solution_id
|
||||
|
||||
Phase 4: Summary
|
||||
├─ Display bound solutions
|
||||
├─ Show task counts per issue
|
||||
└─ Display next steps (/issue:queue)
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
### Phase 1: Issue Loading (Brief Info Only)
|
||||
|
||||
```javascript
|
||||
const batchSize = flags.batchSize || 3;
|
||||
let issues = []; // {id, title, tags} - brief info for grouping only
|
||||
|
||||
// Default to --all-pending if no input provided
|
||||
const useAllPending = flags.allPending || !userInput || userInput.trim() === '';
|
||||
|
||||
if (useAllPending) {
|
||||
// Get pending issues with brief metadata via CLI
|
||||
const result = Bash(`ccw issue list --status pending,registered --json`).trim();
|
||||
const parsed = result ? JSON.parse(result) : [];
|
||||
issues = parsed.map(i => ({ id: i.id, title: i.title || '', tags: i.tags || [] }));
|
||||
|
||||
if (issues.length === 0) {
|
||||
console.log('No pending issues found.');
|
||||
return;
|
||||
}
|
||||
console.log(`Found ${issues.length} pending issues`);
|
||||
} else {
|
||||
// Parse comma-separated issue IDs, fetch brief metadata
|
||||
const ids = userInput.includes(',')
|
||||
? userInput.split(',').map(s => s.trim())
|
||||
: [userInput.trim()];
|
||||
|
||||
for (const id of ids) {
|
||||
Bash(`ccw issue init ${id} --title "Issue ${id}" 2>/dev/null || true`);
|
||||
const info = Bash(`ccw issue status ${id} --json`).trim();
|
||||
const parsed = info ? JSON.parse(info) : {};
|
||||
issues.push({ id, title: parsed.title || '', tags: parsed.tags || [] });
|
||||
}
|
||||
}
|
||||
// Note: Agent fetches full issue content via `ccw issue status <id> --json`
|
||||
|
||||
// Intelligent grouping: Analyze issues by title/tags, group semantically similar ones
|
||||
// Strategy: Same module/component, related bugs, feature clusters
|
||||
// Constraint: Max ${batchSize} issues per batch
|
||||
|
||||
console.log(`Processing ${issues.length} issues in ${batches.length} batch(es)`);
|
||||
|
||||
TodoWrite({
|
||||
todos: batches.map((_, i) => ({
|
||||
content: `Plan batch ${i+1}`,
|
||||
status: 'pending',
|
||||
activeForm: `Planning batch ${i+1}`
|
||||
}))
|
||||
});
|
||||
```
|
||||
|
||||
### Phase 2: Unified Explore + Plan (issue-plan-agent) - PARALLEL
|
||||
|
||||
```javascript
|
||||
Bash(`mkdir -p .workflow/issues/solutions`);
|
||||
const pendingSelections = []; // Collect multi-solution issues for user selection
|
||||
const agentResults = []; // Collect all agent results for conflict aggregation
|
||||
|
||||
// Build prompts for all batches
|
||||
const agentTasks = batches.map((batch, batchIndex) => {
|
||||
const issueList = batch.map(i => `- ${i.id}: ${i.title}${i.tags.length ? ` [${i.tags.join(', ')}]` : ''}`).join('\n');
|
||||
const batchIds = batch.map(i => i.id);
|
||||
|
||||
const issuePrompt = `
|
||||
## Plan Issues
|
||||
|
||||
**Issues** (grouped by similarity):
|
||||
${issueList}
|
||||
|
||||
**Project Root**: ${process.cwd()}
|
||||
|
||||
### Project Context (MANDATORY)
|
||||
1. Read: .workflow/project-tech.json (technology stack, architecture)
|
||||
2. Read: .workflow/project-guidelines.json (constraints and conventions)
|
||||
|
||||
### Workflow
|
||||
1. Fetch issue details: ccw issue status <id> --json
|
||||
2. **Analyze failure history** (if issue.feedback exists):
|
||||
- Extract failure details from issue.feedback (type='failure', stage='execute')
|
||||
- Parse error_type, message, task_id, solution_id from content JSON
|
||||
- Identify failure patterns: repeated errors, root causes, blockers
|
||||
- **Constraint**: Avoid repeating failed approaches
|
||||
3. Load project context files
|
||||
4. Explore codebase (ACE semantic search)
|
||||
5. Plan solution with tasks (schema: solution-schema.json)
|
||||
- **If previous solution failed**: Reference failure analysis in solution.approach
|
||||
- Add explicit verification steps to prevent same failure mode
|
||||
6. **If github_url exists**: Add final task to comment on GitHub issue
|
||||
7. Write solution to: .workflow/issues/solutions/{issue-id}.jsonl
|
||||
8. **CRITICAL - Binding Decision**:
|
||||
- Single solution → **MUST execute**: ccw issue bind <issue-id> <solution-id>
|
||||
- Multiple solutions → Return pending_selection only (no bind)
|
||||
|
||||
### Failure-Aware Planning Rules
|
||||
- **Extract failure patterns**: Parse issue.feedback where type='failure' and stage='execute'
|
||||
- **Identify root causes**: Analyze error_type (test_failure, compilation, timeout, etc.)
|
||||
- **Design alternative approach**: Create solution that addresses root cause
|
||||
- **Add prevention steps**: Include explicit verification to catch same error earlier
|
||||
- **Document lessons**: Reference previous failures in solution.approach
|
||||
|
||||
### Rules
|
||||
- Solution ID format: SOL-{issue-id}-{uid} (uid: 4 random alphanumeric chars, e.g., a7x9)
|
||||
- Single solution per issue → auto-bind via ccw issue bind
|
||||
- Multiple solutions → register only, return pending_selection
|
||||
- Tasks must have quantified acceptance.criteria
|
||||
|
||||
### Return Summary
|
||||
{"bound":[{"issue_id":"...","solution_id":"...","task_count":N}],"pending_selection":[{"issue_id":"...","solutions":[{"id":"...","description":"...","task_count":N}]}]}
|
||||
`;
|
||||
|
||||
return { batchIndex, batchIds, issuePrompt, batch };
|
||||
});
|
||||
|
||||
// Launch agents in parallel (max 10 concurrent)
|
||||
const MAX_PARALLEL = 10;
|
||||
for (let i = 0; i < agentTasks.length; i += MAX_PARALLEL) {
|
||||
const chunk = agentTasks.slice(i, i + MAX_PARALLEL);
|
||||
const taskIds = [];
|
||||
|
||||
// Launch chunk in parallel
|
||||
for (const { batchIndex, batchIds, issuePrompt, batch } of chunk) {
|
||||
updateTodo(`Plan batch ${batchIndex + 1}`, 'in_progress');
|
||||
const taskId = Task(
|
||||
subagent_type="issue-plan-agent",
|
||||
run_in_background=true,
|
||||
description=`Explore & plan ${batch.length} issues: ${batchIds.join(', ')}`,
|
||||
prompt=issuePrompt
|
||||
);
|
||||
taskIds.push({ taskId, batchIndex });
|
||||
}
|
||||
|
||||
console.log(`Launched ${taskIds.length} agents (batch ${i/MAX_PARALLEL + 1}/${Math.ceil(agentTasks.length/MAX_PARALLEL)})...`);
|
||||
|
||||
// Collect results from this chunk
|
||||
for (const { taskId, batchIndex } of taskIds) {
|
||||
const result = TaskOutput(task_id=taskId, block=true);
|
||||
|
||||
// Extract JSON from potential markdown code blocks (agent may wrap in ```json...```)
|
||||
const jsonText = extractJsonFromMarkdown(result);
|
||||
let summary;
|
||||
try {
|
||||
summary = JSON.parse(jsonText);
|
||||
} catch (e) {
|
||||
console.log(`⚠ Batch ${batchIndex + 1}: Failed to parse agent result, skipping`);
|
||||
updateTodo(`Plan batch ${batchIndex + 1}`, 'completed');
|
||||
continue;
|
||||
}
|
||||
agentResults.push(summary); // Store for Phase 3 conflict aggregation
|
||||
|
||||
// Verify binding for bound issues (agent should have executed bind)
|
||||
for (const item of summary.bound || []) {
|
||||
const status = JSON.parse(Bash(`ccw issue status ${item.issue_id} --json`).trim());
|
||||
if (status.bound_solution_id === item.solution_id) {
|
||||
console.log(`✓ ${item.issue_id}: ${item.solution_id} (${item.task_count} tasks)`);
|
||||
} else {
|
||||
// Fallback: agent failed to bind, execute here
|
||||
Bash(`ccw issue bind ${item.issue_id} ${item.solution_id}`);
|
||||
console.log(`✓ ${item.issue_id}: ${item.solution_id} (${item.task_count} tasks) [recovered]`);
|
||||
}
|
||||
}
|
||||
// Collect pending selections for Phase 3
|
||||
for (const pending of summary.pending_selection || []) {
|
||||
pendingSelections.push(pending);
|
||||
}
|
||||
updateTodo(`Plan batch ${batchIndex + 1}`, 'completed');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: Solution Selection (if pending)
|
||||
|
||||
```javascript
|
||||
// Handle multi-solution issues
|
||||
for (const pending of pendingSelections) {
|
||||
if (pending.solutions.length === 0) continue;
|
||||
|
||||
const options = pending.solutions.slice(0, 4).map(sol => ({
|
||||
label: `${sol.id} (${sol.task_count} tasks)`,
|
||||
description: sol.description || sol.approach || 'No description'
|
||||
}));
|
||||
|
||||
const answer = AskUserQuestion({
|
||||
questions: [{
|
||||
question: `Issue ${pending.issue_id}: which solution to bind?`,
|
||||
header: pending.issue_id,
|
||||
options: options,
|
||||
multiSelect: false
|
||||
}]
|
||||
});
|
||||
|
||||
const selected = answer[Object.keys(answer)[0]];
|
||||
if (!selected || selected === 'Other') continue;
|
||||
|
||||
const solId = selected.split(' ')[0];
|
||||
Bash(`ccw issue bind ${pending.issue_id} ${solId}`);
|
||||
console.log(`✓ ${pending.issue_id}: ${solId} bound`);
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 4: Summary
|
||||
|
||||
```javascript
|
||||
// Count planned issues via CLI
|
||||
const planned = JSON.parse(Bash(`ccw issue list --status planned --brief`) || '[]');
|
||||
const plannedCount = planned.length;
|
||||
|
||||
console.log(`
|
||||
## Done: ${issues.length} issues → ${plannedCount} planned
|
||||
|
||||
Next: \`/issue:queue\` → \`/issue:execute\`
|
||||
`);
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| Issue not found | Auto-create in issues.jsonl |
|
||||
| ACE search fails | Agent falls back to ripgrep |
|
||||
| No solutions generated | Display error, suggest manual planning |
|
||||
| User cancels selection | Skip issue, continue with others |
|
||||
| File conflicts | Agent detects and suggests resolution order |
|
||||
|
||||
## Bash Compatibility
|
||||
|
||||
**Avoid**: `$(cmd)`, `$var`, `for` loops — will be escaped incorrectly
|
||||
|
||||
**Use**: Simple commands + `&&` chains, quote comma params `"pending,registered"`
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before completing, verify:
|
||||
|
||||
- [ ] All input issues have solutions in `solutions/{issue-id}.jsonl`
|
||||
- [ ] Single solution issues are auto-bound (`bound_solution_id` set)
|
||||
- [ ] Multi-solution issues returned in `pending_selection` for user choice
|
||||
- [ ] Each solution has executable tasks with `modification_points`
|
||||
- [ ] Task acceptance criteria are quantified (not vague)
|
||||
- [ ] Conflicts detected and reported (if multiple issues touch same files)
|
||||
- [ ] Issue status updated to `planned` after binding
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/issue:queue` - Form execution queue from bound solutions
|
||||
- `ccw issue list` - List all issues
|
||||
- `ccw issue status` - View issue and solution details
|
||||
@@ -1,445 +0,0 @@
|
||||
---
|
||||
name: queue
|
||||
description: Form execution queue from bound solutions using issue-queue-agent (solution-level)
|
||||
argument-hint: "[-y|--yes] [--queues <n>] [--issue <id>]"
|
||||
allowed-tools: TodoWrite(*), Task(*), Bash(*), Read(*), Write(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-confirm queue formation, use recommended conflict resolutions.
|
||||
|
||||
# Issue Queue Command (/issue:queue)
|
||||
|
||||
## Overview
|
||||
|
||||
Queue formation command using **issue-queue-agent** that analyzes all bound solutions, resolves **inter-solution** conflicts, and creates an ordered execution queue at **solution level**.
|
||||
|
||||
**Design Principle**: Queue items are **solutions**, not individual tasks. Each executor receives a complete solution with all its tasks.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
- **Agent-driven**: issue-queue-agent handles all ordering logic
|
||||
- **Solution-level granularity**: Queue items are solutions, not tasks
|
||||
- **Conflict clarification**: High-severity conflicts prompt user decision
|
||||
- Semantic priority calculation per solution (0.0-1.0)
|
||||
- Parallel/Sequential group assignment for solutions
|
||||
|
||||
## Core Guidelines
|
||||
|
||||
**⚠️ Data Access Principle**: Issues and queue files can grow very large. To avoid context overflow:
|
||||
|
||||
| Operation | Correct | Incorrect |
|
||||
|-----------|---------|-----------|
|
||||
| List issues (brief) | `ccw issue list --status planned --brief` | `Read('issues.jsonl')` |
|
||||
| **Batch solutions (NEW)** | `ccw issue solutions --status planned --brief` | Loop `ccw issue solution <id>` |
|
||||
| List queue (brief) | `ccw issue queue --brief` | `Read('queues/*.json')` |
|
||||
| Read issue details | `ccw issue status <id> --json` | `Read('issues.jsonl')` |
|
||||
| Get next item | `ccw issue next --json` | `Read('queues/*.json')` |
|
||||
| Update status | `ccw issue update <id> --status ...` | Direct file edit |
|
||||
| Sync from queue | `ccw issue update --from-queue` | Direct file edit |
|
||||
| Read solution (single) | `ccw issue solution <id> --brief` | `Read('solutions/*.jsonl')` |
|
||||
|
||||
**Output Options**:
|
||||
- `--brief`: JSON with minimal fields (id, status, counts)
|
||||
- `--json`: Full JSON (agent use only)
|
||||
|
||||
**Orchestration vs Execution**:
|
||||
- **Command (orchestrator)**: Use `--brief` for minimal context
|
||||
- **Agent (executor)**: Fetch full details → `ccw issue status <id> --json`
|
||||
|
||||
**ALWAYS** use CLI commands for CRUD operations. **NEVER** read entire `issues.jsonl` or `queues/*.json` directly.
|
||||
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/issue:queue [FLAGS]
|
||||
|
||||
# Examples
|
||||
/issue:queue # Form NEW queue from all bound solutions
|
||||
/issue:queue --queues 3 # Form 3 parallel queues (solutions distributed)
|
||||
/issue:queue --issue GH-123 # Form queue for specific issue only
|
||||
/issue:queue --append GH-124 # Append to active queue
|
||||
/issue:queue --list # List all queues (history)
|
||||
/issue:queue --switch QUE-xxx # Switch active queue
|
||||
/issue:queue --archive # Archive completed active queue
|
||||
|
||||
# Flags
|
||||
--queues <n> Number of parallel queues (default: 1)
|
||||
--issue <id> Form queue for specific issue only
|
||||
--append <id> Append issue to active queue (don't create new)
|
||||
--force Skip active queue check, always create new queue
|
||||
|
||||
# CLI subcommands (ccw issue queue ...)
|
||||
ccw issue queue list List all queues with status
|
||||
ccw issue queue add <issue-id> Add issue to queue (interactive if active queue exists)
|
||||
ccw issue queue add <issue-id> -f Add to new queue without prompt (force)
|
||||
ccw issue queue merge <src> --queue <target> Merge source queue into target queue
|
||||
ccw issue queue switch <queue-id> Switch active queue
|
||||
ccw issue queue archive Archive current queue
|
||||
ccw issue queue delete <queue-id> Delete queue from history
|
||||
```
|
||||
|
||||
## Execution Process
|
||||
|
||||
```
|
||||
Phase 1: Solution Loading & Distribution
|
||||
├─ Load issues.jsonl, filter by status='planned' + bound_solution_id
|
||||
├─ Read solutions/{issue-id}.jsonl, find bound solution
|
||||
├─ Extract files_touched from task modification_points
|
||||
├─ Build solution objects array
|
||||
└─ If --queues > 1: Partition solutions into N groups (minimize cross-group file conflicts)
|
||||
|
||||
Phase 2-4: Agent-Driven Queue Formation (issue-queue-agent)
|
||||
├─ Generate N queue IDs (QUE-xxx-1, QUE-xxx-2, ...)
|
||||
├─ If --queues == 1: Launch single issue-queue-agent
|
||||
├─ If --queues > 1: Launch N issue-queue-agents IN PARALLEL
|
||||
├─ Each agent performs:
|
||||
│ ├─ Conflict analysis (5 types via Gemini CLI)
|
||||
│ ├─ Build dependency DAG from conflicts
|
||||
│ ├─ Calculate semantic priority per solution
|
||||
│ └─ Assign execution groups (parallel/sequential)
|
||||
└─ Each agent writes: queue JSON + index update (NOT active yet)
|
||||
|
||||
Phase 5: Conflict Clarification (if needed)
|
||||
├─ Collect `clarifications` arrays from all agents
|
||||
├─ If clarifications exist → AskUserQuestion (batched)
|
||||
├─ Pass user decisions back to respective agents (resume)
|
||||
└─ Agents update queues with resolved conflicts
|
||||
|
||||
Phase 6: Status Update & Summary
|
||||
├─ Update issue statuses to 'queued'
|
||||
└─ Display new queue summary (N queues)
|
||||
|
||||
Phase 7: Active Queue Check & Decision (REQUIRED)
|
||||
├─ Read queue index: ccw issue queue list --brief
|
||||
├─ Get generated queue ID from agent output
|
||||
├─ If NO active queue exists:
|
||||
│ ├─ Set generated queue as active_queue_id
|
||||
│ ├─ Update index.json
|
||||
│ └─ Display: "Queue created and activated"
|
||||
│
|
||||
└─ If active queue exists with items:
|
||||
├─ Display both queues to user
|
||||
├─ Use AskUserQuestion to prompt:
|
||||
│ ├─ "Use new queue (keep existing)" → Set new as active, keep old inactive
|
||||
│ ├─ "Merge: add new items to existing" → Merge new → existing, delete new
|
||||
│ ├─ "Merge: add existing items to new" → Merge existing → new, archive old
|
||||
│ └─ "Cancel" → Delete new queue, keep existing active
|
||||
└─ Execute chosen action
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
### Phase 1: Solution Loading & Distribution
|
||||
|
||||
**Data Loading:**
|
||||
- Use `ccw issue solutions --status planned --brief` to get all planned issues with solutions in **one call**
|
||||
- Returns: Array of `{ issue_id, solution_id, is_bound, task_count, files_touched[], priority }`
|
||||
- If no bound solutions found → display message, suggest `/issue:plan`
|
||||
|
||||
**Build Solution Objects:**
|
||||
```javascript
|
||||
// Single CLI call replaces N individual queries
|
||||
const result = Bash(`ccw issue solutions --status planned --brief`).trim();
|
||||
const solutions = result ? JSON.parse(result) : [];
|
||||
|
||||
if (solutions.length === 0) {
|
||||
console.log('No bound solutions found. Run /issue:plan first.');
|
||||
return;
|
||||
}
|
||||
|
||||
// solutions already in correct format:
|
||||
// { issue_id, solution_id, is_bound, task_count, files_touched[], priority }
|
||||
```
|
||||
|
||||
**Multi-Queue Distribution** (if `--queues > 1`):
|
||||
- Use `files_touched` from brief output for partitioning
|
||||
- Group solutions with overlapping files into same queue
|
||||
|
||||
**Output:** Array of solution objects (or N arrays if multi-queue)
|
||||
|
||||
### Phase 2-4: Agent-Driven Queue Formation
|
||||
|
||||
**Generate Queue IDs** (command layer, pass to agent):
|
||||
```javascript
|
||||
const timestamp = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
|
||||
const numQueues = args.queues || 1;
|
||||
const queueIds = numQueues === 1
|
||||
? [`QUE-${timestamp}`]
|
||||
: Array.from({length: numQueues}, (_, i) => `QUE-${timestamp}-${i + 1}`);
|
||||
```
|
||||
|
||||
**Agent Prompt** (same for each queue, with assigned solutions):
|
||||
```
|
||||
## Order Solutions into Execution Queue
|
||||
|
||||
**Queue ID**: ${queueId}
|
||||
**Solutions**: ${solutions.length} from ${issues.length} issues
|
||||
**Project Root**: ${cwd}
|
||||
**Queue Index**: ${queueIndex} of ${numQueues}
|
||||
|
||||
### Input
|
||||
${JSON.stringify(solutions)}
|
||||
// Each object: { issue_id, solution_id, task_count, files_touched[], priority }
|
||||
|
||||
### Workflow
|
||||
|
||||
Step 1: Build dependency graph from solutions (nodes=solutions, edges=file conflicts via files_touched)
|
||||
Step 2: Use Gemini CLI for conflict analysis (5 types: file, API, data, dependency, architecture)
|
||||
Step 3: For high-severity conflicts without clear resolution → add to `clarifications`
|
||||
Step 4: Calculate semantic priority (base from issue priority + task_count boost)
|
||||
Step 5: Assign execution groups: P* (parallel, no overlaps) / S* (sequential, shared files)
|
||||
Step 6: Write queue JSON + update index
|
||||
|
||||
### Output Requirements
|
||||
|
||||
**Write files** (exactly 2):
|
||||
- `.workflow/issues/queues/${queueId}.json` - Full queue with solutions, conflicts, groups
|
||||
- `.workflow/issues/queues/index.json` - Update with new queue entry
|
||||
|
||||
**Return JSON**:
|
||||
\`\`\`json
|
||||
{
|
||||
"queue_id": "${queueId}",
|
||||
"total_solutions": N,
|
||||
"total_tasks": N,
|
||||
"execution_groups": [{"id": "P1", "type": "parallel", "count": N}],
|
||||
"issues_queued": ["ISS-xxx"],
|
||||
"clarifications": [{"conflict_id": "CFT-1", "question": "...", "options": [...]}]
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
### Rules
|
||||
- Solution granularity (NOT individual tasks)
|
||||
- Queue Item ID format: S-1, S-2, S-3, ...
|
||||
- Use provided Queue ID (do NOT generate new)
|
||||
- `clarifications` only present if high-severity unresolved conflicts exist
|
||||
- Use `files_touched` from input (already extracted by orchestrator)
|
||||
|
||||
### Done Criteria
|
||||
- [ ] Queue JSON written with all solutions ordered
|
||||
- [ ] Index updated with active_queue_id
|
||||
- [ ] No circular dependencies
|
||||
- [ ] Parallel groups have no file overlaps
|
||||
- [ ] Return JSON matches required shape
|
||||
```
|
||||
|
||||
**Launch Agents** (parallel if multi-queue):
|
||||
```javascript
|
||||
const numQueues = args.queues || 1;
|
||||
|
||||
if (numQueues === 1) {
|
||||
// Single queue: single agent call
|
||||
const result = Task(
|
||||
subagent_type="issue-queue-agent",
|
||||
prompt=buildPrompt(queueIds[0], solutions),
|
||||
description=`Order ${solutions.length} solutions`
|
||||
);
|
||||
} else {
|
||||
// Multi-queue: parallel agent calls (single message with N Task calls)
|
||||
const agentPromises = solutionGroups.map((group, i) =>
|
||||
Task(
|
||||
subagent_type="issue-queue-agent",
|
||||
prompt=buildPrompt(queueIds[i], group, i + 1, numQueues),
|
||||
description=`Queue ${i + 1}/${numQueues}: ${group.length} solutions`
|
||||
)
|
||||
);
|
||||
// All agents launched in parallel via single message with multiple Task tool calls
|
||||
}
|
||||
```
|
||||
|
||||
**Multi-Queue Index Update:**
|
||||
- First queue sets `active_queue_id`
|
||||
- All queues added to `queues` array with `queue_group` field linking them
|
||||
|
||||
### Phase 5: Conflict Clarification
|
||||
|
||||
**Collect Agent Results** (multi-queue):
|
||||
```javascript
|
||||
// Collect clarifications from all agents
|
||||
const allClarifications = results.flatMap((r, i) =>
|
||||
(r.clarifications || []).map(c => ({ ...c, queue_id: queueIds[i], agent_id: agentIds[i] }))
|
||||
);
|
||||
```
|
||||
|
||||
**Check Agent Return:**
|
||||
- Parse agent result JSON (or all results if multi-queue)
|
||||
- If any `clarifications` array exists and non-empty → user decision required
|
||||
|
||||
**Clarification Flow:**
|
||||
```javascript
|
||||
if (allClarifications.length > 0) {
|
||||
for (const clarification of allClarifications) {
|
||||
// Present to user via AskUserQuestion
|
||||
const answer = AskUserQuestion({
|
||||
questions: [{
|
||||
question: `[${clarification.queue_id}] ${clarification.question}`,
|
||||
header: clarification.conflict_id,
|
||||
options: clarification.options,
|
||||
multiSelect: false
|
||||
}]
|
||||
});
|
||||
|
||||
// Resume respective agent with user decision
|
||||
Task(
|
||||
subagent_type="issue-queue-agent",
|
||||
resume=clarification.agent_id,
|
||||
prompt=`Conflict ${clarification.conflict_id} resolved: ${answer.selected}`
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 6: Status Update & Summary
|
||||
|
||||
**Status Update** (MUST use CLI command, NOT direct file operations):
|
||||
|
||||
```bash
|
||||
# Option 1: Batch update from queue (recommended)
|
||||
ccw issue update --from-queue [queue-id] --json
|
||||
ccw issue update --from-queue --json # Use active queue
|
||||
ccw issue update --from-queue QUE-xxx --json # Use specific queue
|
||||
|
||||
# Option 2: Individual issue update
|
||||
ccw issue update <issue-id> --status queued
|
||||
```
|
||||
|
||||
**⚠️ IMPORTANT**: Do NOT directly modify `issues.jsonl`. Always use CLI command to ensure proper validation and history tracking.
|
||||
|
||||
**Output** (JSON):
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"queue_id": "QUE-xxx",
|
||||
"queued": ["ISS-001", "ISS-002"],
|
||||
"queued_count": 2,
|
||||
"unplanned": ["ISS-003"],
|
||||
"unplanned_count": 1
|
||||
}
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- Updates issues in queue to `status: 'queued'` (skips already queued/executing/completed)
|
||||
- Identifies planned issues with `bound_solution_id` NOT in queue → `unplanned` array
|
||||
- Optional `queue-id`: defaults to active queue if omitted
|
||||
|
||||
**Summary Output:**
|
||||
- Display queue ID, solution count, task count
|
||||
- Show unplanned issues (planned but NOT in queue)
|
||||
- Show next step: `/issue:execute`
|
||||
|
||||
### Phase 7: Active Queue Check & Decision
|
||||
|
||||
**After agent completes Phase 1-6, check for active queue:**
|
||||
|
||||
```bash
|
||||
ccw issue queue list --brief
|
||||
```
|
||||
|
||||
**Decision:**
|
||||
- If `active_queue_id` is null → `ccw issue queue switch <new-queue-id>` (activate new queue)
|
||||
- If active queue exists → Use **AskUserQuestion** to prompt user
|
||||
|
||||
**AskUserQuestion:**
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Active queue exists. How would you like to proceed?",
|
||||
header: "Queue Action",
|
||||
options: [
|
||||
{ label: "Merge into existing queue", description: "Add new items to active queue, delete new queue" },
|
||||
{ label: "Use new queue", description: "Switch to new queue, keep existing in history" },
|
||||
{ label: "Cancel", description: "Delete new queue, keep existing active" }
|
||||
],
|
||||
multiSelect: false
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
**Action Commands:**
|
||||
|
||||
| User Choice | Commands |
|
||||
|-------------|----------|
|
||||
| **Merge into existing** | `ccw issue queue merge <new-queue-id> --queue <active-queue-id>` then `ccw issue queue delete <new-queue-id>` |
|
||||
| **Use new queue** | `ccw issue queue switch <new-queue-id>` |
|
||||
| **Cancel** | `ccw issue queue delete <new-queue-id>` |
|
||||
|
||||
## Storage Structure (Queue History)
|
||||
|
||||
```
|
||||
.workflow/issues/
|
||||
├── issues.jsonl # All issues (one per line)
|
||||
├── queues/ # Queue history directory
|
||||
│ ├── index.json # Queue index (active + history)
|
||||
│ ├── {queue-id}.json # Individual queue files
|
||||
│ └── ...
|
||||
└── solutions/
|
||||
├── {issue-id}.jsonl # Solutions for issue
|
||||
└── ...
|
||||
```
|
||||
|
||||
### Queue Index Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"active_queue_id": "QUE-20251227-143000",
|
||||
"active_queue_group": "QGR-20251227-143000",
|
||||
"queues": [
|
||||
{
|
||||
"id": "QUE-20251227-143000-1",
|
||||
"queue_group": "QGR-20251227-143000",
|
||||
"queue_index": 1,
|
||||
"total_queues": 3,
|
||||
"status": "active",
|
||||
"issue_ids": ["ISS-xxx", "ISS-yyy"],
|
||||
"total_solutions": 3,
|
||||
"completed_solutions": 1,
|
||||
"created_at": "2025-12-27T14:30:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Multi-Queue Fields:**
|
||||
- `queue_group`: Links queues created in same batch (format: `QGR-{timestamp}`)
|
||||
- `queue_index`: Position in group (1-based)
|
||||
- `total_queues`: Total queues in group
|
||||
- `active_queue_group`: Current active group (for multi-queue execution)
|
||||
|
||||
**Note**: Queue file schema is produced by `issue-queue-agent`. See agent documentation for details.
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| No bound solutions | Display message, suggest /issue:plan |
|
||||
| Circular dependency | List cycles, abort queue formation |
|
||||
| High-severity conflict | Return `clarifications`, prompt user decision |
|
||||
| User cancels clarification | Abort queue formation |
|
||||
| **index.json not updated** | Auto-fix: Set active_queue_id to new queue |
|
||||
| **Queue file missing solutions** | Abort with error, agent must regenerate |
|
||||
| **User cancels queue add** | Display message, return without changes |
|
||||
| **Merge with empty source** | Skip merge, display warning |
|
||||
| **All items duplicate** | Skip merge, display "All items already exist" |
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before completing, verify:
|
||||
|
||||
- [ ] All planned issues with `bound_solution_id` are included
|
||||
- [ ] Queue JSON written to `queues/{queue-id}.json` (N files if multi-queue)
|
||||
- [ ] Index updated in `queues/index.json` with `active_queue_id`
|
||||
- [ ] Multi-queue: All queues share same `queue_group`
|
||||
- [ ] No circular dependencies in solution DAG
|
||||
- [ ] All conflicts resolved (auto or via user clarification)
|
||||
- [ ] Parallel groups have no file overlaps
|
||||
- [ ] Cross-queue: No file overlaps between queues
|
||||
- [ ] Issue statuses updated to `queued`
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/issue:execute` - Execute queue with codex
|
||||
- `ccw issue queue list` - View current queue
|
||||
- `ccw issue update --from-queue [queue-id]` - Sync issue statuses from queue
|
||||
@@ -1,383 +0,0 @@
|
||||
---
|
||||
name: 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
|
||||
argument-hint: "[optional: session description]"
|
||||
allowed-tools: mcp__ccw-tools__core_memory(*), Read(*)
|
||||
examples:
|
||||
- /memory:compact
|
||||
- /memory:compact "completed core-memory module"
|
||||
---
|
||||
|
||||
# Memory Compact Command (/memory:compact)
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The `memory:compact` command **compresses current session working memory** into structured text optimized for **session recovery**, extracts critical information, and saves it to persistent storage via MCP `core_memory` tool.
|
||||
|
||||
**Core Philosophy**:
|
||||
- **Session Recovery First**: Capture everything needed to resume work seamlessly
|
||||
- **Minimize Re-exploration**: Include file paths, decisions, and state to avoid redundant analysis
|
||||
- **Preserve Train of Thought**: Keep notes and hypotheses for complex debugging
|
||||
- **Actionable State**: Record last action result and known issues
|
||||
|
||||
## 2. Parameters
|
||||
|
||||
- `"session description"` (Optional): Session description to supplement objective
|
||||
- Example: "completed core-memory module"
|
||||
- Example: "debugging JWT refresh - suspected memory leak"
|
||||
|
||||
## 3. Structured Output Format
|
||||
|
||||
```markdown
|
||||
## Session ID
|
||||
[WFS-ID if workflow session active, otherwise (none)]
|
||||
|
||||
## Project Root
|
||||
[Absolute path to project root, e.g., D:\Claude_dms3]
|
||||
|
||||
## Objective
|
||||
[High-level goal - the "North Star" of this session]
|
||||
|
||||
## Execution Plan
|
||||
[CRITICAL: Embed the LATEST plan in its COMPLETE and DETAILED form]
|
||||
|
||||
### Source: [workflow | todo | user-stated | inferred]
|
||||
|
||||
<details>
|
||||
<summary>Full Execution Plan (Click to expand)</summary>
|
||||
|
||||
[PRESERVE COMPLETE PLAN VERBATIM - DO NOT SUMMARIZE]
|
||||
- ALL phases, tasks, subtasks
|
||||
- ALL file paths (absolute)
|
||||
- ALL dependencies and prerequisites
|
||||
- ALL acceptance criteria
|
||||
- ALL status markers ([x] done, [ ] pending)
|
||||
- ALL notes and context
|
||||
|
||||
Example:
|
||||
## Phase 1: Setup
|
||||
- [x] Initialize project structure
|
||||
- Created D:\Claude_dms3\src\core\index.ts
|
||||
- Added dependencies: lodash, zod
|
||||
- [ ] Configure TypeScript
|
||||
- Update tsconfig.json for strict mode
|
||||
|
||||
## Phase 2: Implementation
|
||||
- [ ] Implement core API
|
||||
- Target: D:\Claude_dms3\src\api\handler.ts
|
||||
- Dependencies: Phase 1 complete
|
||||
- Acceptance: All tests pass
|
||||
|
||||
</details>
|
||||
|
||||
## Working Files (Modified)
|
||||
[Absolute paths to actively modified files]
|
||||
- D:\Claude_dms3\src\file1.ts (role: main implementation)
|
||||
- D:\Claude_dms3\tests\file1.test.ts (role: unit tests)
|
||||
|
||||
## Reference Files (Read-Only)
|
||||
[Absolute paths to context files - NOT modified but essential for understanding]
|
||||
- D:\Claude_dms3\.claude\CLAUDE.md (role: project instructions)
|
||||
- D:\Claude_dms3\src\types\index.ts (role: type definitions)
|
||||
- D:\Claude_dms3\package.json (role: dependencies)
|
||||
|
||||
## Last Action
|
||||
[Last significant action and its result/status]
|
||||
|
||||
## Decisions
|
||||
- [Decision]: [Reasoning]
|
||||
- [Decision]: [Reasoning]
|
||||
|
||||
## Constraints
|
||||
- [User-specified limitation or preference]
|
||||
|
||||
## Dependencies
|
||||
- [Added/changed packages or environment requirements]
|
||||
|
||||
## Known Issues
|
||||
- [Deferred bug or edge case]
|
||||
|
||||
## Changes Made
|
||||
- [Completed modification]
|
||||
|
||||
## Pending
|
||||
- [Next step] or (none)
|
||||
|
||||
## Notes
|
||||
[Unstructured thoughts, hypotheses, debugging trails]
|
||||
```
|
||||
|
||||
## 4. Field Definitions
|
||||
|
||||
| Field | Purpose | Recovery Value |
|
||||
|-------|---------|----------------|
|
||||
| **Session ID** | Workflow session identifier (WFS-*) | Links memory to specific stateful task execution |
|
||||
| **Project Root** | Absolute path to project directory | Enables correct path resolution in new sessions |
|
||||
| **Objective** | Ultimate goal of the session | Prevents losing track of broader feature |
|
||||
| **Execution Plan** | Complete plan from any source (verbatim) | Preserves full planning context, avoids re-planning |
|
||||
| **Working Files** | Actively modified files (absolute paths) | Immediately identifies where work was happening |
|
||||
| **Reference Files** | Read-only context files (absolute paths) | Eliminates re-exploration for critical context |
|
||||
| **Last Action** | Final tool output/status | Immediate state awareness (success/failure) |
|
||||
| **Decisions** | Architectural choices + reasoning | Prevents re-litigating settled decisions |
|
||||
| **Constraints** | User-imposed limitations | Maintains personalized coding style |
|
||||
| **Dependencies** | Package/environment changes | Prevents missing dependency errors |
|
||||
| **Known Issues** | Deferred bugs/edge cases | Ensures issues aren't forgotten |
|
||||
| **Changes Made** | Completed modifications | Clear record of what was done |
|
||||
| **Pending** | Next steps | Immediate action items |
|
||||
| **Notes** | Hypotheses, debugging trails | Preserves "train of thought" |
|
||||
|
||||
## 5. Execution Flow
|
||||
|
||||
### Step 1: Analyze Current Session
|
||||
|
||||
Extract the following from conversation history:
|
||||
|
||||
```javascript
|
||||
const sessionAnalysis = {
|
||||
sessionId: "", // WFS-* if workflow session active, null otherwise
|
||||
projectRoot: "", // Absolute path: D:\Claude_dms3
|
||||
objective: "", // High-level goal (1-2 sentences)
|
||||
executionPlan: {
|
||||
source: "workflow" | "todo" | "user-stated" | "inferred",
|
||||
content: "" // Full plan content - ALWAYS preserve COMPLETE and DETAILED form
|
||||
},
|
||||
workingFiles: [], // {absolutePath, role} - modified files
|
||||
referenceFiles: [], // {absolutePath, role} - read-only context files
|
||||
lastAction: "", // Last significant action + result
|
||||
decisions: [], // {decision, reasoning}
|
||||
constraints: [], // User-specified limitations
|
||||
dependencies: [], // Added/changed packages
|
||||
knownIssues: [], // Deferred bugs
|
||||
changesMade: [], // Completed modifications
|
||||
pending: [], // Next steps
|
||||
notes: "" // Unstructured thoughts
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Generate Structured Text
|
||||
|
||||
```javascript
|
||||
// Helper: Generate execution plan section
|
||||
const generateExecutionPlan = (plan) => {
|
||||
const sourceLabels = {
|
||||
'workflow': 'workflow (IMPL_PLAN.md)',
|
||||
'todo': 'todo (TodoWrite)',
|
||||
'user-stated': 'user-stated',
|
||||
'inferred': 'inferred'
|
||||
};
|
||||
|
||||
// CRITICAL: Preserve complete plan content verbatim - DO NOT summarize
|
||||
return `### Source: ${sourceLabels[plan.source] || plan.source}
|
||||
|
||||
<details>
|
||||
<summary>Full Execution Plan (Click to expand)</summary>
|
||||
|
||||
${plan.content}
|
||||
|
||||
</details>`;
|
||||
};
|
||||
|
||||
const structuredText = `## Session ID
|
||||
${sessionAnalysis.sessionId || '(none)'}
|
||||
|
||||
## Project Root
|
||||
${sessionAnalysis.projectRoot}
|
||||
|
||||
## Objective
|
||||
${sessionAnalysis.objective}
|
||||
|
||||
## Execution Plan
|
||||
${generateExecutionPlan(sessionAnalysis.executionPlan)}
|
||||
|
||||
## Working Files (Modified)
|
||||
${sessionAnalysis.workingFiles.map(f => `- ${f.absolutePath} (role: ${f.role})`).join('\n') || '(none)'}
|
||||
|
||||
## Reference Files (Read-Only)
|
||||
${sessionAnalysis.referenceFiles.map(f => `- ${f.absolutePath} (role: ${f.role})`).join('\n') || '(none)'}
|
||||
|
||||
## Last Action
|
||||
${sessionAnalysis.lastAction}
|
||||
|
||||
## Decisions
|
||||
${sessionAnalysis.decisions.map(d => `- ${d.decision}: ${d.reasoning}`).join('\n') || '(none)'}
|
||||
|
||||
## Constraints
|
||||
${sessionAnalysis.constraints.map(c => `- ${c}`).join('\n') || '(none)'}
|
||||
|
||||
## Dependencies
|
||||
${sessionAnalysis.dependencies.map(d => `- ${d}`).join('\n') || '(none)'}
|
||||
|
||||
## Known Issues
|
||||
${sessionAnalysis.knownIssues.map(i => `- ${i}`).join('\n') || '(none)'}
|
||||
|
||||
## Changes Made
|
||||
${sessionAnalysis.changesMade.map(c => `- ${c}`).join('\n') || '(none)'}
|
||||
|
||||
## Pending
|
||||
${sessionAnalysis.pending.length > 0
|
||||
? sessionAnalysis.pending.map(p => `- ${p}`).join('\n')
|
||||
: '(none)'}
|
||||
|
||||
## Notes
|
||||
${sessionAnalysis.notes || '(none)'}`
|
||||
```
|
||||
|
||||
### Step 3: Import to Core Memory via MCP
|
||||
|
||||
Use the MCP `core_memory` tool to save the structured text:
|
||||
|
||||
```javascript
|
||||
mcp__ccw-tools__core_memory({
|
||||
operation: "import",
|
||||
text: structuredText
|
||||
})
|
||||
```
|
||||
|
||||
Or via CLI (pipe structured text to import):
|
||||
|
||||
```bash
|
||||
# Write structured text to temp file, then import
|
||||
echo "$structuredText" | ccw core-memory import
|
||||
|
||||
# Or from a file
|
||||
ccw core-memory import --file /path/to/session-memory.md
|
||||
```
|
||||
|
||||
**Response Format**:
|
||||
```json
|
||||
{
|
||||
"operation": "import",
|
||||
"id": "CMEM-YYYYMMDD-HHMMSS",
|
||||
"message": "Created memory: CMEM-YYYYMMDD-HHMMSS"
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Report Recovery ID
|
||||
|
||||
After successful import, **clearly display the Recovery ID** to the user:
|
||||
|
||||
```
|
||||
╔════════════════════════════════════════════════════════════════════════════╗
|
||||
║ ✓ Session Memory Saved ║
|
||||
║ ║
|
||||
║ Recovery ID: CMEM-YYYYMMDD-HHMMSS ║
|
||||
║ ║
|
||||
║ To restore: "Please import memory <ID>" ║
|
||||
║ (MCP: core_memory export | CLI: ccw core-memory export --id <ID>) ║
|
||||
╚════════════════════════════════════════════════════════════════════════════╝
|
||||
```
|
||||
|
||||
## 6. Quality Checklist
|
||||
|
||||
Before generating:
|
||||
- [ ] Session ID captured if workflow session active (WFS-*)
|
||||
- [ ] Project Root is absolute path (e.g., D:\Claude_dms3)
|
||||
- [ ] Objective clearly states the "North Star" goal
|
||||
- [ ] Execution Plan: COMPLETE plan preserved VERBATIM (no summarization)
|
||||
- [ ] Plan Source: Clearly identified (workflow | todo | user-stated | inferred)
|
||||
- [ ] Plan Details: ALL phases, tasks, file paths, dependencies, status markers included
|
||||
- [ ] All file paths are ABSOLUTE (not relative)
|
||||
- [ ] Working Files: 3-8 modified files with roles
|
||||
- [ ] Reference Files: Key context files (CLAUDE.md, types, configs)
|
||||
- [ ] Last Action captures final state (success/failure)
|
||||
- [ ] Decisions include reasoning, not just choices
|
||||
- [ ] Known Issues separates deferred from forgotten bugs
|
||||
- [ ] Notes preserve debugging hypotheses if any
|
||||
|
||||
## 7. Path Resolution Rules
|
||||
|
||||
### Project Root Detection
|
||||
1. Check current working directory from environment
|
||||
2. Look for project markers: `.git/`, `package.json`, `.claude/`
|
||||
3. Use the topmost directory containing these markers
|
||||
|
||||
### Absolute Path Conversion
|
||||
```javascript
|
||||
// Convert relative to absolute
|
||||
const toAbsolutePath = (relativePath, projectRoot) => {
|
||||
if (path.isAbsolute(relativePath)) return relativePath;
|
||||
return path.join(projectRoot, relativePath);
|
||||
};
|
||||
|
||||
// Example: "src/api/auth.ts" → "D:\Claude_dms3\src\api\auth.ts"
|
||||
```
|
||||
|
||||
### Reference File Categories
|
||||
| Category | Examples | Priority |
|
||||
|----------|----------|----------|
|
||||
| Project Config | `.claude/CLAUDE.md`, `package.json`, `tsconfig.json` | High |
|
||||
| Type Definitions | `src/types/*.ts`, `*.d.ts` | High |
|
||||
| Related Modules | Parent/sibling modules with shared interfaces | Medium |
|
||||
| Test Files | Corresponding test files for modified code | Medium |
|
||||
| Documentation | `README.md`, `ARCHITECTURE.md` | Low |
|
||||
|
||||
## 8. Plan Detection (Priority Order)
|
||||
|
||||
### Priority 1: Workflow Session (IMPL_PLAN.md)
|
||||
```javascript
|
||||
// Check for active workflow session
|
||||
const manifest = await mcp__ccw-tools__session_manager({
|
||||
operation: "list",
|
||||
location: "active"
|
||||
});
|
||||
|
||||
if (manifest.sessions?.length > 0) {
|
||||
const session = manifest.sessions[0];
|
||||
const plan = await mcp__ccw-tools__session_manager({
|
||||
operation: "read",
|
||||
session_id: session.id,
|
||||
content_type: "plan"
|
||||
});
|
||||
sessionAnalysis.sessionId = session.id;
|
||||
sessionAnalysis.executionPlan.source = "workflow";
|
||||
sessionAnalysis.executionPlan.content = plan.content;
|
||||
}
|
||||
```
|
||||
|
||||
### Priority 2: TodoWrite (Current Session Todos)
|
||||
```javascript
|
||||
// Extract from conversation - look for TodoWrite tool calls
|
||||
// Preserve COMPLETE todo list with all details
|
||||
const todos = extractTodosFromConversation();
|
||||
if (todos.length > 0) {
|
||||
sessionAnalysis.executionPlan.source = "todo";
|
||||
// Format todos with full context - preserve status markers
|
||||
sessionAnalysis.executionPlan.content = todos.map(t =>
|
||||
`- [${t.status === 'completed' ? 'x' : t.status === 'in_progress' ? '>' : ' '}] ${t.content}`
|
||||
).join('\n');
|
||||
}
|
||||
```
|
||||
|
||||
### Priority 3: User-Stated Plan
|
||||
```javascript
|
||||
// Look for explicit plan statements in user messages:
|
||||
// - "Here's my plan: 1. ... 2. ... 3. ..."
|
||||
// - "I want to: first..., then..., finally..."
|
||||
// - Numbered or bulleted lists describing steps
|
||||
const userPlan = extractUserStatedPlan();
|
||||
if (userPlan) {
|
||||
sessionAnalysis.executionPlan.source = "user-stated";
|
||||
sessionAnalysis.executionPlan.content = userPlan;
|
||||
}
|
||||
```
|
||||
|
||||
### Priority 4: Inferred Plan
|
||||
```javascript
|
||||
// If no explicit plan, infer from:
|
||||
// - Task description and breakdown discussion
|
||||
// - Sequence of actions taken
|
||||
// - Outstanding work mentioned
|
||||
const inferredPlan = inferPlanFromDiscussion();
|
||||
if (inferredPlan) {
|
||||
sessionAnalysis.executionPlan.source = "inferred";
|
||||
sessionAnalysis.executionPlan.content = inferredPlan;
|
||||
}
|
||||
```
|
||||
|
||||
## 9. Notes
|
||||
|
||||
- **Timing**: Execute at task completion or before context switch
|
||||
- **Frequency**: Once per independent task or milestone
|
||||
- **Recovery**: New session can immediately continue with full context
|
||||
- **Knowledge Graph**: Entity relationships auto-extracted for visualization
|
||||
- **Absolute Paths**: Critical for cross-session recovery on different machines
|
||||
@@ -101,10 +101,10 @@ src/ (depth 1) → SINGLE STRATEGY
|
||||
Bash({command: "pwd && basename \"$(pwd)\" && git rev-parse --show-toplevel 2>/dev/null || pwd", run_in_background: false});
|
||||
|
||||
// Get module structure with classification
|
||||
Bash({command: "ccw tool exec get_modules_by_depth '{\"format\":\"list\"}' | ccw tool exec classify_folders '{}'", run_in_background: false});
|
||||
Bash({command: "~/.claude/scripts/get_modules_by_depth.sh list | ~/.claude/scripts/classify-folders.sh", run_in_background: false});
|
||||
|
||||
// OR with path parameter
|
||||
Bash({command: "cd <target-path> && ccw tool exec get_modules_by_depth '{\"format\":\"list\"}' | ccw tool exec classify_folders '{}'", run_in_background: false});
|
||||
Bash({command: "cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list | ~/.claude/scripts/classify-folders.sh", run_in_background: false});
|
||||
```
|
||||
|
||||
**Parse output** `depth:N|path:<PATH>|type:<code|navigation>|...` to extract module paths, types, and count.
|
||||
@@ -200,7 +200,7 @@ for (let layer of [3, 2, 1]) {
|
||||
let strategy = module.depth >= 3 ? "full" : "single";
|
||||
for (let tool of tool_order) {
|
||||
Bash({
|
||||
command: `cd ${module.path} && ccw tool exec generate_module_docs '{"strategy":"${strategy}","sourcePath":".","projectName":"${project_name}","tool":"${tool}"}'`,
|
||||
command: `cd ${module.path} && ~/.claude/scripts/generate_module_docs.sh "${strategy}" "." "${project_name}" "${tool}"`,
|
||||
run_in_background: false
|
||||
});
|
||||
if (bash_result.exit_code === 0) {
|
||||
@@ -263,7 +263,7 @@ MODULES:
|
||||
|
||||
TOOLS (try in order): {{tool_1}}, {{tool_2}}, {{tool_3}}
|
||||
|
||||
EXECUTION SCRIPT: ccw tool exec generate_module_docs
|
||||
EXECUTION SCRIPT: ~/.claude/scripts/generate_module_docs.sh
|
||||
- Accepts strategy parameter: full | single
|
||||
- Accepts folder type detection: code | navigation
|
||||
- Tool execution via direct CLI commands (gemini/qwen/codex)
|
||||
@@ -273,7 +273,7 @@ EXECUTION FLOW (for each module):
|
||||
1. Tool fallback loop (exit on first success):
|
||||
for tool in {{tool_1}} {{tool_2}} {{tool_3}}; do
|
||||
Bash({
|
||||
command: `cd "{{module_path}}" && ccw tool exec generate_module_docs '{"strategy":"{{strategy}}","sourcePath":".","projectName":"{{project_name}}","tool":"${tool}"}'`,
|
||||
command: `cd "{{module_path}}" && ~/.claude/scripts/generate_module_docs.sh "{{strategy}}" "." "{{project_name}}" "${tool}"`,
|
||||
run_in_background: false
|
||||
})
|
||||
exit_code=$?
|
||||
@@ -322,7 +322,7 @@ let project_root = get_project_root();
|
||||
report("Generating project README.md...");
|
||||
for (let tool of tool_order) {
|
||||
Bash({
|
||||
command: `cd ${project_root} && ccw tool exec generate_module_docs '{"strategy":"project-readme","sourcePath":".","projectName":"${project_name}","tool":"${tool}"}'`,
|
||||
command: `cd ${project_root} && ~/.claude/scripts/generate_module_docs.sh "project-readme" "." "${project_name}" "${tool}"`,
|
||||
run_in_background: false
|
||||
});
|
||||
if (bash_result.exit_code === 0) {
|
||||
@@ -335,7 +335,7 @@ for (let tool of tool_order) {
|
||||
report("Generating ARCHITECTURE.md and EXAMPLES.md...");
|
||||
for (let tool of tool_order) {
|
||||
Bash({
|
||||
command: `cd ${project_root} && ccw tool exec generate_module_docs '{"strategy":"project-architecture","sourcePath":".","projectName":"${project_name}","tool":"${tool}"}'`,
|
||||
command: `cd ${project_root} && ~/.claude/scripts/generate_module_docs.sh "project-architecture" "." "${project_name}" "${tool}"`,
|
||||
run_in_background: false
|
||||
});
|
||||
if (bash_result.exit_code === 0) {
|
||||
@@ -350,7 +350,7 @@ if (bash_result.stdout.includes("API_FOUND")) {
|
||||
report("Generating HTTP API documentation...");
|
||||
for (let tool of tool_order) {
|
||||
Bash({
|
||||
command: `cd ${project_root} && ccw tool exec generate_module_docs '{"strategy":"http-api","sourcePath":".","projectName":"${project_name}","tool":"${tool}"}'`,
|
||||
command: `cd ${project_root} && ~/.claude/scripts/generate_module_docs.sh "http-api" "." "${project_name}" "${tool}"`,
|
||||
run_in_background: false
|
||||
});
|
||||
if (bash_result.exit_code === 0) {
|
||||
|
||||
@@ -51,7 +51,7 @@ Orchestrates context-aware documentation generation/update for changed modules u
|
||||
Bash({command: "pwd && basename \"$(pwd)\" && git rev-parse --show-toplevel 2>/dev/null || pwd", run_in_background: false});
|
||||
|
||||
// Detect changed modules
|
||||
Bash({command: "ccw tool exec detect_changed_modules '{\"format\":\"list\"}'", run_in_background: false});
|
||||
Bash({command: "~/.claude/scripts/detect_changed_modules.sh list", run_in_background: false});
|
||||
|
||||
// Cache git changes
|
||||
Bash({command: "git add -A 2>/dev/null || true", run_in_background: false});
|
||||
@@ -123,7 +123,7 @@ for (let depth of sorted_depths.reverse()) { // N → 0
|
||||
return async () => {
|
||||
for (let tool of tool_order) {
|
||||
Bash({
|
||||
command: `cd ${module.path} && ccw tool exec generate_module_docs '{"strategy":"single","sourcePath":".","projectName":"${project_name}","tool":"${tool}"}'`,
|
||||
command: `cd ${module.path} && ~/.claude/scripts/generate_module_docs.sh "single" "." "${project_name}" "${tool}"`,
|
||||
run_in_background: false
|
||||
});
|
||||
if (bash_result.exit_code === 0) {
|
||||
@@ -207,21 +207,21 @@ EXECUTION:
|
||||
For each module above:
|
||||
1. Try tool 1:
|
||||
Bash({
|
||||
command: `cd "{{module_path}}" && ccw tool exec generate_module_docs '{"strategy":"single","sourcePath":".","projectName":"{{project_name}}","tool":"{{tool_1}}"}'`,
|
||||
command: `cd "{{module_path}}" && ~/.claude/scripts/generate_module_docs.sh "single" "." "{{project_name}}" "{{tool_1}}"`,
|
||||
run_in_background: false
|
||||
})
|
||||
→ Success: Report "✅ {{module_path}} docs generated with {{tool_1}}", proceed to next module
|
||||
→ Failure: Try tool 2
|
||||
2. Try tool 2:
|
||||
Bash({
|
||||
command: `cd "{{module_path}}" && ccw tool exec generate_module_docs '{"strategy":"single","sourcePath":".","projectName":"{{project_name}}","tool":"{{tool_2}}"}'`,
|
||||
command: `cd "{{module_path}}" && ~/.claude/scripts/generate_module_docs.sh "single" "." "{{project_name}}" "{{tool_2}}"`,
|
||||
run_in_background: false
|
||||
})
|
||||
→ Success: Report "✅ {{module_path}} docs generated with {{tool_2}}", proceed to next module
|
||||
→ Failure: Try tool 3
|
||||
3. Try tool 3:
|
||||
Bash({
|
||||
command: `cd "{{module_path}}" && ccw tool exec generate_module_docs '{"strategy":"single","sourcePath":".","projectName":"{{project_name}}","tool":"{{tool_3}}"}'`,
|
||||
command: `cd "{{module_path}}" && ~/.claude/scripts/generate_module_docs.sh "single" "." "{{project_name}}" "{{tool_3}}"`,
|
||||
run_in_background: false
|
||||
})
|
||||
→ Success: Report "✅ {{module_path}} docs generated with {{tool_3}}", proceed to next module
|
||||
|
||||
@@ -85,10 +85,10 @@ bash(jq '. + {"target_path":"{target_path}","project_root":"{project_root}","pro
|
||||
|
||||
```bash
|
||||
# 1. Run folder analysis
|
||||
bash(ccw tool exec get_modules_by_depth '{}' | ccw tool exec classify_folders '{}')
|
||||
bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh)
|
||||
|
||||
# 2. Get top-level directories (first 2 path levels)
|
||||
bash(ccw tool exec get_modules_by_depth '{}' | ccw tool exec classify_folders '{}' | awk -F'|' '{print $1}' | sed 's|^\./||' | awk -F'/' '{if(NF>=2) print $1"/"$2; else if(NF==1) print $1}' | sort -u)
|
||||
bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh | awk -F'|' '{print $1}' | sed 's|^\./||' | awk -F'/' '{if(NF>=2) print $1"/"$2; else if(NF==1) print $1}' | sort -u)
|
||||
|
||||
# 3. Find existing docs (if directory exists)
|
||||
bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${project_name} -type f -name "*.md" ! -path "*/README.md" ! -path "*/ARCHITECTURE.md" ! -path "*/EXAMPLES.md" ! -path "*/api/*" 2>/dev/null; fi)
|
||||
@@ -235,12 +235,12 @@ api_id=$((group_count + 3))
|
||||
| Mode | cli_execute | Placement | CLI MODE | Approval Flag | Agent Role |
|
||||
|------|-------------|-----------|----------|---------------|------------|
|
||||
| **Agent** | false | pre_analysis | analysis | (none) | Generate docs in implementation_approach |
|
||||
| **CLI** | true | implementation_approach | write | --mode write | Execute CLI commands, validate output |
|
||||
| **CLI** | true | implementation_approach | write | --approval-mode yolo | Execute CLI commands, validate output |
|
||||
|
||||
**Command Patterns**:
|
||||
- Gemini/Qwen: `ccw cli -p "..." --tool gemini --mode analysis --cd dir`
|
||||
- CLI Mode: `ccw cli -p "..." --tool gemini --mode write --cd dir`
|
||||
- Codex: `ccw cli -p "..." --tool codex --mode write --cd dir`
|
||||
- Gemini/Qwen: `cd dir && gemini -p "..."`
|
||||
- CLI Mode: `cd dir && gemini --approval-mode yolo -p "..."`
|
||||
- Codex: `codex -C dir --full-auto exec "..." --skip-git-repo-check -s danger-full-access`
|
||||
|
||||
**Generation Process**:
|
||||
1. Read configuration values (tool, cli_execute, mode) from workflow-session.json
|
||||
@@ -331,7 +331,7 @@ api_id=$((group_count + 3))
|
||||
{
|
||||
"step": 2,
|
||||
"title": "Batch generate documentation via CLI",
|
||||
"command": "ccw cli -p 'PURPOSE: Generate module docs\\nTASK: Create documentation\\nMODE: write\\nCONTEXT: @**/* [phase2_context]\\nEXPECTED: API.md and README.md\\nRULES: Mirror structure' --tool gemini --mode write --cd ${dirs_from_group}",
|
||||
"command": "bash(dirs=$(jq -r '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories[]' ${session_dir}/.process/doc-planning-data.json); for dir in $dirs; do cd \"$dir\" && gemini --approval-mode yolo -p \"PURPOSE: Generate module docs\\nTASK: Create documentation\\nMODE: write\\nCONTEXT: @**/* [phase2_context]\\nEXPECTED: API.md and README.md\\nRULES: Mirror structure\" || echo \"Failed: $dir\"; cd -; done)",
|
||||
"depends_on": [1],
|
||||
"output": "generated_docs"
|
||||
}
|
||||
@@ -363,7 +363,7 @@ api_id=$((group_count + 3))
|
||||
},
|
||||
{
|
||||
"step": "analyze_project",
|
||||
"command": "bash(ccw cli -p \"PURPOSE: Analyze project structure\\nTASK: Extract overview from modules\\nMODE: analysis\\nCONTEXT: [all_module_docs]\\nEXPECTED: Project outline\" --tool gemini --mode analysis)",
|
||||
"command": "bash(gemini \"PURPOSE: Analyze project structure\\nTASK: Extract overview from modules\\nMODE: analysis\\nCONTEXT: [all_module_docs]\\nEXPECTED: Project outline\")",
|
||||
"output_to": "project_outline"
|
||||
}
|
||||
],
|
||||
@@ -403,7 +403,7 @@ api_id=$((group_count + 3))
|
||||
"pre_analysis": [
|
||||
{"step": "load_existing_docs", "command": "bash(cat .workflow/docs/${project_name}/{ARCHITECTURE,EXAMPLES}.md 2>/dev/null || echo 'No existing docs')", "output_to": "existing_arch_examples"},
|
||||
{"step": "load_all_docs", "command": "bash(cat .workflow/docs/${project_name}/README.md && find .workflow/docs/${project_name} -type f -name '*.md' ! -path '*/README.md' ! -path '*/ARCHITECTURE.md' ! -path '*/EXAMPLES.md' ! -path '*/api/*' | xargs cat)", "output_to": "all_docs"},
|
||||
{"step": "analyze_architecture", "command": "bash(ccw cli -p \"PURPOSE: Analyze system architecture\\nTASK: Synthesize architectural overview and examples\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture + Examples outline\" --tool gemini --mode analysis)", "output_to": "arch_examples_outline"}
|
||||
{"step": "analyze_architecture", "command": "bash(gemini \"PURPOSE: Analyze system architecture\\nTASK: Synthesize architectural overview and examples\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture + Examples outline\")", "output_to": "arch_examples_outline"}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
@@ -440,7 +440,7 @@ api_id=$((group_count + 3))
|
||||
"pre_analysis": [
|
||||
{"step": "discover_api", "command": "bash(rg 'router\\.| @(Get|Post)' -g '*.{ts,js}')", "output_to": "endpoint_discovery"},
|
||||
{"step": "load_existing_api", "command": "bash(cat .workflow/docs/${project_name}/api/README.md 2>/dev/null || echo 'No existing API docs')", "output_to": "existing_api_docs"},
|
||||
{"step": "analyze_api", "command": "bash(ccw cli -p \"PURPOSE: Document HTTP API\\nTASK: Analyze endpoints\\nMODE: analysis\\nCONTEXT: @src/api/**/* [endpoint_discovery]\\nEXPECTED: API outline\" --tool gemini --mode analysis)", "output_to": "api_outline"}
|
||||
{"step": "analyze_api", "command": "bash(gemini \"PURPOSE: Document HTTP API\\nTASK: Analyze endpoints\\nMODE: analysis\\nCONTEXT: @src/api/**/* [endpoint_discovery]\\nEXPECTED: API outline\")", "output_to": "api_outline"}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
@@ -601,7 +601,7 @@ api_id=$((group_count + 3))
|
||||
| Mode | CLI Placement | CLI MODE | Approval Flag | Agent Role |
|
||||
|------|---------------|----------|---------------|------------|
|
||||
| **Agent (default)** | pre_analysis | analysis | (none) | Generates documentation content |
|
||||
| **CLI (--cli-execute)** | implementation_approach | write | --mode write | Executes CLI commands, validates output |
|
||||
| **CLI (--cli-execute)** | implementation_approach | write | --approval-mode yolo | Executes CLI commands, validates output |
|
||||
|
||||
**Execution Flow**:
|
||||
- **Phase 2**: Unified analysis once, results in `.process/`
|
||||
|
||||
@@ -5,7 +5,7 @@ argument-hint: "[--tool gemini|qwen] \"task context description\""
|
||||
allowed-tools: Task(*), Bash(*)
|
||||
examples:
|
||||
- /memory:load "在当前前端基础上开发用户认证功能"
|
||||
- /memory:load --tool qwen "重构支付模块API"
|
||||
- /memory:load --tool qwen -p "重构支付模块API"
|
||||
---
|
||||
|
||||
# Memory Load Command (/memory:load)
|
||||
@@ -39,7 +39,7 @@ The command fully delegates to **universal-executor agent**, which autonomously:
|
||||
1. **Analyzes Project Structure**: Executes `get_modules_by_depth.sh` to understand architecture
|
||||
2. **Loads Documentation**: Reads CLAUDE.md, README.md and other key docs
|
||||
3. **Extracts Keywords**: Derives core keywords from task description
|
||||
4. **Discovers Files**: Uses CodexLens MCP or rg/find to locate relevant files
|
||||
4. **Discovers Files**: Uses MCP code-index or rg/find to locate relevant files
|
||||
5. **CLI Deep Analysis**: Executes Gemini/Qwen CLI for deep context analysis
|
||||
6. **Generates Content Package**: Returns structured JSON core content package
|
||||
|
||||
@@ -109,7 +109,7 @@ Task(
|
||||
|
||||
1. **Project Structure**
|
||||
\`\`\`bash
|
||||
bash(ccw tool exec get_modules_by_depth '{}')
|
||||
bash(~/.claude/scripts/get_modules_by_depth.sh)
|
||||
\`\`\`
|
||||
|
||||
2. **Core Documentation**
|
||||
@@ -136,7 +136,7 @@ Task(
|
||||
Execute Gemini/Qwen CLI for deep analysis (saves main thread tokens):
|
||||
|
||||
\`\`\`bash
|
||||
ccw cli -p "
|
||||
cd . && ${tool} -p "
|
||||
PURPOSE: Extract project core context for task: ${task_description}
|
||||
TASK: Analyze project architecture, tech stack, key patterns, relevant files
|
||||
MODE: analysis
|
||||
@@ -147,7 +147,7 @@ RULES:
|
||||
- Identify key architecture patterns and technical constraints
|
||||
- Extract integration points and development standards
|
||||
- Output concise, structured format
|
||||
" --tool ${tool} --mode analysis
|
||||
"
|
||||
\`\`\`
|
||||
|
||||
### Step 4: Generate Core Content Package
|
||||
@@ -212,7 +212,7 @@ Before returning:
|
||||
### Example 2: Using Qwen Tool
|
||||
|
||||
```bash
|
||||
/memory:load --tool qwen "重构支付模块API"
|
||||
/memory:load --tool qwen -p "重构支付模块API"
|
||||
```
|
||||
|
||||
Agent uses Qwen CLI for analysis, returns same structured package.
|
||||
|
||||
@@ -1,773 +0,0 @@
|
||||
---
|
||||
name: swagger-docs
|
||||
description: Generate complete Swagger/OpenAPI documentation following RESTful standards with global security, API details, error codes, and validation tests
|
||||
argument-hint: "[path] [--tool <gemini|qwen|codex>] [--format <yaml|json>] [--version <v3.0|v3.1>] [--lang <zh|en>]"
|
||||
---
|
||||
|
||||
# Swagger API Documentation Workflow (/memory:swagger-docs)
|
||||
|
||||
## Overview
|
||||
|
||||
Professional Swagger/OpenAPI documentation generator that strictly follows RESTful API design standards to produce enterprise-grade API documentation.
|
||||
|
||||
**Core Features**:
|
||||
- **RESTful Standards**: Strict adherence to REST architecture and HTTP semantics
|
||||
- **Global Security**: Unified Authorization Token validation mechanism
|
||||
- **Complete API Docs**: Descriptions, methods, URLs, parameters for each endpoint
|
||||
- **Organized Structure**: Clear directory hierarchy by business domain
|
||||
- **Detailed Fields**: Type, required, example, description for each field
|
||||
- **Error Code Standards**: Unified error response format and code definitions
|
||||
- **Validation Tests**: Boundary conditions and exception handling tests
|
||||
|
||||
**Output Structure** (--lang zh):
|
||||
```
|
||||
.workflow/docs/{project_name}/api/
|
||||
├── swagger.yaml # Main OpenAPI spec file
|
||||
├── 概述/
|
||||
│ ├── README.md # API overview
|
||||
│ ├── 认证说明.md # Authentication guide
|
||||
│ ├── 错误码规范.md # Error code definitions
|
||||
│ └── 版本历史.md # Version history
|
||||
├── 用户模块/ # Grouped by business domain
|
||||
│ ├── 用户认证.md
|
||||
│ ├── 用户管理.md
|
||||
│ └── 权限控制.md
|
||||
├── 业务模块/
|
||||
│ └── ...
|
||||
└── 测试报告/
|
||||
├── 接口测试.md # API test results
|
||||
└── 边界测试.md # Boundary condition tests
|
||||
```
|
||||
|
||||
**Output Structure** (--lang en):
|
||||
```
|
||||
.workflow/docs/{project_name}/api/
|
||||
├── swagger.yaml # Main OpenAPI spec file
|
||||
├── overview/
|
||||
│ ├── README.md # API overview
|
||||
│ ├── authentication.md # Authentication guide
|
||||
│ ├── error-codes.md # Error code definitions
|
||||
│ └── changelog.md # Version history
|
||||
├── users/ # Grouped by business domain
|
||||
│ ├── authentication.md
|
||||
│ ├── management.md
|
||||
│ └── permissions.md
|
||||
├── orders/
|
||||
│ └── ...
|
||||
└── test-reports/
|
||||
├── api-tests.md # API test results
|
||||
└── boundary-tests.md # Boundary condition tests
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
```bash
|
||||
/memory:swagger-docs [path] [--tool <gemini|qwen|codex>] [--format <yaml|json>] [--version <v3.0|v3.1>] [--lang <zh|en>]
|
||||
```
|
||||
|
||||
- **path**: API source code directory (default: current directory)
|
||||
- **--tool**: CLI tool selection (default: gemini)
|
||||
- `gemini`: Comprehensive analysis, pattern recognition
|
||||
- `qwen`: Architecture analysis, system design
|
||||
- `codex`: Implementation validation, code quality
|
||||
- **--format**: OpenAPI spec format (default: yaml)
|
||||
- `yaml`: YAML format (recommended, better readability)
|
||||
- `json`: JSON format
|
||||
- **--version**: OpenAPI version (default: v3.0)
|
||||
- `v3.0`: OpenAPI 3.0.x
|
||||
- `v3.1`: OpenAPI 3.1.0 (supports JSON Schema 2020-12)
|
||||
- **--lang**: Documentation language (default: zh)
|
||||
- `zh`: Chinese documentation with Chinese directory names
|
||||
- `en`: English documentation with English directory names
|
||||
|
||||
## Planning Workflow
|
||||
|
||||
### Phase 1: Initialize Session
|
||||
|
||||
```bash
|
||||
# Get project info
|
||||
bash(pwd && basename "$(pwd)" && git rev-parse --show-toplevel 2>/dev/null || pwd && date +%Y%m%d-%H%M%S)
|
||||
```
|
||||
|
||||
```javascript
|
||||
// Create swagger-docs session
|
||||
SlashCommand(command="/workflow:session:start --type swagger-docs --new \"{project_name}-swagger-{timestamp}\"")
|
||||
// Parse output to get sessionId
|
||||
```
|
||||
|
||||
```bash
|
||||
# Update workflow-session.json
|
||||
bash(jq '. + {"target_path":"{target_path}","project_root":"{project_root}","project_name":"{project_name}","format":"yaml","openapi_version":"3.0.3","lang":"{lang}","tool":"gemini"}' .workflow/active/{sessionId}/workflow-session.json > tmp.json && mv tmp.json .workflow/active/{sessionId}/workflow-session.json)
|
||||
```
|
||||
|
||||
### Phase 2: Scan API Endpoints
|
||||
|
||||
**Discovery Patterns**: Auto-detect framework signatures and API definition styles.
|
||||
|
||||
**Supported Frameworks**:
|
||||
| Framework | Detection Pattern | Example |
|
||||
|-----------|-------------------|---------|
|
||||
| Express.js | `router.get/post/put/delete` | `router.get('/users/:id')` |
|
||||
| Fastify | `fastify.route`, `@Route` | `fastify.get('/api/users')` |
|
||||
| NestJS | `@Controller`, `@Get/@Post` | `@Get('users/:id')` |
|
||||
| Koa | `router.get`, `ctx.body` | `router.get('/users')` |
|
||||
| Hono | `app.get/post`, `c.json` | `app.get('/users/:id')` |
|
||||
| FastAPI | `@app.get`, `@router.post` | `@app.get("/users/{id}")` |
|
||||
| Flask | `@app.route`, `@bp.route` | `@app.route('/users')` |
|
||||
| Spring | `@GetMapping`, `@PostMapping` | `@GetMapping("/users/{id}")` |
|
||||
| Go Gin | `r.GET`, `r.POST` | `r.GET("/users/:id")` |
|
||||
| Go Chi | `r.Get`, `r.Post` | `r.Get("/users/{id}")` |
|
||||
|
||||
**Commands**:
|
||||
|
||||
```bash
|
||||
# 1. Detect API framework type
|
||||
bash(
|
||||
if rg -q "@Controller|@Get|@Post|@Put|@Delete" --type ts 2>/dev/null; then echo "NESTJS";
|
||||
elif rg -q "router\.(get|post|put|delete|patch)" --type ts --type js 2>/dev/null; then echo "EXPRESS";
|
||||
elif rg -q "fastify\.(get|post|route)" --type ts --type js 2>/dev/null; then echo "FASTIFY";
|
||||
elif rg -q "@app\.(get|post|put|delete)" --type py 2>/dev/null; then echo "FASTAPI";
|
||||
elif rg -q "@GetMapping|@PostMapping|@RequestMapping" --type java 2>/dev/null; then echo "SPRING";
|
||||
elif rg -q 'r\.(GET|POST|PUT|DELETE)' --type go 2>/dev/null; then echo "GO_GIN";
|
||||
else echo "UNKNOWN"; fi
|
||||
)
|
||||
|
||||
# 2. Scan all API endpoint definitions
|
||||
bash(rg -n "(router|app|fastify)\.(get|post|put|delete|patch)|@(Get|Post|Put|Delete|Patch|Controller|RequestMapping)" --type ts --type js --type py --type java --type go -g '!*.test.*' -g '!*.spec.*' -g '!node_modules/**' 2>/dev/null | head -200)
|
||||
|
||||
# 3. Extract route paths
|
||||
bash(rg -o "['\"](/api)?/[a-zA-Z0-9/:_-]+['\"]" --type ts --type js --type py -g '!*.test.*' 2>/dev/null | sort -u | head -100)
|
||||
|
||||
# 4. Detect existing OpenAPI/Swagger files
|
||||
bash(find . -type f \( -name "swagger.yaml" -o -name "swagger.json" -o -name "openapi.yaml" -o -name "openapi.json" \) ! -path "*/node_modules/*" 2>/dev/null)
|
||||
|
||||
# 5. Extract DTO/Schema definitions
|
||||
bash(rg -n "export (interface|type|class).*Dto|@ApiProperty|class.*Schema" --type ts -g '!*.test.*' 2>/dev/null | head -100)
|
||||
```
|
||||
|
||||
**Data Processing**: Parse outputs, use **Write tool** to create `${session_dir}/.process/swagger-planning-data.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"generated_at": "2025-01-01T12:00:00+08:00",
|
||||
"project_name": "project_name",
|
||||
"project_root": "/path/to/project",
|
||||
"openapi_version": "3.0.3",
|
||||
"format": "yaml",
|
||||
"lang": "zh"
|
||||
},
|
||||
"framework": {
|
||||
"type": "NESTJS",
|
||||
"detected_patterns": ["@Controller", "@Get", "@Post"],
|
||||
"base_path": "/api/v1"
|
||||
},
|
||||
"endpoints": [
|
||||
{
|
||||
"file": "src/modules/users/users.controller.ts",
|
||||
"line": 25,
|
||||
"method": "GET",
|
||||
"path": "/api/v1/users/:id",
|
||||
"handler": "getUser",
|
||||
"controller": "UsersController"
|
||||
}
|
||||
],
|
||||
"existing_specs": {
|
||||
"found": false,
|
||||
"files": []
|
||||
},
|
||||
"dto_schemas": [
|
||||
{
|
||||
"name": "CreateUserDto",
|
||||
"file": "src/modules/users/dto/create-user.dto.ts",
|
||||
"properties": ["email", "password", "name"]
|
||||
}
|
||||
],
|
||||
"statistics": {
|
||||
"total_endpoints": 45,
|
||||
"by_method": {"GET": 20, "POST": 15, "PUT": 5, "DELETE": 5},
|
||||
"by_module": {"users": 12, "auth": 8, "orders": 15, "products": 10}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: Analyze API Structure
|
||||
|
||||
**Commands**:
|
||||
|
||||
```bash
|
||||
# 1. Analyze controller/route file structure
|
||||
bash(cat ${session_dir}/.process/swagger-planning-data.json | jq -r '.endpoints[].file' | sort -u | head -20)
|
||||
|
||||
# 2. Extract request/response types
|
||||
bash(for f in $(jq -r '.dto_schemas[].file' ${session_dir}/.process/swagger-planning-data.json | head -20); do echo "=== $f ===" && cat "$f" 2>/dev/null; done)
|
||||
|
||||
# 3. Analyze authentication middleware
|
||||
bash(rg -n "auth|guard|middleware|jwt|bearer|token" -i --type ts --type js -g '!*.test.*' -g '!node_modules/**' 2>/dev/null | head -50)
|
||||
|
||||
# 4. Detect error handling patterns
|
||||
bash(rg -n "HttpException|BadRequest|Unauthorized|Forbidden|NotFound|throw new" --type ts --type js -g '!*.test.*' 2>/dev/null | head -50)
|
||||
```
|
||||
|
||||
**Deep Analysis via Gemini CLI**:
|
||||
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Analyze API structure and generate OpenAPI specification outline for comprehensive documentation
|
||||
TASK:
|
||||
• Parse all API endpoints and identify business module boundaries
|
||||
• Extract request parameters, request bodies, and response formats
|
||||
• Identify authentication mechanisms and security requirements
|
||||
• Discover error handling patterns and error codes
|
||||
• Map endpoints to logical module groups
|
||||
MODE: analysis
|
||||
CONTEXT: @src/**/*.controller.ts @src/**/*.routes.ts @src/**/*.dto.ts @src/**/middleware/**/*
|
||||
EXPECTED: JSON format API structure analysis report with modules, endpoints, security schemes, and error codes
|
||||
CONSTRAINTS: Strict RESTful standards | Identify all public endpoints | Document output language: {lang}
|
||||
" --tool gemini --mode analysis --rule analysis-code-patterns --cd {project_root}
|
||||
```
|
||||
|
||||
**Update swagger-planning-data.json** with analysis results:
|
||||
|
||||
```json
|
||||
{
|
||||
"api_structure": {
|
||||
"modules": [
|
||||
{
|
||||
"name": "Users",
|
||||
"name_zh": "用户模块",
|
||||
"base_path": "/api/v1/users",
|
||||
"endpoints": [
|
||||
{
|
||||
"path": "/api/v1/users",
|
||||
"method": "GET",
|
||||
"operation_id": "listUsers",
|
||||
"summary": "List all users",
|
||||
"summary_zh": "获取用户列表",
|
||||
"description": "Paginated list of system users with filtering by status and role",
|
||||
"description_zh": "分页获取系统用户列表，支持按状态、角色筛选",
|
||||
"tags": ["User Management"],
|
||||
"tags_zh": ["用户管理"],
|
||||
"security": ["bearerAuth"],
|
||||
"parameters": {
|
||||
"query": ["page", "limit", "status", "role"]
|
||||
},
|
||||
"responses": {
|
||||
"200": "UserListResponse",
|
||||
"401": "UnauthorizedError",
|
||||
"403": "ForbiddenError"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"security_schemes": {
|
||||
"bearerAuth": {
|
||||
"type": "http",
|
||||
"scheme": "bearer",
|
||||
"bearerFormat": "JWT",
|
||||
"description": "JWT Token authentication. Add Authorization: Bearer <token> to request header"
|
||||
}
|
||||
},
|
||||
"error_codes": [
|
||||
{"code": "AUTH_001", "status": 401, "message": "Invalid or expired token", "message_zh": "Token 无效或已过期"},
|
||||
{"code": "AUTH_002", "status": 401, "message": "Authentication required", "message_zh": "未提供认证信息"},
|
||||
{"code": "AUTH_003", "status": 403, "message": "Insufficient permissions", "message_zh": "权限不足"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 4: Task Decomposition
|
||||
|
||||
**Task Hierarchy**:
|
||||
|
||||
```
|
||||
Level 1: Infrastructure Tasks (Parallel)
|
||||
├─ IMPL-001: Generate main OpenAPI spec file (swagger.yaml)
|
||||
├─ IMPL-002: Generate global security config and auth documentation
|
||||
└─ IMPL-003: Generate unified error code specification
|
||||
|
||||
Level 2: Module Documentation Tasks (Parallel, by business module)
|
||||
├─ IMPL-004: Users module API documentation
|
||||
├─ IMPL-005: Auth module API documentation
|
||||
├─ IMPL-006: Business module N API documentation
|
||||
└─ ...
|
||||
|
||||
Level 3: Aggregation Tasks (Depends on Level 1-2)
|
||||
├─ IMPL-N+1: Generate API overview and navigation
|
||||
└─ IMPL-N+2: Generate version history and changelog
|
||||
|
||||
Level 4: Validation Tasks (Depends on Level 1-3)
|
||||
├─ IMPL-N+3: API endpoint validation tests
|
||||
└─ IMPL-N+4: Boundary condition tests
|
||||
```
|
||||
|
||||
**Grouping Strategy**:
|
||||
1. Group by business module (users, orders, products, etc.)
|
||||
2. Maximum 10 endpoints per task
|
||||
3. Large modules (>10 endpoints) split by submodules
|
||||
|
||||
**Commands**:
|
||||
|
||||
```bash
|
||||
# 1. Count endpoints by module
|
||||
bash(cat ${session_dir}/.process/swagger-planning-data.json | jq '.statistics.by_module')
|
||||
|
||||
# 2. Calculate task groupings
|
||||
bash(cat ${session_dir}/.process/swagger-planning-data.json | jq -r '.api_structure.modules[] | "\(.name):\(.endpoints | length)"')
|
||||
```
|
||||
|
||||
**Data Processing**: Use **Edit tool** to update `swagger-planning-data.json` with task groups:
|
||||
|
||||
```json
|
||||
{
|
||||
"task_groups": {
|
||||
"level1_count": 3,
|
||||
"level2_count": 5,
|
||||
"total_count": 12,
|
||||
"assignments": [
|
||||
{"task_id": "IMPL-001", "level": 1, "type": "openapi-spec", "title": "Generate OpenAPI main spec file"},
|
||||
{"task_id": "IMPL-002", "level": 1, "type": "security", "title": "Generate global security config"},
|
||||
{"task_id": "IMPL-003", "level": 1, "type": "error-codes", "title": "Generate error code specification"},
|
||||
{"task_id": "IMPL-004", "level": 2, "type": "module-doc", "module": "users", "endpoint_count": 12},
|
||||
{"task_id": "IMPL-005", "level": 2, "type": "module-doc", "module": "auth", "endpoint_count": 8}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 5: Generate Task JSONs
|
||||
|
||||
**Generation Process**:
|
||||
1. Read configuration values from workflow-session.json
|
||||
2. Read task groups from swagger-planning-data.json
|
||||
3. Generate Level 1 tasks (infrastructure)
|
||||
4. Generate Level 2 tasks (by module)
|
||||
5. Generate Level 3-4 tasks (aggregation and validation)
|
||||
|
||||
## Task Templates
|
||||
|
||||
### Level 1-1: OpenAPI Main Spec File
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-001",
|
||||
"title": "Generate OpenAPI main specification file",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "swagger-openapi-spec",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"priority": "critical"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Generate OpenAPI 3.0.3 compliant swagger.yaml",
|
||||
"Include complete info, servers, tags, paths, components definitions",
|
||||
"Follow RESTful design standards, use {lang} for descriptions"
|
||||
],
|
||||
"precomputed_data": {
|
||||
"planning_data": "${session_dir}/.process/swagger-planning-data.json"
|
||||
}
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_analysis_data",
|
||||
"action": "Load API analysis data",
|
||||
"commands": [
|
||||
"bash(cat ${session_dir}/.process/swagger-planning-data.json)"
|
||||
],
|
||||
"output_to": "api_analysis"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate OpenAPI spec file",
|
||||
"description": "Create complete swagger.yaml specification file",
|
||||
"cli_prompt": "PURPOSE: Generate OpenAPI 3.0.3 specification file from analyzed API structure\nTASK:\n• Define openapi version: 3.0.3\n• Define info: title, description, version, contact, license\n• Define servers: development, staging, production environments\n• Define tags: organized by business modules\n• Define paths: all API endpoints with complete specifications\n• Define components: schemas, securitySchemes, parameters, responses\nMODE: write\nCONTEXT: @[api_analysis]\nEXPECTED: Complete swagger.yaml file following OpenAPI 3.0.3 specification\nCONSTRAINTS: Use {lang} for all descriptions | Strict RESTful standards\n--rule documentation-swagger-api",
|
||||
"output": "swagger.yaml"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/swagger.yaml"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 1-2: Global Security Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-002",
|
||||
"title": "Generate global security configuration and authentication guide",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "swagger-security",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Document Authorization header format in detail",
|
||||
"Describe token acquisition, refresh, and expiration mechanisms",
|
||||
"List permission requirements for each endpoint"
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "analyze_auth",
|
||||
"command": "bash(rg -n 'auth|guard|jwt|bearer' -i --type ts -g '!*.test.*' 2>/dev/null | head -50)",
|
||||
"output_to": "auth_patterns"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate authentication documentation",
|
||||
"cli_prompt": "PURPOSE: Generate comprehensive authentication documentation for API security\nTASK:\n• Document authentication mechanism: JWT Bearer Token\n• Explain header format: Authorization: Bearer <token>\n• Describe token lifecycle: acquisition, refresh, expiration handling\n• Define permission levels: public, user, admin, super_admin\n• Document authentication failure responses: 401/403 error handling\nMODE: write\nCONTEXT: @[auth_patterns] @src/**/auth/**/* @src/**/guard/**/*\nEXPECTED: Complete authentication guide in {lang}\nCONSTRAINTS: Include code examples | Clear step-by-step instructions\n--rule development-feature",
|
||||
"output": "{auth_doc_name}"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/{overview_dir}/{auth_doc_name}"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 1-3: Unified Error Code Specification
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-003",
|
||||
"title": "Generate unified error code specification",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "swagger-error-codes",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Define unified error response format",
|
||||
"Create categorized error code system (auth, business, system)",
|
||||
"Provide detailed description and examples for each error code"
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate error code specification document",
|
||||
"cli_prompt": "PURPOSE: Generate comprehensive error code specification for consistent API error handling\nTASK:\n• Define error response format: {code, message, details, timestamp}\n• Document authentication errors (AUTH_xxx): 401/403 series\n• Document parameter errors (PARAM_xxx): 400 series\n• Document business errors (BIZ_xxx): business logic errors\n• Document system errors (SYS_xxx): 500 series\n• For each error code: HTTP status, error message, possible causes, resolution suggestions\nMODE: write\nCONTEXT: @src/**/*.exception.ts @src/**/*.filter.ts\nEXPECTED: Complete error code specification in {lang} with tables and examples\nCONSTRAINTS: Include response examples | Clear categorization\n--rule development-feature",
|
||||
"output": "{error_doc_name}"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/{overview_dir}/{error_doc_name}"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 2: Module API Documentation (Template)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-${module_task_id}",
|
||||
"title": "Generate ${module_name} API documentation",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-001", "IMPL-002", "IMPL-003"],
|
||||
"meta": {
|
||||
"type": "swagger-module-doc",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"module": "${module_name}",
|
||||
"endpoint_count": "${endpoint_count}"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Complete documentation for all endpoints in this module",
|
||||
"Each endpoint: description, method, URL, parameters, responses",
|
||||
"Include success and failure response examples",
|
||||
"Mark API version and last update time"
|
||||
],
|
||||
"focus_paths": ["${module_source_paths}"]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_module_endpoints",
|
||||
"action": "Load module endpoint information",
|
||||
"commands": [
|
||||
"bash(cat ${session_dir}/.process/swagger-planning-data.json | jq '.api_structure.modules[] | select(.name == \"${module_name}\")')"
|
||||
],
|
||||
"output_to": "module_endpoints"
|
||||
},
|
||||
{
|
||||
"step": "read_source_files",
|
||||
"action": "Read module source files",
|
||||
"commands": [
|
||||
"bash(cat ${module_source_files})"
|
||||
],
|
||||
"output_to": "source_code"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate module API documentation",
|
||||
"description": "Generate complete API documentation for ${module_name}",
|
||||
"cli_prompt": "PURPOSE: Generate complete RESTful API documentation for ${module_name} module\nTASK:\n• Create module overview: purpose, use cases, prerequisites\n• Generate endpoint index: grouped by functionality\n• For each endpoint document:\n - Functional description: purpose and business context\n - Request method: GET/POST/PUT/DELETE\n - URL path: complete API path\n - Request headers: Authorization and other required headers\n - Path parameters: {id} and other path variables\n - Query parameters: pagination, filters, etc.\n - Request body: JSON Schema format\n - Response body: success and error responses\n - Field description table: type, required, example, description\n• Add usage examples: cURL, JavaScript, Python\n• Add version info: v1.0.0, last updated date\nMODE: write\nCONTEXT: @[module_endpoints] @[source_code]\nEXPECTED: Complete module API documentation in {lang} with all endpoints fully documented\nCONSTRAINTS: RESTful standards | Include all response codes\n--rule documentation-swagger-api",
|
||||
"output": "${module_doc_name}"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/${module_dir}/${module_doc_name}"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 3: API Overview and Navigation
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-${overview_task_id}",
|
||||
"title": "Generate API overview and navigation",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-001", "...", "IMPL-${last_module_task_id}"],
|
||||
"meta": {
|
||||
"type": "swagger-overview",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini"
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_all_docs",
|
||||
"command": "bash(find .workflow/docs/${project_name}/api -type f -name '*.md' ! -path '*/{overview_dir}/*' | xargs cat)",
|
||||
"output_to": "all_module_docs"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate API overview",
|
||||
"cli_prompt": "PURPOSE: Generate API overview document with navigation and quick start guide\nTASK:\n• Create introduction: system features, tech stack, version\n• Write quick start guide: authentication, first request example\n• Build module navigation: categorized links to all modules\n• Document environment configuration: development, staging, production\n• List SDKs and tools: client libraries, Postman collection\nMODE: write\nCONTEXT: @[all_module_docs] @.workflow/docs/${project_name}/api/swagger.yaml\nEXPECTED: Complete API overview in {lang} with navigation links\nCONSTRAINTS: Clear structure | Quick start focus\n--rule development-feature",
|
||||
"output": "README.md"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/{overview_dir}/README.md"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 4: Validation Tasks
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-${test_task_id}",
|
||||
"title": "API endpoint validation tests",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-${overview_task_id}"],
|
||||
"meta": {
|
||||
"type": "swagger-validation",
|
||||
"agent": "@test-fix-agent",
|
||||
"tool": "codex"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Validate accessibility of all endpoints",
|
||||
"Test various boundary conditions",
|
||||
"Verify exception handling"
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_swagger_spec",
|
||||
"command": "bash(cat .workflow/docs/${project_name}/api/swagger.yaml)",
|
||||
"output_to": "swagger_spec"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate test report",
|
||||
"cli_prompt": "PURPOSE: Generate comprehensive API test validation report\nTASK:\n• Document test environment configuration\n• Calculate endpoint coverage statistics\n• Report test results: pass/fail counts\n• Document boundary tests: parameter limits, null values, special characters\n• Document exception tests: auth failures, permission denied, resource not found\n• List issues found with recommendations\nMODE: write\nCONTEXT: @[swagger_spec]\nEXPECTED: Complete test report in {lang} with detailed results\nCONSTRAINTS: Include test cases | Clear pass/fail status\n--rule development-tests",
|
||||
"output": "{test_doc_name}"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/{test_dir}/{test_doc_name}"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Language-Specific Directory Mapping
|
||||
|
||||
| Component | --lang zh | --lang en |
|
||||
|-----------|-----------|-----------|
|
||||
| Overview dir | 概述 | overview |
|
||||
| Auth doc | 认证说明.md | authentication.md |
|
||||
| Error doc | 错误码规范.md | error-codes.md |
|
||||
| Changelog | 版本历史.md | changelog.md |
|
||||
| Users module | 用户模块 | users |
|
||||
| Orders module | 订单模块 | orders |
|
||||
| Products module | 商品模块 | products |
|
||||
| Test dir | 测试报告 | test-reports |
|
||||
| API test doc | 接口测试.md | api-tests.md |
|
||||
| Boundary test doc | 边界测试.md | boundary-tests.md |
|
||||
|
||||
## API Documentation Template
|
||||
|
||||
### Single Endpoint Format
|
||||
|
||||
Each endpoint must include:
|
||||
|
||||
```markdown
|
||||
### Get User Details
|
||||
|
||||
**Description**: Retrieve detailed user information by ID, including profile and permissions.
|
||||
|
||||
**Endpoint Info**:
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Method | GET |
|
||||
| URL | `/api/v1/users/{id}` |
|
||||
| Version | v1.0.0 |
|
||||
| Updated | 2025-01-01 |
|
||||
| Auth | Bearer Token |
|
||||
| Permission | user / admin |
|
||||
|
||||
**Request Headers**:
|
||||
|
||||
| Field | Type | Required | Example | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| Authorization | string | Yes | `Bearer eyJhbGc...` | JWT Token |
|
||||
| Content-Type | string | No | `application/json` | Request content type |
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
| Field | Type | Required | Example | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| id | string | Yes | `usr_123456` | Unique user identifier |
|
||||
|
||||
**Query Parameters**:
|
||||
|
||||
| Field | Type | Required | Default | Example | Description |
|
||||
|-------|------|----------|---------|---------|-------------|
|
||||
| include | string | No | - | `roles,permissions` | Related data to include |
|
||||
|
||||
**Success Response** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": "usr_123456",
|
||||
"email": "user@example.com",
|
||||
"name": "John Doe",
|
||||
"status": "active",
|
||||
"roles": ["user"],
|
||||
"created_at": "2025-01-01T00:00:00Z",
|
||||
"updated_at": "2025-01-01T00:00:00Z"
|
||||
},
|
||||
"timestamp": "2025-01-01T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Response Fields**:
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| code | integer | Business status code, 0 = success |
|
||||
| message | string | Response message |
|
||||
| data.id | string | Unique user identifier |
|
||||
| data.email | string | User email address |
|
||||
| data.name | string | User display name |
|
||||
| data.status | string | User status: active/inactive/suspended |
|
||||
| data.roles | array | User role list |
|
||||
| data.created_at | string | Creation timestamp (ISO 8601) |
|
||||
| data.updated_at | string | Last update timestamp (ISO 8601) |
|
||||
|
||||
**Error Responses**:
|
||||
|
||||
| Status | Code | Message | Possible Cause |
|
||||
|--------|------|---------|----------------|
|
||||
| 401 | AUTH_001 | Invalid or expired token | Token format error or expired |
|
||||
| 403 | AUTH_003 | Insufficient permissions | No access to this user info |
|
||||
| 404 | USER_001 | User not found | User ID doesn't exist or deleted |
|
||||
|
||||
**Examples**:
|
||||
|
||||
```bash
|
||||
# cURL
|
||||
curl -X GET "https://api.example.com/api/v1/users/usr_123456" \
|
||||
-H "Authorization: Bearer eyJhbGc..." \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
```javascript
|
||||
// JavaScript (fetch)
|
||||
const response = await fetch('https://api.example.com/api/v1/users/usr_123456', {
|
||||
method: 'GET',
|
||||
headers: {
|
||||
'Authorization': 'Bearer eyJhbGc...',
|
||||
'Content-Type': 'application/json'
|
||||
}
|
||||
});
|
||||
const data = await response.json();
|
||||
```
|
||||
```
|
||||
|
||||
## Session Structure
|
||||
|
||||
```
|
||||
.workflow/active/
|
||||
└── WFS-swagger-{timestamp}/
|
||||
├── workflow-session.json
|
||||
├── IMPL_PLAN.md
|
||||
├── TODO_LIST.md
|
||||
├── .process/
|
||||
│ └── swagger-planning-data.json
|
||||
└── .task/
|
||||
├── IMPL-001.json # OpenAPI spec
|
||||
├── IMPL-002.json # Security config
|
||||
├── IMPL-003.json # Error codes
|
||||
├── IMPL-004.json # Module 1 API
|
||||
├── ...
|
||||
├── IMPL-N+1.json # API overview
|
||||
└── IMPL-N+2.json # Validation tests
|
||||
```
|
||||
|
||||
## Execution Commands
|
||||
|
||||
```bash
|
||||
# Execute entire workflow
|
||||
/workflow:execute
|
||||
|
||||
# Specify session
|
||||
/workflow:execute --resume-session="WFS-swagger-yyyymmdd-hhmmss"
|
||||
|
||||
# Single task execution
|
||||
/task:execute IMPL-001
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/workflow:execute` - Execute documentation tasks
|
||||
- `/workflow:status` - View task progress
|
||||
- `/workflow:session:complete` - Mark session complete
|
||||
- `/memory:docs` - General documentation workflow
|
||||
@@ -1,310 +0,0 @@
|
||||
---
|
||||
name: tech-research-rules
|
||||
description: "3-phase orchestrator: extract tech stack → Exa research → generate path-conditional rules (auto-loaded by Claude Code)"
|
||||
argument-hint: "[session-id | tech-stack-name] [--regenerate] [--tool <gemini|qwen>]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*)
|
||||
---
|
||||
|
||||
# Tech Stack Rules Generator
|
||||
|
||||
## Overview
|
||||
|
||||
**Purpose**: Generate multi-layered, path-conditional rules that Claude Code automatically loads based on file context.
|
||||
|
||||
**Output Structure**:
|
||||
```
|
||||
.claude/rules/tech/{tech-stack}/
|
||||
├── core.md # paths: **/*.{ext} - Core principles
|
||||
├── patterns.md # paths: src/**/*.{ext} - Implementation patterns
|
||||
├── testing.md # paths: **/*.{test,spec}.{ext} - Testing rules
|
||||
├── config.md # paths: *.config.* - Configuration rules
|
||||
├── api.md # paths: **/api/**/* - API rules (backend only)
|
||||
├── components.md # paths: **/components/**/* - Component rules (frontend only)
|
||||
└── metadata.json # Generation metadata
|
||||
```
|
||||
|
||||
**Templates Location**: `~/.claude/workflows/cli-templates/prompts/rules/`
|
||||
|
||||
---
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Start Immediately**: First action is TodoWrite initialization
|
||||
2. **Path-Conditional Output**: Every rule file includes `paths` frontmatter
|
||||
3. **Template-Driven**: Agent reads templates before generating content
|
||||
4. **Agent Produces Files**: Agent writes all rule files directly
|
||||
5. **No Manual Loading**: Rules auto-activate when Claude works with matching files
|
||||
|
||||
---
|
||||
|
||||
## 3-Phase Execution
|
||||
|
||||
### Phase 1: Prepare Context & Detect Tech Stack
|
||||
|
||||
**Goal**: Detect input mode, extract tech stack info, determine file extensions
|
||||
|
||||
**Input Mode Detection**:
|
||||
```bash
|
||||
input="$1"
|
||||
|
||||
if [[ "$input" == WFS-* ]]; then
|
||||
MODE="session"
|
||||
SESSION_ID="$input"
|
||||
# Read workflow-session.json to extract tech stack
|
||||
else
|
||||
MODE="direct"
|
||||
TECH_STACK_NAME="$input"
|
||||
fi
|
||||
```
|
||||
|
||||
**Tech Stack Analysis**:
|
||||
```javascript
|
||||
// Decompose composite tech stacks
|
||||
// "typescript-react-nextjs" → ["typescript", "react", "nextjs"]
|
||||
|
||||
const TECH_EXTENSIONS = {
|
||||
"typescript": "{ts,tsx}",
|
||||
"javascript": "{js,jsx}",
|
||||
"python": "py",
|
||||
"rust": "rs",
|
||||
"go": "go",
|
||||
"java": "java",
|
||||
"csharp": "cs",
|
||||
"ruby": "rb",
|
||||
"php": "php"
|
||||
};
|
||||
|
||||
const FRAMEWORK_TYPE = {
|
||||
"react": "frontend",
|
||||
"vue": "frontend",
|
||||
"angular": "frontend",
|
||||
"nextjs": "fullstack",
|
||||
"nuxt": "fullstack",
|
||||
"fastapi": "backend",
|
||||
"express": "backend",
|
||||
"django": "backend",
|
||||
"rails": "backend"
|
||||
};
|
||||
```
|
||||
|
||||
**Check Existing Rules**:
|
||||
```bash
|
||||
normalized_name=$(echo "$TECH_STACK_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
|
||||
rules_dir=".claude/rules/tech/${normalized_name}"
|
||||
existing_count=$(find "${rules_dir}" -name "*.md" 2>/dev/null | wc -l || echo 0)
|
||||
```
|
||||
|
||||
**Skip Decision**:
|
||||
- If `existing_count > 0` AND no `--regenerate` → `SKIP_GENERATION = true`
|
||||
- If `--regenerate` → Delete existing and regenerate
|
||||
|
||||
**Output Variables**:
|
||||
- `TECH_STACK_NAME`: Normalized name
|
||||
- `PRIMARY_LANG`: Primary language
|
||||
- `FILE_EXT`: File extension pattern
|
||||
- `FRAMEWORK_TYPE`: frontend | backend | fullstack | library
|
||||
- `COMPONENTS`: Array of tech components
|
||||
- `SKIP_GENERATION`: Boolean
|
||||
|
||||
**TodoWrite**: Mark phase 1 completed
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Agent Produces Path-Conditional Rules
|
||||
|
||||
**Skip Condition**: Skipped if `SKIP_GENERATION = true`
|
||||
|
||||
**Goal**: Delegate to agent for Exa research and rule file generation
|
||||
|
||||
**Template Files**:
|
||||
```
|
||||
~/.claude/workflows/cli-templates/prompts/rules/
|
||||
├── tech-rules-agent-prompt.txt # Agent instructions
|
||||
├── rule-core.txt # Core principles template
|
||||
├── rule-patterns.txt # Implementation patterns template
|
||||
├── rule-testing.txt # Testing rules template
|
||||
├── rule-config.txt # Configuration rules template
|
||||
├── rule-api.txt # API rules template (backend)
|
||||
└── rule-components.txt # Component rules template (frontend)
|
||||
```
|
||||
|
||||
**Agent Task**:
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
description: `Generate tech stack rules: ${TECH_STACK_NAME}`,
|
||||
prompt: `
|
||||
You are generating path-conditional rules for Claude Code.
|
||||
|
||||
## Context
|
||||
- Tech Stack: ${TECH_STACK_NAME}
|
||||
- Primary Language: ${PRIMARY_LANG}
|
||||
- File Extensions: ${FILE_EXT}
|
||||
- Framework Type: ${FRAMEWORK_TYPE}
|
||||
- Components: ${JSON.stringify(COMPONENTS)}
|
||||
- Output Directory: .claude/rules/tech/${TECH_STACK_NAME}/
|
||||
|
||||
## Instructions
|
||||
|
||||
Read the agent prompt template for detailed instructions.
|
||||
Use --rule rules-tech-rules-agent-prompt to load the template automatically.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
1. Execute Exa research queries (see agent prompt)
|
||||
2. Read each rule template
|
||||
3. Generate rule files following template structure
|
||||
4. Write files to output directory
|
||||
5. Write metadata.json
|
||||
6. Report completion
|
||||
|
||||
## Variable Substitutions
|
||||
|
||||
Replace in templates:
|
||||
- {TECH_STACK_NAME} → ${TECH_STACK_NAME}
|
||||
- {PRIMARY_LANG} → ${PRIMARY_LANG}
|
||||
- {FILE_EXT} → ${FILE_EXT}
|
||||
- {FRAMEWORK_TYPE} → ${FRAMEWORK_TYPE}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**Completion Criteria**:
|
||||
- 4-6 rule files written with proper `paths` frontmatter
|
||||
- metadata.json written
|
||||
- Agent reports files created
|
||||
|
||||
**TodoWrite**: Mark phase 2 completed
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Verify & Report
|
||||
|
||||
**Goal**: Verify generated files and provide usage summary
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Verify Files**:
|
||||
```bash
|
||||
find ".claude/rules/tech/${TECH_STACK_NAME}" -name "*.md" -type f
|
||||
```
|
||||
|
||||
2. **Validate Frontmatter**:
|
||||
```bash
|
||||
head -5 ".claude/rules/tech/${TECH_STACK_NAME}/core.md"
|
||||
```
|
||||
|
||||
3. **Read Metadata**:
|
||||
```javascript
|
||||
Read(`.claude/rules/tech/${TECH_STACK_NAME}/metadata.json`)
|
||||
```
|
||||
|
||||
4. **Generate Summary Report**:
|
||||
```
|
||||
Tech Stack Rules Generated
|
||||
|
||||
Tech Stack: {TECH_STACK_NAME}
|
||||
Location: .claude/rules/tech/{TECH_STACK_NAME}/
|
||||
|
||||
Files Created:
|
||||
├── core.md → paths: **/*.{ext}
|
||||
├── patterns.md → paths: src/**/*.{ext}
|
||||
├── testing.md → paths: **/*.{test,spec}.{ext}
|
||||
├── config.md → paths: *.config.*
|
||||
├── api.md → paths: **/api/**/* (if backend)
|
||||
└── components.md → paths: **/components/**/* (if frontend)
|
||||
|
||||
Auto-Loading:
|
||||
- Rules apply automatically when editing matching files
|
||||
- No manual loading required
|
||||
|
||||
Example Activation:
|
||||
- Edit src/components/Button.tsx → core.md + patterns.md + components.md
|
||||
- Edit tests/api.test.ts → core.md + testing.md
|
||||
- Edit package.json → config.md
|
||||
```
|
||||
|
||||
**TodoWrite**: Mark phase 3 completed
|
||||
|
||||
---
|
||||
|
||||
## Path Pattern Reference
|
||||
|
||||
| Pattern | Matches |
|
||||
|---------|---------|
|
||||
| `**/*.ts` | All .ts files |
|
||||
| `src/**/*` | All files under src/ |
|
||||
| `*.config.*` | Config files in root |
|
||||
| `**/*.{ts,tsx}` | .ts and .tsx files |
|
||||
|
||||
| Tech Stack | Core Pattern | Test Pattern |
|
||||
|------------|--------------|--------------|
|
||||
| TypeScript | `**/*.{ts,tsx}` | `**/*.{test,spec}.{ts,tsx}` |
|
||||
| Python | `**/*.py` | `**/test_*.py, **/*_test.py` |
|
||||
| Rust | `**/*.rs` | `**/tests/**/*.rs` |
|
||||
| Go | `**/*.go` | `**/*_test.go` |
|
||||
|
||||
---
|
||||
|
||||
## Parameters
|
||||
|
||||
```bash
|
||||
/memory:tech-research [session-id | "tech-stack-name"] [--regenerate]
|
||||
```
|
||||
|
||||
**Arguments**:
|
||||
- **session-id**: `WFS-*` format - Extract from workflow session
|
||||
- **tech-stack-name**: Direct input - `"typescript"`, `"typescript-react"`
|
||||
- **--regenerate**: Force regenerate existing rules
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Single Language
|
||||
|
||||
```bash
|
||||
/memory:tech-research "typescript"
|
||||
```
|
||||
|
||||
**Output**: `.claude/rules/tech/typescript/` with 4 rule files
|
||||
|
||||
### Frontend Stack
|
||||
|
||||
```bash
|
||||
/memory:tech-research "typescript-react"
|
||||
```
|
||||
|
||||
**Output**: `.claude/rules/tech/typescript-react/` with 5 rule files (includes components.md)
|
||||
|
||||
### Backend Stack
|
||||
|
||||
```bash
|
||||
/memory:tech-research "python-fastapi"
|
||||
```
|
||||
|
||||
**Output**: `.claude/rules/tech/python-fastapi/` with 5 rule files (includes api.md)
|
||||
|
||||
### From Session
|
||||
|
||||
```bash
|
||||
/memory:tech-research WFS-user-auth-20251104
|
||||
```
|
||||
|
||||
**Workflow**: Extract tech stack from session → Generate rules
|
||||
|
||||
---
|
||||
|
||||
## Comparison: Rules vs SKILL
|
||||
|
||||
| Aspect | SKILL Memory | Rules |
|
||||
|--------|--------------|-------|
|
||||
| Loading | Manual: `Skill("tech")` | Automatic by path |
|
||||
| Scope | All files when loaded | Only matching files |
|
||||
| Granularity | Monolithic packages | Per-file-type |
|
||||
| Context | Full package | Only relevant rules |
|
||||
|
||||
**When to Use**:
|
||||
- **Rules**: Tech stack conventions per file type
|
||||
- **SKILL**: Reference docs, APIs, examples for manual lookup
|
||||
477
.claude/commands/memory/tech-research.md
Normal file
477
.claude/commands/memory/tech-research.md
Normal file
@@ -0,0 +1,477 @@
|
||||
---
|
||||
name: tech-research
|
||||
description: 3-phase orchestrator: extract tech stack from session/name → delegate to agent for Exa research and module generation → generate SKILL.md index (skips phase 2 if exists)
|
||||
argument-hint: "[session-id | tech-stack-name] [--regenerate] [--tool <gemini|qwen>]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*)
|
||||
---
|
||||
|
||||
# Tech Stack Research SKILL Generator
|
||||
|
||||
## Overview
|
||||
|
||||
**Pure Orchestrator with Agent Delegation**: Prepares context paths and delegates ALL work to agent. Agent produces files directly.
|
||||
|
||||
**Auto-Continue Workflow**: Runs fully autonomously once triggered. Each phase completes and automatically triggers the next phase.
|
||||
|
||||
**Execution Paths**:
|
||||
- **Full Path**: All 3 phases (no existing SKILL OR `--regenerate` specified)
|
||||
- **Skip Path**: Phase 1 → Phase 3 (existing SKILL found AND no `--regenerate` flag)
|
||||
- **Phase 3 Always Executes**: SKILL index is always generated or updated
|
||||
|
||||
**Agent Responsibility**:
|
||||
- Agent does ALL the work: context reading, Exa research, content synthesis, file writing
|
||||
- Orchestrator only provides context paths and waits for completion
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
|
||||
2. **Context Path Delegation**: Pass session directory or tech stack name to agent, let agent do discovery
|
||||
3. **Agent Produces Files**: Agent directly writes all module files, orchestrator does NOT parse agent output
|
||||
4. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase
|
||||
5. **No User Prompts**: Never ask user questions or wait for input between phases
|
||||
6. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
|
||||
7. **Lightweight Index**: Phase 3 only generates SKILL.md index by reading existing files
|
||||
|
||||
---
|
||||
|
||||
## 3-Phase Execution
|
||||
|
||||
### Phase 1: Prepare Context Paths
|
||||
|
||||
**Goal**: Detect input mode, prepare context paths for agent, check existing SKILL
|
||||
|
||||
**Input Mode Detection**:
|
||||
```bash
|
||||
# Get input parameter
|
||||
input="$1"
|
||||
|
||||
# Detect mode
|
||||
if [[ "$input" == WFS-* ]]; then
|
||||
MODE="session"
|
||||
SESSION_ID="$input"
|
||||
CONTEXT_PATH=".workflow/${SESSION_ID}"
|
||||
else
|
||||
MODE="direct"
|
||||
TECH_STACK_NAME="$input"
|
||||
CONTEXT_PATH="$input" # Pass tech stack name as context
|
||||
fi
|
||||
```
|
||||
|
||||
**Check Existing SKILL**:
|
||||
```bash
|
||||
# For session mode, peek at session to get tech stack name
|
||||
if [[ "$MODE" == "session" ]]; then
|
||||
bash(test -f ".workflow/${SESSION_ID}/workflow-session.json")
|
||||
Read(.workflow/${SESSION_ID}/workflow-session.json)
|
||||
# Extract tech_stack_name (minimal extraction)
|
||||
fi
|
||||
|
||||
# Normalize and check
|
||||
normalized_name=$(echo "$TECH_STACK_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
|
||||
bash(test -d ".claude/skills/${normalized_name}" && echo "exists" || echo "not_exists")
|
||||
bash(find ".claude/skills/${normalized_name}" -name "*.md" 2>/dev/null | wc -l || echo 0)
|
||||
```
|
||||
|
||||
**Skip Decision**:
|
||||
```javascript
|
||||
if (existing_files > 0 && !regenerate_flag) {
|
||||
SKIP_GENERATION = true
|
||||
message = "Tech stack SKILL already exists, skipping Phase 2. Use --regenerate to force regeneration."
|
||||
} else if (regenerate_flag) {
|
||||
bash(rm -rf ".claude/skills/${normalized_name}")
|
||||
SKIP_GENERATION = false
|
||||
message = "Regenerating tech stack SKILL from scratch."
|
||||
} else {
|
||||
SKIP_GENERATION = false
|
||||
message = "No existing SKILL found, generating new tech stack documentation."
|
||||
}
|
||||
```
|
||||
|
||||
**Output Variables**:
|
||||
- `MODE`: `session` or `direct`
|
||||
- `SESSION_ID`: Session ID (if session mode)
|
||||
- `CONTEXT_PATH`: Path to session directory OR tech stack name
|
||||
- `TECH_STACK_NAME`: Extracted or provided tech stack name
|
||||
- `SKIP_GENERATION`: Boolean - whether to skip Phase 2
|
||||
|
||||
**TodoWrite**:
|
||||
- If skipping: Mark phase 1 completed, phase 2 completed, phase 3 in_progress
|
||||
- If not skipping: Mark phase 1 completed, phase 2 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Agent Produces All Files
|
||||
|
||||
**Skip Condition**: Skipped if `SKIP_GENERATION = true`
|
||||
|
||||
**Goal**: Delegate EVERYTHING to agent - context reading, Exa research, content synthesis, and file writing
|
||||
|
||||
**Agent Task Specification**:
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type: "general-purpose",
|
||||
description: "Generate tech stack SKILL: {CONTEXT_PATH}",
|
||||
prompt: "
|
||||
Generate a complete tech stack SKILL package with Exa research.
|
||||
|
||||
**Context Provided**:
|
||||
- Mode: {MODE}
|
||||
- Context Path: {CONTEXT_PATH}
|
||||
|
||||
**Templates Available**:
|
||||
- Module Format: ~/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt
|
||||
- SKILL Index: ~/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt
|
||||
|
||||
**Your Responsibilities**:
|
||||
|
||||
1. **Extract Tech Stack Information**:
|
||||
|
||||
IF MODE == 'session':
|
||||
- Read `.workflow/active/{session_id}/workflow-session.json`
|
||||
- Read `.workflow/active/{session_id}/.process/context-package.json`
|
||||
- Extract tech_stack: {language, frameworks, libraries}
|
||||
- Build tech stack name: \"{language}-{framework1}-{framework2}\"
|
||||
- Example: \"typescript-react-nextjs\"
|
||||
|
||||
IF MODE == 'direct':
|
||||
- Tech stack name = CONTEXT_PATH
|
||||
- Parse composite: split by '-' delimiter
|
||||
- Example: \"typescript-react-nextjs\" → [\"typescript\", \"react\", \"nextjs\"]
|
||||
|
||||
2. **Execute Exa Research** (4-6 parallel queries):
|
||||
|
||||
Base Queries (always execute):
|
||||
- mcp__exa__get_code_context_exa(query: \"{tech} core principles best practices 2025\", tokensNum: 8000)
|
||||
- mcp__exa__get_code_context_exa(query: \"{tech} common patterns architecture examples\", tokensNum: 7000)
|
||||
- mcp__exa__web_search_exa(query: \"{tech} configuration setup tooling 2025\", numResults: 5)
|
||||
- mcp__exa__get_code_context_exa(query: \"{tech} testing strategies\", tokensNum: 5000)
|
||||
|
||||
Component Queries (if composite):
|
||||
- For each additional component:
|
||||
mcp__exa__get_code_context_exa(query: \"{main_tech} {component} integration\", tokensNum: 5000)
|
||||
|
||||
3. **Read Module Format Template**:
|
||||
|
||||
Read template for structure guidance:
|
||||
```bash
|
||||
Read(~/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt)
|
||||
```
|
||||
|
||||
4. **Synthesize Content into 6 Modules**:
|
||||
|
||||
Follow template structure from tech-module-format.txt:
|
||||
- **principles.md** - Core concepts, philosophies (~3K tokens)
|
||||
- **patterns.md** - Implementation patterns with code examples (~5K tokens)
|
||||
- **practices.md** - Best practices, anti-patterns, pitfalls (~4K tokens)
|
||||
- **testing.md** - Testing strategies, frameworks (~3K tokens)
|
||||
- **config.md** - Setup, configuration, tooling (~3K tokens)
|
||||
- **frameworks.md** - Framework integration (only if composite, ~4K tokens)
|
||||
|
||||
Each module follows template format:
|
||||
- Frontmatter (YAML)
|
||||
- Main sections with clear headings
|
||||
- Code examples from Exa research
|
||||
- Best practices sections
|
||||
- References to Exa sources
|
||||
|
||||
5. **Write Files Directly**:
|
||||
|
||||
```javascript
|
||||
// Create directory
|
||||
bash(mkdir -p \".claude/skills/{tech_stack_name}\")
|
||||
|
||||
// Write each module file using Write tool
|
||||
Write({ file_path: \".claude/skills/{tech_stack_name}/principles.md\", content: ... })
|
||||
Write({ file_path: \".claude/skills/{tech_stack_name}/patterns.md\", content: ... })
|
||||
Write({ file_path: \".claude/skills/{tech_stack_name}/practices.md\", content: ... })
|
||||
Write({ file_path: \".claude/skills/{tech_stack_name}/testing.md\", content: ... })
|
||||
Write({ file_path: \".claude/skills/{tech_stack_name}/config.md\", content: ... })
|
||||
// Write frameworks.md only if composite
|
||||
|
||||
// Write metadata.json
|
||||
Write({
|
||||
file_path: \".claude/skills/{tech_stack_name}/metadata.json\",
|
||||
content: JSON.stringify({
|
||||
tech_stack_name,
|
||||
components,
|
||||
is_composite,
|
||||
generated_at: timestamp,
|
||||
source: \"exa-research\",
|
||||
research_summary: { total_queries, total_sources }
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
6. **Report Completion**:
|
||||
|
||||
Provide summary:
|
||||
- Tech stack name
|
||||
- Files created (count)
|
||||
- Exa queries executed
|
||||
- Sources consulted
|
||||
|
||||
**CRITICAL**:
|
||||
- MUST read external template files before generating content (step 3 for modules, step 4 for index)
|
||||
- You have FULL autonomy - read files, execute Exa, synthesize content, write files
|
||||
- Do NOT return JSON or structured data - produce actual .md files
|
||||
- Handle errors gracefully (Exa failures, missing files, template read failures)
|
||||
- If tech stack cannot be determined, ask orchestrator to clarify
|
||||
"
|
||||
)
|
||||
```
|
||||
|
||||
**Completion Criteria**:
|
||||
- Agent task executed successfully
|
||||
- 5-6 modular files written to `.claude/skills/{tech_stack_name}/`
|
||||
- metadata.json written
|
||||
- Agent reports completion
|
||||
|
||||
**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Generate SKILL.md Index
|
||||
|
||||
**Note**: This phase **ALWAYS executes** - generates or updates the SKILL index.
|
||||
|
||||
**Goal**: Read generated module files and create SKILL.md index with loading recommendations
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Verify Generated Files**:
|
||||
```bash
|
||||
bash(find ".claude/skills/${TECH_STACK_NAME}" -name "*.md" -type f | sort)
|
||||
```
|
||||
|
||||
2. **Read metadata.json**:
|
||||
```javascript
|
||||
Read(.claude/skills/${TECH_STACK_NAME}/metadata.json)
|
||||
// Extract: tech_stack_name, components, is_composite, research_summary
|
||||
```
|
||||
|
||||
3. **Read Module Headers** (optional, first 20 lines):
|
||||
```javascript
|
||||
Read(.claude/skills/${TECH_STACK_NAME}/principles.md, limit: 20)
|
||||
// Repeat for other modules
|
||||
```
|
||||
|
||||
4. **Read SKILL Index Template**:
|
||||
|
||||
```javascript
|
||||
Read(~/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt)
|
||||
```
|
||||
|
||||
5. **Generate SKILL.md Index**:
|
||||
|
||||
Follow template from tech-skill-index.txt with variable substitutions:
|
||||
- `{TECH_STACK_NAME}`: From metadata.json
|
||||
- `{MAIN_TECH}`: Primary technology
|
||||
- `{ISO_TIMESTAMP}`: Current timestamp
|
||||
- `{QUERY_COUNT}`: From research_summary
|
||||
- `{SOURCE_COUNT}`: From research_summary
|
||||
- Conditional sections for composite tech stacks
|
||||
|
||||
Template provides structure for:
|
||||
- Frontmatter with metadata
|
||||
- Overview and tech stack description
|
||||
- Module organization (Core/Practical/Config sections)
|
||||
- Loading recommendations (Quick/Implementation/Complete)
|
||||
- Usage guidelines and auto-trigger keywords
|
||||
- Research metadata and version history
|
||||
|
||||
6. **Write SKILL.md**:
|
||||
```javascript
|
||||
Write({
|
||||
file_path: `.claude/skills/${TECH_STACK_NAME}/SKILL.md`,
|
||||
content: generatedIndexMarkdown
|
||||
})
|
||||
```
|
||||
|
||||
**Completion Criteria**:
|
||||
- SKILL.md index written
|
||||
- All module files verified
|
||||
- Loading recommendations included
|
||||
|
||||
**TodoWrite**: Mark phase 3 completed
|
||||
|
||||
**Final Report**:
|
||||
```
|
||||
Tech Stack SKILL Package Complete
|
||||
|
||||
Tech Stack: {TECH_STACK_NAME}
|
||||
Location: .claude/skills/{TECH_STACK_NAME}/
|
||||
|
||||
Files: SKILL.md + 5-6 modules + metadata.json
|
||||
Exa Research: {queries} queries, {sources} sources
|
||||
|
||||
Usage: Skill(command: "{TECH_STACK_NAME}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### TodoWrite Patterns
|
||||
|
||||
**Initialization** (Before Phase 1):
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{"content": "Prepare context paths", "status": "in_progress", "activeForm": "Preparing context paths"},
|
||||
{"content": "Agent produces all module files", "status": "pending", "activeForm": "Agent producing files"},
|
||||
{"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL index"}
|
||||
]})
|
||||
```
|
||||
|
||||
**Full Path** (SKIP_GENERATION = false):
|
||||
```javascript
|
||||
// After Phase 1
|
||||
TodoWrite({todos: [
|
||||
{"content": "Prepare context paths", "status": "completed", ...},
|
||||
{"content": "Agent produces all module files", "status": "in_progress", ...},
|
||||
{"content": "Generate SKILL.md index", "status": "pending", ...}
|
||||
]})
|
||||
|
||||
// After Phase 2
|
||||
TodoWrite({todos: [
|
||||
{"content": "Prepare context paths", "status": "completed", ...},
|
||||
{"content": "Agent produces all module files", "status": "completed", ...},
|
||||
{"content": "Generate SKILL.md index", "status": "in_progress", ...}
|
||||
]})
|
||||
|
||||
// After Phase 3
|
||||
TodoWrite({todos: [
|
||||
{"content": "Prepare context paths", "status": "completed", ...},
|
||||
{"content": "Agent produces all module files", "status": "completed", ...},
|
||||
{"content": "Generate SKILL.md index", "status": "completed", ...}
|
||||
]})
|
||||
```
|
||||
|
||||
**Skip Path** (SKIP_GENERATION = true):
|
||||
```javascript
|
||||
// After Phase 1 (skip Phase 2)
|
||||
TodoWrite({todos: [
|
||||
{"content": "Prepare context paths", "status": "completed", ...},
|
||||
{"content": "Agent produces all module files", "status": "completed", ...}, // Skipped
|
||||
{"content": "Generate SKILL.md index", "status": "in_progress", ...}
|
||||
]})
|
||||
```
|
||||
|
||||
### Execution Flow
|
||||
|
||||
**Full Path**:
|
||||
```
|
||||
User → TodoWrite Init → Phase 1 (prepare) → Phase 2 (agent writes files) → Phase 3 (write index) → Report
|
||||
```
|
||||
|
||||
**Skip Path**:
|
||||
```
|
||||
User → TodoWrite Init → Phase 1 (detect existing) → Phase 3 (update index) → Report
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
**Phase 1 Errors**:
|
||||
- Invalid session ID: Report error, verify session exists
|
||||
- Missing context-package: Warn, fall back to direct mode
|
||||
- No tech stack detected: Ask user to specify tech stack name
|
||||
|
||||
**Phase 2 Errors (Agent)**:
|
||||
- Agent task fails: Retry once, report if fails again
|
||||
- Exa API failures: Agent handles internally with retries
|
||||
- Incomplete results: Warn user, proceed with partial data if minimum sections available
|
||||
|
||||
**Phase 3 Errors**:
|
||||
- Write failures: Report which files failed
|
||||
- Missing files: Note in SKILL.md, suggest regeneration
|
||||
|
||||
---
|
||||
|
||||
## Parameters
|
||||
|
||||
```bash
|
||||
/memory:tech-research [session-id | "tech-stack-name"] [--regenerate] [--tool <gemini|qwen>]
|
||||
```
|
||||
|
||||
**Arguments**:
|
||||
- **session-id | tech-stack-name**: Input source (auto-detected by WFS- prefix)
|
||||
- Session mode: `WFS-user-auth-v2` - Extract tech stack from workflow
|
||||
- Direct mode: `"typescript"`, `"typescript-react-nextjs"` - User specifies
|
||||
- **--regenerate**: Force regenerate existing SKILL (deletes and recreates)
|
||||
- **--tool**: Reserved for future CLI integration (default: gemini)
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
**Generated File Structure** (for all examples):
|
||||
```
|
||||
.claude/skills/{tech-stack}/
|
||||
├── SKILL.md # Index (Phase 3)
|
||||
├── principles.md # Agent (Phase 2)
|
||||
├── patterns.md # Agent
|
||||
├── practices.md # Agent
|
||||
├── testing.md # Agent
|
||||
├── config.md # Agent
|
||||
├── frameworks.md # Agent (if composite)
|
||||
└── metadata.json # Agent
|
||||
```
|
||||
|
||||
### Direct Mode - Single Stack
|
||||
|
||||
```bash
|
||||
/memory:tech-research "typescript"
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Detects direct mode, checks existing SKILL
|
||||
2. Phase 2: Agent executes 4 Exa queries, writes 5 modules
|
||||
3. Phase 3: Generates SKILL.md index
|
||||
|
||||
### Direct Mode - Composite Stack
|
||||
|
||||
```bash
|
||||
/memory:tech-research "typescript-react-nextjs"
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Decomposes into ["typescript", "react", "nextjs"]
|
||||
2. Phase 2: Agent executes 6 Exa queries (4 base + 2 components), writes 6 modules (adds frameworks.md)
|
||||
3. Phase 3: Generates SKILL.md index with framework integration
|
||||
|
||||
### Session Mode - Extract from Workflow
|
||||
|
||||
```bash
|
||||
/memory:tech-research WFS-user-auth-20251104
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Reads session, extracts tech stack: `python-fastapi-sqlalchemy`
|
||||
2. Phase 2: Agent researches Python + FastAPI + SQLAlchemy, writes 6 modules
|
||||
3. Phase 3: Generates SKILL.md index
|
||||
|
||||
### Regenerate Existing
|
||||
|
||||
```bash
|
||||
/memory:tech-research "react" --regenerate
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Deletes existing SKILL due to --regenerate
|
||||
2. Phase 2: Agent executes fresh Exa research (latest 2025 practices)
|
||||
3. Phase 3: Generates updated SKILL.md
|
||||
|
||||
### Skip Path - Fast Update
|
||||
|
||||
```bash
|
||||
/memory:tech-research "python"
|
||||
```
|
||||
|
||||
**Scenario**: SKILL already exists with 7 files
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Detects existing SKILL, sets SKIP_GENERATION = true
|
||||
2. Phase 2: **SKIPPED**
|
||||
3. Phase 3: Updates SKILL.md index only (5-10x faster)
|
||||
|
||||
|
||||
@@ -99,10 +99,10 @@ src/ (depth 1) → SINGLE-LAYER STRATEGY
|
||||
Bash({command: "git add -A 2>/dev/null || true", run_in_background: false});
|
||||
|
||||
// Get module structure
|
||||
Bash({command: "ccw tool exec get_modules_by_depth '{\"format\":\"list\"}'", run_in_background: false});
|
||||
Bash({command: "~/.claude/scripts/get_modules_by_depth.sh list", run_in_background: false});
|
||||
|
||||
// OR with --path
|
||||
Bash({command: "cd <target-path> && ccw tool exec get_modules_by_depth '{\"format\":\"list\"}'", run_in_background: false});
|
||||
Bash({command: "cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list", run_in_background: false});
|
||||
```
|
||||
|
||||
**Parse output** `depth:N|path:<PATH>|...` to extract module paths and count.
|
||||
@@ -185,7 +185,7 @@ for (let layer of [3, 2, 1]) {
|
||||
let strategy = module.depth >= 3 ? "multi-layer" : "single-layer";
|
||||
for (let tool of tool_order) {
|
||||
Bash({
|
||||
command: `cd ${module.path} && ccw tool exec update_module_claude '{"strategy":"${strategy}","path":".","tool":"${tool}"}'`,
|
||||
command: `cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "${tool}"`,
|
||||
run_in_background: false
|
||||
});
|
||||
if (bash_result.exit_code === 0) {
|
||||
@@ -244,7 +244,7 @@ MODULES:
|
||||
|
||||
TOOLS (try in order): {{tool_1}}, {{tool_2}}, {{tool_3}}
|
||||
|
||||
EXECUTION SCRIPT: ccw tool exec update_module_claude
|
||||
EXECUTION SCRIPT: ~/.claude/scripts/update_module_claude.sh
|
||||
- Accepts strategy parameter: multi-layer | single-layer
|
||||
- Tool execution via direct CLI commands (gemini/qwen/codex)
|
||||
|
||||
@@ -252,7 +252,7 @@ EXECUTION FLOW (for each module):
|
||||
1. Tool fallback loop (exit on first success):
|
||||
for tool in {{tool_1}} {{tool_2}} {{tool_3}}; do
|
||||
Bash({
|
||||
command: `cd "{{module_path}}" && ccw tool exec update_module_claude '{"strategy":"{{strategy}}","path":".","tool":"${tool}"}'`,
|
||||
command: `cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "{{strategy}}" "." "${tool}"`,
|
||||
run_in_background: false
|
||||
})
|
||||
exit_code=$?
|
||||
|
||||
@@ -41,7 +41,7 @@ Orchestrates context-aware CLAUDE.md updates for changed modules using batched a
|
||||
|
||||
```javascript
|
||||
// Detect changed modules
|
||||
Bash({command: "ccw tool exec detect_changed_modules '{\"format\":\"list\"}'", run_in_background: false});
|
||||
Bash({command: "~/.claude/scripts/detect_changed_modules.sh list", run_in_background: false});
|
||||
|
||||
// Cache git changes
|
||||
Bash({command: "git add -A 2>/dev/null || true", run_in_background: false});
|
||||
@@ -102,7 +102,7 @@ for (let depth of sorted_depths.reverse()) { // N → 0
|
||||
return async () => {
|
||||
for (let tool of tool_order) {
|
||||
Bash({
|
||||
command: `cd ${module.path} && ccw tool exec update_module_claude '{"strategy":"single-layer","path":".","tool":"${tool}"}'`,
|
||||
command: `cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "${tool}"`,
|
||||
run_in_background: false
|
||||
});
|
||||
if (bash_result.exit_code === 0) {
|
||||
@@ -184,21 +184,21 @@ EXECUTION:
|
||||
For each module above:
|
||||
1. Try tool 1:
|
||||
Bash({
|
||||
command: `cd "{{module_path}}" && ccw tool exec update_module_claude '{"strategy":"single-layer","path":".","tool":"{{tool_1}}"}'`,
|
||||
command: `cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_1}}"`,
|
||||
run_in_background: false
|
||||
})
|
||||
→ Success: Report "✅ {{module_path}} updated with {{tool_1}}", proceed to next module
|
||||
→ Failure: Try tool 2
|
||||
2. Try tool 2:
|
||||
Bash({
|
||||
command: `cd "{{module_path}}" && ccw tool exec update_module_claude '{"strategy":"single-layer","path":".","tool":"{{tool_2}}"}'`,
|
||||
command: `cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_2}}"`,
|
||||
run_in_background: false
|
||||
})
|
||||
→ Success: Report "✅ {{module_path}} updated with {{tool_2}}", proceed to next module
|
||||
→ Failure: Try tool 3
|
||||
3. Try tool 3:
|
||||
Bash({
|
||||
command: `cd "{{module_path}}" && ccw tool exec update_module_claude '{"strategy":"single-layer","path":".","tool":"{{tool_3}}"}'`,
|
||||
command: `cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_3}}"`,
|
||||
run_in_background: false
|
||||
})
|
||||
→ Success: Report "✅ {{module_path}} updated with {{tool_3}}", proceed to next module
|
||||
|
||||
@@ -187,7 +187,7 @@ Objectives:
|
||||
|
||||
3. Use Gemini for aggregation (optional):
|
||||
Command pattern:
|
||||
ccw cli -p "
|
||||
cd .workflow/.archives/{session_id} && gemini -p "
|
||||
PURPOSE: Extract lessons and conflicts from workflow session
|
||||
TASK:
|
||||
• Analyze IMPL_PLAN and lessons from manifest
|
||||
@@ -198,7 +198,7 @@ Objectives:
|
||||
CONTEXT: @IMPL_PLAN.md @workflow-session.json
|
||||
EXPECTED: Structured lessons and conflicts in JSON format
|
||||
RULES: Template reference from skill-aggregation.txt
|
||||
" --tool gemini --mode analysis --cd .workflow/.archives/{session_id}
|
||||
"
|
||||
|
||||
3.5. **Generate SKILL.md Description** (CRITICAL for auto-loading):
|
||||
|
||||
@@ -334,7 +334,7 @@ Objectives:
|
||||
- Sort sessions by date
|
||||
|
||||
2. Use Gemini for final aggregation:
|
||||
ccw cli -p "
|
||||
gemini -p "
|
||||
PURPOSE: Aggregate lessons and conflicts from all workflow sessions
|
||||
TASK:
|
||||
• Group successes by functional domain
|
||||
@@ -345,7 +345,7 @@ Objectives:
|
||||
CONTEXT: [Provide aggregated JSON data]
|
||||
EXPECTED: Final aggregated structure for SKILL documents
|
||||
RULES: Template reference from skill-aggregation.txt
|
||||
" --tool gemini --mode analysis
|
||||
"
|
||||
|
||||
3. Read templates for formatting (same 4 templates as single mode)
|
||||
|
||||
|
||||
@@ -1,13 +1,9 @@
|
||||
---
|
||||
name: breakdown
|
||||
description: Decompose complex task into subtasks with dependency mapping, creates child task JSONs with parent references and execution order
|
||||
argument-hint: "[-y|--yes] task-id"
|
||||
argument-hint: "task-id"
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-confirm breakdown, use recommended subtask structure.
|
||||
|
||||
# Task Breakdown Command (/task:breakdown)
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -1,14 +1,10 @@
|
||||
---
|
||||
name: replan
|
||||
description: Update task JSON with new requirements or batch-update multiple tasks from verification report, tracks changes in task-changes.json
|
||||
argument-hint: "[-y|--yes] task-id [\"text\"|file.md] | --batch [verification-report.md]"
|
||||
argument-hint: "task-id [\"text\"|file.md] | --batch [verification-report.md]"
|
||||
allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-confirm updates, use recommended changes.
|
||||
|
||||
# Task Replan Command (/task:replan)
|
||||
|
||||
> **⚠️ DEPRECATION NOTICE**: This command is maintained for backward compatibility. For new workflows, use `/workflow:replan` which provides:
|
||||
@@ -357,7 +353,7 @@ Review error details in summary report
|
||||
|
||||
# No replan recommendations found
|
||||
Verification report contains no replan recommendations
|
||||
Check report content or use /workflow:plan-verify first
|
||||
Check report content or use /workflow:action-plan-verify first
|
||||
```
|
||||
|
||||
## Batch Mode Integration
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: 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.
|
||||
name: action-plan-verify
|
||||
description: Perform non-destructive cross-artifact consistency analysis between IMPL_PLAN.md and task JSONs with quality gate validation
|
||||
argument-hint: "[optional: --session session-id]"
|
||||
allowed-tools: Read(*), Write(*), Glob(*), Bash(*)
|
||||
allowed-tools: Read(*), TodoWrite(*), Glob(*), Bash(*)
|
||||
---
|
||||
|
||||
## User Input
|
||||
@@ -15,26 +15,13 @@ You **MUST** consider the user input before proceeding (if not empty).
|
||||
|
||||
## Goal
|
||||
|
||||
Generate a comprehensive verification report that identifies inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`role analysis documents`). This command MUST run only after `/workflow:plan` has successfully produced complete `IMPL_PLAN.md` and task JSON files.
|
||||
|
||||
**Output**: A structured Markdown report saved to `.workflow/active/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md` containing:
|
||||
- Executive summary with quality gate recommendation
|
||||
- Detailed findings by severity (CRITICAL/HIGH/MEDIUM/LOW)
|
||||
- Requirements coverage analysis
|
||||
- Dependency integrity check
|
||||
- Synthesis alignment validation
|
||||
- Actionable remediation recommendations
|
||||
Identify inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`role analysis documents`) before implementation. This command MUST run only after `/workflow:plan` has successfully produced complete `IMPL_PLAN.md` and task JSON files.
|
||||
|
||||
## Operating Constraints
|
||||
|
||||
**STRICTLY READ-ONLY FOR SOURCE ARTIFACTS**:
|
||||
- **MUST NOT** modify `IMPL_PLAN.md`, any `task.json` files, or brainstorming artifacts
|
||||
- **MUST NOT** create or delete task files
|
||||
- **MUST ONLY** write the verification report to `.process/ACTION_PLAN_VERIFICATION.md`
|
||||
**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands).
|
||||
|
||||
**Synthesis Authority**: The `role analysis documents` are **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasks—not reinterpretation of requirements.
|
||||
|
||||
**Quality Gate Authority**: The verification report provides a binding recommendation (BLOCK_EXECUTION / PROCEED_WITH_FIXES / PROCEED_WITH_CAUTION / PROCEED) based on objective severity criteria. User MUST review critical/high issues before proceeding with implementation.
|
||||
**Synthesis Authority**: The `role analysis documents` is **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasks—not reinterpretation of requirements.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
@@ -60,12 +47,6 @@ ELSE:
|
||||
session_dir = .workflow/active/WFS-{session}
|
||||
brainstorm_dir = session_dir/.brainstorming
|
||||
task_dir = session_dir/.task
|
||||
process_dir = session_dir/.process
|
||||
session_file = session_dir/workflow-session.json
|
||||
|
||||
# Create .process directory if not exists (report output location)
|
||||
IF NOT EXISTS(process_dir):
|
||||
bash(mkdir -p "{process_dir}")
|
||||
|
||||
# Validate required artifacts
|
||||
# Note: "role analysis documents" refers to [role]/analysis.md files (e.g., product-manager/analysis.md)
|
||||
@@ -73,12 +54,7 @@ SYNTHESIS_DIR = brainstorm_dir # Contains role analysis files: */analysis.md
|
||||
IMPL_PLAN = session_dir/IMPL_PLAN.md
|
||||
TASK_FILES = Glob(task_dir/*.json)
|
||||
|
||||
# Abort if missing - in order of dependency
|
||||
SESSION_FILE_EXISTS = EXISTS(session_file)
|
||||
IF NOT SESSION_FILE_EXISTS:
|
||||
WARNING: "workflow-session.json not found. User intent alignment verification will be skipped."
|
||||
# Continue execution - this is optional context, not blocking
|
||||
|
||||
# Abort if missing
|
||||
SYNTHESIS_FILES = Glob(brainstorm_dir/*/analysis.md)
|
||||
IF SYNTHESIS_FILES.count == 0:
|
||||
ERROR: "No role analysis documents found in .brainstorming/*/analysis.md. Run /workflow:brainstorm:synthesis first"
|
||||
@@ -97,14 +73,12 @@ IF TASK_FILES.count == 0:
|
||||
|
||||
Load only minimal necessary context from each artifact:
|
||||
|
||||
**From workflow-session.json** (OPTIONAL - Primary Reference for User Intent):
|
||||
- **ONLY IF EXISTS**: Load user intent context
|
||||
**From workflow-session.json** (NEW - PRIMARY REFERENCE):
|
||||
- Original user prompt/intent (project or description field)
|
||||
- User's stated goals and objectives
|
||||
- User's scope definition
|
||||
- **IF MISSING**: Set user_intent_analysis = "SKIPPED: workflow-session.json not found"
|
||||
|
||||
**From role analysis documents** (AUTHORITATIVE SOURCE):
|
||||
**From role analysis documents**:
|
||||
- Functional Requirements (IDs, descriptions, acceptance criteria)
|
||||
- Non-Functional Requirements (IDs, targets)
|
||||
- Business Requirements (IDs, success metrics)
|
||||
@@ -152,21 +126,9 @@ Create internal representations (do not include raw artifacts in output):
|
||||
|
||||
### 4. Detection Passes (Token-Efficient Analysis)
|
||||
|
||||
**Token Budget Strategy**:
|
||||
- **Total Limit**: 50 findings maximum (aggregate remainder in overflow summary)
|
||||
- **Priority Allocation**: CRITICAL (unlimited) → HIGH (15) → MEDIUM (20) → LOW (15)
|
||||
- **Early Exit**: If CRITICAL findings > 0 in User Intent/Requirements Coverage, skip LOW/MEDIUM priority checks
|
||||
Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
|
||||
|
||||
**Execution Order** (Process in sequence; skip if token budget exhausted):
|
||||
|
||||
1. **Tier 1 (CRITICAL Path)**: A, B, C - User intent, coverage, consistency (process fully)
|
||||
2. **Tier 2 (HIGH Priority)**: D, E - Dependencies, synthesis alignment (limit 15 findings total)
|
||||
3. **Tier 3 (MEDIUM Priority)**: F - Specification quality (limit 20 findings)
|
||||
4. **Tier 4 (LOW Priority)**: G, H - Duplication, feasibility (limit 15 findings total)
|
||||
|
||||
---
|
||||
|
||||
#### A. User Intent Alignment (CRITICAL - Tier 1)
|
||||
#### A. User Intent Alignment (NEW - CRITICAL)
|
||||
|
||||
- **Goal Alignment**: IMPL_PLAN objectives match user's original intent
|
||||
- **Scope Drift**: Plan covers user's stated scope without unauthorized expansion
|
||||
|
||||
@@ -81,7 +81,6 @@ ELSE:
|
||||
**Framework-Based Analysis** (when guidance-specification.md exists):
|
||||
```bash
|
||||
Task(subagent_type="conceptual-planning-agent",
|
||||
run_in_background=false,
|
||||
prompt="Generate API designer analysis addressing topic framework
|
||||
|
||||
## Framework Integration Required
|
||||
@@ -137,7 +136,6 @@ Task(subagent_type="conceptual-planning-agent",
|
||||
# For existing analysis updates
|
||||
IF update_mode = "incremental":
|
||||
Task(subagent_type="conceptual-planning-agent",
|
||||
run_in_background=false,
|
||||
prompt="Update existing API designer analysis
|
||||
|
||||
## Current Analysis Context
|
||||
|
||||
@@ -1,14 +1,10 @@
|
||||
---
|
||||
name: artifacts
|
||||
description: Interactive clarification generating confirmed guidance specification through role-based analysis and synthesis
|
||||
argument-hint: "[-y|--yes] topic or challenge description [--count N]"
|
||||
argument-hint: "topic or challenge description [--count N]"
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), AskUserQuestion(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-select recommended roles, skip all clarification questions, use default answers.
|
||||
|
||||
## Overview
|
||||
|
||||
Seven-phase workflow: **Context collection** → **Topic analysis** → **Role selection** → **Role questions** → **Conflict resolution** → **Final check** → **Generate specification**
|
||||
@@ -132,7 +128,6 @@ for (let i = 0; i < allQuestions.length; i += BATCH_SIZE) {
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="context-search-agent",
|
||||
run_in_background=false,
|
||||
description="Gather project context for brainstorm",
|
||||
prompt=`
|
||||
Execute context-search-agent in BRAINSTORM MODE (Phase 1-2 only).
|
||||
|
||||
@@ -1,23 +1,19 @@
|
||||
---
|
||||
name: auto-parallel
|
||||
description: Parallel brainstorming automation with dynamic role selection and concurrent execution across multiple perspectives
|
||||
argument-hint: "[-y|--yes] topic or challenge description [--count N]"
|
||||
argument-hint: "topic or challenge description" [--count N]
|
||||
allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-select recommended roles, skip all clarification questions, use default answers.
|
||||
|
||||
# Workflow Brainstorm Parallel Auto Command
|
||||
|
||||
## Coordinator Role
|
||||
|
||||
**This command is a pure orchestrator**: Executes 3 phases in sequence (interactive framework → parallel role analysis → synthesis), coordinating specialized commands/agents through task attachment model.
|
||||
**This command is a pure orchestrator**: Dispatches 3 phases in sequence (interactive framework → parallel role analysis → synthesis), coordinating specialized commands/agents through task attachment model.
|
||||
|
||||
**Task Attachment Model**:
|
||||
- SlashCommand execute **expands workflow** by attaching sub-tasks to current TodoWrite
|
||||
- Task agent execute **attaches analysis tasks** to orchestrator's TodoWrite
|
||||
- SlashCommand dispatch **expands workflow** by attaching sub-tasks to current TodoWrite
|
||||
- Task agent dispatch **attaches analysis tasks** to orchestrator's TodoWrite
|
||||
- Phase 1: artifacts command attaches its internal tasks (Phase 1-5)
|
||||
- Phase 2: N conceptual-planning-agent tasks attached in parallel
|
||||
- Phase 3: synthesis command attaches its internal tasks
|
||||
@@ -30,9 +26,9 @@ When `--yes` or `-y`: Auto-select recommended roles, skip all clarification ques
|
||||
This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) handles user interaction, Phase 2 (role agents) runs in parallel.
|
||||
|
||||
1. **User triggers**: `/workflow:brainstorm:auto-parallel "topic" [--count N]`
|
||||
2. **Execute Phase 1** → artifacts command (tasks ATTACHED) → Auto-continues
|
||||
3. **Execute Phase 2** → Parallel role agents (N tasks ATTACHED concurrently) → Auto-continues
|
||||
4. **Execute Phase 3** → Synthesis command (tasks ATTACHED) → Reports final summary
|
||||
2. **Dispatch Phase 1** → artifacts command (tasks ATTACHED) → Auto-continues
|
||||
3. **Dispatch Phase 2** → Parallel role agents (N tasks ATTACHED concurrently) → Auto-continues
|
||||
4. **Dispatch Phase 3** → Synthesis command (tasks ATTACHED) → Reports final summary
|
||||
|
||||
**Auto-Continue Mechanism**:
|
||||
- TodoList tracks current phase status and dynamically manages task attachment/collapse
|
||||
@@ -42,13 +38,13 @@ This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) ha
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Start Immediately**: First action is TodoWrite initialization, second action is execute Phase 1 command
|
||||
1. **Start Immediately**: First action is TodoWrite initialization, second action is dispatch Phase 1 command
|
||||
2. **No Preliminary Analysis**: Do not analyze topic before Phase 1 - artifacts handles all analysis
|
||||
3. **Parse Every Output**: Extract selected_roles from workflow-session.json after Phase 1
|
||||
4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
|
||||
4. **Auto-Continue via TodoList**: Check TodoList status to dispatch next pending phase automatically
|
||||
5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
|
||||
6. **Task Attachment Model**: SlashCommand and Task executes **attach** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
|
||||
7. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
|
||||
6. **Task Attachment Model**: SlashCommand and Task dispatches **attach** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
|
||||
7. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and dispatch next phase
|
||||
8. **Parallel Execution**: Phase 2 attaches multiple agent tasks simultaneously for concurrent execution
|
||||
|
||||
## Usage
|
||||
@@ -71,7 +67,7 @@ This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) ha
|
||||
|
||||
### Phase 1: Interactive Framework Generation
|
||||
|
||||
**Step 1: Execute** - Interactive framework generation via artifacts command
|
||||
**Step 1: Dispatch** - Interactive framework generation via artifacts command
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:brainstorm:artifacts \"{topic}\" --count {N}")
|
||||
@@ -95,7 +91,7 @@ SlashCommand(command="/workflow:brainstorm:artifacts \"{topic}\" --count {N}")
|
||||
- workflow-session.json contains selected_roles[] (metadata only, no content duplication)
|
||||
- Session directory `.workflow/active/WFS-{topic}/.brainstorming/` exists
|
||||
|
||||
**TodoWrite Update (Phase 1 SlashCommand executed - tasks attached)**:
|
||||
**TodoWrite Update (Phase 1 SlashCommand dispatched - tasks attached)**:
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 0: Parameter Parsing", "status": "completed", "activeForm": "Parsing count parameter"},
|
||||
@@ -110,7 +106,7 @@ SlashCommand(command="/workflow:brainstorm:artifacts \"{topic}\" --count {N}")
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: SlashCommand execute **attaches** artifacts' 5 internal tasks. Orchestrator **executes** these tasks sequentially.
|
||||
**Note**: SlashCommand dispatch **attaches** artifacts' 5 internal tasks. Orchestrator **executes** these tasks sequentially.
|
||||
|
||||
**Next Action**: Tasks attached → **Execute Phase 1.1-1.5** sequentially
|
||||
|
||||
@@ -171,7 +167,7 @@ TOPIC: {user-provided-topic}
|
||||
"
|
||||
```
|
||||
|
||||
**Parallel Execute**:
|
||||
**Parallel Dispatch**:
|
||||
- Launch N agents simultaneously (one message with multiple Task calls)
|
||||
- Each agent task **attached** to orchestrator's TodoWrite
|
||||
- All agents execute concurrently, each attaching their own analysis sub-tasks
|
||||
@@ -189,7 +185,7 @@ TOPIC: {user-provided-topic}
|
||||
- **FORBIDDEN**: `recommendations.md` or any non-`analysis` prefixed files
|
||||
- All N role analyses completed
|
||||
|
||||
**TodoWrite Update (Phase 2 agents executed - tasks attached in parallel)**:
|
||||
**TodoWrite Update (Phase 2 agents dispatched - tasks attached in parallel)**:
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 0: Parameter Parsing", "status": "completed", "activeForm": "Parsing count parameter"},
|
||||
@@ -202,7 +198,7 @@ TOPIC: {user-provided-topic}
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: Multiple Task executes **attach** N role analysis tasks simultaneously. Orchestrator **executes** these tasks in parallel.
|
||||
**Note**: Multiple Task dispatches **attach** N role analysis tasks simultaneously. Orchestrator **executes** these tasks in parallel.
|
||||
|
||||
**Next Action**: Tasks attached → **Execute Phase 2.1-2.N** concurrently
|
||||
|
||||
@@ -224,7 +220,7 @@ TOPIC: {user-provided-topic}
|
||||
|
||||
### Phase 3: Synthesis Generation
|
||||
|
||||
**Step 3: Execute** - Synthesis integration via synthesis command
|
||||
**Step 3: Dispatch** - Synthesis integration via synthesis command
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:brainstorm:synthesis --session {sessionId}")
|
||||
@@ -242,7 +238,7 @@ SlashCommand(command="/workflow:brainstorm:synthesis --session {sessionId}")
|
||||
- `.workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.md` exists
|
||||
- Synthesis references all role analyses
|
||||
|
||||
**TodoWrite Update (Phase 3 SlashCommand executed - tasks attached)**:
|
||||
**TodoWrite Update (Phase 3 SlashCommand dispatched - tasks attached)**:
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 0: Parameter Parsing", "status": "completed", "activeForm": "Parsing count parameter"},
|
||||
@@ -255,7 +251,7 @@ SlashCommand(command="/workflow:brainstorm:synthesis --session {sessionId}")
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: SlashCommand execute **attaches** synthesis' internal tasks. Orchestrator **executes** these tasks sequentially.
|
||||
**Note**: SlashCommand dispatch **attaches** synthesis' internal tasks. Orchestrator **executes** these tasks sequentially.
|
||||
|
||||
**Next Action**: Tasks attached → **Execute Phase 3.1-3.3** sequentially
|
||||
|
||||
@@ -288,7 +284,7 @@ Synthesis: .workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.m
|
||||
|
||||
### Key Principles
|
||||
|
||||
1. **Task Attachment** (when SlashCommand/Task executed):
|
||||
1. **Task Attachment** (when SlashCommand/Task dispatched):
|
||||
- Sub-command's or agent's internal tasks are **attached** to orchestrator's TodoWrite
|
||||
- Phase 1: `/workflow:brainstorm:artifacts` attaches 5 internal tasks (Phase 1.1-1.5)
|
||||
- Phase 2: Multiple `Task(conceptual-planning-agent)` calls attach N role analysis tasks simultaneously
|
||||
@@ -309,7 +305,7 @@ Synthesis: .workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.m
|
||||
- No user intervention required between phases
|
||||
- TodoWrite dynamically reflects current execution state
|
||||
|
||||
**Lifecycle Summary**: Initial pending tasks → Phase 1 executed (artifacts tasks ATTACHED) → Artifacts sub-tasks executed → Phase 1 completed (tasks COLLAPSED) → Phase 2 executed (N role tasks ATTACHED in parallel) → Role analyses executed concurrently → Phase 2 completed (tasks COLLAPSED) → Phase 3 executed (synthesis tasks ATTACHED) → Synthesis sub-tasks executed → Phase 3 completed (tasks COLLAPSED) → Workflow complete.
|
||||
**Lifecycle Summary**: Initial pending tasks → Phase 1 dispatched (artifacts tasks ATTACHED) → Artifacts sub-tasks executed → Phase 1 completed (tasks COLLAPSED) → Phase 2 dispatched (N role tasks ATTACHED in parallel) → Role analyses executed concurrently → Phase 2 completed (tasks COLLAPSED) → Phase 3 dispatched (synthesis tasks ATTACHED) → Synthesis sub-tasks executed → Phase 3 completed (tasks COLLAPSED) → Workflow complete.
|
||||
|
||||
### Brainstorming Workflow Specific Features
|
||||
|
||||
@@ -428,17 +424,6 @@ CONTEXT_VARS:
|
||||
- **Agent execution failure**: Agent-specific retry with minimal dependencies
|
||||
- **Template loading issues**: Agent handles graceful degradation
|
||||
- **Synthesis conflicts**: Synthesis highlights disagreements without resolution
|
||||
- **Context overflow protection**: See below for automatic context management
|
||||
|
||||
## Context Overflow Protection
|
||||
|
||||
**Per-role limits**: See `conceptual-planning-agent.md` (< 3000 words main, < 2000 words sub-docs, max 5 sub-docs)
|
||||
|
||||
**Synthesis protection**: If total analysis > 100KB, synthesis reads only `analysis.md` files (not sub-documents)
|
||||
|
||||
**Recovery**: Check logs → reduce scope (--count 2) → use --summary-only → manual synthesis
|
||||
|
||||
**Prevention**: Start with --count 3, use structured topic format, review output sizes before synthesis
|
||||
|
||||
## Reference Information
|
||||
|
||||
|
||||
@@ -1,14 +1,10 @@
|
||||
---
|
||||
name: synthesis
|
||||
description: Clarify and refine role analyses through intelligent Q&A and targeted updates with synthesis agent
|
||||
argument-hint: "[-y|--yes] [optional: --session session-id]"
|
||||
argument-hint: "[optional: --session session-id]"
|
||||
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*), Edit(*), Glob(*), AskUserQuestion(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-select all enhancements, skip clarification questions, use default answers.
|
||||
|
||||
## Overview
|
||||
|
||||
Six-phase workflow to eliminate ambiguities and enhance conceptual depth in role analyses:
|
||||
|
||||
@@ -81,7 +81,6 @@ ELSE:
|
||||
**Framework-Based Analysis** (when guidance-specification.md exists):
|
||||
```bash
|
||||
Task(subagent_type="conceptual-planning-agent",
|
||||
run_in_background=false,
|
||||
prompt="Generate system architect analysis addressing topic framework
|
||||
|
||||
## Framework Integration Required
|
||||
@@ -137,7 +136,6 @@ Task(subagent_type="conceptual-planning-agent",
|
||||
# For existing analysis updates
|
||||
IF update_mode = "incremental":
|
||||
Task(subagent_type="conceptual-planning-agent",
|
||||
run_in_background=false,
|
||||
prompt="Update existing system architect analysis
|
||||
|
||||
## Current Analysis Context
|
||||
|
||||
@@ -1,548 +0,0 @@
|
||||
---
|
||||
name: clean
|
||||
description: Intelligent code cleanup with mainline detection, stale artifact discovery, and safe execution
|
||||
argument-hint: "[-y|--yes] [--dry-run] [\"focus area\"]"
|
||||
allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Glob(*), Bash(*), Write(*)
|
||||
---
|
||||
|
||||
# Clean Command (/workflow:clean)
|
||||
|
||||
## Overview
|
||||
|
||||
Intelligent cleanup command that explores the codebase to identify the development mainline, discovers artifacts that have drifted from it, and safely removes stale sessions, abandoned documents, and dead code.
|
||||
|
||||
**Core capabilities:**
|
||||
- Mainline detection: Identify active development branches and core modules
|
||||
- Drift analysis: Find sessions, documents, and code that deviate from mainline
|
||||
- Intelligent discovery: cli-explore-agent based artifact scanning
|
||||
- Safe execution: Confirmation-based cleanup with dry-run preview
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/workflow:clean # Full intelligent cleanup (explore → analyze → confirm → execute)
|
||||
/workflow:clean --yes # Auto mode (use safe defaults, no confirmation)
|
||||
/workflow:clean --dry-run # Explore and analyze only, no execution
|
||||
/workflow:clean -y "auth module" # Auto mode with focus area
|
||||
```
|
||||
|
||||
## Auto Mode Defaults
|
||||
|
||||
When `--yes` or `-y` flag is used:
|
||||
- **Categories to Clean**: Auto-selects `["Sessions"]` only (safest - only workflow sessions)
|
||||
- **Risk Level**: Auto-selects `"Low only"` (only low-risk items)
|
||||
- All confirmations skipped, proceeds directly to execution
|
||||
|
||||
**Flag Parsing**:
|
||||
```javascript
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
const dryRun = $ARGUMENTS.includes('--dry-run')
|
||||
```
|
||||
|
||||
## Execution Process
|
||||
|
||||
```
|
||||
Phase 1: Mainline Detection
|
||||
├─ Analyze git history for development trends
|
||||
├─ Identify core modules (high commit frequency)
|
||||
├─ Map active vs stale branches
|
||||
└─ Build mainline profile
|
||||
|
||||
Phase 2: Drift Discovery (cli-explore-agent)
|
||||
├─ Scan workflow sessions for orphaned artifacts
|
||||
├─ Identify documents drifted from mainline
|
||||
├─ Detect dead code and unused exports
|
||||
└─ Generate cleanup manifest
|
||||
|
||||
Phase 3: Confirmation
|
||||
├─ Display cleanup summary by category
|
||||
├─ Show impact analysis (files, size, risk)
|
||||
└─ AskUserQuestion: Select categories to clean
|
||||
|
||||
Phase 4: Execution (unless --dry-run)
|
||||
├─ Execute cleanup by category
|
||||
├─ Update manifests and indexes
|
||||
└─ Report results
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
### Phase 1: Mainline Detection
|
||||
|
||||
**Session Setup**:
|
||||
```javascript
|
||||
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
|
||||
|
||||
const dateStr = getUtc8ISOString().substring(0, 10)
|
||||
const sessionId = `clean-${dateStr}`
|
||||
const sessionFolder = `.workflow/.clean/${sessionId}`
|
||||
|
||||
Bash(`mkdir -p ${sessionFolder}`)
|
||||
```
|
||||
|
||||
**Step 1.1: Git History Analysis**
|
||||
```bash
|
||||
# Get commit frequency by directory (last 30 days)
|
||||
bash(git log --since="30 days ago" --name-only --pretty=format: | grep -v "^$" | cut -d/ -f1-2 | sort | uniq -c | sort -rn | head -20)
|
||||
|
||||
# Get recent active branches
|
||||
bash(git for-each-ref --sort=-committerdate refs/heads/ --format='%(refname:short) %(committerdate:relative)' | head -10)
|
||||
|
||||
# Get files with most recent changes
|
||||
bash(git log --since="7 days ago" --name-only --pretty=format: | grep -v "^$" | sort | uniq -c | sort -rn | head -30)
|
||||
```
|
||||
|
||||
**Step 1.2: Build Mainline Profile**
|
||||
```javascript
|
||||
const mainlineProfile = {
|
||||
coreModules: [], // High-frequency directories
|
||||
activeFiles: [], // Recently modified files
|
||||
activeBranches: [], // Branches with recent commits
|
||||
staleThreshold: {
|
||||
sessions: 7, // Days
|
||||
branches: 30,
|
||||
documents: 14
|
||||
},
|
||||
timestamp: getUtc8ISOString()
|
||||
}
|
||||
|
||||
// Parse git log output to identify core modules
|
||||
// Modules with >5 commits in last 30 days = core
|
||||
// Modules with 0 commits in last 30 days = potentially stale
|
||||
|
||||
Write(`${sessionFolder}/mainline-profile.json`, JSON.stringify(mainlineProfile, null, 2))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Drift Discovery
|
||||
|
||||
**Launch cli-explore-agent for intelligent artifact scanning**:
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
run_in_background=false,
|
||||
description="Discover stale artifacts",
|
||||
prompt=`
|
||||
## Task Objective
|
||||
Discover artifacts that have drifted from the development mainline. Identify stale sessions, abandoned documents, and dead code for cleanup.
|
||||
|
||||
## Context
|
||||
- **Session Folder**: ${sessionFolder}
|
||||
- **Mainline Profile**: ${sessionFolder}/mainline-profile.json
|
||||
- **Focus Area**: ${focusArea || "全项目"}
|
||||
|
||||
## Discovery Categories
|
||||
|
||||
### Category 1: Stale Workflow Sessions
|
||||
Scan and analyze workflow session directories:
|
||||
|
||||
**Locations to scan**:
|
||||
- .workflow/active/WFS-* (active sessions)
|
||||
- .workflow/archives/WFS-* (archived sessions)
|
||||
- .workflow/.lite-plan/* (lite-plan sessions)
|
||||
- .workflow/.debug/DBG-* (debug sessions)
|
||||
|
||||
**Staleness criteria**:
|
||||
- Active sessions: No modification >7 days + no related git commits
|
||||
- Archives: >30 days old + no feature references in project-tech.json
|
||||
- Lite-plan: >7 days old + plan.json not executed
|
||||
- Debug: >3 days old + issue not in recent commits
|
||||
|
||||
**Analysis steps**:
|
||||
1. List all session directories with modification times
|
||||
2. Cross-reference with git log (are session topics in recent commits?)
|
||||
3. Check manifest.json for orphan entries
|
||||
4. Identify sessions with .archiving marker (interrupted)
|
||||
|
||||
### Category 2: Drifted Documents
|
||||
Scan documentation that no longer aligns with code:
|
||||
|
||||
**Locations to scan**:
|
||||
- .claude/rules/tech/* (generated tech rules)
|
||||
- .workflow/.scratchpad/* (temporary notes)
|
||||
- **/CLAUDE.md (module documentation)
|
||||
- **/README.md (outdated descriptions)
|
||||
|
||||
**Drift criteria**:
|
||||
- Tech rules: Referenced files no longer exist
|
||||
- Scratchpad: Any file (always temporary)
|
||||
- Module docs: Describe functions/classes that were removed
|
||||
- READMEs: Reference deleted directories
|
||||
|
||||
**Analysis steps**:
|
||||
1. Parse document content for file/function references
|
||||
2. Verify referenced entities still exist in codebase
|
||||
3. Flag documents with >30% broken references
|
||||
|
||||
### Category 3: Dead Code
|
||||
Identify code that is no longer used:
|
||||
|
||||
**Scan patterns**:
|
||||
- Unused exports (exported but never imported)
|
||||
- Orphan files (not imported anywhere)
|
||||
- Commented-out code blocks (>10 lines)
|
||||
- TODO/FIXME comments >90 days old
|
||||
|
||||
**Analysis steps**:
|
||||
1. Build import graph using rg/grep
|
||||
2. Identify exports with no importers
|
||||
3. Find files not in import graph
|
||||
4. Scan for large comment blocks
|
||||
|
||||
## Output Format
|
||||
|
||||
Write to: ${sessionFolder}/cleanup-manifest.json
|
||||
|
||||
\`\`\`json
|
||||
{
|
||||
"generated_at": "ISO timestamp",
|
||||
"mainline_summary": {
|
||||
"core_modules": ["src/core", "src/api"],
|
||||
"active_branches": ["main", "feature/auth"],
|
||||
"health_score": 0.85
|
||||
},
|
||||
"discoveries": {
|
||||
"stale_sessions": [
|
||||
{
|
||||
"path": ".workflow/active/WFS-old-feature",
|
||||
"type": "active",
|
||||
"age_days": 15,
|
||||
"reason": "No related commits in 15 days",
|
||||
"size_kb": 1024,
|
||||
"risk": "low"
|
||||
}
|
||||
],
|
||||
"drifted_documents": [
|
||||
{
|
||||
"path": ".claude/rules/tech/deprecated-lib",
|
||||
"type": "tech_rules",
|
||||
"broken_references": 5,
|
||||
"total_references": 6,
|
||||
"drift_percentage": 83,
|
||||
"reason": "Referenced library removed",
|
||||
"risk": "low"
|
||||
}
|
||||
],
|
||||
"dead_code": [
|
||||
{
|
||||
"path": "src/utils/legacy.ts",
|
||||
"type": "orphan_file",
|
||||
"reason": "Not imported by any file",
|
||||
"last_modified": "2025-10-01",
|
||||
"risk": "medium"
|
||||
}
|
||||
]
|
||||
},
|
||||
"summary": {
|
||||
"total_items": 12,
|
||||
"total_size_mb": 45.2,
|
||||
"by_category": {
|
||||
"stale_sessions": 5,
|
||||
"drifted_documents": 4,
|
||||
"dead_code": 3
|
||||
},
|
||||
"by_risk": {
|
||||
"low": 8,
|
||||
"medium": 3,
|
||||
"high": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## Execution Commands
|
||||
|
||||
\`\`\`bash
|
||||
# Session directories
|
||||
find .workflow -type d -name "WFS-*" -o -name "DBG-*" 2>/dev/null
|
||||
|
||||
# Check modification times (Linux/Mac)
|
||||
stat -c "%Y %n" .workflow/active/WFS-* 2>/dev/null
|
||||
|
||||
# Check modification times (Windows PowerShell via bash)
|
||||
powershell -Command "Get-ChildItem '.workflow/active/WFS-*' | ForEach-Object { Write-Output \"$($_.LastWriteTime) $($_.FullName)\" }"
|
||||
|
||||
# Find orphan exports (TypeScript)
|
||||
rg "export (const|function|class|interface|type)" --type ts -l
|
||||
|
||||
# Find imports
|
||||
rg "import.*from" --type ts
|
||||
|
||||
# Find large comment blocks
|
||||
rg "^\\s*/\\*" -A 10 --type ts
|
||||
|
||||
# Find old TODOs
|
||||
rg "TODO|FIXME" --type ts -n
|
||||
\`\`\`
|
||||
|
||||
## Success Criteria
|
||||
- [ ] All session directories scanned with age calculation
|
||||
- [ ] Documents cross-referenced with existing code
|
||||
- [ ] Dead code detection via import graph analysis
|
||||
- [ ] cleanup-manifest.json written with complete data
|
||||
- [ ] Each item has risk level and cleanup reason
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Confirmation
|
||||
|
||||
**Step 3.1: Display Summary**
|
||||
```javascript
|
||||
const manifest = JSON.parse(Read(`${sessionFolder}/cleanup-manifest.json`))
|
||||
|
||||
console.log(`
|
||||
## Cleanup Discovery Report
|
||||
|
||||
**Mainline Health**: ${Math.round(manifest.mainline_summary.health_score * 100)}%
|
||||
**Core Modules**: ${manifest.mainline_summary.core_modules.join(', ')}
|
||||
|
||||
### Summary
|
||||
| Category | Count | Size | Risk |
|
||||
|----------|-------|------|------|
|
||||
| Stale Sessions | ${manifest.summary.by_category.stale_sessions} | - | ${getRiskSummary('sessions')} |
|
||||
| Drifted Documents | ${manifest.summary.by_category.drifted_documents} | - | ${getRiskSummary('documents')} |
|
||||
| Dead Code | ${manifest.summary.by_category.dead_code} | - | ${getRiskSummary('code')} |
|
||||
|
||||
**Total**: ${manifest.summary.total_items} items, ~${manifest.summary.total_size_mb} MB
|
||||
|
||||
### Stale Sessions
|
||||
${manifest.discoveries.stale_sessions.map(s =>
|
||||
`- ${s.path} (${s.age_days}d, ${s.risk}): ${s.reason}`
|
||||
).join('\n')}
|
||||
|
||||
### Drifted Documents
|
||||
${manifest.discoveries.drifted_documents.map(d =>
|
||||
`- ${d.path} (${d.drift_percentage}% broken, ${d.risk}): ${d.reason}`
|
||||
).join('\n')}
|
||||
|
||||
### Dead Code
|
||||
${manifest.discoveries.dead_code.map(c =>
|
||||
`- ${c.path} (${c.type}, ${c.risk}): ${c.reason}`
|
||||
).join('\n')}
|
||||
`)
|
||||
```
|
||||
|
||||
**Step 3.2: Dry-Run Exit**
|
||||
```javascript
|
||||
if (flags.includes('--dry-run')) {
|
||||
console.log(`
|
||||
---
|
||||
**Dry-run mode**: No changes made.
|
||||
Manifest saved to: ${sessionFolder}/cleanup-manifest.json
|
||||
|
||||
To execute cleanup: /workflow:clean
|
||||
`)
|
||||
return
|
||||
}
|
||||
```
|
||||
|
||||
**Step 3.3: User Confirmation**
|
||||
```javascript
|
||||
// Parse --yes flag
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
|
||||
let userSelection
|
||||
|
||||
if (autoYes) {
|
||||
// Auto mode: Use safe defaults
|
||||
console.log(`[--yes] Auto-selecting safe cleanup defaults:`)
|
||||
console.log(` - Categories: Sessions only`)
|
||||
console.log(` - Risk level: Low only`)
|
||||
|
||||
userSelection = {
|
||||
categories: ["Sessions"],
|
||||
risk: "Low only"
|
||||
}
|
||||
} else {
|
||||
// Interactive mode: Ask user
|
||||
userSelection = AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "Which categories to clean?",
|
||||
header: "Categories",
|
||||
multiSelect: true,
|
||||
options: [
|
||||
{
|
||||
label: "Sessions",
|
||||
description: `${manifest.summary.by_category.stale_sessions} stale workflow sessions`
|
||||
},
|
||||
{
|
||||
label: "Documents",
|
||||
description: `${manifest.summary.by_category.drifted_documents} drifted documents`
|
||||
},
|
||||
{
|
||||
label: "Dead Code",
|
||||
description: `${manifest.summary.by_category.dead_code} unused code files`
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Risk level to include?",
|
||||
header: "Risk",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Low only", description: "Safest - only obviously stale items" },
|
||||
{ label: "Low + Medium", description: "Recommended - includes likely unused items" },
|
||||
{ label: "All", description: "Aggressive - includes high-risk items" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Execution
|
||||
|
||||
**Step 4.1: Filter Items by Selection**
|
||||
```javascript
|
||||
const selectedCategories = userSelection.categories // ['Sessions', 'Documents', ...]
|
||||
const riskLevel = userSelection.risk // 'Low only', 'Low + Medium', 'All'
|
||||
|
||||
const riskFilter = {
|
||||
'Low only': ['low'],
|
||||
'Low + Medium': ['low', 'medium'],
|
||||
'All': ['low', 'medium', 'high']
|
||||
}[riskLevel]
|
||||
|
||||
const itemsToClean = []
|
||||
|
||||
if (selectedCategories.includes('Sessions')) {
|
||||
itemsToClean.push(...manifest.discoveries.stale_sessions.filter(s => riskFilter.includes(s.risk)))
|
||||
}
|
||||
if (selectedCategories.includes('Documents')) {
|
||||
itemsToClean.push(...manifest.discoveries.drifted_documents.filter(d => riskFilter.includes(d.risk)))
|
||||
}
|
||||
if (selectedCategories.includes('Dead Code')) {
|
||||
itemsToClean.push(...manifest.discoveries.dead_code.filter(c => riskFilter.includes(c.risk)))
|
||||
}
|
||||
|
||||
TodoWrite({
|
||||
todos: itemsToClean.map(item => ({
|
||||
content: `Clean: ${item.path}`,
|
||||
status: "pending",
|
||||
activeForm: `Cleaning ${item.path}`
|
||||
}))
|
||||
})
|
||||
```
|
||||
|
||||
**Step 4.2: Execute Cleanup**
|
||||
```javascript
|
||||
const results = { deleted: [], failed: [], skipped: [] }
|
||||
|
||||
for (const item of itemsToClean) {
|
||||
TodoWrite({ todos: [...] }) // Mark current as in_progress
|
||||
|
||||
try {
|
||||
if (item.type === 'orphan_file' || item.type === 'dead_export') {
|
||||
// Dead code: Delete file or remove export
|
||||
Bash({ command: `rm -rf "${item.path}"` })
|
||||
} else {
|
||||
// Sessions and documents: Delete directory/file
|
||||
Bash({ command: `rm -rf "${item.path}"` })
|
||||
}
|
||||
|
||||
results.deleted.push(item.path)
|
||||
TodoWrite({ todos: [...] }) // Mark as completed
|
||||
} catch (error) {
|
||||
results.failed.push({ path: item.path, error: error.message })
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Step 4.3: Update Manifests**
|
||||
```javascript
|
||||
// Update archives manifest if sessions were deleted
|
||||
if (selectedCategories.includes('Sessions')) {
|
||||
const archiveManifestPath = '.workflow/archives/manifest.json'
|
||||
if (fileExists(archiveManifestPath)) {
|
||||
const archiveManifest = JSON.parse(Read(archiveManifestPath))
|
||||
const deletedSessionIds = results.deleted
|
||||
.filter(p => p.includes('WFS-'))
|
||||
.map(p => p.split('/').pop())
|
||||
|
||||
const updatedManifest = archiveManifest.filter(entry =>
|
||||
!deletedSessionIds.includes(entry.session_id)
|
||||
)
|
||||
|
||||
Write(archiveManifestPath, JSON.stringify(updatedManifest, null, 2))
|
||||
}
|
||||
}
|
||||
|
||||
// Update project-tech.json if features referenced deleted sessions
|
||||
const projectPath = '.workflow/project-tech.json'
|
||||
if (fileExists(projectPath)) {
|
||||
const project = JSON.parse(Read(projectPath))
|
||||
const deletedPaths = new Set(results.deleted)
|
||||
|
||||
project.features = project.features.filter(f =>
|
||||
!deletedPaths.has(f.traceability?.archive_path)
|
||||
)
|
||||
|
||||
project.statistics.total_features = project.features.length
|
||||
project.statistics.last_updated = getUtc8ISOString()
|
||||
|
||||
Write(projectPath, JSON.stringify(project, null, 2))
|
||||
}
|
||||
```
|
||||
|
||||
**Step 4.4: Report Results**
|
||||
```javascript
|
||||
console.log(`
|
||||
## Cleanup Complete
|
||||
|
||||
**Deleted**: ${results.deleted.length} items
|
||||
**Failed**: ${results.failed.length} items
|
||||
**Skipped**: ${results.skipped.length} items
|
||||
|
||||
### Deleted Items
|
||||
${results.deleted.map(p => `- ${p}`).join('\n')}
|
||||
|
||||
${results.failed.length > 0 ? `
|
||||
### Failed Items
|
||||
${results.failed.map(f => `- ${f.path}: ${f.error}`).join('\n')}
|
||||
` : ''}
|
||||
|
||||
Cleanup manifest archived to: ${sessionFolder}/cleanup-manifest.json
|
||||
`)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Folder Structure
|
||||
|
||||
```
|
||||
.workflow/.clean/{YYYY-MM-DD}/
|
||||
├── mainline-profile.json # Git history analysis
|
||||
└── cleanup-manifest.json # Discovery results
|
||||
```
|
||||
|
||||
## Risk Level Definitions
|
||||
|
||||
| Risk | Description | Examples |
|
||||
|------|-------------|----------|
|
||||
| **Low** | Safe to delete, no dependencies | Empty sessions, scratchpad files, 100% broken docs |
|
||||
| **Medium** | Likely unused, verify before delete | Orphan files, old archives, partially broken docs |
|
||||
| **High** | May have hidden dependencies | Files with some imports, recent modifications |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| No git repository | Skip mainline detection, use file timestamps only |
|
||||
| Session in use (.archiving) | Skip with warning |
|
||||
| Permission denied | Report error, continue with others |
|
||||
| Manifest parse error | Regenerate from filesystem scan |
|
||||
| Empty discovery | Report "codebase is clean" |
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/workflow:session:complete` - Properly archive active sessions
|
||||
- `/memory:compact` - Save session memory before cleanup
|
||||
- `/workflow:status` - View current workflow state
|
||||
@@ -1,670 +0,0 @@
|
||||
---
|
||||
name: debug-with-file
|
||||
description: Interactive hypothesis-driven debugging with documented exploration, understanding evolution, and Gemini-assisted correction
|
||||
argument-hint: "[-y|--yes] \"bug description or error message\""
|
||||
allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-confirm all decisions (hypotheses, fixes, iteration), use recommended settings.
|
||||
|
||||
# Workflow Debug-With-File Command (/workflow:debug-with-file)
|
||||
|
||||
## Overview
|
||||
|
||||
Enhanced evidence-based debugging with **documented exploration process**. Records understanding evolution, consolidates insights, and uses Gemini to correct misunderstandings.
|
||||
|
||||
**Core workflow**: Explore → Document → Log → Analyze → Correct Understanding → Fix → Verify
|
||||
|
||||
**Key enhancements over /workflow:debug**:
|
||||
- **understanding.md**: Timeline of exploration and learning
|
||||
- **Gemini-assisted correction**: Validates and corrects hypotheses
|
||||
- **Consolidation**: Simplifies proven-wrong understanding to avoid clutter
|
||||
- **Learning retention**: Preserves what was learned, even from failed attempts
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/workflow:debug-with-file <BUG_DESCRIPTION>
|
||||
|
||||
# Arguments
|
||||
<bug-description> Bug description, error message, or stack trace (required)
|
||||
```
|
||||
|
||||
## Execution Process
|
||||
|
||||
```
|
||||
Session Detection:
|
||||
├─ Check if debug session exists for this bug
|
||||
├─ EXISTS + understanding.md exists → Continue mode
|
||||
└─ NOT_FOUND → Explore mode
|
||||
|
||||
Explore Mode:
|
||||
├─ Locate error source in codebase
|
||||
├─ Document initial understanding in understanding.md
|
||||
├─ Generate testable hypotheses with Gemini validation
|
||||
├─ Add NDJSON logging instrumentation
|
||||
└─ Output: Hypothesis list + await user reproduction
|
||||
|
||||
Analyze Mode:
|
||||
├─ Parse debug.log, validate each hypothesis
|
||||
├─ Use Gemini to analyze evidence and correct understanding
|
||||
├─ Update understanding.md with:
|
||||
│ ├─ New evidence
|
||||
│ ├─ Corrected misunderstandings (strikethrough + correction)
|
||||
│ └─ Consolidated current understanding
|
||||
└─ Decision:
|
||||
├─ Confirmed → Fix root cause
|
||||
├─ Inconclusive → Add more logging, iterate
|
||||
└─ All rejected → Gemini-assisted new hypotheses
|
||||
|
||||
Fix & Cleanup:
|
||||
├─ Apply fix based on confirmed hypothesis
|
||||
├─ User verifies
|
||||
├─ Document final understanding + lessons learned
|
||||
├─ Remove debug instrumentation
|
||||
└─ If not fixed → Return to Analyze mode
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
### Session Setup & Mode Detection
|
||||
|
||||
```javascript
|
||||
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
|
||||
|
||||
const bugSlug = bug_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 30)
|
||||
const dateStr = getUtc8ISOString().substring(0, 10)
|
||||
|
||||
const sessionId = `DBG-${bugSlug}-${dateStr}`
|
||||
const sessionFolder = `.workflow/.debug/${sessionId}`
|
||||
const debugLogPath = `${sessionFolder}/debug.log`
|
||||
const understandingPath = `${sessionFolder}/understanding.md`
|
||||
const hypothesesPath = `${sessionFolder}/hypotheses.json`
|
||||
|
||||
// Auto-detect mode
|
||||
const sessionExists = fs.existsSync(sessionFolder)
|
||||
const hasUnderstanding = sessionExists && fs.existsSync(understandingPath)
|
||||
const logHasContent = sessionExists && fs.existsSync(debugLogPath) && fs.statSync(debugLogPath).size > 0
|
||||
|
||||
const mode = logHasContent ? 'analyze' : (hasUnderstanding ? 'continue' : 'explore')
|
||||
|
||||
if (!sessionExists) {
|
||||
bash(`mkdir -p ${sessionFolder}`)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Explore Mode
|
||||
|
||||
**Step 1.1: Locate Error Source**
|
||||
|
||||
```javascript
|
||||
// Extract keywords from bug description
|
||||
const keywords = extractErrorKeywords(bug_description)
|
||||
|
||||
// Search codebase for error locations
|
||||
const searchResults = []
|
||||
for (const keyword of keywords) {
|
||||
const results = Grep({ pattern: keyword, path: ".", output_mode: "content", "-C": 3 })
|
||||
searchResults.push({ keyword, results })
|
||||
}
|
||||
|
||||
// Identify affected files and functions
|
||||
const affectedLocations = analyzeSearchResults(searchResults)
|
||||
```
|
||||
|
||||
**Step 1.2: Document Initial Understanding**
|
||||
|
||||
Create `understanding.md` with exploration timeline:
|
||||
|
||||
```markdown
|
||||
# Understanding Document
|
||||
|
||||
**Session ID**: ${sessionId}
|
||||
**Bug Description**: ${bug_description}
|
||||
**Started**: ${getUtc8ISOString()}
|
||||
|
||||
---
|
||||
|
||||
## Exploration Timeline
|
||||
|
||||
### Iteration 1 - Initial Exploration (${timestamp})
|
||||
|
||||
#### Current Understanding
|
||||
|
||||
Based on bug description and initial code search:
|
||||
|
||||
- Error pattern: ${errorPattern}
|
||||
- Affected areas: ${affectedLocations.map(l => l.file).join(', ')}
|
||||
- Initial hypothesis: ${initialThoughts}
|
||||
|
||||
#### Evidence from Code Search
|
||||
|
||||
${searchResults.map(r => `
|
||||
**Keyword: "${r.keyword}"**
|
||||
- Found in: ${r.results.files.join(', ')}
|
||||
- Key findings: ${r.insights}
|
||||
`).join('\n')}
|
||||
|
||||
#### Next Steps
|
||||
|
||||
- Generate testable hypotheses
|
||||
- Add instrumentation
|
||||
- Await reproduction
|
||||
|
||||
---
|
||||
|
||||
## Current Consolidated Understanding
|
||||
|
||||
${initialConsolidatedUnderstanding}
|
||||
```
|
||||
|
||||
**Step 1.3: Gemini-Assisted Hypothesis Generation**
|
||||
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Generate debugging hypotheses for: ${bug_description}
|
||||
Success criteria: Testable hypotheses with clear evidence criteria
|
||||
|
||||
TASK:
|
||||
• Analyze error pattern and code search results
|
||||
• Identify 3-5 most likely root causes
|
||||
• For each hypothesis, specify:
|
||||
- What might be wrong
|
||||
- What evidence would confirm/reject it
|
||||
- Where to add instrumentation
|
||||
• Rank by likelihood
|
||||
|
||||
MODE: analysis
|
||||
|
||||
CONTEXT: @${sessionFolder}/understanding.md | Search results in understanding.md
|
||||
|
||||
EXPECTED:
|
||||
- Structured hypothesis list (JSON format)
|
||||
- Each hypothesis with: id, description, testable_condition, logging_point, evidence_criteria
|
||||
- Likelihood ranking (1=most likely)
|
||||
|
||||
CONSTRAINTS: Focus on testable conditions
|
||||
" --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause
|
||||
```
|
||||
|
||||
Save Gemini output to `hypotheses.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"iteration": 1,
|
||||
"timestamp": "2025-01-21T10:00:00+08:00",
|
||||
"hypotheses": [
|
||||
{
|
||||
"id": "H1",
|
||||
"description": "Data structure mismatch - expected key not present",
|
||||
"testable_condition": "Check if target key exists in dict",
|
||||
"logging_point": "file.py:func:42",
|
||||
"evidence_criteria": {
|
||||
"confirm": "data shows missing key",
|
||||
"reject": "key exists with valid value"
|
||||
},
|
||||
"likelihood": 1,
|
||||
"status": "pending"
|
||||
}
|
||||
],
|
||||
"gemini_insights": "...",
|
||||
"corrected_assumptions": []
|
||||
}
|
||||
```
|
||||
|
||||
**Step 1.4: Add NDJSON Instrumentation**
|
||||
|
||||
For each hypothesis, add logging (same as original debug command).
|
||||
|
||||
**Step 1.5: Update understanding.md**
|
||||
|
||||
Append hypothesis section:
|
||||
|
||||
```markdown
|
||||
#### Hypotheses Generated (Gemini-Assisted)
|
||||
|
||||
${hypotheses.map(h => `
|
||||
**${h.id}** (Likelihood: ${h.likelihood}): ${h.description}
|
||||
- Logging at: ${h.logging_point}
|
||||
- Testing: ${h.testable_condition}
|
||||
- Evidence to confirm: ${h.evidence_criteria.confirm}
|
||||
- Evidence to reject: ${h.evidence_criteria.reject}
|
||||
`).join('\n')}
|
||||
|
||||
**Gemini Insights**: ${geminiInsights}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Analyze Mode
|
||||
|
||||
**Step 2.1: Parse Debug Log**
|
||||
|
||||
```javascript
|
||||
// Parse NDJSON log
|
||||
const entries = Read(debugLogPath).split('\n')
|
||||
.filter(l => l.trim())
|
||||
.map(l => JSON.parse(l))
|
||||
|
||||
// Group by hypothesis
|
||||
const byHypothesis = groupBy(entries, 'hid')
|
||||
```
|
||||
|
||||
**Step 2.2: Gemini-Assisted Evidence Analysis**
|
||||
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Analyze debug log evidence to validate/correct hypotheses for: ${bug_description}
|
||||
Success criteria: Clear verdict per hypothesis + corrected understanding
|
||||
|
||||
TASK:
|
||||
• Parse log entries by hypothesis
|
||||
• Evaluate evidence against expected criteria
|
||||
• Determine verdict: confirmed | rejected | inconclusive
|
||||
• Identify incorrect assumptions from previous understanding
|
||||
• Suggest corrections to understanding
|
||||
|
||||
MODE: analysis
|
||||
|
||||
CONTEXT:
|
||||
@${debugLogPath}
|
||||
@${understandingPath}
|
||||
@${hypothesesPath}
|
||||
|
||||
EXPECTED:
|
||||
- Per-hypothesis verdict with reasoning
|
||||
- Evidence summary
|
||||
- List of incorrect assumptions with corrections
|
||||
- Updated consolidated understanding
|
||||
- Root cause if confirmed, or next investigation steps
|
||||
|
||||
CONSTRAINTS: Evidence-based reasoning only, no speculation
|
||||
" --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause
|
||||
```
|
||||
|
||||
**Step 2.3: Update Understanding with Corrections**
|
||||
|
||||
Append new iteration to `understanding.md`:
|
||||
|
||||
```markdown
|
||||
### Iteration ${n} - Evidence Analysis (${timestamp})
|
||||
|
||||
#### Log Analysis Results
|
||||
|
||||
${results.map(r => `
|
||||
**${r.id}**: ${r.verdict.toUpperCase()}
|
||||
- Evidence: ${JSON.stringify(r.evidence)}
|
||||
- Reasoning: ${r.reason}
|
||||
`).join('\n')}
|
||||
|
||||
#### Corrected Understanding
|
||||
|
||||
Previous misunderstandings identified and corrected:
|
||||
|
||||
${corrections.map(c => `
|
||||
- ~~${c.wrong}~~ → ${c.corrected}
|
||||
- Why wrong: ${c.reason}
|
||||
- Evidence: ${c.evidence}
|
||||
`).join('\n')}
|
||||
|
||||
#### New Insights
|
||||
|
||||
${newInsights.join('\n- ')}
|
||||
|
||||
#### Gemini Analysis
|
||||
|
||||
${geminiAnalysis}
|
||||
|
||||
${confirmedHypothesis ? `
|
||||
#### Root Cause Identified
|
||||
|
||||
**${confirmedHypothesis.id}**: ${confirmedHypothesis.description}
|
||||
|
||||
Evidence supporting this conclusion:
|
||||
${confirmedHypothesis.supportingEvidence}
|
||||
` : `
|
||||
#### Next Steps
|
||||
|
||||
${nextSteps}
|
||||
`}
|
||||
|
||||
---
|
||||
|
||||
## Current Consolidated Understanding (Updated)
|
||||
|
||||
${consolidatedUnderstanding}
|
||||
```
|
||||
|
||||
**Step 2.4: Consolidate Understanding**
|
||||
|
||||
At the bottom of `understanding.md`, update the consolidated section:
|
||||
|
||||
- Remove or simplify proven-wrong assumptions
|
||||
- Keep them in strikethrough for reference
|
||||
- Focus on current valid understanding
|
||||
- Avoid repeating details from timeline
|
||||
|
||||
```markdown
|
||||
## Current Consolidated Understanding
|
||||
|
||||
### What We Know
|
||||
|
||||
- ${validUnderstanding1}
|
||||
- ${validUnderstanding2}
|
||||
|
||||
### What Was Disproven
|
||||
|
||||
- ~~Initial assumption: ${wrongAssumption}~~ (Evidence: ${disproofEvidence})
|
||||
|
||||
### Current Investigation Focus
|
||||
|
||||
${currentFocus}
|
||||
|
||||
### Remaining Questions
|
||||
|
||||
- ${openQuestion1}
|
||||
- ${openQuestion2}
|
||||
```
|
||||
|
||||
**Step 2.5: Update hypotheses.json**
|
||||
|
||||
```json
|
||||
{
|
||||
"iteration": 2,
|
||||
"timestamp": "2025-01-21T10:15:00+08:00",
|
||||
"hypotheses": [
|
||||
{
|
||||
"id": "H1",
|
||||
"status": "rejected",
|
||||
"verdict_reason": "Evidence shows key exists with valid value",
|
||||
"evidence": {...}
|
||||
},
|
||||
{
|
||||
"id": "H2",
|
||||
"status": "confirmed",
|
||||
"verdict_reason": "Log data confirms timing issue",
|
||||
"evidence": {...}
|
||||
}
|
||||
],
|
||||
"gemini_corrections": [
|
||||
{
|
||||
"wrong_assumption": "...",
|
||||
"corrected_to": "...",
|
||||
"reason": "..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Fix & Verification
|
||||
|
||||
**Step 3.1: Apply Fix**
|
||||
|
||||
(Same as original debug command)
|
||||
|
||||
**Step 3.2: Document Resolution**
|
||||
|
||||
Append to `understanding.md`:
|
||||
|
||||
```markdown
|
||||
### Iteration ${n} - Resolution (${timestamp})
|
||||
|
||||
#### Fix Applied
|
||||
|
||||
- Modified files: ${modifiedFiles.join(', ')}
|
||||
- Fix description: ${fixDescription}
|
||||
- Root cause addressed: ${rootCause}
|
||||
|
||||
#### Verification Results
|
||||
|
||||
${verificationResults}
|
||||
|
||||
#### Lessons Learned
|
||||
|
||||
What we learned from this debugging session:
|
||||
|
||||
1. ${lesson1}
|
||||
2. ${lesson2}
|
||||
3. ${lesson3}
|
||||
|
||||
#### Key Insights for Future
|
||||
|
||||
- ${insight1}
|
||||
- ${insight2}
|
||||
```
|
||||
|
||||
**Step 3.3: Cleanup**
|
||||
|
||||
Remove debug instrumentation (same as original command).
|
||||
|
||||
---
|
||||
|
||||
## Session Folder Structure
|
||||
|
||||
```
|
||||
.workflow/.debug/DBG-{slug}-{date}/
|
||||
├── debug.log # NDJSON log (execution evidence)
|
||||
├── understanding.md # NEW: Exploration timeline + consolidated understanding
|
||||
├── hypotheses.json # NEW: Hypothesis history with verdicts
|
||||
└── resolution.md # Optional: Final summary
|
||||
```
|
||||
|
||||
## Understanding Document Template
|
||||
|
||||
```markdown
|
||||
# Understanding Document
|
||||
|
||||
**Session ID**: DBG-xxx-2025-01-21
|
||||
**Bug Description**: [original description]
|
||||
**Started**: 2025-01-21T10:00:00+08:00
|
||||
|
||||
---
|
||||
|
||||
## Exploration Timeline
|
||||
|
||||
### Iteration 1 - Initial Exploration (2025-01-21 10:00)
|
||||
|
||||
#### Current Understanding
|
||||
...
|
||||
|
||||
#### Evidence from Code Search
|
||||
...
|
||||
|
||||
#### Hypotheses Generated (Gemini-Assisted)
|
||||
...
|
||||
|
||||
### Iteration 2 - Evidence Analysis (2025-01-21 10:15)
|
||||
|
||||
#### Log Analysis Results
|
||||
...
|
||||
|
||||
#### Corrected Understanding
|
||||
- ~~[wrong]~~ → [corrected]
|
||||
|
||||
#### Gemini Analysis
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
## Current Consolidated Understanding
|
||||
|
||||
### What We Know
|
||||
- [valid understanding points]
|
||||
|
||||
### What Was Disproven
|
||||
- ~~[disproven assumptions]~~
|
||||
|
||||
### Current Investigation Focus
|
||||
[current focus]
|
||||
|
||||
### Remaining Questions
|
||||
- [open questions]
|
||||
```
|
||||
|
||||
## Iteration Flow
|
||||
|
||||
```
|
||||
First Call (/workflow:debug-with-file "error"):
|
||||
├─ No session exists → Explore mode
|
||||
├─ Extract error keywords, search codebase
|
||||
├─ Document initial understanding in understanding.md
|
||||
├─ Use Gemini to generate hypotheses
|
||||
├─ Add logging instrumentation
|
||||
└─ Await user reproduction
|
||||
|
||||
After Reproduction (/workflow:debug-with-file "error"):
|
||||
├─ Session exists + debug.log has content → Analyze mode
|
||||
├─ Parse log, use Gemini to evaluate hypotheses
|
||||
├─ Update understanding.md with:
|
||||
│ ├─ Evidence analysis results
|
||||
│ ├─ Corrected misunderstandings (strikethrough)
|
||||
│ ├─ New insights
|
||||
│ └─ Updated consolidated understanding
|
||||
├─ Update hypotheses.json with verdicts
|
||||
└─ Decision:
|
||||
├─ Confirmed → Fix → Document resolution
|
||||
├─ Inconclusive → Add logging, document next steps
|
||||
└─ All rejected → Gemini-assisted new hypotheses
|
||||
|
||||
Output:
|
||||
├─ .workflow/.debug/DBG-{slug}-{date}/debug.log
|
||||
├─ .workflow/.debug/DBG-{slug}-{date}/understanding.md (evolving document)
|
||||
└─ .workflow/.debug/DBG-{slug}-{date}/hypotheses.json (history)
|
||||
```
|
||||
|
||||
## Gemini Integration Points
|
||||
|
||||
### 1. Hypothesis Generation (Explore Mode)
|
||||
|
||||
**Purpose**: Generate evidence-based, testable hypotheses
|
||||
|
||||
**Prompt Pattern**:
|
||||
```
|
||||
PURPOSE: Generate debugging hypotheses + evidence criteria
|
||||
TASK: Analyze error + code → testable hypotheses with clear pass/fail criteria
|
||||
CONTEXT: @understanding.md (search results)
|
||||
EXPECTED: JSON with hypotheses, likelihood ranking, evidence criteria
|
||||
```
|
||||
|
||||
### 2. Evidence Analysis (Analyze Mode)
|
||||
|
||||
**Purpose**: Validate hypotheses and correct misunderstandings
|
||||
|
||||
**Prompt Pattern**:
|
||||
```
|
||||
PURPOSE: Analyze debug log evidence + correct understanding
|
||||
TASK: Evaluate each hypothesis → identify wrong assumptions → suggest corrections
|
||||
CONTEXT: @debug.log @understanding.md @hypotheses.json
|
||||
EXPECTED: Verdicts + corrections + updated consolidated understanding
|
||||
```
|
||||
|
||||
### 3. New Hypothesis Generation (After All Rejected)
|
||||
|
||||
**Purpose**: Generate new hypotheses based on what was disproven
|
||||
|
||||
**Prompt Pattern**:
|
||||
```
|
||||
PURPOSE: Generate new hypotheses given disproven assumptions
|
||||
TASK: Review rejected hypotheses → identify knowledge gaps → new investigation angles
|
||||
CONTEXT: @understanding.md (with disproven section) @hypotheses.json
|
||||
EXPECTED: New hypotheses avoiding previously rejected paths
|
||||
```
|
||||
|
||||
## Error Correction Mechanism
|
||||
|
||||
### Correction Format in understanding.md
|
||||
|
||||
```markdown
|
||||
#### Corrected Understanding
|
||||
|
||||
- ~~Assumed dict key "config" was missing~~ → Key exists, but value is None
|
||||
- Why wrong: Only checked existence, not value validity
|
||||
- Evidence: H1 log shows {"config": null, "exists": true}
|
||||
|
||||
- ~~Thought error occurred in initialization~~ → Error happens during runtime update
|
||||
- Why wrong: Stack trace misread as init code
|
||||
- Evidence: H2 timestamp shows 30s after startup
|
||||
```
|
||||
|
||||
### Consolidation Rules
|
||||
|
||||
When updating "Current Consolidated Understanding":
|
||||
|
||||
1. **Simplify disproven items**: Move to "What Was Disproven" with single-line summary
|
||||
2. **Keep valid insights**: Promote confirmed findings to "What We Know"
|
||||
3. **Avoid duplication**: Don't repeat timeline details in consolidated section
|
||||
4. **Focus on current state**: What do we know NOW, not the journey
|
||||
5. **Preserve key corrections**: Keep important wrong→right transformations for learning
|
||||
|
||||
**Bad (cluttered)**:
|
||||
```markdown
|
||||
## Current Consolidated Understanding
|
||||
|
||||
In iteration 1 we thought X, but in iteration 2 we found Y, then in iteration 3...
|
||||
Also we checked A and found B, and then we checked C...
|
||||
```
|
||||
|
||||
**Good (consolidated)**:
|
||||
```markdown
|
||||
## Current Consolidated Understanding
|
||||
|
||||
### What We Know
|
||||
- Error occurs during runtime update, not initialization
|
||||
- Config value is None (not missing key)
|
||||
|
||||
### What Was Disproven
|
||||
- ~~Initialization error~~ (Timing evidence)
|
||||
- ~~Missing key hypothesis~~ (Key exists)
|
||||
|
||||
### Current Investigation Focus
|
||||
Why is config value None during update?
|
||||
```
|
||||
|
||||
## Post-Completion Expansion
|
||||
|
||||
完成后询问用户是否扩展为issue(test/enhance/refactor/doc)，选中项调用 `/issue:new "{summary} - {dimension}"`
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| Empty debug.log | Verify reproduction triggered the code path |
|
||||
| All hypotheses rejected | Use Gemini to generate new hypotheses based on disproven assumptions |
|
||||
| Fix doesn't work | Document failed fix attempt, iterate with refined understanding |
|
||||
| >5 iterations | Review consolidated understanding, escalate to `/workflow:lite-fix` with full context |
|
||||
| Gemini unavailable | Fallback to manual hypothesis generation, document without Gemini insights |
|
||||
| Understanding too long | Consolidate aggressively, archive old iterations to separate file |
|
||||
|
||||
## Comparison with /workflow:debug
|
||||
|
||||
| Feature | /workflow:debug | /workflow:debug-with-file |
|
||||
|---------|-----------------|---------------------------|
|
||||
| NDJSON logging | ✅ | ✅ |
|
||||
| Hypothesis generation | Manual | Gemini-assisted |
|
||||
| Exploration documentation | ❌ | ✅ understanding.md |
|
||||
| Understanding evolution | ❌ | ✅ Timeline + corrections |
|
||||
| Error correction | ❌ | ✅ Strikethrough + reasoning |
|
||||
| Consolidated learning | ❌ | ✅ Current understanding section |
|
||||
| Hypothesis history | ❌ | ✅ hypotheses.json |
|
||||
| Gemini validation | ❌ | ✅ At key decision points |
|
||||
|
||||
## Usage Recommendations
|
||||
|
||||
Use `/workflow:debug-with-file` when:
|
||||
- Complex bugs requiring multiple investigation rounds
|
||||
- Learning from debugging process is valuable
|
||||
- Team needs to understand debugging rationale
|
||||
- Bug might recur, documentation helps prevention
|
||||
|
||||
Use `/workflow:debug` when:
|
||||
- Simple, quick bugs
|
||||
- One-off issues
|
||||
- Documentation overhead not needed
|
||||
@@ -1,331 +0,0 @@
|
||||
---
|
||||
name: debug
|
||||
description: Interactive hypothesis-driven debugging with NDJSON logging, iterative until resolved
|
||||
argument-hint: "[-y|--yes] \"bug description or error message\""
|
||||
allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-confirm all decisions (hypotheses, fixes, iteration), use recommended settings.
|
||||
|
||||
# Workflow Debug Command (/workflow:debug)
|
||||
|
||||
## Overview
|
||||
|
||||
Evidence-based interactive debugging command. Systematically identifies root causes through hypothesis-driven logging and iterative verification.
|
||||
|
||||
**Core workflow**: Explore → Add Logging → Reproduce → Analyze Log → Fix → Verify
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/workflow:debug <BUG_DESCRIPTION>
|
||||
|
||||
# Arguments
|
||||
<bug-description> Bug description, error message, or stack trace (required)
|
||||
```
|
||||
|
||||
## Execution Process
|
||||
|
||||
```
|
||||
Session Detection:
|
||||
├─ Check if debug session exists for this bug
|
||||
├─ EXISTS + debug.log has content → Analyze mode
|
||||
└─ NOT_FOUND or empty log → Explore mode
|
||||
|
||||
Explore Mode:
|
||||
├─ Locate error source in codebase
|
||||
├─ Generate testable hypotheses (dynamic count)
|
||||
├─ Add NDJSON logging instrumentation
|
||||
└─ Output: Hypothesis list + await user reproduction
|
||||
|
||||
Analyze Mode:
|
||||
├─ Parse debug.log, validate each hypothesis
|
||||
└─ Decision:
|
||||
├─ Confirmed → Fix root cause
|
||||
├─ Inconclusive → Add more logging, iterate
|
||||
└─ All rejected → Generate new hypotheses
|
||||
|
||||
Fix & Cleanup:
|
||||
├─ Apply fix based on confirmed hypothesis
|
||||
├─ User verifies
|
||||
├─ Remove debug instrumentation
|
||||
└─ If not fixed → Return to Analyze mode
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
### Session Setup & Mode Detection
|
||||
|
||||
```javascript
|
||||
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
|
||||
|
||||
const bugSlug = bug_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 30)
|
||||
const dateStr = getUtc8ISOString().substring(0, 10)
|
||||
|
||||
const sessionId = `DBG-${bugSlug}-${dateStr}`
|
||||
const sessionFolder = `.workflow/.debug/${sessionId}`
|
||||
const debugLogPath = `${sessionFolder}/debug.log`
|
||||
|
||||
// Auto-detect mode
|
||||
const sessionExists = fs.existsSync(sessionFolder)
|
||||
const logHasContent = sessionExists && fs.existsSync(debugLogPath) && fs.statSync(debugLogPath).size > 0
|
||||
|
||||
const mode = logHasContent ? 'analyze' : 'explore'
|
||||
|
||||
if (!sessionExists) {
|
||||
bash(`mkdir -p ${sessionFolder}`)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Explore Mode
|
||||
|
||||
**Step 1.1: Locate Error Source**
|
||||
|
||||
```javascript
|
||||
// Extract keywords from bug description
|
||||
const keywords = extractErrorKeywords(bug_description)
|
||||
// e.g., ['Stack Length', '未找到', 'registered 0']
|
||||
|
||||
// Search codebase for error locations
|
||||
for (const keyword of keywords) {
|
||||
Grep({ pattern: keyword, path: ".", output_mode: "content", "-C": 3 })
|
||||
}
|
||||
|
||||
// Identify affected files and functions
|
||||
const affectedLocations = [...] // from search results
|
||||
```
|
||||
|
||||
**Step 1.2: Generate Hypotheses (Dynamic)**
|
||||
|
||||
```javascript
|
||||
// Hypothesis categories based on error pattern
|
||||
const HYPOTHESIS_PATTERNS = {
|
||||
"not found|missing|undefined|未找到": "data_mismatch",
|
||||
"0|empty|zero|registered 0": "logic_error",
|
||||
"timeout|connection|sync": "integration_issue",
|
||||
"type|format|parse": "type_mismatch"
|
||||
}
|
||||
|
||||
// Generate hypotheses based on actual issue (NOT fixed count)
|
||||
function generateHypotheses(bugDescription, affectedLocations) {
|
||||
const hypotheses = []
|
||||
|
||||
// Analyze bug and create targeted hypotheses
|
||||
// Each hypothesis has:
|
||||
// - id: H1, H2, ... (dynamic count)
|
||||
// - description: What might be wrong
|
||||
// - testable_condition: What to log
|
||||
// - logging_point: Where to add instrumentation
|
||||
|
||||
return hypotheses // Could be 1, 3, 5, or more
|
||||
}
|
||||
|
||||
const hypotheses = generateHypotheses(bug_description, affectedLocations)
|
||||
```
|
||||
|
||||
**Step 1.3: Add NDJSON Instrumentation**
|
||||
|
||||
For each hypothesis, add logging at the relevant location:
|
||||
|
||||
**Python template**:
|
||||
```python
|
||||
# region debug [H{n}]
|
||||
try:
|
||||
import json, time
|
||||
_dbg = {
|
||||
"sid": "{sessionId}",
|
||||
"hid": "H{n}",
|
||||
"loc": "{file}:{line}",
|
||||
"msg": "{testable_condition}",
|
||||
"data": {
|
||||
# Capture relevant values here
|
||||
},
|
||||
"ts": int(time.time() * 1000)
|
||||
}
|
||||
with open(r"{debugLogPath}", "a", encoding="utf-8") as _f:
|
||||
_f.write(json.dumps(_dbg, ensure_ascii=False) + "\n")
|
||||
except: pass
|
||||
# endregion
|
||||
```
|
||||
|
||||
**JavaScript/TypeScript template**:
|
||||
```javascript
|
||||
// region debug [H{n}]
|
||||
try {
|
||||
require('fs').appendFileSync("{debugLogPath}", JSON.stringify({
|
||||
sid: "{sessionId}",
|
||||
hid: "H{n}",
|
||||
loc: "{file}:{line}",
|
||||
msg: "{testable_condition}",
|
||||
data: { /* Capture relevant values */ },
|
||||
ts: Date.now()
|
||||
}) + "\n");
|
||||
} catch(_) {}
|
||||
// endregion
|
||||
```
|
||||
|
||||
**Output to user**:
|
||||
```
|
||||
## Hypotheses Generated
|
||||
|
||||
Based on error "{bug_description}", generated {n} hypotheses:
|
||||
|
||||
{hypotheses.map(h => `
|
||||
### ${h.id}: ${h.description}
|
||||
- Logging at: ${h.logging_point}
|
||||
- Testing: ${h.testable_condition}
|
||||
`).join('')}
|
||||
|
||||
**Debug log**: ${debugLogPath}
|
||||
|
||||
**Next**: Run reproduction steps, then come back for analysis.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Analyze Mode
|
||||
|
||||
```javascript
|
||||
// Parse NDJSON log
|
||||
const entries = Read(debugLogPath).split('\n')
|
||||
.filter(l => l.trim())
|
||||
.map(l => JSON.parse(l))
|
||||
|
||||
// Group by hypothesis
|
||||
const byHypothesis = groupBy(entries, 'hid')
|
||||
|
||||
// Validate each hypothesis
|
||||
for (const [hid, logs] of Object.entries(byHypothesis)) {
|
||||
const hypothesis = hypotheses.find(h => h.id === hid)
|
||||
const latestLog = logs[logs.length - 1]
|
||||
|
||||
// Check if evidence confirms or rejects hypothesis
|
||||
const verdict = evaluateEvidence(hypothesis, latestLog.data)
|
||||
// Returns: 'confirmed' | 'rejected' | 'inconclusive'
|
||||
}
|
||||
```
|
||||
|
||||
**Output**:
|
||||
```
|
||||
## Evidence Analysis
|
||||
|
||||
Analyzed ${entries.length} log entries.
|
||||
|
||||
${results.map(r => `
|
||||
### ${r.id}: ${r.description}
|
||||
- **Status**: ${r.verdict}
|
||||
- **Evidence**: ${JSON.stringify(r.evidence)}
|
||||
- **Reason**: ${r.reason}
|
||||
`).join('')}
|
||||
|
||||
${confirmedHypothesis ? `
|
||||
## Root Cause Identified
|
||||
|
||||
**${confirmedHypothesis.id}**: ${confirmedHypothesis.description}
|
||||
|
||||
Ready to fix.
|
||||
` : `
|
||||
## Need More Evidence
|
||||
|
||||
Add more logging or refine hypotheses.
|
||||
`}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Fix & Cleanup
|
||||
|
||||
```javascript
|
||||
// Apply fix based on confirmed hypothesis
|
||||
// ... Edit affected files
|
||||
|
||||
// After user verifies fix works:
|
||||
|
||||
// Remove debug instrumentation (search for region markers)
|
||||
const instrumentedFiles = Grep({
|
||||
pattern: "# region debug|// region debug",
|
||||
output_mode: "files_with_matches"
|
||||
})
|
||||
|
||||
for (const file of instrumentedFiles) {
|
||||
// Remove content between region markers
|
||||
removeDebugRegions(file)
|
||||
}
|
||||
|
||||
console.log(`
|
||||
## Debug Complete
|
||||
|
||||
- Root cause: ${confirmedHypothesis.description}
|
||||
- Fix applied to: ${modifiedFiles.join(', ')}
|
||||
- Debug instrumentation removed
|
||||
`)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Debug Log Format (NDJSON)
|
||||
|
||||
Each line is a JSON object:
|
||||
|
||||
```json
|
||||
{"sid":"DBG-xxx-2025-12-18","hid":"H1","loc":"file.py:func:42","msg":"Check dict keys","data":{"keys":["a","b"],"target":"c","found":false},"ts":1734567890123}
|
||||
```
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `sid` | Session ID |
|
||||
| `hid` | Hypothesis ID (H1, H2, ...) |
|
||||
| `loc` | Code location |
|
||||
| `msg` | What's being tested |
|
||||
| `data` | Captured values |
|
||||
| `ts` | Timestamp (ms) |
|
||||
|
||||
## Session Folder
|
||||
|
||||
```
|
||||
.workflow/.debug/DBG-{slug}-{date}/
|
||||
├── debug.log # NDJSON log (main artifact)
|
||||
└── resolution.md # Summary after fix (optional)
|
||||
```
|
||||
|
||||
## Iteration Flow
|
||||
|
||||
```
|
||||
First Call (/workflow:debug "error"):
|
||||
├─ No session exists → Explore mode
|
||||
├─ Extract error keywords, search codebase
|
||||
├─ Generate hypotheses, add logging
|
||||
└─ Await user reproduction
|
||||
|
||||
After Reproduction (/workflow:debug "error"):
|
||||
├─ Session exists + debug.log has content → Analyze mode
|
||||
├─ Parse log, evaluate hypotheses
|
||||
└─ Decision:
|
||||
├─ Confirmed → Fix → User verify
|
||||
│ ├─ Fixed → Cleanup → Done
|
||||
│ └─ Not fixed → Add logging → Iterate
|
||||
├─ Inconclusive → Add logging → Iterate
|
||||
└─ All rejected → New hypotheses → Iterate
|
||||
|
||||
Output:
|
||||
└─ .workflow/.debug/DBG-{slug}-{date}/debug.log
|
||||
```
|
||||
|
||||
## Post-Completion Expansion
|
||||
|
||||
完成后询问用户是否扩展为issue(test/enhance/refactor/doc)，选中项调用 `/issue:new "{summary} - {dimension}"`
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| Empty debug.log | Verify reproduction triggered the code path |
|
||||
| All hypotheses rejected | Generate new hypotheses with broader scope |
|
||||
| Fix doesn't work | Iterate with more granular logging |
|
||||
| >5 iterations | Escalate to `/workflow:lite-fix` with evidence |
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: execute
|
||||
description: Coordinate agent execution for workflow tasks with automatic session discovery, parallel task processing, and status tracking
|
||||
argument-hint: "[-y|--yes] [--resume-session=\"session-id\"]"
|
||||
argument-hint: "[--resume-session=\"session-id\"]"
|
||||
---
|
||||
|
||||
# Workflow Execute Command
|
||||
@@ -11,30 +11,6 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
|
||||
|
||||
**Resume Mode**: When called with `--resume-session` flag, skips discovery phase and directly enters TodoWrite generation and agent execution for the specified session.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Interactive mode (with confirmations)
|
||||
/workflow:execute
|
||||
/workflow:execute --resume-session="WFS-auth"
|
||||
|
||||
# Auto mode (skip confirmations, use defaults)
|
||||
/workflow:execute --yes
|
||||
/workflow:execute -y
|
||||
/workflow:execute -y --resume-session="WFS-auth"
|
||||
```
|
||||
|
||||
## Auto Mode Defaults
|
||||
|
||||
When `--yes` or `-y` flag is used:
|
||||
- **Session Selection**: Automatically selects the first (most recent) active session
|
||||
- **Completion Choice**: Automatically completes session (runs `/workflow:session:complete --yes`)
|
||||
|
||||
**Flag Parsing**:
|
||||
```javascript
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
```
|
||||
|
||||
## Performance Optimization Strategy
|
||||
|
||||
**Lazy Loading**: Task JSONs read **on-demand** during execution, not upfront. TODO_LIST.md + IMPL_PLAN.md provide metadata for planning.
|
||||
@@ -47,7 +23,7 @@ const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
## Core Rules
|
||||
**Complete entire workflow autonomously without user interruption, using TodoWrite for comprehensive progress tracking.**
|
||||
**Execute all discovered pending tasks until workflow completion or blocking dependency.**
|
||||
**User-choice completion: When all tasks finished, ask user to choose review or complete.**
|
||||
**Auto-complete session when all tasks finished: Call `/workflow:session:complete` upon workflow completion.**
|
||||
**ONE AGENT = ONE TASK JSON: Each agent instance executes exactly one task JSON file - never batch multiple tasks into single agent execution.**
|
||||
|
||||
## Core Responsibilities
|
||||
@@ -57,7 +33,7 @@ const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
- **Agent Orchestration**: Coordinate specialized agents with complete context
|
||||
- **Status Synchronization**: Update task JSON files and workflow state
|
||||
- **Autonomous Completion**: Continue execution until all tasks complete or reach blocking state
|
||||
- **Session User-Choice Completion**: Ask user to choose review or complete when all tasks finished
|
||||
- **Session Auto-Complete**: Call `/workflow:session:complete` when all workflow tasks finished
|
||||
|
||||
## Execution Philosophy
|
||||
- **Progress tracking**: Continuous TodoWrite updates throughout entire workflow execution
|
||||
@@ -80,7 +56,6 @@ Phase 2: Planning Document Validation
|
||||
└─ Validate .task/ contains IMPL-*.json files
|
||||
|
||||
Phase 3: TodoWrite Generation
|
||||
├─ Update session status to "active" (Step 0)
|
||||
├─ Parse TODO_LIST.md for task statuses
|
||||
├─ Generate TodoWrite for entire workflow
|
||||
└─ Prepare session context paths
|
||||
@@ -92,22 +67,17 @@ Phase 4: Execution Strategy & Task Execution
|
||||
├─ Get next in_progress task from TodoWrite
|
||||
├─ Lazy load task JSON
|
||||
├─ Launch agent with task context
|
||||
├─ Mark task completed (update IMPL-*.json status)
|
||||
│ # Quick fix: Update task status for ccw dashboard
|
||||
│ # TS=$(date -Iseconds) && jq --arg ts "$TS" '.status="completed" | .status_history=(.status_history // [])+[{"from":"in_progress","to":"completed","changed_at":$ts}]' IMPL-X.json > tmp.json && mv tmp.json IMPL-X.json
|
||||
├─ Mark task completed
|
||||
└─ Advance to next task
|
||||
|
||||
Phase 5: Completion
|
||||
├─ Update task statuses in JSON files
|
||||
├─ Generate summaries
|
||||
└─ AskUserQuestion: Choose next step
|
||||
├─ "Enter Review" → /workflow:review
|
||||
└─ "Complete Session" → /workflow:session:complete
|
||||
└─ Auto-call /workflow:session:complete
|
||||
|
||||
Resume Mode (--resume-session):
|
||||
├─ Skip Phase 1 & Phase 2
|
||||
└─ Entry Point: Phase 3 (TodoWrite Generation)
|
||||
├─ Update session status to "active" (if not already)
|
||||
└─ Continue: Phase 4 → Phase 5
|
||||
```
|
||||
|
||||
@@ -143,41 +113,34 @@ Auto-select and continue to Phase 2.
|
||||
|
||||
List sessions with metadata and prompt user selection:
|
||||
```bash
|
||||
bash(for dir in .workflow/active/WFS-*/; do [ -d "$dir" ] || continue; session=$(basename "$dir"); project=$(jq -r '.project // "Unknown"' "${dir}workflow-session.json" 2>/dev/null || echo "Unknown"); total=$(grep -c '^\- \[' "${dir}TODO_LIST.md" 2>/dev/null || echo 0); completed=$(grep -c '^\- \[x\]' "${dir}TODO_LIST.md" 2>/dev/null || echo 0); if [ "$total" -gt 0 ]; then progress=$((completed * 100 / total)); else progress=0; fi; echo "$session | $project | $completed/$total tasks ($progress%)"; done)
|
||||
bash(for dir in .workflow/active/WFS-*/; do
|
||||
session=$(basename "$dir")
|
||||
project=$(jq -r '.project // "Unknown"' "$dir/workflow-session.json" 2>/dev/null)
|
||||
total=$(grep -c "^- \[" "$dir/TODO_LIST.md" 2>/dev/null || echo "0")
|
||||
completed=$(grep -c "^- \[x\]" "$dir/TODO_LIST.md" 2>/dev/null || echo "0")
|
||||
[ "$total" -gt 0 ] && progress=$((completed * 100 / total)) || progress=0
|
||||
echo "${session} | ${project} | ${completed}/${total} tasks (${progress}%)"
|
||||
done)
|
||||
```
|
||||
|
||||
**Parse --yes flag**:
|
||||
Use AskUserQuestion to present formatted options (max 4 options shown):
|
||||
```javascript
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
```
|
||||
// If more than 4 sessions, show most recent 4 with "Other" option for manual input
|
||||
const sessions = getActiveSessions() // sorted by last modified
|
||||
const displaySessions = sessions.slice(0, 4)
|
||||
|
||||
**Conditional Selection**:
|
||||
```javascript
|
||||
if (autoYes) {
|
||||
// Auto mode: Select first session (most recent)
|
||||
const firstSession = sessions[0]
|
||||
console.log(`[--yes] Auto-selecting session: ${firstSession.id}`)
|
||||
selectedSessionId = firstSession.id
|
||||
// Continue to Phase 2
|
||||
} else {
|
||||
// Interactive mode: Use AskUserQuestion to present formatted options (max 4 options shown)
|
||||
// If more than 4 sessions, show most recent 4 with "Other" option for manual input
|
||||
const sessions = getActiveSessions() // sorted by last modified
|
||||
const displaySessions = sessions.slice(0, 4)
|
||||
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Multiple active sessions detected. Select one:",
|
||||
header: "Session",
|
||||
multiSelect: false,
|
||||
options: displaySessions.map(s => ({
|
||||
label: s.id,
|
||||
description: `${s.project} | ${s.progress}`
|
||||
}))
|
||||
// Note: User can select "Other" to manually enter session ID
|
||||
}]
|
||||
})
|
||||
}
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Multiple active sessions detected. Select one:",
|
||||
header: "Session",
|
||||
multiSelect: false,
|
||||
options: displaySessions.map(s => ({
|
||||
label: s.id,
|
||||
description: `${s.project} | ${s.progress}`
|
||||
}))
|
||||
// Note: User can select "Other" to manually enter session ID
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
**Input Validation**:
|
||||
@@ -214,16 +177,6 @@ bash(cat .workflow/active/${sessionId}/workflow-session.json)
|
||||
### Phase 3: TodoWrite Generation
|
||||
**Applies to**: Both normal and resume modes (resume mode entry point)
|
||||
|
||||
**Step 0: Update Session Status to Active**
|
||||
Before generating TodoWrite, update session status from "planning" to "active":
|
||||
```bash
|
||||
# Update session status (idempotent - safe to run if already active)
|
||||
jq '.status = "active" | .execution_started_at = (.execution_started_at // now | todate)' \
|
||||
.workflow/active/${sessionId}/workflow-session.json > tmp.json && \
|
||||
mv tmp.json .workflow/active/${sessionId}/workflow-session.json
|
||||
```
|
||||
This ensures the dashboard shows the session as "ACTIVE" during execution.
|
||||
|
||||
**Process**:
|
||||
1. **Create TodoWrite List**: Generate task list from TODO_LIST.md (not from task JSONs)
|
||||
- Parse TODO_LIST.md to extract all tasks with current statuses
|
||||
@@ -287,45 +240,7 @@ while (TODO_LIST.md has pending tasks) {
|
||||
3. **Update TodoWrite**: Mark current task complete, advance to next
|
||||
4. **Synchronize State**: Update session state and workflow status
|
||||
5. **Check Workflow Complete**: Verify all tasks are completed
|
||||
6. **User Choice**: When all tasks finished, ask user to choose next step:
|
||||
|
||||
```javascript
|
||||
// Parse --yes flag
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
|
||||
if (autoYes) {
|
||||
// Auto mode: Complete session automatically
|
||||
console.log(`[--yes] Auto-selecting: Complete Session`)
|
||||
SlashCommand("/workflow:session:complete --yes")
|
||||
} else {
|
||||
// Interactive mode: Ask user
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "All tasks completed. What would you like to do next?",
|
||||
header: "Next Step",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Enter Review",
|
||||
description: "Run specialized review (security/architecture/quality/action-items)"
|
||||
},
|
||||
{
|
||||
label: "Complete Session",
|
||||
description: "Archive session and update manifest"
|
||||
}
|
||||
]
|
||||
}]
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
**Based on user selection**:
|
||||
- **"Enter Review"**: Execute `/workflow:review`
|
||||
- **"Complete Session"**: Execute `/workflow:session:complete`
|
||||
|
||||
### Post-Completion Expansion
|
||||
|
||||
完成后询问用户是否扩展为issue(test/enhance/refactor/doc)，选中项调用 `/issue:new "{summary} - {dimension}"`
|
||||
6. **Auto-Complete Session**: Call `/workflow:session:complete` when all tasks finished
|
||||
|
||||
## Execution Strategy (IMPL_PLAN-Driven)
|
||||
|
||||
@@ -401,7 +316,7 @@ blocked → skip until dependencies clear
|
||||
- **Continuous Tracking**: Maintain TodoWrite throughout entire workflow execution until completion
|
||||
|
||||
**Rule 4: Workflow Completion Check**
|
||||
- When all tasks marked `completed`, prompt user to choose review or complete session
|
||||
- When all tasks marked `completed`, auto-call `/workflow:session:complete`
|
||||
|
||||
### TodoWrite Tool Usage
|
||||
|
||||
@@ -459,40 +374,39 @@ TodoWrite({
|
||||
**Note**: Orchestrator does NOT execute flow control steps - Agent interprets and executes them autonomously.
|
||||
|
||||
### Agent Prompt Template
|
||||
**Path-Based Invocation**: Pass paths and trigger markers, let agent parse task JSON autonomously.
|
||||
**Dynamic Generation**: Before agent invocation, read task JSON and extract key requirements.
|
||||
|
||||
```bash
|
||||
Task(subagent_type="{meta.agent}",
|
||||
run_in_background=false,
|
||||
prompt="Implement task {task.id}: {task.title}
|
||||
prompt="Execute task: {task.title}
|
||||
|
||||
[FLOW_CONTROL]
|
||||
{[FLOW_CONTROL]}
|
||||
|
||||
**Input**:
|
||||
- Task JSON: {session.task_json_path}
|
||||
**Task Objectives** (from task JSON):
|
||||
{task.context.objective}
|
||||
|
||||
**Expected Deliverables** (from task JSON):
|
||||
{task.context.deliverables}
|
||||
|
||||
**Quality Standards** (from task JSON):
|
||||
{task.context.acceptance_criteria}
|
||||
|
||||
**MANDATORY FIRST STEPS**:
|
||||
1. Read complete task JSON: {session.task_json_path}
|
||||
2. Load context package: {session.context_package_path}
|
||||
|
||||
Follow complete execution guidelines in @.claude/agents/{meta.agent}.md
|
||||
|
||||
**Session Paths**:
|
||||
- Workflow Dir: {session.workflow_dir}
|
||||
- TODO List: {session.todo_list_path}
|
||||
- Summaries Dir: {session.summaries_dir}
|
||||
- Context Package: {session.context_package_path}
|
||||
|
||||
**Output Location**:
|
||||
- Workflow: {session.workflow_dir}
|
||||
- TODO List: {session.todo_list_path}
|
||||
- Summaries: {session.summaries_dir}
|
||||
|
||||
**Execution**: Read task JSON → Parse flow_control → Execute implementation_approach → Update TODO_LIST.md → Generate summary",
|
||||
description="Implement: {task.id}")
|
||||
**Success Criteria**: Complete all objectives, meet all quality standards, deliver all outputs as specified above.",
|
||||
description="Executing: {task.title}")
|
||||
```
|
||||
|
||||
**Key Markers**:
|
||||
- `Implement` keyword: Triggers tech stack detection and guidelines loading
|
||||
- `[FLOW_CONTROL]`: Triggers flow_control.pre_analysis execution
|
||||
|
||||
**Why Path-Based**: Agent (code-developer.md) autonomously:
|
||||
- Reads and parses task JSON (requirements, acceptance, flow_control)
|
||||
- Loads tech stack guidelines based on detected language
|
||||
- Executes pre_analysis steps and implementation_approach
|
||||
- Generates structured summary with integration points
|
||||
|
||||
Embedding task content in prompt creates duplication and conflicts with agent's parsing logic.
|
||||
|
||||
### Agent Assignment Rules
|
||||
```
|
||||
meta.agent specified → Use specified agent
|
||||
|
||||
@@ -10,11 +10,7 @@ examples:
|
||||
# Workflow Init Command (/workflow:init)
|
||||
|
||||
## Overview
|
||||
Initialize `.workflow/project-tech.json` and `.workflow/project-guidelines.json` with comprehensive project understanding by delegating analysis to **cli-explore-agent**.
|
||||
|
||||
**Dual File System**:
|
||||
- `project-tech.json`: Auto-generated technical analysis (stack, architecture, components)
|
||||
- `project-guidelines.json`: User-maintained rules and constraints (created as scaffold)
|
||||
Initialize `.workflow/project.json` with comprehensive project understanding by delegating analysis to **cli-explore-agent**.
|
||||
|
||||
**Note**: This command may be called by other workflow commands. Upon completion, return immediately to continue the calling workflow without interrupting the task flow.
|
||||
|
||||
@@ -31,7 +27,7 @@ Input Parsing:
|
||||
└─ Parse --regenerate flag → regenerate = true | false
|
||||
|
||||
Decision:
|
||||
├─ BOTH_EXIST + no --regenerate → Exit: "Already initialized"
|
||||
├─ EXISTS + no --regenerate → Exit: "Already initialized"
|
||||
├─ EXISTS + --regenerate → Backup existing → Continue analysis
|
||||
└─ NOT_FOUND → Continue analysis
|
||||
|
||||
@@ -41,14 +37,11 @@ Analysis Flow:
|
||||
│ ├─ Structural scan (get_modules_by_depth.sh, find, wc)
|
||||
│ ├─ Semantic analysis (Gemini CLI)
|
||||
│ ├─ Synthesis and merge
|
||||
│ └─ Write .workflow/project-tech.json
|
||||
├─ Create guidelines scaffold (if not exists)
|
||||
│ └─ Write .workflow/project-guidelines.json (empty structure)
|
||||
│ └─ Write .workflow/project.json
|
||||
└─ Display summary
|
||||
|
||||
Output:
|
||||
├─ .workflow/project-tech.json (+ .backup if regenerate)
|
||||
└─ .workflow/project-guidelines.json (scaffold if new)
|
||||
└─ .workflow/project.json (+ .backup if regenerate)
|
||||
```
|
||||
|
||||
## Implementation
|
||||
@@ -63,18 +56,13 @@ const regenerate = $ARGUMENTS.includes('--regenerate')
|
||||
**Check existing state**:
|
||||
|
||||
```bash
|
||||
bash(test -f .workflow/project-tech.json && echo "TECH_EXISTS" || echo "TECH_NOT_FOUND")
|
||||
bash(test -f .workflow/project-guidelines.json && echo "GUIDELINES_EXISTS" || echo "GUIDELINES_NOT_FOUND")
|
||||
bash(test -f .workflow/project.json && echo "EXISTS" || echo "NOT_FOUND")
|
||||
```
|
||||
|
||||
**If BOTH_EXIST and no --regenerate**: Exit early
|
||||
**If EXISTS and no --regenerate**: Exit early
|
||||
```
|
||||
Project already initialized:
|
||||
- Tech analysis: .workflow/project-tech.json
|
||||
- Guidelines: .workflow/project-guidelines.json
|
||||
|
||||
Use /workflow:init --regenerate to rebuild tech analysis
|
||||
Use /workflow:session:solidify to add guidelines
|
||||
Project already initialized at .workflow/project.json
|
||||
Use /workflow:init --regenerate to rebuild
|
||||
Use /workflow:status --project to view state
|
||||
```
|
||||
|
||||
@@ -90,7 +78,7 @@ bash(mkdir -p .workflow)
|
||||
|
||||
**For --regenerate**: Backup and preserve existing data
|
||||
```bash
|
||||
bash(cp .workflow/project-tech.json .workflow/project-tech.json.backup)
|
||||
bash(cp .workflow/project.json .workflow/project.json.backup)
|
||||
```
|
||||
|
||||
**Delegate analysis to agent**:
|
||||
@@ -98,34 +86,23 @@ bash(cp .workflow/project-tech.json .workflow/project-tech.json.backup)
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
run_in_background=false,
|
||||
description="Deep project analysis",
|
||||
prompt=`
|
||||
Analyze project for workflow initialization and generate .workflow/project-tech.json.
|
||||
Analyze project for workflow initialization and generate .workflow/project.json.
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
1. Execute: cat ~/.claude/workflows/cli-templates/schemas/project-tech-schema.json (get schema reference)
|
||||
2. Execute: ccw tool exec get_modules_by_depth '{}' (get project structure)
|
||||
1. Execute: cat ~/.claude/workflows/cli-templates/schemas/project-json-schema.json (get schema reference)
|
||||
2. Execute: ~/.claude/scripts/get_modules_by_depth.sh (get project structure)
|
||||
|
||||
## Task
|
||||
Generate complete project-tech.json following the schema structure:
|
||||
- project_name: "${projectName}"
|
||||
- initialized_at: ISO 8601 timestamp
|
||||
- overview: {
|
||||
description: "Brief project description",
|
||||
technology_stack: {
|
||||
languages: [{name, file_count, primary}],
|
||||
frameworks: ["string"],
|
||||
build_tools: ["string"],
|
||||
test_frameworks: ["string"]
|
||||
},
|
||||
architecture: {style, layers: [], patterns: []},
|
||||
key_components: [{name, path, description, importance}]
|
||||
}
|
||||
- features: []
|
||||
Generate complete project.json with:
|
||||
- project_name: ${projectName}
|
||||
- initialized_at: current ISO timestamp
|
||||
- overview: {description, technology_stack, architecture, key_components}
|
||||
- features: ${regenerate ? 'preserve from backup' : '[] (empty)'}
|
||||
- development_index: ${regenerate ? 'preserve from backup' : '{feature: [], enhancement: [], bugfix: [], refactor: [], docs: []}'}
|
||||
- statistics: ${regenerate ? 'preserve from backup' : '{total_features: 0, total_sessions: 0, last_updated: ISO timestamp}'}
|
||||
- _metadata: {initialized_by: "cli-explore-agent", analysis_timestamp: ISO timestamp, analysis_mode: "deep-scan"}
|
||||
- statistics: ${regenerate ? 'preserve from backup' : '{total_features: 0, total_sessions: 0, last_updated}'}
|
||||
- _metadata: {initialized_by: "cli-explore-agent", analysis_timestamp, analysis_mode}
|
||||
|
||||
## Analysis Requirements
|
||||
|
||||
@@ -145,8 +122,8 @@ Generate complete project-tech.json following the schema structure:
|
||||
1. Structural scan: get_modules_by_depth.sh, find, wc -l
|
||||
2. Semantic analysis: Gemini for patterns/architecture
|
||||
3. Synthesis: Merge findings
|
||||
4. ${regenerate ? 'Merge with preserved development_index and statistics from .workflow/project-tech.json.backup' : ''}
|
||||
5. Write JSON: Write('.workflow/project-tech.json', jsonContent)
|
||||
4. ${regenerate ? 'Merge with preserved features/development_index/statistics from .workflow/project.json.backup' : ''}
|
||||
5. Write JSON: Write('.workflow/project.json', jsonContent)
|
||||
6. Report: Return brief completion summary
|
||||
|
||||
Project root: ${projectRoot}
|
||||
@@ -154,66 +131,29 @@ Project root: ${projectRoot}
|
||||
)
|
||||
```
|
||||
|
||||
### Step 3.5: Create Guidelines Scaffold (if not exists)
|
||||
|
||||
```javascript
|
||||
// Only create if not exists (never overwrite user guidelines)
|
||||
if (!file_exists('.workflow/project-guidelines.json')) {
|
||||
const guidelinesScaffold = {
|
||||
conventions: {
|
||||
coding_style: [],
|
||||
naming_patterns: [],
|
||||
file_structure: [],
|
||||
documentation: []
|
||||
},
|
||||
constraints: {
|
||||
architecture: [],
|
||||
tech_stack: [],
|
||||
performance: [],
|
||||
security: []
|
||||
},
|
||||
quality_rules: [],
|
||||
learnings: [],
|
||||
_metadata: {
|
||||
created_at: new Date().toISOString(),
|
||||
version: "1.0.0"
|
||||
}
|
||||
};
|
||||
|
||||
Write('.workflow/project-guidelines.json', JSON.stringify(guidelinesScaffold, null, 2));
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Display Summary
|
||||
|
||||
```javascript
|
||||
const projectTech = JSON.parse(Read('.workflow/project-tech.json'));
|
||||
const guidelinesExists = file_exists('.workflow/project-guidelines.json');
|
||||
const projectJson = JSON.parse(Read('.workflow/project.json'));
|
||||
|
||||
console.log(`
|
||||
✓ Project initialized successfully
|
||||
|
||||
## Project Overview
|
||||
Name: ${projectTech.project_name}
|
||||
Description: ${projectTech.overview.description}
|
||||
Name: ${projectJson.project_name}
|
||||
Description: ${projectJson.overview.description}
|
||||
|
||||
### Technology Stack
|
||||
Languages: ${projectTech.overview.technology_stack.languages.map(l => l.name).join(', ')}
|
||||
Frameworks: ${projectTech.overview.technology_stack.frameworks.join(', ')}
|
||||
Languages: ${projectJson.overview.technology_stack.languages.map(l => l.name).join(', ')}
|
||||
Frameworks: ${projectJson.overview.technology_stack.frameworks.join(', ')}
|
||||
|
||||
### Architecture
|
||||
Style: ${projectTech.overview.architecture.style}
|
||||
Components: ${projectTech.overview.key_components.length} core modules
|
||||
Style: ${projectJson.overview.architecture.style}
|
||||
Components: ${projectJson.overview.key_components.length} core modules
|
||||
|
||||
---
|
||||
Files created:
|
||||
- Tech analysis: .workflow/project-tech.json
|
||||
- Guidelines: .workflow/project-guidelines.json ${guidelinesExists ? '(scaffold)' : ''}
|
||||
${regenerate ? '- Backup: .workflow/project-tech.json.backup' : ''}
|
||||
|
||||
Next steps:
|
||||
- Use /workflow:session:solidify to add project guidelines
|
||||
- Use /workflow:plan to start planning
|
||||
Project state: .workflow/project.json
|
||||
${regenerate ? 'Backup: .workflow/project.json.backup' : ''}
|
||||
`);
|
||||
```
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: lite-execute
|
||||
description: Execute tasks based on in-memory plan, prompt description, or file content
|
||||
argument-hint: "[-y|--yes] [--in-memory] [\"task description\"|file-path]"
|
||||
argument-hint: "[--in-memory] [\"task description\"|file-path]"
|
||||
allowed-tools: TodoWrite(*), Task(*), Bash(*)
|
||||
---
|
||||
|
||||
@@ -62,49 +62,30 @@ Flexible task execution command supporting three input modes: in-memory plan (fr
|
||||
|
||||
**User Interaction**:
|
||||
```javascript
|
||||
// Parse --yes flag
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
|
||||
let userSelection
|
||||
|
||||
if (autoYes) {
|
||||
// Auto mode: Use defaults
|
||||
console.log(`[--yes] Auto-confirming execution:`)
|
||||
console.log(` - Execution method: Auto`)
|
||||
console.log(` - Code review: Skip`)
|
||||
|
||||
userSelection = {
|
||||
execution_method: "Auto",
|
||||
code_review_tool: "Skip"
|
||||
}
|
||||
} else {
|
||||
// Interactive mode: Ask user
|
||||
userSelection = AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "Select execution method:",
|
||||
header: "Execution",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Agent", description: "@code-developer agent" },
|
||||
{ label: "Codex", description: "codex CLI tool" },
|
||||
{ label: "Auto", description: "Auto-select based on complexity" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Enable code review after execution?",
|
||||
header: "Code Review",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Skip", description: "No review" },
|
||||
{ label: "Gemini Review", description: "Gemini CLI tool" },
|
||||
{ label: "Codex Review", description: "Git-aware review (prompt OR --uncommitted)" },
|
||||
{ label: "Agent Review", description: "Current agent review" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
}
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "Select execution method:",
|
||||
header: "Execution",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Agent", description: "@code-developer agent" },
|
||||
{ label: "Codex", description: "codex CLI tool" },
|
||||
{ label: "Auto", description: "Auto-select based on complexity" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Enable code review after execution?",
|
||||
header: "Code Review",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Skip", description: "No review" },
|
||||
{ label: "Gemini Review", description: "Gemini CLI tool" },
|
||||
{ label: "Agent Review", description: "Current agent review" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
### Mode 3: File Content
|
||||
@@ -190,23 +171,10 @@ Output:
|
||||
**Operations**:
|
||||
- Initialize result tracking for multi-execution scenarios
|
||||
- Set up `previousExecutionResults` array for context continuity
|
||||
- **In-Memory Mode**: Echo execution strategy from lite-plan for transparency
|
||||
|
||||
```javascript
|
||||
// Initialize result tracking
|
||||
previousExecutionResults = []
|
||||
|
||||
// In-Memory Mode: Echo execution strategy (transparency before execution)
|
||||
if (executionContext) {
|
||||
console.log(`
|
||||
📋 Execution Strategy (from lite-plan):
|
||||
Method: ${executionContext.executionMethod}
|
||||
Review: ${executionContext.codeReviewTool}
|
||||
Tasks: ${executionContext.planObject.tasks.length}
|
||||
Complexity: ${executionContext.planObject.complexity}
|
||||
${executionContext.executorAssignments ? ` Assignments: ${JSON.stringify(executionContext.executorAssignments)}` : ''}
|
||||
`)
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Task Grouping & Batch Creation
|
||||
@@ -290,33 +258,6 @@ TodoWrite({
|
||||
|
||||
### Step 3: Launch Execution
|
||||
|
||||
**Executor Resolution** (任务级 executor 优先于全局设置):
|
||||
```javascript
|
||||
// 获取任务的 executor（优先使用 executorAssignments，fallback 到全局 executionMethod）
|
||||
function getTaskExecutor(task) {
|
||||
const assignments = executionContext?.executorAssignments || {}
|
||||
if (assignments[task.id]) {
|
||||
return assignments[task.id].executor // 'gemini' | 'codex' | 'agent'
|
||||
}
|
||||
// Fallback: 全局 executionMethod 映射
|
||||
const method = executionContext?.executionMethod || 'Auto'
|
||||
if (method === 'Agent') return 'agent'
|
||||
if (method === 'Codex') return 'codex'
|
||||
// Auto: 根据复杂度
|
||||
return planObject.complexity === 'Low' ? 'agent' : 'codex'
|
||||
}
|
||||
|
||||
// 按 executor 分组任务
|
||||
function groupTasksByExecutor(tasks) {
|
||||
const groups = { gemini: [], codex: [], agent: [] }
|
||||
tasks.forEach(task => {
|
||||
const executor = getTaskExecutor(task)
|
||||
groups[executor].push(task)
|
||||
})
|
||||
return groups
|
||||
}
|
||||
```
|
||||
|
||||
**Execution Flow**: Parallel batches concurrently → Sequential batches in order
|
||||
```javascript
|
||||
const parallel = executionCalls.filter(c => c.executionType === "parallel")
|
||||
@@ -339,99 +280,118 @@ for (const call of sequential) {
|
||||
}
|
||||
```
|
||||
|
||||
### Unified Task Prompt Builder
|
||||
|
||||
**Task Formatting Principle**: Each task is a self-contained checklist. The executor only needs to know what THIS task requires. Same template for Agent and CLI.
|
||||
|
||||
```javascript
|
||||
function buildExecutionPrompt(batch) {
|
||||
// Task template (6 parts: Modification Points → Why → How → Reference → Risks → Done)
|
||||
const formatTask = (t) => `
|
||||
## ${t.title}
|
||||
|
||||
**Scope**: \`${t.scope}\` | **Action**: ${t.action}
|
||||
|
||||
### Modification Points
|
||||
${t.modification_points.map(p => `- **${p.file}** → \`${p.target}\`: ${p.change}`).join('\n')}
|
||||
|
||||
${t.rationale ? `
|
||||
### Why this approach (Medium/High)
|
||||
${t.rationale.chosen_approach}
|
||||
${t.rationale.decision_factors?.length > 0 ? `\nKey factors: ${t.rationale.decision_factors.join(', ')}` : ''}
|
||||
${t.rationale.tradeoffs ? `\nTradeoffs: ${t.rationale.tradeoffs}` : ''}
|
||||
` : ''}
|
||||
|
||||
### How to do it
|
||||
${t.description}
|
||||
|
||||
${t.implementation.map(step => `- ${step}`).join('\n')}
|
||||
|
||||
${t.code_skeleton ? `
|
||||
### Code skeleton (High)
|
||||
${t.code_skeleton.interfaces?.length > 0 ? `**Interfaces**: ${t.code_skeleton.interfaces.map(i => `\`${i.name}\` - ${i.purpose}`).join(', ')}` : ''}
|
||||
${t.code_skeleton.key_functions?.length > 0 ? `\n**Functions**: ${t.code_skeleton.key_functions.map(f => `\`${f.signature}\` - ${f.purpose}`).join(', ')}` : ''}
|
||||
${t.code_skeleton.classes?.length > 0 ? `\n**Classes**: ${t.code_skeleton.classes.map(c => `\`${c.name}\` - ${c.purpose}`).join(', ')}` : ''}
|
||||
` : ''}
|
||||
|
||||
### Reference
|
||||
- Pattern: ${t.reference?.pattern || 'N/A'}
|
||||
- Files: ${t.reference?.files?.join(', ') || 'N/A'}
|
||||
${t.reference?.examples ? `- Notes: ${t.reference.examples}` : ''}
|
||||
|
||||
${t.risks?.length > 0 ? `
|
||||
### Risk mitigations (High)
|
||||
${t.risks.map(r => `- ${r.description} → **${r.mitigation}**`).join('\n')}
|
||||
` : ''}
|
||||
|
||||
### Done when
|
||||
${t.acceptance.map(c => `- [ ] ${c}`).join('\n')}
|
||||
${t.verification?.success_metrics?.length > 0 ? `\n**Success metrics**: ${t.verification.success_metrics.join(', ')}` : ''}`
|
||||
|
||||
// Build prompt
|
||||
const sections = []
|
||||
|
||||
if (originalUserInput) sections.push(`## Goal\n${originalUserInput}`)
|
||||
|
||||
sections.push(`## Tasks\n${batch.tasks.map(formatTask).join('\n\n---\n')}`)
|
||||
|
||||
// Context (reference only)
|
||||
const context = []
|
||||
if (previousExecutionResults.length > 0) {
|
||||
context.push(`### Previous Work\n${previousExecutionResults.map(r => `- ${r.tasksSummary}: ${r.status}`).join('\n')}`)
|
||||
}
|
||||
if (clarificationContext) {
|
||||
context.push(`### Clarifications\n${Object.entries(clarificationContext).map(([q, a]) => `- ${q}: ${a}`).join('\n')}`)
|
||||
}
|
||||
if (executionContext?.planObject?.data_flow?.diagram) {
|
||||
context.push(`### Data Flow\n${executionContext.planObject.data_flow.diagram}`)
|
||||
}
|
||||
if (executionContext?.session?.artifacts?.plan) {
|
||||
context.push(`### Artifacts\nPlan: ${executionContext.session.artifacts.plan}`)
|
||||
}
|
||||
// Project guidelines (user-defined constraints from /workflow:session:solidify)
|
||||
context.push(`### Project Guidelines\n@.workflow/project-guidelines.json`)
|
||||
if (context.length > 0) sections.push(`## Context\n${context.join('\n\n')}`)
|
||||
|
||||
sections.push(`Complete each task according to its "Done when" checklist.`)
|
||||
|
||||
return sections.join('\n\n')
|
||||
}
|
||||
```
|
||||
|
||||
**Option A: Agent Execution**
|
||||
|
||||
When to use:
|
||||
- `getTaskExecutor(task) === "agent"`
|
||||
- 或 `executionMethod = "Agent"` (全局 fallback)
|
||||
- 或 `executionMethod = "Auto" AND complexity = "Low"` (全局 fallback)
|
||||
- `executionMethod = "Agent"`
|
||||
- `executionMethod = "Auto" AND complexity = "Low"`
|
||||
|
||||
**Task Formatting Principle**: Each task is a self-contained checklist. The agent only needs to know what THIS task requires, not its position or relation to other tasks.
|
||||
|
||||
Agent call format:
|
||||
```javascript
|
||||
// Format single task as self-contained checklist
|
||||
function formatTaskChecklist(task) {
|
||||
return `
|
||||
## ${task.title}
|
||||
|
||||
**Target**: \`${task.file}\`
|
||||
**Action**: ${task.action}
|
||||
|
||||
### What to do
|
||||
${task.description}
|
||||
|
||||
### How to do it
|
||||
${task.implementation.map(step => `- ${step}`).join('\n')}
|
||||
|
||||
### Reference
|
||||
- Pattern: ${task.reference.pattern}
|
||||
- Examples: ${task.reference.files.join(', ')}
|
||||
- Notes: ${task.reference.examples}
|
||||
|
||||
### Done when
|
||||
${task.acceptance.map(c => `- [ ] ${c}`).join('\n')}
|
||||
`
|
||||
}
|
||||
|
||||
// For batch execution: aggregate tasks without numbering
|
||||
function formatBatchPrompt(batch) {
|
||||
const tasksSection = batch.tasks.map(t => formatTaskChecklist(t)).join('\n---\n')
|
||||
|
||||
return `
|
||||
${originalUserInput ? `## Goal\n${originalUserInput}\n` : ''}
|
||||
|
||||
## Tasks
|
||||
|
||||
${tasksSection}
|
||||
|
||||
${batch.context ? `## Context\n${batch.context}` : ''}
|
||||
|
||||
Complete each task according to its "Done when" checklist.
|
||||
`
|
||||
}
|
||||
|
||||
Task(
|
||||
subagent_type="code-developer",
|
||||
run_in_background=false,
|
||||
description=batch.taskSummary,
|
||||
prompt=buildExecutionPrompt(batch)
|
||||
prompt=formatBatchPrompt({
|
||||
tasks: batch.tasks,
|
||||
context: buildRelevantContext(batch.tasks)
|
||||
})
|
||||
)
|
||||
|
||||
// Helper: Build relevant context for batch
|
||||
// Context serves as REFERENCE ONLY - helps agent understand existing state
|
||||
function buildRelevantContext(tasks) {
|
||||
const sections = []
|
||||
|
||||
// 1. Previous work completion - what's already done (reference for continuity)
|
||||
if (previousExecutionResults.length > 0) {
|
||||
sections.push(`### Previous Work (Reference)
|
||||
Use this to understand what's already completed. Avoid duplicating work.
|
||||
|
||||
${previousExecutionResults.map(r => `**${r.tasksSummary}**
|
||||
- Status: ${r.status}
|
||||
- Outputs: ${r.keyOutputs || 'See git diff'}
|
||||
${r.notes ? `- Notes: ${r.notes}` : ''}`
|
||||
).join('\n\n')}`)
|
||||
}
|
||||
|
||||
// 2. Related files - files that may need to be read/referenced
|
||||
const relatedFiles = extractRelatedFiles(tasks)
|
||||
if (relatedFiles.length > 0) {
|
||||
sections.push(`### Related Files (Reference)
|
||||
These files may contain patterns, types, or utilities relevant to your tasks:
|
||||
|
||||
${relatedFiles.map(f => `- \`${f}\``).join('\n')}`)
|
||||
}
|
||||
|
||||
// 3. Clarifications from user
|
||||
if (clarificationContext) {
|
||||
sections.push(`### User Clarifications
|
||||
${Object.entries(clarificationContext).map(([q, a]) => `- **${q}**: ${a}`).join('\n')}`)
|
||||
}
|
||||
|
||||
// 4. Artifact files (for deeper context if needed)
|
||||
if (executionContext?.session?.artifacts?.plan) {
|
||||
sections.push(`### Artifacts
|
||||
For detailed planning context, read: ${executionContext.session.artifacts.plan}`)
|
||||
}
|
||||
|
||||
return sections.join('\n\n')
|
||||
}
|
||||
|
||||
// Extract related files from task references
|
||||
function extractRelatedFiles(tasks) {
|
||||
const files = new Set()
|
||||
tasks.forEach(task => {
|
||||
// Add reference example files
|
||||
if (task.reference?.files) {
|
||||
task.reference.files.forEach(f => files.add(f))
|
||||
}
|
||||
})
|
||||
return [...files]
|
||||
}
|
||||
```
|
||||
|
||||
**Result Collection**: After completion, collect result following `executionResult` structure (see Data Structures section)
|
||||
@@ -439,64 +399,103 @@ Task(
|
||||
**Option B: CLI Execution (Codex)**
|
||||
|
||||
When to use:
|
||||
- `getTaskExecutor(task) === "codex"`
|
||||
- 或 `executionMethod = "Codex"` (全局 fallback)
|
||||
- 或 `executionMethod = "Auto" AND complexity = "Medium/High"` (全局 fallback)
|
||||
- `executionMethod = "Codex"`
|
||||
- `executionMethod = "Auto" AND complexity = "Medium" or "High"`
|
||||
|
||||
**Task Formatting Principle**: Same as Agent - each task is a self-contained checklist. No task numbering or position awareness.
|
||||
|
||||
Command format:
|
||||
```bash
|
||||
ccw cli -p "${buildExecutionPrompt(batch)}" --tool codex --mode write
|
||||
```
|
||||
// Format single task as compact checklist for CLI
|
||||
function formatTaskForCLI(task) {
|
||||
return `
|
||||
## ${task.title}
|
||||
File: ${task.file}
|
||||
Action: ${task.action}
|
||||
|
||||
**Execution with fixed IDs** (predictable ID pattern):
|
||||
```javascript
|
||||
// Launch CLI in background, wait for task hook callback
|
||||
// Generate fixed execution ID: ${sessionId}-${groupId}
|
||||
const sessionId = executionContext?.session?.id || 'standalone'
|
||||
const fixedExecutionId = `${sessionId}-${batch.groupId}` // e.g., "implement-auth-2025-12-13-P1"
|
||||
What: ${task.description}
|
||||
|
||||
// Check if resuming from previous failed execution
|
||||
const previousCliId = batch.resumeFromCliId || null
|
||||
How:
|
||||
${task.implementation.map(step => `- ${step}`).join('\n')}
|
||||
|
||||
// Build command with fixed ID (and optional resume for continuation)
|
||||
const cli_command = previousCliId
|
||||
? `ccw cli -p "${buildExecutionPrompt(batch)}" --tool codex --mode write --id ${fixedExecutionId} --resume ${previousCliId}`
|
||||
: `ccw cli -p "${buildExecutionPrompt(batch)}" --tool codex --mode write --id ${fixedExecutionId}`
|
||||
Reference: ${task.reference.pattern} (see ${task.reference.files.join(', ')})
|
||||
Notes: ${task.reference.examples}
|
||||
|
||||
// Execute in background, stop output and wait for task hook callback
|
||||
Bash(
|
||||
command=cli_command,
|
||||
run_in_background=true
|
||||
)
|
||||
// STOP HERE - CLI executes in background, task hook will notify on completion
|
||||
```
|
||||
|
||||
**Resume on Failure** (with fixed ID):
|
||||
```javascript
|
||||
// If execution failed or timed out, offer resume option
|
||||
if (bash_result.status === 'failed' || bash_result.status === 'timeout') {
|
||||
console.log(`
|
||||
⚠️ Execution incomplete. Resume available:
|
||||
Fixed ID: ${fixedExecutionId}
|
||||
Lookup: ccw cli detail ${fixedExecutionId}
|
||||
Resume: ccw cli -p "Continue tasks" --resume ${fixedExecutionId} --tool codex --mode write --id ${fixedExecutionId}-retry
|
||||
`)
|
||||
|
||||
// Store for potential retry in same session
|
||||
batch.resumeFromCliId = fixedExecutionId
|
||||
Done when:
|
||||
${task.acceptance.map(c => `- [ ] ${c}`).join('\n')}
|
||||
`
|
||||
}
|
||||
|
||||
// Build CLI prompt for batch
|
||||
// Context provides REFERENCE information - not requirements to fulfill
|
||||
function buildCLIPrompt(batch) {
|
||||
const tasksSection = batch.tasks.map(t => formatTaskForCLI(t)).join('\n---\n')
|
||||
|
||||
let prompt = `${originalUserInput ? `## Goal\n${originalUserInput}\n\n` : ''}`
|
||||
prompt += `## Tasks\n\n${tasksSection}\n`
|
||||
|
||||
// Context section - reference information only
|
||||
const contextSections = []
|
||||
|
||||
// 1. Previous work - what's already completed
|
||||
if (previousExecutionResults.length > 0) {
|
||||
contextSections.push(`### Previous Work (Reference)
|
||||
Already completed - avoid duplicating:
|
||||
${previousExecutionResults.map(r => `- ${r.tasksSummary}: ${r.status}${r.keyOutputs ? ` (${r.keyOutputs})` : ''}`).join('\n')}`)
|
||||
}
|
||||
|
||||
// 2. Related files from task references
|
||||
const relatedFiles = [...new Set(batch.tasks.flatMap(t => t.reference?.files || []))]
|
||||
if (relatedFiles.length > 0) {
|
||||
contextSections.push(`### Related Files (Reference)
|
||||
Patterns and examples to follow:
|
||||
${relatedFiles.map(f => `- ${f}`).join('\n')}`)
|
||||
}
|
||||
|
||||
// 3. User clarifications
|
||||
if (clarificationContext) {
|
||||
contextSections.push(`### Clarifications
|
||||
${Object.entries(clarificationContext).map(([q, a]) => `- ${q}: ${a}`).join('\n')}`)
|
||||
}
|
||||
|
||||
// 4. Plan artifact for deeper context
|
||||
if (executionContext?.session?.artifacts?.plan) {
|
||||
contextSections.push(`### Artifacts
|
||||
Detailed plan: ${executionContext.session.artifacts.plan}`)
|
||||
}
|
||||
|
||||
if (contextSections.length > 0) {
|
||||
prompt += `\n## Context\n${contextSections.join('\n\n')}\n`
|
||||
}
|
||||
|
||||
prompt += `\nComplete each task according to its "Done when" checklist.`
|
||||
|
||||
return prompt
|
||||
}
|
||||
|
||||
codex --full-auto exec "${buildCLIPrompt(batch)}" --skip-git-repo-check -s danger-full-access
|
||||
```
|
||||
|
||||
**Result Collection**: After completion, analyze output and collect result following `executionResult` structure (include `cliExecutionId` for resume capability)
|
||||
**Execution with tracking**:
|
||||
```javascript
|
||||
// Launch CLI in foreground (NOT background)
|
||||
// Timeout based on complexity: Low=40min, Medium=60min, High=100min
|
||||
const timeoutByComplexity = {
|
||||
"Low": 2400000, // 40 minutes
|
||||
"Medium": 3600000, // 60 minutes
|
||||
"High": 6000000 // 100 minutes
|
||||
}
|
||||
|
||||
**Option C: CLI Execution (Gemini)**
|
||||
bash_result = Bash(
|
||||
command=cli_command,
|
||||
timeout=timeoutByComplexity[planObject.complexity] || 3600000
|
||||
)
|
||||
|
||||
When to use: `getTaskExecutor(task) === "gemini"` (分析类任务)
|
||||
|
||||
```bash
|
||||
# 使用统一的 buildExecutionPrompt，切换 tool 和 mode
|
||||
ccw cli -p "${buildExecutionPrompt(batch)}" --tool gemini --mode analysis --id ${sessionId}-${batch.groupId}
|
||||
// Update TodoWrite when execution completes
|
||||
```
|
||||
|
||||
**Result Collection**: After completion, analyze output and collect result following `executionResult` structure
|
||||
|
||||
### Step 4: Progress Tracking
|
||||
|
||||
Progress tracked at batch level (not individual task level). Icons: ⚡ (parallel, concurrent), → (sequential, one-by-one)
|
||||
@@ -505,41 +504,32 @@ Progress tracked at batch level (not individual task level). Icons: ⚡ (paralle
|
||||
|
||||
**Skip Condition**: Only run if `codeReviewTool ≠ "Skip"`
|
||||
|
||||
**Review Focus**: Verify implementation against plan acceptance criteria and verification requirements
|
||||
- Read plan.json for task acceptance criteria and verification checklist
|
||||
**Review Focus**: Verify implementation against plan acceptance criteria
|
||||
- Read plan.json for task acceptance criteria
|
||||
- Check each acceptance criterion is fulfilled
|
||||
- Verify success metrics from verification field (Medium/High complexity)
|
||||
- Run unit/integration tests specified in verification field
|
||||
- Validate code quality and identify issues
|
||||
- Ensure alignment with planned approach and risk mitigations
|
||||
- Ensure alignment with planned approach
|
||||
|
||||
**Operations**:
|
||||
- Agent Review: Current agent performs direct review
|
||||
- Gemini Review: Execute gemini CLI with review prompt
|
||||
- Codex Review: Two options - (A) with prompt for complex reviews, (B) `--uncommitted` flag only for quick reviews
|
||||
- Custom tool: Execute specified CLI tool (qwen, etc.)
|
||||
- Custom tool: Execute specified CLI tool (qwen, codex, etc.)
|
||||
|
||||
**Unified Review Template** (All tools use same standard):
|
||||
|
||||
**Review Criteria**:
|
||||
- **Acceptance Criteria**: Verify each criterion from plan.tasks[].acceptance
|
||||
- **Verification Checklist** (Medium/High): Check unit_tests, integration_tests, success_metrics from plan.tasks[].verification
|
||||
- **Code Quality**: Analyze quality, identify issues, suggest improvements
|
||||
- **Plan Alignment**: Validate implementation matches planned approach and risk mitigations
|
||||
- **Plan Alignment**: Validate implementation matches planned approach
|
||||
|
||||
**Shared Prompt Template** (used by all CLI tools):
|
||||
```
|
||||
PURPOSE: Code review for implemented changes against plan acceptance criteria and verification requirements
|
||||
TASK: • Verify plan acceptance criteria fulfillment • Check verification requirements (unit tests, success metrics) • Analyze code quality • Identify issues • Suggest improvements • Validate plan adherence and risk mitigations
|
||||
PURPOSE: Code review for implemented changes against plan acceptance criteria
|
||||
TASK: • Verify plan acceptance criteria fulfillment • Analyze code quality • Identify issues • Suggest improvements • Validate plan adherence
|
||||
MODE: analysis
|
||||
CONTEXT: @**/* @{plan.json} [@{exploration.json}] | Memory: Review lite-execute changes against plan requirements including verification checklist
|
||||
EXPECTED: Quality assessment with:
|
||||
- Acceptance criteria verification (all tasks)
|
||||
- Verification checklist validation (Medium/High: unit_tests, integration_tests, success_metrics)
|
||||
- Issue identification
|
||||
- Recommendations
|
||||
Explicitly check each acceptance criterion and verification item from plan.json tasks.
|
||||
CONSTRAINTS: Focus on plan acceptance criteria, verification requirements, and plan adherence | analysis=READ-ONLY
|
||||
CONTEXT: @**/* @{plan.json} [@{exploration.json}] | Memory: Review lite-execute changes against plan requirements
|
||||
EXPECTED: Quality assessment with acceptance criteria verification, issue identification, and recommendations. Explicitly check each acceptance criterion from plan.json tasks.
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on plan acceptance criteria and plan adherence | analysis=READ-ONLY
|
||||
```
|
||||
|
||||
**Tool-Specific Execution** (Apply shared prompt template above):
|
||||
@@ -551,39 +541,15 @@ CONSTRAINTS: Focus on plan acceptance criteria, verification requirements, and p
|
||||
# - Report findings directly
|
||||
|
||||
# Method 2: Gemini Review (recommended)
|
||||
ccw cli -p "[Shared Prompt Template with artifacts]" --tool gemini --mode analysis
|
||||
gemini -p "[Shared Prompt Template with artifacts]"
|
||||
# CONTEXT includes: @**/* @${plan.json} [@${exploration.json}]
|
||||
|
||||
# Method 3: Qwen Review (alternative)
|
||||
ccw cli -p "[Shared Prompt Template with artifacts]" --tool qwen --mode analysis
|
||||
qwen -p "[Shared Prompt Template with artifacts]"
|
||||
# Same prompt as Gemini, different execution engine
|
||||
|
||||
# Method 4: Codex Review (git-aware) - Two mutually exclusive options:
|
||||
|
||||
# Option A: With custom prompt (reviews uncommitted by default)
|
||||
ccw cli -p "[Shared Prompt Template with artifacts]" --tool codex --mode review
|
||||
# Use for complex reviews with specific focus areas
|
||||
|
||||
# Option B: Target flag only (no prompt allowed)
|
||||
ccw cli --tool codex --mode review --uncommitted
|
||||
# Quick review of uncommitted changes without custom instructions
|
||||
|
||||
# ⚠️ IMPORTANT: -p prompt and target flags (--uncommitted/--base/--commit) are MUTUALLY EXCLUSIVE
|
||||
```
|
||||
|
||||
**Multi-Round Review with Fixed IDs**:
|
||||
```javascript
|
||||
// Generate fixed review ID
|
||||
const reviewId = `${sessionId}-review`
|
||||
|
||||
// First review pass with fixed ID
|
||||
const reviewResult = Bash(`ccw cli -p "[Review prompt]" --tool gemini --mode analysis --id ${reviewId}`)
|
||||
|
||||
// If issues found, continue review dialog with fixed ID chain
|
||||
if (hasUnresolvedIssues(reviewResult)) {
|
||||
// Resume with follow-up questions
|
||||
Bash(`ccw cli -p "Clarify the security concerns you mentioned" --resume ${reviewId} --tool gemini --mode analysis --id ${reviewId}-followup`)
|
||||
}
|
||||
# Method 4: Codex Review (autonomous)
|
||||
codex --full-auto exec "[Verify plan acceptance criteria at ${plan.json}]" --skip-git-repo-check -s danger-full-access
|
||||
```
|
||||
|
||||
**Implementation Note**: Replace `[Shared Prompt Template with artifacts]` placeholder with actual template content, substituting:
|
||||
@@ -594,11 +560,11 @@ if (hasUnresolvedIssues(reviewResult)) {
|
||||
|
||||
**Trigger**: After all executions complete (regardless of code review)
|
||||
|
||||
**Skip Condition**: Skip if `.workflow/project-tech.json` does not exist
|
||||
**Skip Condition**: Skip if `.workflow/project.json` does not exist
|
||||
|
||||
**Operations**:
|
||||
```javascript
|
||||
const projectJsonPath = '.workflow/project-tech.json'
|
||||
const projectJsonPath = '.workflow/project.json'
|
||||
if (!fileExists(projectJsonPath)) return // Silent skip
|
||||
|
||||
const projectJson = JSON.parse(Read(projectJsonPath))
|
||||
@@ -657,10 +623,8 @@ console.log(`✓ Development index: [${category}] ${entry.title}`)
|
||||
| Empty file | File exists but no content | Error: "File is empty: {path}. Provide task description." |
|
||||
| Invalid Enhanced Task JSON | JSON missing required fields | Warning: "Missing required fields. Treating as plain text." |
|
||||
| Malformed JSON | JSON parsing fails | Treat as plain text (expected for non-JSON files) |
|
||||
| Execution failure | Agent/Codex crashes | Display error, use fixed ID `${sessionId}-${groupId}` for resume: `ccw cli -p "Continue" --resume <fixed-id> --id <fixed-id>-retry` |
|
||||
| Execution timeout | CLI exceeded timeout | Use fixed ID for resume with extended timeout |
|
||||
| Execution failure | Agent/Codex crashes | Display error, save partial progress, suggest retry |
|
||||
| Codex unavailable | Codex not installed | Show installation instructions, offer Agent execution |
|
||||
| Fixed ID not found | Custom ID lookup failed | Check `ccw cli history`, verify date directories |
|
||||
|
||||
## Data Structures
|
||||
|
||||
@@ -682,15 +646,10 @@ Passed from lite-plan via global variable:
|
||||
explorationAngles: string[], // List of exploration angles
|
||||
explorationManifest: {...} | null, // Exploration manifest
|
||||
clarificationContext: {...} | null,
|
||||
executionMethod: "Agent" | "Codex" | "Auto", // 全局默认
|
||||
executionMethod: "Agent" | "Codex" | "Auto",
|
||||
codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string,
|
||||
originalUserInput: string,
|
||||
|
||||
// 任务级 executor 分配（优先于 executionMethod）
|
||||
executorAssignments: {
|
||||
[taskId]: { executor: "gemini" | "codex" | "agent", reason: string }
|
||||
},
|
||||
|
||||
// Session artifacts location (saved by lite-plan)
|
||||
session: {
|
||||
id: string, // Session identifier: {taskSlug}-{shortTimestamp}
|
||||
@@ -720,24 +679,8 @@ Collected after each execution call completes:
|
||||
tasksSummary: string, // Brief description of tasks handled
|
||||
completionSummary: string, // What was completed
|
||||
keyOutputs: string, // Files created/modified, key changes
|
||||
notes: string, // Important context for next execution
|
||||
fixedCliId: string | null // Fixed CLI execution ID (e.g., "implement-auth-2025-12-13-P1")
|
||||
notes: string // Important context for next execution
|
||||
}
|
||||
```
|
||||
|
||||
Appended to `previousExecutionResults` array for context continuity in multi-execution scenarios.
|
||||
|
||||
## Post-Completion Expansion
|
||||
|
||||
完成后询问用户是否扩展为issue(test/enhance/refactor/doc)，选中项调用 `/issue:new "{summary} - {dimension}"`
|
||||
|
||||
**Fixed ID Pattern**: `${sessionId}-${groupId}` enables predictable lookup without auto-generated timestamps.
|
||||
|
||||
**Resume Usage**: If `status` is "partial" or "failed", use `fixedCliId` to resume:
|
||||
```bash
|
||||
# Lookup previous execution
|
||||
ccw cli detail ${fixedCliId}
|
||||
|
||||
# Resume with new fixed ID for retry
|
||||
ccw cli -p "Continue from where we left off" --resume ${fixedCliId} --tool codex --mode write --id ${fixedCliId}-retry
|
||||
```
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: lite-fix
|
||||
description: Lightweight bug diagnosis and fix workflow with intelligent severity assessment and optional hotfix mode for production incidents
|
||||
argument-hint: "[-y|--yes] [--hotfix] \"bug description or issue reference\""
|
||||
argument-hint: "[--hotfix] \"bug description or issue reference\""
|
||||
allowed-tools: TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*)
|
||||
---
|
||||
|
||||
@@ -17,7 +17,7 @@ Intelligent lightweight bug fixing command with dynamic workflow adaptation base
|
||||
- Interactive clarification after diagnosis to gather missing information
|
||||
- Adaptive fix planning strategy (direct Claude vs cli-lite-planning-agent) based on complexity
|
||||
- Two-step confirmation: fix-plan display -> multi-dimensional input collection
|
||||
- Execution execute with complete context handoff to lite-execute
|
||||
- Execution dispatch with complete context handoff to lite-execute
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -25,32 +25,10 @@ Intelligent lightweight bug fixing command with dynamic workflow adaptation base
|
||||
/workflow:lite-fix [FLAGS] <BUG_DESCRIPTION>
|
||||
|
||||
# Flags
|
||||
-y, --yes Skip all confirmations (auto mode)
|
||||
--hotfix, -h Production hotfix mode (minimal diagnosis, fast fix)
|
||||
|
||||
# Arguments
|
||||
<bug-description> Bug description, error message, or path to .md file (required)
|
||||
|
||||
# Examples
|
||||
/workflow:lite-fix "用户登录失败" # Interactive mode
|
||||
/workflow:lite-fix --yes "用户登录失败" # Auto mode (no confirmations)
|
||||
/workflow:lite-fix -y --hotfix "生产环境数据库连接失败" # Auto + hotfix mode
|
||||
```
|
||||
|
||||
## Auto Mode Defaults
|
||||
|
||||
When `--yes` or `-y` flag is used:
|
||||
- **Clarification Questions**: Skipped (no clarification phase)
|
||||
- **Fix Plan Confirmation**: Auto-selected "Allow"
|
||||
- **Execution Method**: Auto-selected "Auto"
|
||||
- **Code Review**: Auto-selected "Skip"
|
||||
- **Severity**: Uses auto-detected severity (no manual override)
|
||||
- **Hotfix Mode**: Respects --hotfix flag if present, otherwise normal mode
|
||||
|
||||
**Flag Parsing**:
|
||||
```javascript
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
const hotfixMode = $ARGUMENTS.includes('--hotfix') || $ARGUMENTS.includes('-h')
|
||||
```
|
||||
|
||||
## Execution Process
|
||||
@@ -84,7 +62,7 @@ Phase 4: Confirmation & Selection
|
||||
|- Execution: Agent / Codex / Auto
|
||||
+- Review: Gemini / Agent / Skip
|
||||
|
||||
Phase 5: Execute
|
||||
Phase 5: Dispatch
|
||||
|- Build executionContext (fix-plan + diagnoses + clarifications + selections)
|
||||
+- SlashCommand("/workflow:lite-execute --in-memory --mode bugfix")
|
||||
```
|
||||
@@ -186,7 +164,6 @@ Launching ${selectedAngles.length} parallel diagnoses...
|
||||
const diagnosisTasks = selectedAngles.map((angle, index) =>
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
run_in_background=false,
|
||||
description=`Diagnose: ${angle}`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
@@ -200,11 +177,9 @@ Execute **${angle}** diagnosis for bug root cause analysis. Analyze codebase fro
|
||||
|
||||
## MANDATORY FIRST STEPS (Execute by Agent)
|
||||
**You (cli-explore-agent) MUST execute these steps in order:**
|
||||
1. Run: ccw tool exec get_modules_by_depth '{}' (project structure)
|
||||
1. Run: ~/.claude/scripts/get_modules_by_depth.sh (project structure)
|
||||
2. Run: rg -l "{error_keyword_from_bug}" --type ts (locate relevant files)
|
||||
3. Execute: cat ~/.claude/workflows/cli-templates/schemas/diagnosis-json-schema.json (get output schema reference)
|
||||
4. Read: .workflow/project-tech.json (technology stack and architecture context)
|
||||
5. Read: .workflow/project-guidelines.json (user-defined constraints and conventions)
|
||||
|
||||
## Diagnosis Strategy (${angle} focus)
|
||||
|
||||
@@ -354,17 +329,9 @@ function deduplicateClarifications(clarifications) {
|
||||
|
||||
const uniqueClarifications = deduplicateClarifications(allClarifications)
|
||||
|
||||
// Parse --yes flag
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
|
||||
if (autoYes) {
|
||||
// Auto mode: Skip clarification phase
|
||||
console.log(`[--yes] Skipping ${uniqueClarifications.length} clarification questions`)
|
||||
console.log(`Proceeding to fix planning with diagnosis results...`)
|
||||
// Continue to Phase 3
|
||||
} else if (uniqueClarifications.length > 0) {
|
||||
// Interactive mode: Multi-round clarification
|
||||
// ⚠️ MUST execute ALL rounds until uniqueClarifications exhausted
|
||||
// Multi-round clarification: batch questions (max 4 per round)
|
||||
// ⚠️ MUST execute ALL rounds until uniqueClarifications exhausted
|
||||
if (uniqueClarifications.length > 0) {
|
||||
const BATCH_SIZE = 4
|
||||
const totalRounds = Math.ceil(uniqueClarifications.length / BATCH_SIZE)
|
||||
|
||||
@@ -410,7 +377,6 @@ if (autoYes) {
|
||||
const schema = Bash(`cat ~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json`)
|
||||
|
||||
// Step 2: Generate fix-plan following schema (Claude directly, no agent)
|
||||
// For Medium complexity: include rationale + verification (optional, but recommended)
|
||||
const fixPlan = {
|
||||
summary: "...",
|
||||
root_cause: "...",
|
||||
@@ -420,67 +386,13 @@ const fixPlan = {
|
||||
recommended_execution: "Agent",
|
||||
severity: severity,
|
||||
risk_level: "...",
|
||||
|
||||
// Medium complexity fields (optional for direct planning, auto-filled for Low)
|
||||
...(severity === "Medium" ? {
|
||||
design_decisions: [
|
||||
{
|
||||
decision: "Use immediate_patch strategy for minimal risk",
|
||||
rationale: "Keeps changes localized and quick to review",
|
||||
tradeoff: "Defers comprehensive refactoring"
|
||||
}
|
||||
],
|
||||
tasks_with_rationale: {
|
||||
// Each task gets rationale if Medium
|
||||
task_rationale_example: {
|
||||
rationale: {
|
||||
chosen_approach: "Direct fix approach",
|
||||
alternatives_considered: ["Workaround", "Refactor"],
|
||||
decision_factors: ["Minimal impact", "Quick turnaround"],
|
||||
tradeoffs: "Doesn't address underlying issue"
|
||||
},
|
||||
verification: {
|
||||
unit_tests: ["test_bug_fix_basic"],
|
||||
integration_tests: [],
|
||||
manual_checks: ["Reproduce issue", "Verify fix"],
|
||||
success_metrics: ["Issue resolved", "No regressions"]
|
||||
}
|
||||
}
|
||||
}
|
||||
} : {}),
|
||||
|
||||
_metadata: {
|
||||
timestamp: getUtc8ISOString(),
|
||||
source: "direct-planning",
|
||||
planning_mode: "direct",
|
||||
complexity: severity === "Medium" ? "Medium" : "Low"
|
||||
}
|
||||
_metadata: { timestamp: getUtc8ISOString(), source: "direct-planning", planning_mode: "direct" }
|
||||
}
|
||||
|
||||
// Step 3: Merge task rationale into tasks array
|
||||
if (severity === "Medium") {
|
||||
fixPlan.tasks = fixPlan.tasks.map(task => ({
|
||||
...task,
|
||||
rationale: fixPlan.tasks_with_rationale[task.id]?.rationale || {
|
||||
chosen_approach: "Standard fix",
|
||||
alternatives_considered: [],
|
||||
decision_factors: ["Correctness", "Simplicity"],
|
||||
tradeoffs: "None"
|
||||
},
|
||||
verification: fixPlan.tasks_with_rationale[task.id]?.verification || {
|
||||
unit_tests: [`test_${task.id}_basic`],
|
||||
integration_tests: [],
|
||||
manual_checks: ["Verify fix works"],
|
||||
success_metrics: ["Test pass"]
|
||||
}
|
||||
}))
|
||||
delete fixPlan.tasks_with_rationale // Clean up temp field
|
||||
}
|
||||
|
||||
// Step 4: Write fix-plan to session folder
|
||||
// Step 3: Write fix-plan to session folder
|
||||
Write(`${sessionFolder}/fix-plan.json`, JSON.stringify(fixPlan, null, 2))
|
||||
|
||||
// Step 5: MUST continue to Phase 4 (Confirmation) - DO NOT execute code here
|
||||
// Step 4: MUST continue to Phase 4 (Confirmation) - DO NOT execute code here
|
||||
```
|
||||
|
||||
**High/Critical Severity** - Invoke cli-lite-planning-agent:
|
||||
@@ -488,7 +400,6 @@ Write(`${sessionFolder}/fix-plan.json`, JSON.stringify(fixPlan, null, 2))
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-lite-planning-agent",
|
||||
run_in_background=false,
|
||||
description="Generate detailed fix plan",
|
||||
prompt=`
|
||||
Generate fix plan and write fix-plan.json.
|
||||
@@ -496,12 +407,6 @@ Generate fix plan and write fix-plan.json.
|
||||
## Output Schema Reference
|
||||
Execute: cat ~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json (get schema reference before generating plan)
|
||||
|
||||
## Project Context (MANDATORY - Read Both Files)
|
||||
1. Read: .workflow/project-tech.json (technology stack, architecture, key components)
|
||||
2. Read: .workflow/project-guidelines.json (user-defined constraints and conventions)
|
||||
|
||||
**CRITICAL**: All fix tasks MUST comply with constraints in project-guidelines.json
|
||||
|
||||
## Bug Description
|
||||
${bug_description}
|
||||
|
||||
@@ -536,41 +441,11 @@ Generate fix-plan.json with:
|
||||
- description
|
||||
- modification_points: ALL files to modify for this fix (group related changes)
|
||||
- implementation (2-5 steps covering all modification_points)
|
||||
- acceptance: Quantified acceptance criteria
|
||||
- verification (test criteria)
|
||||
- depends_on: task IDs this task depends on (use sparingly)
|
||||
|
||||
**High/Critical complexity fields per task** (REQUIRED):
|
||||
- rationale:
|
||||
- chosen_approach: Why this fix approach (not alternatives)
|
||||
- alternatives_considered: Other approaches evaluated
|
||||
- decision_factors: Key factors influencing choice
|
||||
- tradeoffs: Known tradeoffs of this approach
|
||||
- verification:
|
||||
- unit_tests: Test names to add/verify
|
||||
- integration_tests: Integration test names
|
||||
- manual_checks: Manual verification steps
|
||||
- success_metrics: Quantified success criteria
|
||||
- risks:
|
||||
- description: Risk description
|
||||
- probability: Low|Medium|High
|
||||
- impact: Low|Medium|High
|
||||
- mitigation: How to mitigate
|
||||
- fallback: Fallback if fix fails
|
||||
- code_skeleton (optional): Key interfaces/functions to implement
|
||||
- interfaces: [{name, definition, purpose}]
|
||||
- key_functions: [{signature, purpose, returns}]
|
||||
|
||||
**Top-level High/Critical fields** (REQUIRED):
|
||||
- data_flow: How data flows through affected code
|
||||
- diagram: "A → B → C" style flow
|
||||
- stages: [{stage, input, output, component}]
|
||||
- design_decisions: Global fix decisions
|
||||
- [{decision, rationale, tradeoff}]
|
||||
|
||||
- estimated_time, recommended_execution, severity, risk_level
|
||||
- _metadata:
|
||||
- timestamp, source, planning_mode
|
||||
- complexity: "High" | "Critical"
|
||||
- diagnosis_angles: ${JSON.stringify(manifest.diagnoses.map(d => d.angle))}
|
||||
|
||||
## Task Grouping Rules
|
||||
@@ -582,21 +457,11 @@ Generate fix-plan.json with:
|
||||
|
||||
## Execution
|
||||
1. Read ALL diagnosis files for comprehensive context
|
||||
2. Execute CLI planning using Gemini (Qwen fallback) with --rule planning-fix-strategy template
|
||||
2. Execute CLI planning using Gemini (Qwen fallback)
|
||||
3. Synthesize findings from multiple diagnosis angles
|
||||
4. Generate fix-plan with:
|
||||
- For High/Critical: REQUIRED new fields (rationale, verification, risks, code_skeleton, data_flow, design_decisions)
|
||||
- Each task MUST have rationale (why this fix), verification (how to verify success), and risks (potential issues)
|
||||
5. Parse output and structure fix-plan
|
||||
6. Write JSON: Write('${sessionFolder}/fix-plan.json', jsonContent)
|
||||
7. Return brief completion summary
|
||||
|
||||
## Output Format for CLI
|
||||
Include these sections in your fix-plan output:
|
||||
- Summary, Root Cause, Strategy (existing)
|
||||
- Data Flow: Diagram showing affected code paths
|
||||
- Design Decisions: Key architectural choices in the fix
|
||||
- Tasks: Each with rationale (Medium/High), verification (Medium/High), risks (High), code_skeleton (High)
|
||||
4. Parse output and structure fix-plan
|
||||
5. Write JSON: Write('${sessionFolder}/fix-plan.json', jsonContent)
|
||||
6. Return brief completion summary
|
||||
`
|
||||
)
|
||||
```
|
||||
@@ -630,65 +495,45 @@ ${fixPlan.tasks.map((t, i) => `${i+1}. ${t.title} (${t.scope})`).join('\n')}
|
||||
|
||||
**Step 4.2: Collect Confirmation**
|
||||
```javascript
|
||||
// Parse --yes flag
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
|
||||
let userSelection
|
||||
|
||||
if (autoYes) {
|
||||
// Auto mode: Use defaults
|
||||
console.log(`[--yes] Auto-confirming fix plan:`)
|
||||
console.log(` - Confirmation: Allow`)
|
||||
console.log(` - Execution: Auto`)
|
||||
console.log(` - Review: Skip`)
|
||||
|
||||
userSelection = {
|
||||
confirmation: "Allow",
|
||||
execution_method: "Auto",
|
||||
code_review_tool: "Skip"
|
||||
}
|
||||
} else {
|
||||
// Interactive mode: Ask user
|
||||
userSelection = AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: `Confirm fix plan? (${fixPlan.tasks.length} tasks, ${fixPlan.severity} severity)`,
|
||||
header: "Confirm",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Allow", description: "Proceed as-is" },
|
||||
{ label: "Modify", description: "Adjust before execution" },
|
||||
{ label: "Cancel", description: "Abort workflow" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Execution method:",
|
||||
header: "Execution",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Agent", description: "@code-developer agent" },
|
||||
{ label: "Codex", description: "codex CLI tool" },
|
||||
{ label: "Auto", description: `Auto: ${fixPlan.severity === 'Low' ? 'Agent' : 'Codex'}` }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Code review after fix?",
|
||||
header: "Review",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Gemini Review", description: "Gemini CLI" },
|
||||
{ label: "Agent Review", description: "@code-reviewer" },
|
||||
{ label: "Skip", description: "No review" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
}
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: `Confirm fix plan? (${fixPlan.tasks.length} tasks, ${fixPlan.severity} severity)`,
|
||||
header: "Confirm",
|
||||
multiSelect: true,
|
||||
options: [
|
||||
{ label: "Allow", description: "Proceed as-is" },
|
||||
{ label: "Modify", description: "Adjust before execution" },
|
||||
{ label: "Cancel", description: "Abort workflow" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Execution method:",
|
||||
header: "Execution",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Agent", description: "@code-developer agent" },
|
||||
{ label: "Codex", description: "codex CLI tool" },
|
||||
{ label: "Auto", description: `Auto: ${fixPlan.severity === 'Low' ? 'Agent' : 'Codex'}` }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Code review after fix?",
|
||||
header: "Review",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Gemini Review", description: "Gemini CLI" },
|
||||
{ label: "Agent Review", description: "@code-reviewer" },
|
||||
{ label: "Skip", description: "No review" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Execute to Execution
|
||||
### Phase 5: Dispatch to Execution
|
||||
|
||||
**CRITICAL**: lite-fix NEVER executes code directly. ALL execution MUST go through lite-execute.
|
||||
|
||||
@@ -710,11 +555,7 @@ const fixPlan = JSON.parse(Read(`${sessionFolder}/fix-plan.json`))
|
||||
executionContext = {
|
||||
mode: "bugfix",
|
||||
severity: fixPlan.severity,
|
||||
planObject: {
|
||||
...fixPlan,
|
||||
// Ensure complexity is set based on severity for new field consumption
|
||||
complexity: fixPlan.complexity || (fixPlan.severity === 'Critical' ? 'High' : (fixPlan.severity === 'High' ? 'High' : 'Medium'))
|
||||
},
|
||||
planObject: fixPlan,
|
||||
diagnosisContext: diagnoses,
|
||||
diagnosisAngles: manifest.diagnoses.map(d => d.angle),
|
||||
diagnosisManifest: manifest,
|
||||
@@ -737,7 +578,7 @@ executionContext = {
|
||||
}
|
||||
```
|
||||
|
||||
**Step 5.2: Execute**
|
||||
**Step 5.2: Dispatch**
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:lite-execute --in-memory --mode bugfix")
|
||||
|
||||
@@ -1,465 +0,0 @@
|
||||
---
|
||||
name: 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.
|
||||
argument-hint: "[-y|--yes] <task description>"
|
||||
allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Bash(*), Write(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__write_file(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Skip clarification questions, auto-select tools, execute directly with recommended settings.
|
||||
|
||||
# Ultra-Lite Multi-Tool Workflow
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
/workflow:lite-lite-lite "Fix the login bug"
|
||||
/workflow:lite-lite-lite "Refactor payment module for multi-gateway support"
|
||||
```
|
||||
|
||||
**Core Philosophy**: Minimal friction, maximum velocity. Simple tasks = no artifacts. Complex tasks = lightweight planning doc in `.workflow/.scratchpad/`.
|
||||
|
||||
## Overview
|
||||
|
||||
**Complexity-aware workflow**: Clarify → Assess Complexity → Select Tools → Multi-Mode Analysis → Decision → Direct Execution
|
||||
|
||||
**vs multi-cli-plan**: No IMPL_PLAN.md, plan.json, synthesis.json - state in memory or lightweight scratchpad doc for complex tasks.
|
||||
|
||||
## Execution Flow
|
||||
|
||||
```
|
||||
Phase 1: Clarify Requirements → AskUser for missing details
|
||||
Phase 1.5: Assess Complexity → Determine if planning doc needed
|
||||
Phase 2: Select Tools (CLI → Mode → Agent) → 3-step selection
|
||||
Phase 3: Multi-Mode Analysis → Execute with --resume chaining
|
||||
Phase 4: User Decision → Execute / Refine / Change / Cancel
|
||||
Phase 5: Direct Execution → No plan files (simple) or scratchpad doc (complex)
|
||||
```
|
||||
|
||||
## Phase 1: Clarify Requirements
|
||||
|
||||
```javascript
|
||||
const taskDescription = $ARGUMENTS
|
||||
|
||||
if (taskDescription.length < 20 || isAmbiguous(taskDescription)) {
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Please provide more details: target files/modules, expected behavior, constraints?",
|
||||
header: "Details",
|
||||
options: [
|
||||
{ label: "I'll provide more", description: "Add more context" },
|
||||
{ label: "Continue analysis", description: "Let tools explore autonomously" }
|
||||
],
|
||||
multiSelect: false
|
||||
}]
|
||||
})
|
||||
}
|
||||
|
||||
// Optional: Quick ACE Context for complex tasks
|
||||
mcp__ace-tool__search_context({
|
||||
project_root_path: process.cwd(),
|
||||
query: `${taskDescription} implementation patterns`
|
||||
})
|
||||
```
|
||||
|
||||
## Phase 1.5: Assess Complexity
|
||||
|
||||
| Level | Creates Plan Doc | Trigger Keywords |
|
||||
|-------|------------------|------------------|
|
||||
| **simple** | ❌ | (default) |
|
||||
| **moderate** | ✅ | module, system, service, integration, multiple |
|
||||
| **complex** | ✅ | refactor, migrate, security, auth, payment, database |
|
||||
|
||||
```javascript
|
||||
// Complexity detection (after ACE query)
|
||||
const isComplex = /refactor|migrate|security|auth|payment|database/i.test(taskDescription)
|
||||
const isModerate = /module|system|service|integration|multiple/i.test(taskDescription) || aceContext?.relevant_files?.length > 2
|
||||
|
||||
if (isComplex || isModerate) {
|
||||
const planPath = `.workflow/.scratchpad/lite3-${taskSlug}-${dateStr}.md`
|
||||
// Create planning doc with: Task, Status, Complexity, Analysis Summary, Execution Plan, Progress Log
|
||||
}
|
||||
```
|
||||
|
||||
## Phase 2: Select Tools
|
||||
|
||||
### Tool Definitions
|
||||
|
||||
**CLI Tools** (from cli-tools.json):
|
||||
```javascript
|
||||
const cliConfig = JSON.parse(Read("~/.claude/cli-tools.json"))
|
||||
const cliTools = Object.entries(cliConfig.tools)
|
||||
.filter(([_, config]) => config.enabled)
|
||||
.map(([name, config]) => ({
|
||||
name, type: 'cli',
|
||||
tags: config.tags || [],
|
||||
model: config.primaryModel,
|
||||
toolType: config.type // builtin, cli-wrapper, api-endpoint
|
||||
}))
|
||||
```
|
||||
|
||||
**Sub Agents**:
|
||||
|
||||
| Agent | Strengths | canExecute |
|
||||
|-------|-----------|------------|
|
||||
| **code-developer** | Code implementation, test writing | ✅ |
|
||||
| **Explore** | Fast code exploration, pattern discovery | ❌ |
|
||||
| **cli-explore-agent** | Dual-source analysis (Bash+CLI) | ❌ |
|
||||
| **cli-discuss-agent** | Multi-CLI collaboration, cross-verification | ❌ |
|
||||
| **debug-explore-agent** | Hypothesis-driven debugging | ❌ |
|
||||
| **context-search-agent** | Multi-layer file discovery, dependency analysis | ❌ |
|
||||
| **test-fix-agent** | Test execution, failure diagnosis, code fixing | ✅ |
|
||||
| **universal-executor** | General execution, multi-domain adaptation | ✅ |
|
||||
|
||||
**Analysis Modes**:
|
||||
|
||||
| Mode | Pattern | Use Case | minCLIs |
|
||||
|------|---------|----------|---------|
|
||||
| **Parallel** | `A \|\| B \|\| C → Aggregate` | Fast multi-perspective | 1+ |
|
||||
| **Sequential** | `A → B(resume) → C(resume)` | Incremental deepening | 2+ |
|
||||
| **Collaborative** | `A → B → A → B → Synthesize` | Multi-round refinement | 2+ |
|
||||
| **Debate** | `A(propose) → B(challenge) → A(defend)` | Adversarial validation | 2 |
|
||||
| **Challenge** | `A(analyze) → B(challenge)` | Find flaws and risks | 2 |
|
||||
|
||||
### Three-Step Selection Flow
|
||||
|
||||
```javascript
|
||||
// Step 1: Select CLIs (multiSelect)
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Select CLI tools for analysis (1-3 for collaboration modes)",
|
||||
header: "CLI Tools",
|
||||
options: cliTools.map(cli => ({
|
||||
label: cli.name,
|
||||
description: cli.tags.length > 0 ? cli.tags.join(', ') : cli.model || 'general'
|
||||
})),
|
||||
multiSelect: true
|
||||
}]
|
||||
})
|
||||
|
||||
// Step 2: Select Mode (filtered by CLI count)
|
||||
const availableModes = analysisModes.filter(m => selectedCLIs.length >= m.minCLIs)
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Select analysis mode",
|
||||
header: "Mode",
|
||||
options: availableModes.map(m => ({
|
||||
label: m.label,
|
||||
description: `${m.description} [${m.pattern}]`
|
||||
})),
|
||||
multiSelect: false
|
||||
}]
|
||||
})
|
||||
|
||||
// Step 3: Select Agent for execution
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Select Sub Agent for execution",
|
||||
header: "Agent",
|
||||
options: agents.map(a => ({ label: a.name, description: a.strength })),
|
||||
multiSelect: false
|
||||
}]
|
||||
})
|
||||
|
||||
// Confirm selection
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Confirm selection?",
|
||||
header: "Confirm",
|
||||
options: [
|
||||
{ label: "Confirm and continue", description: `${selectedMode.label} with ${selectedCLIs.length} CLIs` },
|
||||
{ label: "Re-select CLIs", description: "Choose different CLI tools" },
|
||||
{ label: "Re-select Mode", description: "Choose different analysis mode" },
|
||||
{ label: "Re-select Agent", description: "Choose different Sub Agent" }
|
||||
],
|
||||
multiSelect: false
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
## Phase 3: Multi-Mode Analysis
|
||||
|
||||
### Universal CLI Prompt Template
|
||||
|
||||
```javascript
|
||||
// Unified prompt builder - used by all modes
|
||||
function buildPrompt({ purpose, tasks, expected, rules, taskDescription }) {
|
||||
return `
|
||||
PURPOSE: ${purpose}: ${taskDescription}
|
||||
TASK: ${tasks.map(t => `• ${t}`).join(' ')}
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*
|
||||
EXPECTED: ${expected}
|
||||
CONSTRAINTS: ${rules}
|
||||
`
|
||||
}
|
||||
|
||||
// Execute CLI with prompt
|
||||
function execCLI(cli, prompt, options = {}) {
|
||||
const { resume, background = false } = options
|
||||
const resumeFlag = resume ? `--resume ${resume}` : ''
|
||||
return Bash({
|
||||
command: `ccw cli -p "${prompt}" --tool ${cli.name} --mode analysis ${resumeFlag}`,
|
||||
run_in_background: background
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Prompt Presets by Role
|
||||
|
||||
| Role | PURPOSE | TASKS | EXPECTED | RULES |
|
||||
|------|---------|-------|----------|-------|
|
||||
| **initial** | Initial analysis | Identify files, Analyze approach, List changes | Root cause, files, changes, risks | Focus on actionable insights |
|
||||
| **extend** | Build on previous | Review previous, Extend, Add insights | Extended analysis building on findings | Build incrementally, avoid repetition |
|
||||
| **synthesize** | Refine and synthesize | Review, Identify gaps, Synthesize | Refined synthesis with new perspectives | Add value not repetition |
|
||||
| **propose** | Propose comprehensive analysis | Analyze thoroughly, Propose solution, State assumptions | Well-reasoned proposal with trade-offs | Be clear about assumptions |
|
||||
| **challenge** | Challenge and stress-test | Identify weaknesses, Question assumptions, Suggest alternatives | Critique with counter-arguments | Be adversarial but constructive |
|
||||
| **defend** | Respond to challenges | Address challenges, Defend valid aspects, Propose refined solution | Refined proposal incorporating feedback | Be open to criticism, synthesize |
|
||||
| **criticize** | Find flaws ruthlessly | Find logical flaws, Identify edge cases, Rate criticisms | Critique with severity: [CRITICAL]/[HIGH]/[MEDIUM]/[LOW] | Be ruthlessly critical |
|
||||
|
||||
```javascript
|
||||
const PROMPTS = {
|
||||
initial: { purpose: 'Initial analysis', tasks: ['Identify affected files', 'Analyze implementation approach', 'List specific changes'], expected: 'Root cause, files to modify, key changes, risks', rules: 'Focus on actionable insights' },
|
||||
extend: { purpose: 'Build on previous analysis', tasks: ['Review previous findings', 'Extend analysis', 'Add new insights'], expected: 'Extended analysis building on previous', rules: 'Build incrementally, avoid repetition' },
|
||||
synthesize: { purpose: 'Refine and synthesize', tasks: ['Review previous', 'Identify gaps', 'Add insights', 'Synthesize findings'], expected: 'Refined synthesis with new perspectives', rules: 'Build collaboratively, add value' },
|
||||
propose: { purpose: 'Propose comprehensive analysis', tasks: ['Analyze thoroughly', 'Propose solution', 'State assumptions clearly'], expected: 'Well-reasoned proposal with trade-offs', rules: 'Be clear about assumptions' },
|
||||
challenge: { purpose: 'Challenge and stress-test', tasks: ['Identify weaknesses', 'Question assumptions', 'Suggest alternatives', 'Highlight overlooked risks'], expected: 'Constructive critique with counter-arguments', rules: 'Be adversarial but constructive' },
|
||||
defend: { purpose: 'Respond to challenges', tasks: ['Address each challenge', 'Defend valid aspects', 'Acknowledge valid criticisms', 'Propose refined solution'], expected: 'Refined proposal incorporating alternatives', rules: 'Be open to criticism, synthesize best ideas' },
|
||||
criticize: { purpose: 'Stress-test and find weaknesses', tasks: ['Find logical flaws', 'Identify missed edge cases', 'Propose alternatives', 'Rate criticisms (High/Medium/Low)'], expected: 'Detailed critique with severity ratings', rules: 'Be ruthlessly critical, find every flaw' }
|
||||
}
|
||||
```
|
||||
|
||||
### Mode Implementations
|
||||
|
||||
```javascript
|
||||
// Parallel: All CLIs run simultaneously
|
||||
async function executeParallel(clis, task) {
|
||||
return await Promise.all(clis.map(cli =>
|
||||
execCLI(cli, buildPrompt({ ...PROMPTS.initial, taskDescription: task }), { background: true })
|
||||
))
|
||||
}
|
||||
|
||||
// Sequential: Each CLI builds on previous via --resume
|
||||
async function executeSequential(clis, task) {
|
||||
const results = []
|
||||
let prevId = null
|
||||
for (const cli of clis) {
|
||||
const preset = prevId ? PROMPTS.extend : PROMPTS.initial
|
||||
const result = await execCLI(cli, buildPrompt({ ...preset, taskDescription: task }), { resume: prevId })
|
||||
results.push(result)
|
||||
prevId = extractSessionId(result)
|
||||
}
|
||||
return results
|
||||
}
|
||||
|
||||
// Collaborative: Multi-round synthesis
|
||||
async function executeCollaborative(clis, task, rounds = 2) {
|
||||
const results = []
|
||||
let prevId = null
|
||||
for (let r = 0; r < rounds; r++) {
|
||||
for (const cli of clis) {
|
||||
const preset = !prevId ? PROMPTS.initial : PROMPTS.synthesize
|
||||
const result = await execCLI(cli, buildPrompt({ ...preset, taskDescription: task }), { resume: prevId })
|
||||
results.push({ cli: cli.name, round: r, result })
|
||||
prevId = extractSessionId(result)
|
||||
}
|
||||
}
|
||||
return results
|
||||
}
|
||||
|
||||
// Debate: Propose → Challenge → Defend
|
||||
async function executeDebate(clis, task) {
|
||||
const [cliA, cliB] = clis
|
||||
const results = []
|
||||
|
||||
const propose = await execCLI(cliA, buildPrompt({ ...PROMPTS.propose, taskDescription: task }))
|
||||
results.push({ phase: 'propose', cli: cliA.name, result: propose })
|
||||
|
||||
const challenge = await execCLI(cliB, buildPrompt({ ...PROMPTS.challenge, taskDescription: task }), { resume: extractSessionId(propose) })
|
||||
results.push({ phase: 'challenge', cli: cliB.name, result: challenge })
|
||||
|
||||
const defend = await execCLI(cliA, buildPrompt({ ...PROMPTS.defend, taskDescription: task }), { resume: extractSessionId(challenge) })
|
||||
results.push({ phase: 'defend', cli: cliA.name, result: defend })
|
||||
|
||||
return results
|
||||
}
|
||||
|
||||
// Challenge: Analyze → Criticize
|
||||
async function executeChallenge(clis, task) {
|
||||
const [cliA, cliB] = clis
|
||||
const results = []
|
||||
|
||||
const analyze = await execCLI(cliA, buildPrompt({ ...PROMPTS.initial, taskDescription: task }))
|
||||
results.push({ phase: 'analyze', cli: cliA.name, result: analyze })
|
||||
|
||||
const criticize = await execCLI(cliB, buildPrompt({ ...PROMPTS.criticize, taskDescription: task }), { resume: extractSessionId(analyze) })
|
||||
results.push({ phase: 'challenge', cli: cliB.name, result: criticize })
|
||||
|
||||
return results
|
||||
}
|
||||
```
|
||||
|
||||
### Mode Router & Result Aggregation
|
||||
|
||||
```javascript
|
||||
async function executeAnalysis(mode, clis, taskDescription) {
|
||||
switch (mode.name) {
|
||||
case 'parallel': return await executeParallel(clis, taskDescription)
|
||||
case 'sequential': return await executeSequential(clis, taskDescription)
|
||||
case 'collaborative': return await executeCollaborative(clis, taskDescription)
|
||||
case 'debate': return await executeDebate(clis, taskDescription)
|
||||
case 'challenge': return await executeChallenge(clis, taskDescription)
|
||||
}
|
||||
}
|
||||
|
||||
function aggregateResults(mode, results) {
|
||||
const base = { mode: mode.name, pattern: mode.pattern, tools_used: results.map(r => r.cli || 'unknown') }
|
||||
|
||||
switch (mode.name) {
|
||||
case 'parallel':
|
||||
return { ...base, findings: results.map(parseOutput), consensus: findCommonPoints(results), divergences: findDifferences(results) }
|
||||
case 'sequential':
|
||||
return { ...base, evolution: results.map((r, i) => ({ step: i + 1, analysis: parseOutput(r) })), finalAnalysis: parseOutput(results.at(-1)) }
|
||||
case 'collaborative':
|
||||
return { ...base, rounds: groupByRound(results), synthesis: extractSynthesis(results.at(-1)) }
|
||||
case 'debate':
|
||||
return { ...base, proposal: parseOutput(results.find(r => r.phase === 'propose')?.result),
|
||||
challenges: parseOutput(results.find(r => r.phase === 'challenge')?.result),
|
||||
resolution: parseOutput(results.find(r => r.phase === 'defend')?.result), confidence: calculateDebateConfidence(results) }
|
||||
case 'challenge':
|
||||
return { ...base, originalAnalysis: parseOutput(results.find(r => r.phase === 'analyze')?.result),
|
||||
critiques: parseCritiques(results.find(r => r.phase === 'challenge')?.result), riskScore: calculateRiskScore(results) }
|
||||
}
|
||||
}
|
||||
|
||||
// If planPath exists: update Analysis Summary & Execution Plan sections
|
||||
```
|
||||
|
||||
## Phase 4: User Decision
|
||||
|
||||
```javascript
|
||||
function presentSummary(analysis) {
|
||||
console.log(`## Analysis Result\n**Mode**: ${analysis.mode} (${analysis.pattern})\n**Tools**: ${analysis.tools_used.join(' → ')}`)
|
||||
|
||||
switch (analysis.mode) {
|
||||
case 'parallel':
|
||||
console.log(`### Consensus\n${analysis.consensus.map(c => `- ${c}`).join('\n')}\n### Divergences\n${analysis.divergences.map(d => `- ${d}`).join('\n')}`)
|
||||
break
|
||||
case 'sequential':
|
||||
console.log(`### Evolution\n${analysis.evolution.map(e => `**Step ${e.step}**: ${e.analysis.summary}`).join('\n')}\n### Final\n${analysis.finalAnalysis.summary}`)
|
||||
break
|
||||
case 'collaborative':
|
||||
console.log(`### Rounds\n${Object.entries(analysis.rounds).map(([r, a]) => `**Round ${r}**: ${a.map(x => x.cli).join(' + ')}`).join('\n')}\n### Synthesis\n${analysis.synthesis}`)
|
||||
break
|
||||
case 'debate':
|
||||
console.log(`### Debate\n**Proposal**: ${analysis.proposal.summary}\n**Challenges**: ${analysis.challenges.points?.length || 0} points\n**Resolution**: ${analysis.resolution.summary}\n**Confidence**: ${analysis.confidence}%`)
|
||||
break
|
||||
case 'challenge':
|
||||
console.log(`### Challenge\n**Original**: ${analysis.originalAnalysis.summary}\n**Critiques**: ${analysis.critiques.length} issues\n${analysis.critiques.map(c => `- [${c.severity}] ${c.description}`).join('\n')}\n**Risk Score**: ${analysis.riskScore}/100`)
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "How to proceed?",
|
||||
header: "Next Step",
|
||||
options: [
|
||||
{ label: "Execute directly", description: "Implement immediately" },
|
||||
{ label: "Refine analysis", description: "Add constraints, re-analyze" },
|
||||
{ label: "Change tools", description: "Different tool combination" },
|
||||
{ label: "Cancel", description: "End workflow" }
|
||||
],
|
||||
multiSelect: false
|
||||
}]
|
||||
})
|
||||
// If planPath exists: record decision to Decisions Made table
|
||||
// Routing: Execute → Phase 5 | Refine → Phase 3 | Change → Phase 2 | Cancel → End
|
||||
```
|
||||
|
||||
## Phase 5: Direct Execution
|
||||
|
||||
```javascript
|
||||
// Simple tasks: No artifacts | Complex tasks: Update scratchpad doc
|
||||
const executionAgents = agents.filter(a => a.canExecute)
|
||||
const executionTool = selectedAgent.canExecute ? selectedAgent : selectedCLIs[0]
|
||||
|
||||
if (executionTool.type === 'agent') {
|
||||
Task({
|
||||
subagent_type: executionTool.name,
|
||||
run_in_background: false,
|
||||
description: `Execute: ${taskDescription.slice(0, 30)}`,
|
||||
prompt: `## Task\n${taskDescription}\n\n## Analysis Results\n${JSON.stringify(aggregatedAnalysis, null, 2)}\n\n## Instructions\n1. Apply changes to identified files\n2. Follow recommended approach\n3. Handle identified risks\n4. Verify changes work correctly`
|
||||
})
|
||||
} else {
|
||||
Bash({
|
||||
command: `ccw cli -p "
|
||||
PURPOSE: Implement solution: ${taskDescription}
|
||||
TASK: ${extractedTasks.join(' • ')}
|
||||
MODE: write
|
||||
CONTEXT: @${affectedFiles.join(' @')}
|
||||
EXPECTED: Working implementation with all changes applied
|
||||
CONSTRAINTS: Follow existing patterns
|
||||
" --tool ${executionTool.name} --mode write`,
|
||||
run_in_background: false
|
||||
})
|
||||
}
|
||||
// If planPath exists: update Status to completed/failed, append to Progress Log
|
||||
```
|
||||
|
||||
## TodoWrite Structure
|
||||
|
||||
```javascript
|
||||
TodoWrite({ todos: [
|
||||
{ content: "Phase 1: Clarify requirements", status: "in_progress", activeForm: "Clarifying requirements" },
|
||||
{ content: "Phase 1.5: Assess complexity", status: "pending", activeForm: "Assessing complexity" },
|
||||
{ content: "Phase 2: Select tools", status: "pending", activeForm: "Selecting tools" },
|
||||
{ content: "Phase 3: Multi-mode analysis", status: "pending", activeForm: "Running analysis" },
|
||||
{ content: "Phase 4: User decision", status: "pending", activeForm: "Awaiting decision" },
|
||||
{ content: "Phase 5: Direct execution", status: "pending", activeForm: "Executing" }
|
||||
]})
|
||||
```
|
||||
|
||||
## Iteration Patterns
|
||||
|
||||
| Pattern | Flow |
|
||||
|---------|------|
|
||||
| **Direct** | Phase 1 → 2 → 3 → 4(execute) → 5 |
|
||||
| **Refinement** | Phase 3 → 4(refine) → 3 → 4 → 5 |
|
||||
| **Tool Adjust** | Phase 2(adjust) → 3 → 4 → 5 |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| CLI timeout | Retry with secondary model |
|
||||
| No enabled tools | Ask user to enable tools in cli-tools.json |
|
||||
| Task unclear | Default to first CLI + code-developer |
|
||||
| Ambiguous task | Force clarification via AskUser |
|
||||
| Execution fails | Present error, ask user for direction |
|
||||
| Plan doc write fails | Continue without doc (degrade to zero-artifact mode) |
|
||||
| Scratchpad dir missing | Auto-create `.workflow/.scratchpad/` |
|
||||
|
||||
## Comparison with multi-cli-plan
|
||||
|
||||
| Aspect | lite-lite-lite | multi-cli-plan |
|
||||
|--------|----------------|----------------|
|
||||
| **Artifacts** | Conditional (scratchpad doc for complex tasks) | Always (IMPL_PLAN.md, plan.json, synthesis.json) |
|
||||
| **Session** | Stateless (--resume chaining) | Persistent session folder |
|
||||
| **Tool Selection** | 3-step (CLI → Mode → Agent) | Config-driven fixed tools |
|
||||
| **Analysis Modes** | 5 modes with --resume | Fixed synthesis rounds |
|
||||
| **Complexity** | Auto-detected (simple/moderate/complex) | Assumed complex |
|
||||
| **Best For** | Quick analysis, simple-to-moderate tasks | Complex multi-step implementations |
|
||||
|
||||
## Post-Completion Expansion
|
||||
|
||||
完成后询问用户是否扩展为issue(test/enhance/refactor/doc)，选中项调用 `/issue:new "{summary} - {dimension}"`
|
||||
|
||||
## Related Commands
|
||||
|
||||
```bash
|
||||
/workflow:multi-cli-plan "complex task" # Full planning workflow
|
||||
/workflow:lite-plan "task" # Single CLI planning
|
||||
/workflow:lite-execute --in-memory # Direct execution
|
||||
```
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: lite-plan
|
||||
description: Lightweight interactive planning workflow with in-memory planning, code exploration, and execution execute to lite-execute after user confirmation
|
||||
argument-hint: "[-y|--yes] [-e|--explore] \"task description\"|file.md"
|
||||
description: Lightweight interactive planning workflow with in-memory planning, code exploration, and execution dispatch to lite-execute after user confirmation
|
||||
argument-hint: "[-e|--explore] \"task description\"|file.md"
|
||||
allowed-tools: TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*)
|
||||
---
|
||||
|
||||
@@ -15,9 +15,9 @@ Intelligent lightweight planning command with dynamic workflow adaptation based
|
||||
- Intelligent task analysis with automatic exploration detection
|
||||
- Dynamic code exploration (cli-explore-agent) when codebase understanding needed
|
||||
- Interactive clarification after exploration to gather missing information
|
||||
- Adaptive planning: Low complexity → Direct Claude; Medium/High → cli-lite-planning-agent
|
||||
- Adaptive planning strategy (direct Claude vs cli-lite-planning-agent) based on complexity
|
||||
- Two-step confirmation: plan display → multi-dimensional input collection
|
||||
- Execution execute with complete context handoff to lite-execute
|
||||
- Execution dispatch with complete context handoff to lite-execute
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -25,30 +25,10 @@ Intelligent lightweight planning command with dynamic workflow adaptation based
|
||||
/workflow:lite-plan [FLAGS] <TASK_DESCRIPTION>
|
||||
|
||||
# Flags
|
||||
-y, --yes Skip all confirmations (auto mode)
|
||||
-e, --explore Force code exploration phase (overrides auto-detection)
|
||||
|
||||
# Arguments
|
||||
<task-description> Task description or path to .md file (required)
|
||||
|
||||
# Examples
|
||||
/workflow:lite-plan "实现JWT认证" # Interactive mode
|
||||
/workflow:lite-plan --yes "实现JWT认证" # Auto mode (no confirmations)
|
||||
/workflow:lite-plan -y -e "优化数据库查询性能" # Auto mode + force exploration
|
||||
```
|
||||
|
||||
## Auto Mode Defaults
|
||||
|
||||
When `--yes` or `-y` flag is used:
|
||||
- **Clarification Questions**: Skipped (no clarification phase)
|
||||
- **Plan Confirmation**: Auto-selected "Allow"
|
||||
- **Execution Method**: Auto-selected "Auto"
|
||||
- **Code Review**: Auto-selected "Skip"
|
||||
|
||||
**Flag Parsing**:
|
||||
```javascript
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
const forceExplore = $ARGUMENTS.includes('--explore') || $ARGUMENTS.includes('-e')
|
||||
```
|
||||
|
||||
## Execution Process
|
||||
@@ -58,7 +38,7 @@ Phase 1: Task Analysis & Exploration
|
||||
├─ Parse input (description or .md file)
|
||||
├─ intelligent complexity assessment (Low/Medium/High)
|
||||
├─ Exploration decision (auto-detect or --explore flag)
|
||||
├─ Context protection: If file reading ≥50k chars → force cli-explore-agent
|
||||
├─ ⚠️ Context protection: If file reading ≥50k chars → force cli-explore-agent
|
||||
└─ Decision:
|
||||
├─ needsExploration=true → Launch parallel cli-explore-agents (1-4 based on complexity)
|
||||
└─ needsExploration=false → Skip to Phase 2/3
|
||||
@@ -82,7 +62,7 @@ Phase 4: Confirmation & Selection
|
||||
├─ Execution: Agent / Codex / Auto
|
||||
└─ Review: Gemini / Agent / Skip
|
||||
|
||||
Phase 5: Execute
|
||||
Phase 5: Dispatch
|
||||
├─ Build executionContext (plan + explorations + clarifications + selections)
|
||||
└─ SlashCommand("/workflow:lite-execute --in-memory")
|
||||
```
|
||||
@@ -160,17 +140,11 @@ function selectAngles(taskDescription, count) {
|
||||
|
||||
const selectedAngles = selectAngles(task_description, complexity === 'High' ? 4 : (complexity === 'Medium' ? 3 : 1))
|
||||
|
||||
// Planning strategy determination
|
||||
const planningStrategy = complexity === 'Low'
|
||||
? 'Direct Claude Planning'
|
||||
: 'cli-lite-planning-agent'
|
||||
|
||||
console.log(`
|
||||
## Exploration Plan
|
||||
|
||||
Task Complexity: ${complexity}
|
||||
Selected Angles: ${selectedAngles.join(', ')}
|
||||
Planning Strategy: ${planningStrategy}
|
||||
|
||||
Launching ${selectedAngles.length} parallel explorations...
|
||||
`)
|
||||
@@ -178,16 +152,11 @@ Launching ${selectedAngles.length} parallel explorations...
|
||||
|
||||
**Launch Parallel Explorations** - Orchestrator assigns angle to each agent:
|
||||
|
||||
**⚠️ CRITICAL - NO BACKGROUND EXECUTION**:
|
||||
- **MUST NOT use `run_in_background: true`** - exploration results are REQUIRED before planning
|
||||
|
||||
|
||||
```javascript
|
||||
// Launch agents with pre-assigned angles
|
||||
const explorationTasks = selectedAngles.map((angle, index) =>
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
run_in_background=false, // ⚠️ MANDATORY: Must wait for results
|
||||
description=`Explore: ${angle}`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
@@ -201,11 +170,9 @@ Execute **${angle}** exploration for task planning context. Analyze codebase fro
|
||||
|
||||
## MANDATORY FIRST STEPS (Execute by Agent)
|
||||
**You (cli-explore-agent) MUST execute these steps in order:**
|
||||
1. Run: ccw tool exec get_modules_by_depth '{}' (project structure)
|
||||
1. Run: ~/.claude/scripts/get_modules_by_depth.sh (project structure)
|
||||
2. Run: rg -l "{keyword_from_task}" --type ts (locate relevant files)
|
||||
3. Execute: cat ~/.claude/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference)
|
||||
4. Read: .workflow/project-tech.json (technology stack and architecture context)
|
||||
5. Read: .workflow/project-guidelines.json (user-defined constraints and conventions)
|
||||
|
||||
## Exploration Strategy (${angle} focus)
|
||||
|
||||
@@ -337,22 +304,17 @@ explorations.forEach(exp => {
|
||||
}
|
||||
})
|
||||
|
||||
// Intelligent deduplication: analyze allClarifications by intent
|
||||
// - Identify questions with similar intent across different angles
|
||||
// - Merge similar questions: combine options, consolidate context
|
||||
// - Produce dedupedClarifications with unique intents only
|
||||
const dedupedClarifications = intelligentMerge(allClarifications)
|
||||
// Deduplicate exact same questions only
|
||||
const seen = new Set()
|
||||
const dedupedClarifications = allClarifications.filter(c => {
|
||||
const key = c.question.toLowerCase()
|
||||
if (seen.has(key)) return false
|
||||
seen.add(key)
|
||||
return true
|
||||
})
|
||||
|
||||
// Parse --yes flag
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
|
||||
if (autoYes) {
|
||||
// Auto mode: Skip clarification phase
|
||||
console.log(`[--yes] Skipping ${dedupedClarifications.length} clarification questions`)
|
||||
console.log(`Proceeding to planning with exploration results...`)
|
||||
// Continue to Phase 3
|
||||
} else if (dedupedClarifications.length > 0) {
|
||||
// Interactive mode: Multi-round clarification
|
||||
// Multi-round clarification: batch questions (max 4 per round)
|
||||
if (dedupedClarifications.length > 0) {
|
||||
const BATCH_SIZE = 4
|
||||
const totalRounds = Math.ceil(dedupedClarifications.length / BATCH_SIZE)
|
||||
|
||||
@@ -389,34 +351,12 @@ if (autoYes) {
|
||||
|
||||
**IMPORTANT**: Phase 3 is **planning only** - NO code execution. All execution happens in Phase 5 via lite-execute.
|
||||
|
||||
**Executor Assignment** (Claude 智能分配，plan 生成后执行):
|
||||
|
||||
```javascript
|
||||
// 分配规则（优先级从高到低）：
|
||||
// 1. 用户明确指定："用 gemini 分析..." → gemini, "codex 实现..." → codex
|
||||
// 2. 默认 → agent
|
||||
|
||||
const executorAssignments = {} // { taskId: { executor: 'gemini'|'codex'|'agent', reason: string } }
|
||||
plan.tasks.forEach(task => {
|
||||
// Claude 根据上述规则语义分析，为每个 task 分配 executor
|
||||
executorAssignments[task.id] = { executor: '...', reason: '...' }
|
||||
})
|
||||
```
|
||||
|
||||
**Low Complexity** - Direct planning by Claude:
|
||||
```javascript
|
||||
// Step 1: Read schema
|
||||
const schema = Bash(`cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json`)
|
||||
|
||||
// Step 2: ⚠️ MANDATORY - Read and review ALL exploration files
|
||||
const manifest = JSON.parse(Read(`${sessionFolder}/explorations-manifest.json`))
|
||||
manifest.explorations.forEach(exp => {
|
||||
const explorationData = Read(exp.path)
|
||||
console.log(`\n### Exploration: ${exp.angle}\n${explorationData}`)
|
||||
})
|
||||
|
||||
// Step 3: Generate plan following schema (Claude directly, no agent)
|
||||
// ⚠️ Plan MUST incorporate insights from exploration files read in Step 2
|
||||
// Step 2: Generate plan following schema (Claude directly, no agent)
|
||||
const plan = {
|
||||
summary: "...",
|
||||
approach: "...",
|
||||
@@ -427,10 +367,10 @@ const plan = {
|
||||
_metadata: { timestamp: getUtc8ISOString(), source: "direct-planning", planning_mode: "direct" }
|
||||
}
|
||||
|
||||
// Step 4: Write plan to session folder
|
||||
// Step 3: Write plan to session folder
|
||||
Write(`${sessionFolder}/plan.json`, JSON.stringify(plan, null, 2))
|
||||
|
||||
// Step 5: MUST continue to Phase 4 (Confirmation) - DO NOT execute code here
|
||||
// Step 4: MUST continue to Phase 4 (Confirmation) - DO NOT execute code here
|
||||
```
|
||||
|
||||
**Medium/High Complexity** - Invoke cli-lite-planning-agent:
|
||||
@@ -438,7 +378,6 @@ Write(`${sessionFolder}/plan.json`, JSON.stringify(plan, null, 2))
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-lite-planning-agent",
|
||||
run_in_background=false,
|
||||
description="Generate detailed implementation plan",
|
||||
prompt=`
|
||||
Generate implementation plan and write plan.json.
|
||||
@@ -446,12 +385,6 @@ Generate implementation plan and write plan.json.
|
||||
## Output Schema Reference
|
||||
Execute: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json (get schema reference before generating plan)
|
||||
|
||||
## Project Context (MANDATORY - Read Both Files)
|
||||
1. Read: .workflow/project-tech.json (technology stack, architecture, key components)
|
||||
2. Read: .workflow/project-guidelines.json (user-defined constraints and conventions)
|
||||
|
||||
**CRITICAL**: All generated tasks MUST comply with constraints in project-guidelines.json
|
||||
|
||||
## Task Description
|
||||
${task_description}
|
||||
|
||||
@@ -474,9 +407,23 @@ ${JSON.stringify(clarificationContext) || "None"}
|
||||
${complexity}
|
||||
|
||||
## Requirements
|
||||
Generate plan.json following the schema obtained above. Key constraints:
|
||||
- tasks: 2-7 structured tasks (**group by feature/module, NOT by file**)
|
||||
- _metadata.exploration_angles: ${JSON.stringify(manifest.explorations.map(e => e.angle))}
|
||||
Generate plan.json with:
|
||||
- summary: 2-3 sentence overview
|
||||
- approach: High-level implementation strategy (incorporating insights from all exploration angles)
|
||||
- tasks: 2-7 structured tasks (**IMPORTANT: group by feature/module, NOT by file**)
|
||||
- **Task Granularity Principle**: Each task = one complete feature unit or module
|
||||
- title: action verb + target module/feature (e.g., "Implement auth token refresh")
|
||||
- scope: module path (src/auth/) or feature name, prefer module-level over single file
|
||||
- action, description
|
||||
- modification_points: ALL files to modify for this feature (group related changes)
|
||||
- implementation (3-7 steps covering all modification_points)
|
||||
- reference (pattern, files, examples)
|
||||
- acceptance (2-4 criteria for the entire feature)
|
||||
- depends_on: task IDs this task depends on (use sparingly, only for true dependencies)
|
||||
- estimated_time, recommended_execution, complexity
|
||||
- _metadata:
|
||||
- timestamp, source, planning_mode
|
||||
- exploration_angles: ${JSON.stringify(manifest.explorations.map(e => e.angle))}
|
||||
|
||||
## Task Grouping Rules
|
||||
1. **Group by feature**: All changes for one feature = one task (even if 3-5 files)
|
||||
@@ -488,10 +435,10 @@ Generate plan.json following the schema obtained above. Key constraints:
|
||||
7. **Prefer parallel**: Most tasks should be independent (no depends_on)
|
||||
|
||||
## Execution
|
||||
1. Read schema file (cat command above)
|
||||
1. Read ALL exploration files for comprehensive context
|
||||
2. Execute CLI planning using Gemini (Qwen fallback)
|
||||
3. Read ALL exploration files for comprehensive context
|
||||
4. Synthesize findings and generate plan following schema
|
||||
3. Synthesize findings from multiple exploration angles
|
||||
4. Parse output and structure plan
|
||||
5. Write JSON: Write('${sessionFolder}/plan.json', jsonContent)
|
||||
6. Return brief completion summary
|
||||
`
|
||||
@@ -525,67 +472,45 @@ ${plan.tasks.map((t, i) => `${i+1}. ${t.title} (${t.file})`).join('\n')}
|
||||
|
||||
**Step 4.2: Collect Confirmation**
|
||||
```javascript
|
||||
// Parse --yes flag
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
|
||||
let userSelection
|
||||
|
||||
if (autoYes) {
|
||||
// Auto mode: Use defaults
|
||||
console.log(`[--yes] Auto-confirming plan:`)
|
||||
console.log(` - Confirmation: Allow`)
|
||||
console.log(` - Execution: Auto`)
|
||||
console.log(` - Review: Skip`)
|
||||
|
||||
userSelection = {
|
||||
confirmation: "Allow",
|
||||
execution_method: "Auto",
|
||||
code_review_tool: "Skip"
|
||||
}
|
||||
} else {
|
||||
// Interactive mode: Ask user
|
||||
// Note: Execution "Other" option allows specifying CLI tools from ~/.claude/cli-tools.json
|
||||
userSelection = AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: `Confirm plan? (${plan.tasks.length} tasks, ${plan.complexity})`,
|
||||
header: "Confirm",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Allow", description: "Proceed as-is" },
|
||||
{ label: "Modify", description: "Adjust before execution" },
|
||||
{ label: "Cancel", description: "Abort workflow" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Execution method:",
|
||||
header: "Execution",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Agent", description: "@code-developer agent" },
|
||||
{ label: "Codex", description: "codex CLI tool" },
|
||||
{ label: "Auto", description: `Auto: ${plan.complexity === 'Low' ? 'Agent' : 'Codex'}` }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Code review after execution?",
|
||||
header: "Review",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Gemini Review", description: "Gemini CLI review" },
|
||||
{ label: "Codex Review", description: "Git-aware review (prompt OR --uncommitted)" },
|
||||
{ label: "Agent Review", description: "@code-reviewer agent" },
|
||||
{ label: "Skip", description: "No review" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
}
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: `Confirm plan? (${plan.tasks.length} tasks, ${plan.complexity})`,
|
||||
header: "Confirm",
|
||||
multiSelect: true,
|
||||
options: [
|
||||
{ label: "Allow", description: "Proceed as-is" },
|
||||
{ label: "Modify", description: "Adjust before execution" },
|
||||
{ label: "Cancel", description: "Abort workflow" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Execution method:",
|
||||
header: "Execution",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Agent", description: "@code-developer agent" },
|
||||
{ label: "Codex", description: "codex CLI tool" },
|
||||
{ label: "Auto", description: `Auto: ${plan.complexity === 'Low' ? 'Agent' : 'Codex'}` }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Code review after execution?",
|
||||
header: "Review",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Gemini Review", description: "Gemini CLI" },
|
||||
{ label: "Agent Review", description: "@code-reviewer" },
|
||||
{ label: "Skip", description: "No review" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Execute to Execution
|
||||
### Phase 5: Dispatch to Execution
|
||||
|
||||
**CRITICAL**: lite-plan NEVER executes code directly. ALL execution MUST go through lite-execute.
|
||||
|
||||
@@ -610,13 +535,9 @@ executionContext = {
|
||||
explorationAngles: manifest.explorations.map(e => e.angle),
|
||||
explorationManifest: manifest,
|
||||
clarificationContext: clarificationContext || null,
|
||||
executionMethod: userSelection.execution_method, // 全局默认，可被 executorAssignments 覆盖
|
||||
executionMethod: userSelection.execution_method,
|
||||
codeReviewTool: userSelection.code_review_tool,
|
||||
originalUserInput: task_description,
|
||||
|
||||
// 任务级 executor 分配（优先于全局 executionMethod）
|
||||
executorAssignments: executorAssignments, // { taskId: { executor, reason } }
|
||||
|
||||
session: {
|
||||
id: sessionId,
|
||||
folder: sessionFolder,
|
||||
@@ -632,7 +553,7 @@ executionContext = {
|
||||
}
|
||||
```
|
||||
|
||||
**Step 5.2: Execute**
|
||||
**Step 5.2: Dispatch**
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:lite-execute --in-memory")
|
||||
|
||||
@@ -1,572 +0,0 @@
|
||||
---
|
||||
name: 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.
|
||||
argument-hint: "[-y|--yes] <task description> [--max-rounds=3] [--tools=gemini,codex] [--mode=parallel|serial]"
|
||||
allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Bash(*), Write(*), mcp__ace-tool__search_context(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-approve plan, use recommended solution and execution method (Agent, Skip review).
|
||||
|
||||
# Multi-CLI Collaborative Planning Command
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Basic usage
|
||||
/workflow:multi-cli-plan "Implement user authentication"
|
||||
|
||||
# With options
|
||||
/workflow:multi-cli-plan "Add dark mode support" --max-rounds=3
|
||||
/workflow:multi-cli-plan "Refactor payment module" --tools=gemini,codex,claude
|
||||
/workflow:multi-cli-plan "Fix memory leak" --mode=serial
|
||||
```
|
||||
|
||||
**Context Source**: ACE semantic search + Multi-CLI analysis
|
||||
**Output Directory**: `.workflow/.multi-cli-plan/{session-id}/`
|
||||
**Default Max Rounds**: 3 (convergence may complete earlier)
|
||||
**CLI Tools**: @cli-discuss-agent (analysis), @cli-lite-planning-agent (plan generation)
|
||||
**Execution**: Auto-hands off to `/workflow:lite-execute --in-memory` after plan approval
|
||||
|
||||
## What & Why
|
||||
|
||||
### Core Concept
|
||||
|
||||
Multi-CLI collaborative planning with **three-phase architecture**: ACE context gathering → Iterative multi-CLI discussion → Plan generation. Orchestrator delegates analysis to agents, only handles user decisions and session management.
|
||||
|
||||
**Process**:
|
||||
- **Phase 1**: ACE semantic search gathers codebase context
|
||||
- **Phase 2**: cli-discuss-agent orchestrates Gemini/Codex/Claude for cross-verified analysis
|
||||
- **Phase 3-5**: User decision → Plan generation → Execution handoff
|
||||
|
||||
**vs Single-CLI Planning**:
|
||||
- **Single**: One model perspective, potential blind spots
|
||||
- **Multi-CLI**: Cross-verification catches inconsistencies, builds consensus on solutions
|
||||
|
||||
### Value Proposition
|
||||
|
||||
1. **Multi-Perspective Analysis**: Gemini + Codex + Claude analyze from different angles
|
||||
2. **Cross-Verification**: Identify agreements/disagreements, build confidence
|
||||
3. **User-Driven Decisions**: Every round ends with user decision point
|
||||
4. **Iterative Convergence**: Progressive refinement until consensus reached
|
||||
|
||||
### Orchestrator Boundary (CRITICAL)
|
||||
|
||||
- **ONLY command** for multi-CLI collaborative planning
|
||||
- Manages: Session state, user decisions, agent delegation, phase transitions
|
||||
- Delegates: CLI execution to @cli-discuss-agent, plan generation to @cli-lite-planning-agent
|
||||
|
||||
### Execution Flow
|
||||
|
||||
```
|
||||
Phase 1: Context Gathering
|
||||
└─ ACE semantic search, extract keywords, build context package
|
||||
|
||||
Phase 2: Multi-CLI Discussion (Iterative, via @cli-discuss-agent)
|
||||
├─ Round N: Agent executes Gemini + Codex + Claude
|
||||
├─ Cross-verify findings, synthesize solutions
|
||||
├─ Write synthesis.json to rounds/{N}/
|
||||
└─ Loop until convergence or max rounds
|
||||
|
||||
Phase 3: Present Options
|
||||
└─ Display solutions with trade-offs from agent output
|
||||
|
||||
Phase 4: User Decision
|
||||
├─ Select solution approach
|
||||
├─ Select execution method (Agent/Codex/Auto)
|
||||
├─ Select code review tool (Skip/Gemini/Codex/Agent)
|
||||
└─ Route:
|
||||
├─ Approve → Phase 5
|
||||
├─ Need More Analysis → Return to Phase 2
|
||||
└─ Cancel → Save session
|
||||
|
||||
Phase 5: Plan Generation & Execution Handoff
|
||||
├─ Generate plan.json (via @cli-lite-planning-agent)
|
||||
├─ Build executionContext with user selections
|
||||
└─ Execute to /workflow:lite-execute --in-memory
|
||||
```
|
||||
|
||||
### Agent Roles
|
||||
|
||||
| Agent | Responsibility |
|
||||
|-------|---------------|
|
||||
| **Orchestrator** | Session management, ACE context, user decisions, phase transitions, executionContext assembly |
|
||||
| **@cli-discuss-agent** | Multi-CLI execution (Gemini/Codex/Claude), cross-verification, solution synthesis, synthesis.json output |
|
||||
| **@cli-lite-planning-agent** | Task decomposition, plan.json generation following schema |
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
### Phase 1: Context Gathering
|
||||
|
||||
**Session Initialization**:
|
||||
```javascript
|
||||
const sessionId = `MCP-${taskSlug}-${date}`
|
||||
const sessionFolder = `.workflow/.multi-cli-plan/${sessionId}`
|
||||
Bash(`mkdir -p ${sessionFolder}/rounds`)
|
||||
```
|
||||
|
||||
**ACE Context Queries**:
|
||||
```javascript
|
||||
const aceQueries = [
|
||||
`Project architecture related to ${keywords}`,
|
||||
`Existing implementations of ${keywords[0]}`,
|
||||
`Code patterns for ${keywords} features`,
|
||||
`Integration points for ${keywords[0]}`
|
||||
]
|
||||
// Execute via mcp__ace-tool__search_context
|
||||
```
|
||||
|
||||
**Context Package** (passed to agent):
|
||||
- `relevant_files[]` - Files identified by ACE
|
||||
- `detected_patterns[]` - Code patterns found
|
||||
- `architecture_insights` - Structure understanding
|
||||
|
||||
### Phase 2: Agent Delegation
|
||||
|
||||
**Core Principle**: Orchestrator only delegates and reads output - NO direct CLI execution.
|
||||
|
||||
**Agent Invocation**:
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-discuss-agent",
|
||||
run_in_background: false,
|
||||
description: `Discussion round ${currentRound}`,
|
||||
prompt: `
|
||||
## Input Context
|
||||
- task_description: ${taskDescription}
|
||||
- round_number: ${currentRound}
|
||||
- session: { id: "${sessionId}", folder: "${sessionFolder}" }
|
||||
- ace_context: ${JSON.stringify(contextPackageage)}
|
||||
- previous_rounds: ${JSON.stringify(analysisResults)}
|
||||
- user_feedback: ${userFeedback || 'None'}
|
||||
- cli_config: { tools: ["gemini", "codex"], mode: "parallel", fallback_chain: ["gemini", "codex", "claude"] }
|
||||
|
||||
## Execution Process
|
||||
1. Parse input context (handle JSON strings)
|
||||
2. Check if ACE supplementary search needed
|
||||
3. Build CLI prompts with context
|
||||
4. Execute CLIs (parallel or serial per cli_config.mode)
|
||||
5. Parse CLI outputs, handle failures with fallback
|
||||
6. Perform cross-verification between CLI results
|
||||
7. Synthesize solutions, calculate scores
|
||||
8. Calculate convergence, generate clarification questions
|
||||
9. Write synthesis.json
|
||||
|
||||
## Output
|
||||
Write: ${sessionFolder}/rounds/${currentRound}/synthesis.json
|
||||
|
||||
## Completion Checklist
|
||||
- [ ] All configured CLI tools executed (or fallback triggered)
|
||||
- [ ] Cross-verification completed with agreements/disagreements
|
||||
- [ ] 2-3 solutions generated with file:line references
|
||||
- [ ] Convergence score calculated (0.0-1.0)
|
||||
- [ ] synthesis.json written with all Primary Fields
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**Read Agent Output**:
|
||||
```javascript
|
||||
const synthesis = JSON.parse(Read(`${sessionFolder}/rounds/${round}/synthesis.json`))
|
||||
// Access top-level fields: solutions, convergence, cross_verification, clarification_questions
|
||||
```
|
||||
|
||||
**Convergence Decision**:
|
||||
```javascript
|
||||
if (synthesis.convergence.recommendation === 'converged') {
|
||||
// Proceed to Phase 3
|
||||
} else if (synthesis.convergence.recommendation === 'user_input_needed') {
|
||||
// Collect user feedback, return to Phase 2
|
||||
} else {
|
||||
// Continue to next round if new_insights && round < maxRounds
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: Present Options
|
||||
|
||||
**Display from Agent Output** (no processing):
|
||||
```javascript
|
||||
console.log(`
|
||||
## Solution Options
|
||||
|
||||
${synthesis.solutions.map((s, i) => `
|
||||
**Option ${i+1}: ${s.name}**
|
||||
Source: ${s.source_cli.join(' + ')}
|
||||
Effort: ${s.effort} | Risk: ${s.risk}
|
||||
|
||||
Pros: ${s.pros.join(', ')}
|
||||
Cons: ${s.cons.join(', ')}
|
||||
|
||||
Files: ${s.affected_files.slice(0,3).map(f => `${f.file}:${f.line}`).join(', ')}
|
||||
`).join('\n')}
|
||||
|
||||
## Cross-Verification
|
||||
Agreements: ${synthesis.cross_verification.agreements.length}
|
||||
Disagreements: ${synthesis.cross_verification.disagreements.length}
|
||||
`)
|
||||
```
|
||||
|
||||
### Phase 4: User Decision
|
||||
|
||||
**Decision Options**:
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "Which solution approach?",
|
||||
header: "Solution",
|
||||
multiSelect: false,
|
||||
options: solutions.map((s, i) => ({
|
||||
label: `Option ${i+1}: ${s.name}`,
|
||||
description: `${s.effort} effort, ${s.risk} risk`
|
||||
})).concat([
|
||||
{ label: "Need More Analysis", description: "Return to Phase 2" }
|
||||
])
|
||||
},
|
||||
{
|
||||
question: "Execution method:",
|
||||
header: "Execution",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Agent", description: "@code-developer agent" },
|
||||
{ label: "Codex", description: "codex CLI tool" },
|
||||
{ label: "Auto", description: "Auto-select based on complexity" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Code review after execution?",
|
||||
header: "Review",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Skip", description: "No review" },
|
||||
{ label: "Gemini Review", description: "Gemini CLI tool" },
|
||||
{ label: "Codex Review", description: "codex review --uncommitted" },
|
||||
{ label: "Agent Review", description: "Current agent review" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**Routing**:
|
||||
- Approve + execution method → Phase 5
|
||||
- Need More Analysis → Phase 2 with feedback
|
||||
- Cancel → Save session for resumption
|
||||
|
||||
### Phase 5: Plan Generation & Execution Handoff
|
||||
|
||||
**Step 1: Build Context-Package** (Orchestrator responsibility):
|
||||
```javascript
|
||||
// Extract key information from user decision and synthesis
|
||||
const contextPackage = {
|
||||
// Core solution details
|
||||
solution: {
|
||||
name: selectedSolution.name,
|
||||
source_cli: selectedSolution.source_cli,
|
||||
feasibility: selectedSolution.feasibility,
|
||||
effort: selectedSolution.effort,
|
||||
risk: selectedSolution.risk,
|
||||
summary: selectedSolution.summary
|
||||
},
|
||||
// Implementation plan (tasks, flow, milestones)
|
||||
implementation_plan: selectedSolution.implementation_plan,
|
||||
// Dependencies
|
||||
dependencies: selectedSolution.dependencies || { internal: [], external: [] },
|
||||
// Technical concerns
|
||||
technical_concerns: selectedSolution.technical_concerns || [],
|
||||
// Consensus from cross-verification
|
||||
consensus: {
|
||||
agreements: synthesis.cross_verification.agreements,
|
||||
resolved_conflicts: synthesis.cross_verification.resolution
|
||||
},
|
||||
// User constraints (from Phase 4 feedback)
|
||||
constraints: userConstraints || [],
|
||||
// Task context
|
||||
task_description: taskDescription,
|
||||
session_id: sessionId
|
||||
}
|
||||
|
||||
// Write context-package for traceability
|
||||
Write(`${sessionFolder}/context-package.json`, JSON.stringify(contextPackage, null, 2))
|
||||
```
|
||||
|
||||
**Context-Package Schema**:
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `solution` | object | User-selected solution from synthesis |
|
||||
| `solution.name` | string | Solution identifier |
|
||||
| `solution.feasibility` | number | Viability score (0-1) |
|
||||
| `solution.summary` | string | Brief analysis summary |
|
||||
| `implementation_plan` | object | Task breakdown with flow and dependencies |
|
||||
| `implementation_plan.approach` | string | High-level technical strategy |
|
||||
| `implementation_plan.tasks[]` | array | Discrete tasks with id, name, depends_on, files |
|
||||
| `implementation_plan.execution_flow` | string | Task sequence (e.g., "T1 → T2 → T3") |
|
||||
| `implementation_plan.milestones` | string[] | Key checkpoints |
|
||||
| `dependencies` | object | Module and package dependencies |
|
||||
| `technical_concerns` | string[] | Risks and blockers |
|
||||
| `consensus` | object | Cross-verified agreements from multi-CLI |
|
||||
| `constraints` | string[] | User-specified constraints from Phase 4 |
|
||||
|
||||
```json
|
||||
{
|
||||
"solution": {
|
||||
"name": "Strategy Pattern Refactoring",
|
||||
"source_cli": ["gemini", "codex"],
|
||||
"feasibility": 0.88,
|
||||
"effort": "medium",
|
||||
"risk": "low",
|
||||
"summary": "Extract payment gateway interface, implement strategy pattern for multi-gateway support"
|
||||
},
|
||||
"implementation_plan": {
|
||||
"approach": "Define interface → Create concrete strategies → Implement factory → Migrate existing code",
|
||||
"tasks": [
|
||||
{"id": "T1", "name": "Define PaymentGateway interface", "depends_on": [], "files": [{"file": "src/types/payment.ts", "line": 1, "action": "create"}], "key_point": "Include all existing Stripe methods"},
|
||||
{"id": "T2", "name": "Implement StripeGateway", "depends_on": ["T1"], "files": [{"file": "src/payment/stripe.ts", "line": 1, "action": "create"}], "key_point": "Wrap existing logic"},
|
||||
{"id": "T3", "name": "Create GatewayFactory", "depends_on": ["T1"], "files": [{"file": "src/payment/factory.ts", "line": 1, "action": "create"}], "key_point": null},
|
||||
{"id": "T4", "name": "Migrate processor to use factory", "depends_on": ["T2", "T3"], "files": [{"file": "src/payment/processor.ts", "line": 45, "action": "modify"}], "key_point": "Backward compatible"}
|
||||
],
|
||||
"execution_flow": "T1 → (T2 | T3) → T4",
|
||||
"milestones": ["Interface defined", "Gateway implementations complete", "Migration done"]
|
||||
},
|
||||
"dependencies": {
|
||||
"internal": ["@/lib/payment-gateway", "@/types/payment"],
|
||||
"external": ["stripe@^14.0.0"]
|
||||
},
|
||||
"technical_concerns": ["Existing tests must pass", "No breaking API changes"],
|
||||
"consensus": {
|
||||
"agreements": ["Use strategy pattern", "Keep existing API"],
|
||||
"resolved_conflicts": "Factory over DI for simpler integration"
|
||||
},
|
||||
"constraints": ["backward compatible", "no breaking changes to PaymentResult type"],
|
||||
"task_description": "Refactor payment processing for multi-gateway support",
|
||||
"session_id": "MCP-payment-refactor-2026-01-14"
|
||||
}
|
||||
```
|
||||
|
||||
**Step 2: Invoke Planning Agent**:
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-lite-planning-agent",
|
||||
run_in_background: false,
|
||||
description: "Generate implementation plan",
|
||||
prompt: `
|
||||
## Schema Reference
|
||||
Execute: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json
|
||||
|
||||
## Context-Package (from orchestrator)
|
||||
${JSON.stringify(contextPackage, null, 2)}
|
||||
|
||||
## Execution Process
|
||||
1. Read plan-json-schema.json for output structure
|
||||
2. Read project-tech.json and project-guidelines.json
|
||||
3. Parse context-package fields:
|
||||
- solution: name, feasibility, summary
|
||||
- implementation_plan: tasks[], execution_flow, milestones
|
||||
- dependencies: internal[], external[]
|
||||
- technical_concerns: risks/blockers
|
||||
- consensus: agreements, resolved_conflicts
|
||||
- constraints: user requirements
|
||||
4. Use implementation_plan.tasks[] as task foundation
|
||||
5. Preserve task dependencies (depends_on) and execution_flow
|
||||
6. Expand tasks with detailed acceptance criteria
|
||||
7. Generate plan.json following schema exactly
|
||||
|
||||
## Output
|
||||
- ${sessionFolder}/plan.json
|
||||
|
||||
## Completion Checklist
|
||||
- [ ] plan.json preserves task dependencies from implementation_plan
|
||||
- [ ] Task execution order follows execution_flow
|
||||
- [ ] Key_points reflected in task descriptions
|
||||
- [ ] User constraints applied to implementation
|
||||
- [ ] Acceptance criteria are testable
|
||||
- [ ] Schema fields match plan-json-schema.json exactly
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**Step 3: Build executionContext**:
|
||||
```javascript
|
||||
// After plan.json is generated by cli-lite-planning-agent
|
||||
const plan = JSON.parse(Read(`${sessionFolder}/plan.json`))
|
||||
|
||||
// Build executionContext (same structure as lite-plan)
|
||||
executionContext = {
|
||||
planObject: plan,
|
||||
explorationsContext: null, // Multi-CLI doesn't use exploration files
|
||||
explorationAngles: [], // No exploration angles
|
||||
explorationManifest: null, // No manifest
|
||||
clarificationContext: null, // Store user feedback from Phase 2 if exists
|
||||
executionMethod: userSelection.execution_method, // From Phase 4
|
||||
codeReviewTool: userSelection.code_review_tool, // From Phase 4
|
||||
originalUserInput: taskDescription,
|
||||
|
||||
// Optional: Task-level executor assignments
|
||||
executorAssignments: null, // Could be enhanced in future
|
||||
|
||||
session: {
|
||||
id: sessionId,
|
||||
folder: sessionFolder,
|
||||
artifacts: {
|
||||
explorations: [], // No explorations in multi-CLI workflow
|
||||
explorations_manifest: null,
|
||||
plan: `${sessionFolder}/plan.json`,
|
||||
synthesis_rounds: Array.from({length: currentRound}, (_, i) =>
|
||||
`${sessionFolder}/rounds/${i+1}/synthesis.json`
|
||||
),
|
||||
context_package: `${sessionFolder}/context-package.json`
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Step 4: Hand off to Execution**:
|
||||
```javascript
|
||||
// Execute to lite-execute with in-memory context
|
||||
SlashCommand("/workflow:lite-execute --in-memory")
|
||||
```
|
||||
|
||||
## Output File Structure
|
||||
|
||||
```
|
||||
.workflow/.multi-cli-plan/{MCP-task-slug-YYYY-MM-DD}/
|
||||
├── session-state.json # Session tracking (orchestrator)
|
||||
├── rounds/
|
||||
│ ├── 1/synthesis.json # Round 1 analysis (cli-discuss-agent)
|
||||
│ ├── 2/synthesis.json # Round 2 analysis (cli-discuss-agent)
|
||||
│ └── .../
|
||||
├── context-package.json # Extracted context for planning (orchestrator)
|
||||
└── plan.json # Structured plan (cli-lite-planning-agent)
|
||||
```
|
||||
|
||||
**File Producers**:
|
||||
|
||||
| File | Producer | Content |
|
||||
|------|----------|---------|
|
||||
| `session-state.json` | Orchestrator | Session metadata, rounds, decisions |
|
||||
| `rounds/*/synthesis.json` | cli-discuss-agent | Solutions, convergence, cross-verification |
|
||||
| `context-package.json` | Orchestrator | Extracted solution, dependencies, consensus for planning |
|
||||
| `plan.json` | cli-lite-planning-agent | Structured tasks for lite-execute |
|
||||
|
||||
## synthesis.json Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"round": 1,
|
||||
"solutions": [{
|
||||
"name": "Solution Name",
|
||||
"source_cli": ["gemini", "codex"],
|
||||
"feasibility": 0.85,
|
||||
"effort": "low|medium|high",
|
||||
"risk": "low|medium|high",
|
||||
"summary": "Brief analysis summary",
|
||||
"implementation_plan": {
|
||||
"approach": "High-level technical approach",
|
||||
"tasks": [
|
||||
{"id": "T1", "name": "Task", "depends_on": [], "files": [], "key_point": "..."}
|
||||
],
|
||||
"execution_flow": "T1 → T2 → T3",
|
||||
"milestones": ["Checkpoint 1", "Checkpoint 2"]
|
||||
},
|
||||
"dependencies": {"internal": [], "external": []},
|
||||
"technical_concerns": ["Risk 1", "Blocker 2"]
|
||||
}],
|
||||
"convergence": {
|
||||
"score": 0.85,
|
||||
"new_insights": false,
|
||||
"recommendation": "converged|continue|user_input_needed"
|
||||
},
|
||||
"cross_verification": {
|
||||
"agreements": [],
|
||||
"disagreements": [],
|
||||
"resolution": "..."
|
||||
},
|
||||
"clarification_questions": []
|
||||
}
|
||||
```
|
||||
|
||||
**Key Planning Fields**:
|
||||
|
||||
| Field | Purpose |
|
||||
|-------|---------|
|
||||
| `feasibility` | Viability score (0-1) |
|
||||
| `implementation_plan.tasks[]` | Discrete tasks with dependencies |
|
||||
| `implementation_plan.execution_flow` | Task sequence visualization |
|
||||
| `implementation_plan.milestones` | Key checkpoints |
|
||||
| `technical_concerns` | Risks and blockers |
|
||||
|
||||
**Note**: Solutions ranked by internal scoring (array order = priority)
|
||||
|
||||
## TodoWrite Structure
|
||||
|
||||
**Initialization**:
|
||||
```javascript
|
||||
TodoWrite({ todos: [
|
||||
{ content: "Phase 1: Context Gathering", status: "in_progress", activeForm: "Gathering context" },
|
||||
{ content: "Phase 2: Multi-CLI Discussion", status: "pending", activeForm: "Running discussion" },
|
||||
{ content: "Phase 3: Present Options", status: "pending", activeForm: "Presenting options" },
|
||||
{ content: "Phase 4: User Decision", status: "pending", activeForm: "Awaiting decision" },
|
||||
{ content: "Phase 5: Plan Generation", status: "pending", activeForm: "Generating plan" }
|
||||
]})
|
||||
```
|
||||
|
||||
**During Discussion Rounds**:
|
||||
```javascript
|
||||
TodoWrite({ todos: [
|
||||
{ content: "Phase 1: Context Gathering", status: "completed", activeForm: "Gathering context" },
|
||||
{ content: "Phase 2: Multi-CLI Discussion", status: "in_progress", activeForm: "Running discussion" },
|
||||
{ content: " → Round 1: Initial analysis", status: "completed", activeForm: "Analyzing" },
|
||||
{ content: " → Round 2: Deep verification", status: "in_progress", activeForm: "Verifying" },
|
||||
{ content: "Phase 3: Present Options", status: "pending", activeForm: "Presenting options" },
|
||||
// ...
|
||||
]})
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| ACE search fails | Fall back to Glob/Grep for file discovery |
|
||||
| Agent fails | Retry once, then present partial results |
|
||||
| CLI timeout (in agent) | Agent uses fallback: gemini → codex → claude |
|
||||
| No convergence | Present best options, flag uncertainty |
|
||||
| synthesis.json parse error | Request agent retry |
|
||||
| User cancels | Save session for later resumption |
|
||||
|
||||
## Configuration
|
||||
|
||||
| Flag | Default | Description |
|
||||
|------|---------|-------------|
|
||||
| `--max-rounds` | 3 | Maximum discussion rounds |
|
||||
| `--tools` | gemini,codex | CLI tools for analysis |
|
||||
| `--mode` | parallel | Execution mode: parallel or serial |
|
||||
| `--auto-execute` | false | Auto-execute after approval |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Be Specific**: Detailed task descriptions improve ACE context quality
|
||||
2. **Provide Feedback**: Use clarification rounds to refine requirements
|
||||
3. **Trust Cross-Verification**: Multi-CLI consensus indicates high confidence
|
||||
4. **Review Trade-offs**: Consider pros/cons before selecting solution
|
||||
5. **Check synthesis.json**: Review agent output for detailed analysis
|
||||
6. **Iterate When Needed**: Don't hesitate to request more analysis
|
||||
|
||||
## Related Commands
|
||||
|
||||
```bash
|
||||
# Simpler single-round planning
|
||||
/workflow:lite-plan "task description"
|
||||
|
||||
# Issue-driven discovery
|
||||
/issue:discover-by-prompt "find issues"
|
||||
|
||||
# View session files
|
||||
cat .workflow/.multi-cli-plan/{session-id}/plan.json
|
||||
cat .workflow/.multi-cli-plan/{session-id}/rounds/1/synthesis.json
|
||||
cat .workflow/.multi-cli-plan/{session-id}/context-package.json
|
||||
|
||||
# Direct execution (if you have plan.json)
|
||||
/workflow:lite-execute plan.json
|
||||
```
|
||||
@@ -1,527 +0,0 @@
|
||||
---
|
||||
name: 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.
|
||||
argument-hint: "[optional: --session session-id]"
|
||||
allowed-tools: Read(*), Write(*), Glob(*), Bash(*)
|
||||
---
|
||||
|
||||
## User Input
|
||||
|
||||
```text
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
You **MUST** consider the user input before proceeding (if not empty).
|
||||
|
||||
## Goal
|
||||
|
||||
Generate a comprehensive verification report that identifies inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`role analysis documents`). This command MUST run only after `/workflow:plan` has successfully produced complete `IMPL_PLAN.md` and task JSON files.
|
||||
|
||||
**Output**: A structured Markdown report saved to `.workflow/active/WFS-{session}/.process/PLAN_VERIFICATION.md` containing:
|
||||
- Executive summary with quality gate recommendation
|
||||
- Detailed findings by severity (CRITICAL/HIGH/MEDIUM/LOW)
|
||||
- Requirements coverage analysis
|
||||
- Dependency integrity check
|
||||
- Synthesis alignment validation
|
||||
- Actionable remediation recommendations
|
||||
|
||||
## Operating Constraints
|
||||
|
||||
**STRICTLY READ-ONLY FOR SOURCE ARTIFACTS**:
|
||||
- **MUST NOT** modify `IMPL_PLAN.md`, any `task.json` files, or brainstorming artifacts
|
||||
- **MUST NOT** create or delete task files
|
||||
- **MUST ONLY** write the verification report to `.process/PLAN_VERIFICATION.md`
|
||||
|
||||
**Synthesis Authority**: The `role analysis documents` are **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasks—not reinterpretation of requirements.
|
||||
|
||||
**Quality Gate Authority**: The verification report provides a binding recommendation (BLOCK_EXECUTION / PROCEED_WITH_FIXES / PROCEED_WITH_CAUTION / PROCEED) based on objective severity criteria. User MUST review critical/high issues before proceeding with implementation.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### 1. Initialize Analysis Context
|
||||
|
||||
```bash
|
||||
# Detect active workflow session
|
||||
IF --session parameter provided:
|
||||
session_id = provided session
|
||||
ELSE:
|
||||
# Auto-detect active session
|
||||
active_sessions = bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null)
|
||||
IF active_sessions is empty:
|
||||
ERROR: "No active workflow session found. Use --session <session-id>"
|
||||
EXIT
|
||||
ELSE IF active_sessions has multiple entries:
|
||||
# Use most recently modified session
|
||||
session_id = bash(ls -td .workflow/active/WFS-*/ 2>/dev/null | head -1 | xargs basename)
|
||||
ELSE:
|
||||
session_id = basename(active_sessions[0])
|
||||
|
||||
# Derive absolute paths
|
||||
session_dir = .workflow/active/WFS-{session}
|
||||
brainstorm_dir = session_dir/.brainstorming
|
||||
task_dir = session_dir/.task
|
||||
process_dir = session_dir/.process
|
||||
session_file = session_dir/workflow-session.json
|
||||
|
||||
# Create .process directory if not exists (report output location)
|
||||
IF NOT EXISTS(process_dir):
|
||||
bash(mkdir -p "{process_dir}")
|
||||
|
||||
# Validate required artifacts
|
||||
# Note: "role analysis documents" refers to [role]/analysis.md files (e.g., product-manager/analysis.md)
|
||||
SYNTHESIS_DIR = brainstorm_dir # Contains role analysis files: */analysis.md
|
||||
IMPL_PLAN = session_dir/IMPL_PLAN.md
|
||||
TASK_FILES = Glob(task_dir/*.json)
|
||||
|
||||
# Abort if missing - in order of dependency
|
||||
SESSION_FILE_EXISTS = EXISTS(session_file)
|
||||
IF NOT SESSION_FILE_EXISTS:
|
||||
WARNING: "workflow-session.json not found. User intent alignment verification will be skipped."
|
||||
# Continue execution - this is optional context, not blocking
|
||||
|
||||
SYNTHESIS_FILES = Glob(brainstorm_dir/*/analysis.md)
|
||||
IF SYNTHESIS_FILES.count == 0:
|
||||
ERROR: "No role analysis documents found in .brainstorming/*/analysis.md. Run /workflow:brainstorm:synthesis first"
|
||||
EXIT
|
||||
|
||||
IF NOT EXISTS(IMPL_PLAN):
|
||||
ERROR: "IMPL_PLAN.md not found. Run /workflow:plan first"
|
||||
EXIT
|
||||
|
||||
IF TASK_FILES.count == 0:
|
||||
ERROR: "No task JSON files found. Run /workflow:plan first"
|
||||
EXIT
|
||||
```
|
||||
|
||||
### 2. Load Artifacts (Progressive Disclosure)
|
||||
|
||||
Load only minimal necessary context from each artifact:
|
||||
|
||||
**From workflow-session.json** (OPTIONAL - Primary Reference for User Intent):
|
||||
- **ONLY IF EXISTS**: Load user intent context
|
||||
- Original user prompt/intent (project or description field)
|
||||
- User's stated goals and objectives
|
||||
- User's scope definition
|
||||
- **IF MISSING**: Set user_intent_analysis = "SKIPPED: workflow-session.json not found"
|
||||
|
||||
**From role analysis documents** (AUTHORITATIVE SOURCE):
|
||||
- Functional Requirements (IDs, descriptions, acceptance criteria)
|
||||
- Non-Functional Requirements (IDs, targets)
|
||||
- Business Requirements (IDs, success metrics)
|
||||
- Key Architecture Decisions
|
||||
- Risk factors and mitigation strategies
|
||||
- Implementation Roadmap (high-level phases)
|
||||
|
||||
**From IMPL_PLAN.md**:
|
||||
- Summary and objectives
|
||||
- Context Analysis
|
||||
- Implementation Strategy
|
||||
- Task Breakdown Summary
|
||||
- Success Criteria
|
||||
- Brainstorming Artifacts References (if present)
|
||||
|
||||
**From task.json files**:
|
||||
- Task IDs
|
||||
- Titles and descriptions
|
||||
- Status
|
||||
- Dependencies (depends_on, blocks)
|
||||
- Context (requirements, focus_paths, acceptance, artifacts)
|
||||
- Flow control (pre_analysis, implementation_approach)
|
||||
- Meta (complexity, priority)
|
||||
|
||||
### 3. Build Semantic Models
|
||||
|
||||
Create internal representations (do not include raw artifacts in output):
|
||||
|
||||
**Requirements inventory**:
|
||||
- Each functional/non-functional/business requirement with stable ID
|
||||
- Requirement text, acceptance criteria, priority
|
||||
|
||||
**Architecture decisions inventory**:
|
||||
- ADRs from synthesis
|
||||
- Technology choices
|
||||
- Data model references
|
||||
|
||||
**Task coverage mapping**:
|
||||
- Map each task to one or more requirements (by ID reference or keyword inference)
|
||||
- Map each requirement to covering tasks
|
||||
|
||||
**Dependency graph**:
|
||||
- Task-to-task dependencies (depends_on, blocks)
|
||||
- Requirement-level dependencies (from synthesis)
|
||||
|
||||
### 4. Detection Passes (Token-Efficient Analysis)
|
||||
|
||||
**Token Budget Strategy**:
|
||||
- **Total Limit**: 50 findings maximum (aggregate remainder in overflow summary)
|
||||
- **Priority Allocation**: CRITICAL (unlimited) → HIGH (15) → MEDIUM (20) → LOW (15)
|
||||
- **Early Exit**: If CRITICAL findings > 0 in User Intent/Requirements Coverage, skip LOW/MEDIUM priority checks
|
||||
|
||||
**Execution Order** (Process in sequence; skip if token budget exhausted):
|
||||
|
||||
1. **Tier 1 (CRITICAL Path)**: A, B, C - User intent, coverage, consistency (process fully)
|
||||
2. **Tier 2 (HIGH Priority)**: D, E - Dependencies, synthesis alignment (limit 15 findings total)
|
||||
3. **Tier 3 (MEDIUM Priority)**: F - Specification quality (limit 20 findings)
|
||||
4. **Tier 4 (LOW Priority)**: G, H - Duplication, feasibility (limit 15 findings total)
|
||||
|
||||
---
|
||||
|
||||
#### A. User Intent Alignment (CRITICAL - Tier 1)
|
||||
|
||||
- **Goal Alignment**: IMPL_PLAN objectives match user's original intent
|
||||
- **Scope Drift**: Plan covers user's stated scope without unauthorized expansion
|
||||
- **Success Criteria Match**: Plan's success criteria reflect user's expectations
|
||||
- **Intent Conflicts**: Tasks contradicting user's original objectives
|
||||
|
||||
#### B. Requirements Coverage Analysis
|
||||
|
||||
- **Orphaned Requirements**: Requirements in synthesis with zero associated tasks
|
||||
- **Unmapped Tasks**: Tasks with no clear requirement linkage
|
||||
- **NFR Coverage Gaps**: Non-functional requirements (performance, security, scalability) not reflected in tasks
|
||||
|
||||
#### C. Consistency Validation
|
||||
|
||||
- **Requirement Conflicts**: Tasks contradicting synthesis requirements
|
||||
- **Architecture Drift**: IMPL_PLAN architecture not matching synthesis ADRs
|
||||
- **Terminology Drift**: Same concept named differently across IMPL_PLAN and tasks
|
||||
- **Data Model Inconsistency**: Tasks referencing entities/fields not in synthesis data model
|
||||
|
||||
#### D. Dependency Integrity
|
||||
|
||||
- **Circular Dependencies**: Task A depends on B, B depends on C, C depends on A
|
||||
- **Missing Dependencies**: Task requires outputs from another task but no explicit dependency
|
||||
- **Broken Dependencies**: Task depends on non-existent task ID
|
||||
- **Logical Ordering Issues**: Implementation tasks before foundational setup without dependency note
|
||||
|
||||
#### E. Synthesis Alignment
|
||||
|
||||
- **Priority Conflicts**: High-priority synthesis requirements mapped to low-priority tasks
|
||||
- **Success Criteria Mismatch**: IMPL_PLAN success criteria not covering synthesis acceptance criteria
|
||||
- **Risk Mitigation Gaps**: Critical risks in synthesis without corresponding mitigation tasks
|
||||
|
||||
#### F. Task Specification Quality
|
||||
|
||||
- **Ambiguous Focus Paths**: Tasks with vague or missing focus_paths
|
||||
- **Underspecified Acceptance**: Tasks without clear acceptance criteria
|
||||
- **Missing Artifacts References**: Tasks not referencing relevant brainstorming artifacts in context.artifacts
|
||||
- **Weak Flow Control**: Tasks without clear implementation_approach or pre_analysis steps
|
||||
- **Missing Target Files**: Tasks without flow_control.target_files specification
|
||||
|
||||
#### G. Duplication Detection
|
||||
|
||||
- **Overlapping Task Scope**: Multiple tasks with nearly identical descriptions
|
||||
- **Redundant Requirements Coverage**: Same requirement covered by multiple tasks without clear partitioning
|
||||
|
||||
#### H. Feasibility Assessment
|
||||
|
||||
- **Complexity Misalignment**: Task marked "simple" but requires multiple file modifications
|
||||
- **Resource Conflicts**: Parallel tasks requiring same resources/files
|
||||
- **Skill Gap Risks**: Tasks requiring skills not in team capability assessment (from synthesis)
|
||||
|
||||
### 5. Severity Assignment
|
||||
|
||||
Use this heuristic to prioritize findings:
|
||||
|
||||
- **CRITICAL**:
|
||||
- Violates user's original intent (goal misalignment, scope drift)
|
||||
- Violates synthesis authority (requirement conflict)
|
||||
- Core requirement with zero coverage
|
||||
- Circular dependencies
|
||||
- Broken dependencies
|
||||
|
||||
- **HIGH**:
|
||||
- NFR coverage gaps
|
||||
- Priority conflicts
|
||||
- Missing risk mitigation tasks
|
||||
- Ambiguous acceptance criteria
|
||||
|
||||
- **MEDIUM**:
|
||||
- Terminology drift
|
||||
- Missing artifacts references
|
||||
- Weak flow control
|
||||
- Logical ordering issues
|
||||
|
||||
- **LOW**:
|
||||
- Style/wording improvements
|
||||
- Minor redundancy not affecting execution
|
||||
|
||||
### 6. Produce Compact Analysis Report
|
||||
|
||||
**Report Generation**: Generate report content and save to file.
|
||||
|
||||
Output a Markdown report with the following structure:
|
||||
|
||||
```markdown
|
||||
# Plan Verification Report
|
||||
|
||||
**Session**: WFS-{session-id}
|
||||
**Generated**: {timestamp}
|
||||
**Artifacts Analyzed**: role analysis documents, IMPL_PLAN.md, {N} task files
|
||||
**User Intent Analysis**: {user_intent_analysis or "SKIPPED: workflow-session.json not found"}
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
### Quality Gate Decision
|
||||
|
||||
| Metric | Value | Status |
|
||||
|--------|-------|--------|
|
||||
| Overall Risk Level | CRITICAL \| HIGH \| MEDIUM \| LOW | {status_emoji} |
|
||||
| Critical Issues | {count} | 🔴 |
|
||||
| High Issues | {count} | 🟠 |
|
||||
| Medium Issues | {count} | 🟡 |
|
||||
| Low Issues | {count} | 🟢 |
|
||||
|
||||
### Recommendation
|
||||
|
||||
**{RECOMMENDATION}**
|
||||
|
||||
**Decision Rationale**:
|
||||
{brief explanation based on severity criteria}
|
||||
|
||||
**Quality Gate Criteria**:
|
||||
- **BLOCK_EXECUTION**: Critical issues > 0 (must fix before proceeding)
|
||||
- **PROCEED_WITH_FIXES**: Critical = 0, High > 0 (fix recommended before execution)
|
||||
- **PROCEED_WITH_CAUTION**: Critical = 0, High = 0, Medium > 0 (proceed with awareness)
|
||||
- **PROCEED**: Only Low issues or None (safe to execute)
|
||||
|
||||
---
|
||||
|
||||
## Findings Summary
|
||||
|
||||
| ID | Category | Severity | Location(s) | Summary | Recommendation |
|
||||
|----|----------|----------|-------------|---------|----------------|
|
||||
| C1 | Coverage | CRITICAL | synthesis:FR-03 | Requirement "User auth" has zero task coverage | Add authentication implementation task |
|
||||
| H1 | Consistency | HIGH | IMPL-1.2 vs synthesis:ADR-02 | Task uses REST while synthesis specifies GraphQL | Align task with ADR-02 decision |
|
||||
| M1 | Specification | MEDIUM | IMPL-2.1 | Missing context.artifacts reference | Add @synthesis reference |
|
||||
| L1 | Duplication | LOW | IMPL-3.1, IMPL-3.2 | Similar scope | Consider merging |
|
||||
|
||||
(Generate stable IDs prefixed by severity initial: C/H/M/L + number)
|
||||
|
||||
---
|
||||
|
||||
## User Intent Alignment Analysis
|
||||
|
||||
{IF user_intent_analysis != "SKIPPED"}
|
||||
|
||||
### Goal Alignment
|
||||
- **User Intent**: {user_original_intent}
|
||||
- **IMPL_PLAN Objectives**: {plan_objectives}
|
||||
- **Alignment Status**: {ALIGNED/MISALIGNED/PARTIAL}
|
||||
- **Findings**: {specific alignment issues}
|
||||
|
||||
### Scope Verification
|
||||
- **User Scope**: {user_defined_scope}
|
||||
- **Plan Scope**: {plan_actual_scope}
|
||||
- **Drift Detection**: {NONE/MINOR/MAJOR}
|
||||
- **Findings**: {specific scope issues}
|
||||
|
||||
{ELSE}
|
||||
> ⚠️ User intent alignment analysis was skipped because workflow-session.json was not found.
|
||||
|
||||
{END IF}
|
||||
|
||||
---
|
||||
|
||||
## Requirements Coverage Analysis
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
| Requirement ID | Requirement Summary | Has Task? | Task IDs | Priority Match | Notes |
|
||||
|----------------|---------------------|-----------|----------|----------------|-------|
|
||||
| FR-01 | User authentication | Yes | IMPL-1.1, IMPL-1.2 | Match | Complete |
|
||||
| FR-02 | Data export | Yes | IMPL-2.3 | Mismatch | High req → Med priority task |
|
||||
| FR-03 | Profile management | No | - | - | **CRITICAL: Zero coverage** |
|
||||
|
||||
### Non-Functional Requirements
|
||||
|
||||
| Requirement ID | Requirement Summary | Has Task? | Task IDs | Notes |
|
||||
|----------------|---------------------|-----------|----------|-------|
|
||||
| NFR-01 | Response time <200ms | No | - | **HIGH: No performance tasks** |
|
||||
| NFR-02 | Security compliance | Yes | IMPL-4.1 | Complete |
|
||||
|
||||
### Business Requirements
|
||||
|
||||
| Requirement ID | Requirement Summary | Has Task? | Task IDs | Notes |
|
||||
|----------------|---------------------|-----------|----------|-------|
|
||||
| BR-01 | Launch by Q2 | Yes | IMPL-1.* through IMPL-5.* | Timeline realistic |
|
||||
|
||||
### Coverage Metrics
|
||||
|
||||
| Requirement Type | Total | Covered | Coverage % |
|
||||
|------------------|-------|---------|------------|
|
||||
| Functional | {count} | {count} | {percent}% |
|
||||
| Non-Functional | {count} | {count} | {percent}% |
|
||||
| Business | {count} | {count} | {percent}% |
|
||||
| **Overall** | **{total}** | **{covered}** | **{percent}%** |
|
||||
|
||||
---
|
||||
|
||||
## Dependency Integrity
|
||||
|
||||
### Dependency Graph Analysis
|
||||
|
||||
**Circular Dependencies**: {None or List}
|
||||
|
||||
**Broken Dependencies**:
|
||||
- IMPL-2.3 depends on "IMPL-2.4" (non-existent)
|
||||
|
||||
**Missing Dependencies**:
|
||||
- IMPL-5.1 (integration test) has no dependency on IMPL-1.* (implementation tasks)
|
||||
|
||||
**Logical Ordering Issues**:
|
||||
{List or "None detected"}
|
||||
|
||||
---
|
||||
|
||||
## Synthesis Alignment Issues
|
||||
|
||||
| Issue Type | Synthesis Reference | IMPL_PLAN/Task | Impact | Recommendation |
|
||||
|------------|---------------------|----------------|--------|----------------|
|
||||
| Architecture Conflict | synthesis:ADR-01 (JWT auth) | IMPL_PLAN uses session cookies | HIGH | Update IMPL_PLAN to use JWT |
|
||||
| Priority Mismatch | synthesis:FR-02 (High) | IMPL-2.3 (Medium) | MEDIUM | Elevate task priority |
|
||||
| Missing Risk Mitigation | synthesis:Risk-03 (API rate limits) | No mitigation tasks | HIGH | Add rate limiting implementation task |
|
||||
|
||||
---
|
||||
|
||||
## Task Specification Quality
|
||||
|
||||
### Aggregate Statistics
|
||||
|
||||
| Quality Dimension | Tasks Affected | Percentage |
|
||||
|-------------------|----------------|------------|
|
||||
| Missing Artifacts References | {count} | {percent}% |
|
||||
| Weak Flow Control | {count} | {percent}% |
|
||||
| Missing Target Files | {count} | {percent}% |
|
||||
| Ambiguous Focus Paths | {count} | {percent}% |
|
||||
|
||||
### Sample Issues
|
||||
|
||||
- **IMPL-1.2**: No context.artifacts reference to synthesis
|
||||
- **IMPL-3.1**: Missing flow_control.target_files specification
|
||||
- **IMPL-4.2**: Vague focus_paths ["src/"] - needs refinement
|
||||
|
||||
---
|
||||
|
||||
## Feasibility Concerns
|
||||
|
||||
| Concern | Tasks Affected | Issue | Recommendation |
|
||||
|---------|----------------|-------|----------------|
|
||||
| Skill Gap | IMPL-6.1, IMPL-6.2 | Requires Kubernetes expertise not in team | Add training task or external consultant |
|
||||
| Resource Conflict | IMPL-3.1, IMPL-3.2 | Both modify src/auth/service.ts in parallel | Add dependency or serialize |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Findings by Severity
|
||||
|
||||
### CRITICAL Issues ({count})
|
||||
|
||||
{Detailed breakdown of each critical issue with location, impact, and recommendation}
|
||||
|
||||
### HIGH Issues ({count})
|
||||
|
||||
{Detailed breakdown of each high issue with location, impact, and recommendation}
|
||||
|
||||
### MEDIUM Issues ({count})
|
||||
|
||||
{Detailed breakdown of each medium issue with location, impact, and recommendation}
|
||||
|
||||
### LOW Issues ({count})
|
||||
|
||||
{Detailed breakdown of each low issue with location, impact, and recommendation}
|
||||
|
||||
---
|
||||
|
||||
## Metrics Summary
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Total Requirements | {count} ({functional} functional, {nonfunctional} non-functional, {business} business) |
|
||||
| Total Tasks | {count} |
|
||||
| Overall Coverage | {percent}% ({covered}/{total} requirements with ≥1 task) |
|
||||
| Critical Issues | {count} |
|
||||
| High Issues | {count} |
|
||||
| Medium Issues | {count} |
|
||||
| Low Issues | {count} |
|
||||
| Total Findings | {total_findings} |
|
||||
|
||||
---
|
||||
|
||||
## Remediation Recommendations
|
||||
|
||||
### Priority Order
|
||||
|
||||
1. **CRITICAL** - Must fix before proceeding
|
||||
2. **HIGH** - Fix before execution
|
||||
3. **MEDIUM** - Fix during or after implementation
|
||||
4. **LOW** - Optional improvements
|
||||
|
||||
### Next Steps
|
||||
|
||||
Based on the quality gate recommendation ({RECOMMENDATION}):
|
||||
|
||||
{IF BLOCK_EXECUTION}
|
||||
**🛑 BLOCK EXECUTION**
|
||||
|
||||
You must resolve all CRITICAL issues before proceeding with implementation:
|
||||
|
||||
1. Review each critical issue in detail
|
||||
2. Determine remediation approach (modify IMPL_PLAN.md, update task.json, or add new tasks)
|
||||
3. Apply fixes systematically
|
||||
4. Re-run verification to confirm resolution
|
||||
|
||||
{ELSE IF PROCEED_WITH_FIXES}
|
||||
**⚠️ PROCEED WITH FIXES RECOMMENDED**
|
||||
|
||||
No critical issues detected, but HIGH issues exist. Recommended workflow:
|
||||
|
||||
1. Review high-priority issues
|
||||
2. Apply fixes before execution for optimal results
|
||||
3. Re-run verification (optional)
|
||||
|
||||
{ELSE IF PROCEED_WITH_CAUTION}
|
||||
**✅ PROCEED WITH CAUTION**
|
||||
|
||||
Only MEDIUM issues detected. You may proceed with implementation:
|
||||
|
||||
- Address medium issues during or after implementation
|
||||
- Maintain awareness of identified concerns
|
||||
|
||||
{ELSE}
|
||||
**✅ PROCEED**
|
||||
|
||||
No significant issues detected. Safe to execute implementation workflow.
|
||||
|
||||
{END IF}
|
||||
|
||||
---
|
||||
|
||||
**Report End**
|
||||
```
|
||||
|
||||
### 7. Save and Display Report
|
||||
|
||||
**Step 7.1: Save Report**:
|
||||
```bash
|
||||
report_path = ".workflow/active/WFS-{session}/.process/PLAN_VERIFICATION.md"
|
||||
Write(report_path, full_report_content)
|
||||
```
|
||||
|
||||
**Step 7.2: Display Summary to User**:
|
||||
```bash
|
||||
# Display executive summary in terminal
|
||||
echo "=== Plan Verification Complete ==="
|
||||
echo "Report saved to: {report_path}"
|
||||
echo ""
|
||||
echo "Quality Gate: {RECOMMENDATION}"
|
||||
echo "Critical: {count} | High: {count} | Medium: {count} | Low: {count}"
|
||||
echo ""
|
||||
echo "Next: Review full report for detailed findings and recommendations"
|
||||
```
|
||||
|
||||
**Step 7.3: Completion**:
|
||||
- Report is saved to `.process/PLAN_VERIFICATION.md`
|
||||
- User can review findings and decide on remediation approach
|
||||
- No automatic modifications are made to source artifacts
|
||||
- User can manually apply fixes or use separate remediation command (if available)
|
||||
@@ -1,19 +1,15 @@
|
||||
---
|
||||
name: plan
|
||||
description: 5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs
|
||||
argument-hint: "[-y|--yes] \"text description\"|file.md"
|
||||
argument-hint: "\"text description\"|file.md"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-continue all phases (skip confirmations), use recommended conflict resolutions.
|
||||
|
||||
# Workflow Plan Command (/workflow:plan)
|
||||
|
||||
## Coordinator Role
|
||||
|
||||
**This command is a pure orchestrator**: Execute 5 slash commands in sequence (including a quality gate), parse their outputs, pass context between them, and ensure complete execution through **automatic continuation**.
|
||||
**This command is a pure orchestrator**: Dispatch 5 slash commands in sequence (including a quality gate), parse their outputs, pass context between them, and ensure complete execution through **automatic continuation**.
|
||||
|
||||
**Execution Model - Auto-Continue Workflow with Quality Gate**:
|
||||
|
||||
@@ -21,14 +17,14 @@ This workflow runs **fully autonomously** once triggered. Phase 3 (conflict reso
|
||||
|
||||
|
||||
1. **User triggers**: `/workflow:plan "task"`
|
||||
2. **Phase 1 executes** → Session discovery → Auto-continues
|
||||
3. **Phase 2 executes** → Context gathering → Auto-continues
|
||||
4. **Phase 3 executes** (optional, if conflict_risk ≥ medium) → Conflict resolution → Auto-continues
|
||||
5. **Phase 4 executes** → Task generation (task-generate-agent) → Reports final summary
|
||||
2. **Phase 1 dispatches** → Session discovery → Auto-continues
|
||||
3. **Phase 2 dispatches** → Context gathering → Auto-continues
|
||||
4. **Phase 3 dispatches** (optional, if conflict_risk ≥ medium) → Conflict resolution → Auto-continues
|
||||
5. **Phase 4 dispatches** → Task generation (task-generate-agent) → Reports final summary
|
||||
|
||||
**Task Attachment Model**:
|
||||
- SlashCommand execute **expands workflow** by attaching sub-tasks to current TodoWrite
|
||||
- When a sub-command is executed (e.g., `/workflow:tools:context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
|
||||
- SlashCommand dispatch **expands workflow** by attaching sub-tasks to current TodoWrite
|
||||
- When a sub-command is dispatched (e.g., `/workflow:tools:context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
|
||||
- Orchestrator **executes these attached tasks** sequentially
|
||||
- After completion, attached tasks are **collapsed** back to high-level phase summary
|
||||
- This is **task expansion**, not external delegation
|
||||
@@ -47,7 +43,7 @@ This workflow runs **fully autonomously** once triggered. Phase 3 (conflict reso
|
||||
3. **Parse Every Output**: Extract required data from each command/agent output for next phase
|
||||
4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
|
||||
5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
|
||||
6. **Task Attachment Model**: SlashCommand execute **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
|
||||
6. **Task Attachment Model**: SlashCommand dispatch **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
|
||||
7. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
|
||||
|
||||
## Execution Process
|
||||
@@ -65,7 +61,7 @@ Phase 2: Context Gathering
|
||||
├─ Tasks attached: Analyze structure → Identify integration → Generate package
|
||||
└─ Output: contextPath + conflict_risk
|
||||
|
||||
Phase 3: Conflict Resolution
|
||||
Phase 3: Conflict Resolution (conditional)
|
||||
└─ Decision (conflict_risk check):
|
||||
├─ conflict_risk ≥ medium → Execute /workflow:tools:conflict-resolution
|
||||
│ ├─ Tasks attached: Detect conflicts → Present to user → Apply strategies
|
||||
@@ -84,7 +80,7 @@ Return:
|
||||
|
||||
### Phase 1: Session Discovery
|
||||
|
||||
**Step 1.1: Execute** - Create or discover workflow session
|
||||
**Step 1.1: Dispatch** - Create or discover workflow session
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:session:start --auto \"[structured-task-description]\"")
|
||||
@@ -121,7 +117,7 @@ CONTEXT: Existing user database schema, REST API endpoints
|
||||
|
||||
### Phase 2: Context Gathering
|
||||
|
||||
**Step 2.1: Execute** - Gather project context and analyze codebase
|
||||
**Step 2.1: Dispatch** - Gather project context and analyze codebase
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:tools:context-gather --session [sessionId] \"[structured-task-description]\"")
|
||||
@@ -139,9 +135,9 @@ SlashCommand(command="/workflow:tools:context-gather --session [sessionId] \"[st
|
||||
- Context package path extracted
|
||||
- File exists and is valid JSON
|
||||
|
||||
<!-- TodoWrite: When context-gather executed, INSERT 3 context-gather tasks, mark first as in_progress -->
|
||||
<!-- TodoWrite: When context-gather dispatched, INSERT 3 context-gather tasks, mark first as in_progress -->
|
||||
|
||||
**TodoWrite Update (Phase 2 SlashCommand executed - tasks attached)**:
|
||||
**TodoWrite Update (Phase 2 SlashCommand dispatched - tasks attached)**:
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
@@ -153,7 +149,7 @@ SlashCommand(command="/workflow:tools:context-gather --session [sessionId] \"[st
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: SlashCommand execute **attaches** context-gather's 3 tasks. Orchestrator **executes** these tasks sequentially.
|
||||
**Note**: SlashCommand dispatch **attaches** context-gather's 3 tasks. Orchestrator **executes** these tasks sequentially.
|
||||
|
||||
<!-- TodoWrite: After Phase 2 tasks complete, REMOVE Phase 2.1-2.3, restore to orchestrator view -->
|
||||
|
||||
@@ -172,11 +168,11 @@ SlashCommand(command="/workflow:tools:context-gather --session [sessionId] \"[st
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Conflict Resolution
|
||||
### Phase 3: Conflict Resolution (Optional - auto-triggered by conflict risk)
|
||||
|
||||
**Trigger**: Only execute when context-package.json indicates conflict_risk is "medium" or "high"
|
||||
|
||||
**Step 3.1: Execute** - Detect and resolve conflicts with CLI analysis
|
||||
**Step 3.1: Dispatch** - Detect and resolve conflicts with CLI analysis
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId] --context [contextPath]")
|
||||
@@ -189,10 +185,10 @@ SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId]
|
||||
|
||||
**Parse Output**:
|
||||
- Extract: Execution status (success/skipped/failed)
|
||||
- Verify: conflict-resolution.json file path (if executed)
|
||||
- Verify: CONFLICT_RESOLUTION.md file path (if executed)
|
||||
|
||||
**Validation**:
|
||||
- File `.workflow/active/[sessionId]/.process/conflict-resolution.json` exists (if executed)
|
||||
- File `.workflow/active/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed)
|
||||
|
||||
**Skip Behavior**:
|
||||
- If conflict_risk is "none" or "low", skip directly to Phase 3.5
|
||||
@@ -200,7 +196,7 @@ SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId]
|
||||
|
||||
<!-- TodoWrite: If conflict_risk ≥ medium, INSERT 3 conflict-resolution tasks -->
|
||||
|
||||
**TodoWrite Update (Phase 3 SlashCommand executed - tasks attached, if conflict_risk ≥ medium)**:
|
||||
**TodoWrite Update (Phase 3 SlashCommand dispatched - tasks attached, if conflict_risk ≥ medium)**:
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
@@ -213,7 +209,7 @@ SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId]
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: SlashCommand execute **attaches** conflict-resolution's 3 tasks. Orchestrator **executes** these tasks sequentially.
|
||||
**Note**: SlashCommand dispatch **attaches** conflict-resolution's 3 tasks. Orchestrator **executes** these tasks sequentially.
|
||||
|
||||
<!-- TodoWrite: After Phase 3 tasks complete, REMOVE Phase 3.1-3.3, restore to orchestrator view -->
|
||||
|
||||
@@ -235,7 +231,7 @@ SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId]
|
||||
- Evaluate current context window usage and memory state
|
||||
- If memory usage is high (>120K tokens or approaching context limits):
|
||||
|
||||
**Step 3.2: Execute** - Optimize memory before proceeding
|
||||
**Step 3.2: Dispatch** - Optimize memory before proceeding
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/compact")
|
||||
@@ -274,7 +270,7 @@ SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId]
|
||||
- Task generation translates high-level role analyses into concrete, actionable work items
|
||||
- **Intent priority**: Current user prompt > role analysis.md files > guidance-specification.md
|
||||
|
||||
**Step 4.1: Execute** - Generate implementation plan and task JSONs
|
||||
**Step 4.1: Dispatch** - Generate implementation plan and task JSONs
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")
|
||||
@@ -289,9 +285,9 @@ SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]"
|
||||
- `.workflow/active/[sessionId]/.task/IMPL-*.json` exists (at least one)
|
||||
- `.workflow/active/[sessionId]/TODO_LIST.md` exists
|
||||
|
||||
<!-- TodoWrite: When task-generate-agent executed, ATTACH 1 agent task -->
|
||||
<!-- TodoWrite: When task-generate-agent dispatched, ATTACH 1 agent task -->
|
||||
|
||||
**TodoWrite Update (Phase 4 SlashCommand executed - agent task attached)**:
|
||||
**TodoWrite Update (Phase 4 SlashCommand dispatched - agent task attached)**:
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
@@ -322,11 +318,11 @@ Tasks generated: [count]
|
||||
Plan: .workflow/active/[sessionId]/IMPL_PLAN.md
|
||||
|
||||
Recommended Next Steps:
|
||||
1. /workflow:plan-verify --session [sessionId] # Verify plan quality before execution
|
||||
1. /workflow:action-plan-verify --session [sessionId] # Verify plan quality before execution
|
||||
2. /workflow:status # Review task breakdown
|
||||
3. /workflow:execute # Start implementation (after verification)
|
||||
|
||||
Quality Gate: Consider running /workflow:plan-verify to catch issues early
|
||||
Quality Gate: Consider running /workflow:action-plan-verify to catch issues early
|
||||
```
|
||||
|
||||
## TodoWrite Pattern
|
||||
@@ -335,7 +331,7 @@ Quality Gate: Consider running /workflow:plan-verify to catch issues early
|
||||
|
||||
### Key Principles
|
||||
|
||||
1. **Task Attachment** (when SlashCommand executed):
|
||||
1. **Task Attachment** (when SlashCommand dispatched):
|
||||
- Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
|
||||
- **Phase 2, 3**: Multiple sub-tasks attached (e.g., Phase 2.1, 2.2, 2.3)
|
||||
- **Phase 4**: Single agent task attached (e.g., "Execute task-generate-agent")
|
||||
@@ -354,7 +350,7 @@ Quality Gate: Consider running /workflow:plan-verify to catch issues early
|
||||
- No user intervention required between phases
|
||||
- TodoWrite dynamically reflects current execution state
|
||||
|
||||
**Lifecycle Summary**: Initial pending tasks → Phase executed (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary for Phase 2/3, or marked completed for Phase 4) → Next phase begins → Repeat until all phases complete.
|
||||
**Lifecycle Summary**: Initial pending tasks → Phase dispatched (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary for Phase 2/3, or marked completed for Phase 4) → Next phase begins → Repeat until all phases complete.
|
||||
|
||||
|
||||
|
||||
@@ -446,7 +442,7 @@ User triggers: /workflow:plan "Build authentication system"
|
||||
Phase 1: Session Discovery
|
||||
→ sessionId extracted
|
||||
↓
|
||||
Phase 2: Context Gathering (SlashCommand executed)
|
||||
Phase 2: Context Gathering (SlashCommand dispatched)
|
||||
→ ATTACH 3 sub-tasks: ← ATTACHED
|
||||
- → Analyze codebase structure
|
||||
- → Identify integration points
|
||||
@@ -457,7 +453,7 @@ Phase 2: Context Gathering (SlashCommand executed)
|
||||
↓
|
||||
Conditional Branch: Check conflict_risk
|
||||
├─ IF conflict_risk ≥ medium:
|
||||
│ Phase 3: Conflict Resolution (SlashCommand executed)
|
||||
│ Phase 3: Conflict Resolution (SlashCommand dispatched)
|
||||
│ → ATTACH 3 sub-tasks: ← ATTACHED
|
||||
│ - → Detect conflicts with CLI analysis
|
||||
│ - → Present conflicts to user
|
||||
@@ -467,7 +463,7 @@ Conditional Branch: Check conflict_risk
|
||||
│
|
||||
└─ ELSE: Skip Phase 3, proceed to Phase 4
|
||||
↓
|
||||
Phase 4: Task Generation (SlashCommand executed)
|
||||
Phase 4: Task Generation (SlashCommand dispatched)
|
||||
→ Single agent task (no sub-tasks)
|
||||
→ Agent autonomously completes internally:
|
||||
(discovery → planning → output)
|
||||
@@ -477,12 +473,12 @@ Return summary to user
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
- **← ATTACHED**: Tasks attached to TodoWrite when SlashCommand executed
|
||||
- **← ATTACHED**: Tasks attached to TodoWrite when SlashCommand dispatched
|
||||
- Phase 2, 3: Multiple sub-tasks
|
||||
- Phase 4: Single agent task
|
||||
- **← COLLAPSED**: Sub-tasks collapsed to summary after completion (Phase 2, 3 only)
|
||||
- **Phase 4**: Single agent task, no collapse (just mark completed)
|
||||
- **Conditional Branch**: Phase 3 only executes if conflict_risk ≥ medium
|
||||
- **Conditional Branch**: Phase 3 only dispatches if conflict_risk ≥ medium
|
||||
- **Continuous Flow**: No user intervention between phases
|
||||
|
||||
## Error Handling
|
||||
@@ -501,7 +497,7 @@ Return summary to user
|
||||
- Parse context path from Phase 2 output, store in memory
|
||||
- **Extract conflict_risk from context-package.json**: Determine Phase 3 execution
|
||||
- **If conflict_risk ≥ medium**: Launch Phase 3 conflict-resolution with sessionId and contextPath
|
||||
- Wait for Phase 3 to finish executing (if executed), verify conflict-resolution.json created
|
||||
- Wait for Phase 3 to finish executing (if executed), verify CONFLICT_RESOLUTION.md created
|
||||
- **If conflict_risk is none/low**: Skip Phase 3, proceed directly to Phase 4
|
||||
- **Build Phase 4 command**: `/workflow:tools:task-generate-agent --session [sessionId]`
|
||||
- Pass session ID to Phase 4 command
|
||||
@@ -550,6 +546,6 @@ CONSTRAINTS: [Limitations or boundaries]
|
||||
- `/workflow:tools:task-generate-agent` - Phase 4: Generate task JSON files with agent-driven approach
|
||||
|
||||
**Follow-up Commands**:
|
||||
- `/workflow:plan-verify` - Recommended: Verify plan quality and catch issues before execution
|
||||
- `/workflow:action-plan-verify` - Recommended: Verify plan quality and catch issues before execution
|
||||
- `/workflow:status` - Review task breakdown and current progress
|
||||
- `/workflow:execute` - Begin implementation of generated tasks
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: replan
|
||||
description: Interactive workflow replanning with session-level artifact updates and boundary clarification through guided questioning
|
||||
argument-hint: "[-y|--yes] [--session session-id] [task-id] \"requirements\"|file.md [--interactive]"
|
||||
argument-hint: "[--session session-id] [task-id] \"requirements\"|file.md [--interactive]"
|
||||
allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
|
||||
---
|
||||
|
||||
@@ -117,48 +117,10 @@ const taskId = taskIdMatch?.[1]
|
||||
|
||||
---
|
||||
|
||||
### Auto Mode Support
|
||||
|
||||
When `--yes` or `-y` flag is used, the command skips interactive clarification and uses safe defaults:
|
||||
|
||||
```javascript
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
```
|
||||
|
||||
**Auto Mode Defaults**:
|
||||
- **Modification Scope**: `tasks_only` (safest - only update task details)
|
||||
- **Affected Modules**: All modules related to the task
|
||||
- **Task Changes**: `update_only` (no structural changes)
|
||||
- **Dependency Changes**: `no` (preserve existing dependencies)
|
||||
- **User Confirmation**: Auto-confirm execution
|
||||
|
||||
**Note**: `--interactive` flag overrides `--yes` flag (forces interactive mode).
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Interactive Requirement Clarification
|
||||
|
||||
**Purpose**: Define modification scope through guided questioning
|
||||
|
||||
**Auto Mode Check**:
|
||||
```javascript
|
||||
if (autoYes && !interactive) {
|
||||
// Use defaults and skip to Phase 3
|
||||
console.log(`[--yes] Using safe defaults for replan:`)
|
||||
console.log(` - Scope: tasks_only`)
|
||||
console.log(` - Changes: update_only`)
|
||||
console.log(` - Dependencies: preserve existing`)
|
||||
|
||||
userSelections = {
|
||||
scope: 'tasks_only',
|
||||
modules: 'all_affected',
|
||||
task_changes: 'update_only',
|
||||
dependency_changes: false
|
||||
}
|
||||
// Proceed to Phase 3
|
||||
}
|
||||
```
|
||||
|
||||
#### Session Mode Questions
|
||||
|
||||
**Q1: Modification Scope**
|
||||
@@ -266,29 +228,10 @@ interface ImpactAnalysis {
|
||||
**Step 3.3: User Confirmation**
|
||||
|
||||
```javascript
|
||||
// Parse --yes flag
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
|
||||
if (autoYes) {
|
||||
// Auto mode: Auto-confirm execution
|
||||
console.log(`[--yes] Auto-confirming replan execution`)
|
||||
userConfirmation = '确认执行'
|
||||
// Proceed to Phase 4
|
||||
} else {
|
||||
// Interactive mode: Ask user
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "修改计划已生成，请确认操作:",
|
||||
header: "Confirm",
|
||||
options: [
|
||||
{ label: "确认执行", description: "开始应用所有修改" },
|
||||
{ label: "调整计划", description: "重新回答问题调整范围" },
|
||||
{ label: "取消操作", description: "放弃本次重规划" }
|
||||
],
|
||||
multiSelect: false
|
||||
}]
|
||||
})
|
||||
}
|
||||
Options:
|
||||
- 确认执行: 开始应用所有修改
|
||||
- 调整计划: 重新回答问题调整范围
|
||||
- 取消操作: 放弃本次重规划
|
||||
```
|
||||
|
||||
**Output**: Modification plan confirmed or adjusted
|
||||
|
||||
@@ -585,10 +585,6 @@ TodoWrite({
|
||||
- Mark completed immediately after each group finishes
|
||||
- Update parent phase status when all child items complete
|
||||
|
||||
## Post-Completion Expansion
|
||||
|
||||
完成后询问用户是否扩展为issue(test/enhance/refactor/doc)，选中项调用 `/issue:new "{summary} - {dimension}"`
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Trust AI Planning**: Planning agent's grouping and execution strategy are based on dependency analysis
|
||||
@@ -605,4 +601,6 @@ Use `ccw view` to open the workflow dashboard in browser:
|
||||
|
||||
```bash
|
||||
ccw view
|
||||
```
|
||||
```
|
||||
|
||||
|
||||
|
||||
@@ -391,7 +391,6 @@ done
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
run_in_background=false,
|
||||
description=`Execute ${dimension} review analysis via Deep Scan`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
@@ -409,8 +408,6 @@ Task(
|
||||
2. Get target files: Read resolved_files from review-state.json
|
||||
3. Validate file access: bash(ls -la ${targetFiles.join(' ')})
|
||||
4. Execute: cat ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
|
||||
5. Read: .workflow/project-tech.json (technology stack and architecture context)
|
||||
6. Read: .workflow/project-guidelines.json (user-defined constraints and conventions to validate against)
|
||||
|
||||
## Review Context
|
||||
- Review Type: module (independent)
|
||||
@@ -479,7 +476,6 @@ Task(
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
run_in_background=false,
|
||||
description=`Deep-dive analysis for critical finding: ${findingTitle} via Dependency Map + Deep Scan`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
@@ -513,8 +509,6 @@ Task(
|
||||
3. Identify related code: bash(grep -r "import.*${basename(file)}" ${projectDir}/src --include="*.ts")
|
||||
4. Read test files: bash(find ${projectDir}/tests -name "*${basename(file, '.ts')}*" -type f)
|
||||
5. Execute: cat ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
|
||||
6. Read: .workflow/project-tech.json (technology stack and architecture context)
|
||||
7. Read: .workflow/project-guidelines.json (user-defined constraints for remediation compliance)
|
||||
|
||||
## CLI Configuration
|
||||
- Tool Priority: gemini → qwen → codex
|
||||
|
||||
@@ -401,7 +401,6 @@ git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
run_in_background=false,
|
||||
description=`Execute ${dimension} review analysis via Deep Scan`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
@@ -420,8 +419,6 @@ Task(
|
||||
3. Get changed files: bash(cd ${workflowDir} && git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u)
|
||||
4. Read review state: ${reviewStateJsonPath}
|
||||
5. Execute: cat ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
|
||||
6. Read: .workflow/project-tech.json (technology stack and architecture context)
|
||||
7. Read: .workflow/project-guidelines.json (user-defined constraints and conventions to validate against)
|
||||
|
||||
## Session Context
|
||||
- Session ID: ${sessionId}
|
||||
@@ -490,7 +487,6 @@ Task(
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
run_in_background=false,
|
||||
description=`Deep-dive analysis for critical finding: ${findingTitle} via Dependency Map + Deep Scan`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
@@ -524,8 +520,6 @@ Task(
|
||||
3. Identify related code: bash(grep -r "import.*${basename(file)}" ${workflowDir}/src --include="*.ts")
|
||||
4. Read test files: bash(find ${workflowDir}/tests -name "*${basename(file, '.ts')}*" -type f)
|
||||
5. Execute: cat ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
|
||||
6. Read: .workflow/project-tech.json (technology stack and architecture context)
|
||||
7. Read: .workflow/project-guidelines.json (user-defined constraints for remediation compliance)
|
||||
|
||||
## CLI Configuration
|
||||
- Tool Priority: gemini → qwen → codex
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: review
|
||||
description: Post-implementation review with specialized types (security/architecture/action-items/quality) using analysis agents and Gemini
|
||||
argument-hint: "[--type=security|architecture|action-items|quality] [--archived] [optional: session-id]"
|
||||
argument-hint: "[--type=security|architecture|action-items|quality] [optional: session-id]"
|
||||
---
|
||||
|
||||
## Command Overview: /workflow:review
|
||||
@@ -34,17 +34,15 @@ argument-hint: "[--type=security|architecture|action-items|quality] [--archived]
|
||||
```
|
||||
Input Parsing:
|
||||
├─ Parse --type flag (default: quality)
|
||||
├─ Parse --archived flag (search in archives)
|
||||
└─ Parse session-id argument (optional)
|
||||
|
||||
Step 1: Session Resolution
|
||||
└─ Decision:
|
||||
├─ session-id provided + --archived → Search .workflow/archives/
|
||||
├─ session-id provided → Search .workflow/active/ first, then archives
|
||||
├─ session-id provided → Use provided session
|
||||
└─ Not provided → Auto-detect from .workflow/active/
|
||||
|
||||
Step 2: Validation
|
||||
├─ Check session directory exists (active or archived)
|
||||
├─ Check session directory exists
|
||||
└─ Check for completed implementation (.summaries/IMPL-*.md exists)
|
||||
|
||||
Step 3: Type Check
|
||||
@@ -70,29 +68,21 @@ Step 5: Generate Report
|
||||
#!/bin/bash
|
||||
# Optional specialized review for completed implementation
|
||||
|
||||
# Step 1: Session ID resolution and location detection
|
||||
# Step 1: Session ID resolution
|
||||
if [ -n "$SESSION_ARG" ]; then
|
||||
sessionId="$SESSION_ARG"
|
||||
else
|
||||
sessionId=$(find .workflow/active/ -name "WFS-*" -type d | head -1 | xargs basename)
|
||||
fi
|
||||
|
||||
# Step 2: Resolve session path (active or archived)
|
||||
# Priority: --archived flag → active → archives
|
||||
if [ -n "$ARCHIVED_FLAG" ]; then
|
||||
sessionPath=".workflow/archives/${sessionId}"
|
||||
elif [ -d ".workflow/active/${sessionId}" ]; then
|
||||
sessionPath=".workflow/active/${sessionId}"
|
||||
elif [ -d ".workflow/archives/${sessionId}" ]; then
|
||||
sessionPath=".workflow/archives/${sessionId}"
|
||||
echo "Note: Session found in archives, running review on archived session"
|
||||
else
|
||||
echo "Session ${sessionId} not found in active or archives"
|
||||
# Step 2: Validation
|
||||
if [ ! -d ".workflow/active/${sessionId}" ]; then
|
||||
echo "Session ${sessionId} not found"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check for completed tasks
|
||||
if [ ! -d "${sessionPath}/.summaries" ] || [ -z "$(find ${sessionPath}/.summaries/ -name "IMPL-*.md" -type f 2>/dev/null)" ]; then
|
||||
if [ ! -d ".workflow/active/${sessionId}/.summaries" ] || [ -z "$(find .workflow/active/${sessionId}/.summaries/ -name "IMPL-*.md" -type f 2>/dev/null)" ]; then
|
||||
echo "No completed implementation found. Complete implementation first"
|
||||
exit 1
|
||||
fi
|
||||
@@ -122,18 +112,14 @@ After bash validation, the model takes control to:
|
||||
|
||||
1. **Load Context**: Read completed task summaries and changed files
|
||||
```bash
|
||||
# Load implementation summaries (iterate through .summaries/ directory)
|
||||
for summary in ${sessionPath}/.summaries/*.md; do
|
||||
cat "$summary"
|
||||
done
|
||||
# Load implementation summaries
|
||||
cat .workflow/active/${sessionId}/.summaries/IMPL-*.md
|
||||
|
||||
# Load test results (if available)
|
||||
for test_summary in ${sessionPath}/.summaries/TEST-FIX-*.md 2>/dev/null; do
|
||||
cat "$test_summary"
|
||||
done
|
||||
cat .workflow/active/${sessionId}/.summaries/TEST-FIX-*.md 2>/dev/null
|
||||
|
||||
# Get changed files
|
||||
git log --since="$(cat ${sessionPath}/workflow-session.json | jq -r .created_at)" --name-only --pretty=format: | sort -u
|
||||
git log --since="$(cat .workflow/active/${sessionId}/workflow-session.json | jq -r .created_at)" --name-only --pretty=format: | sort -u
|
||||
```
|
||||
|
||||
2. **Perform Specialized Review**: Based on `review_type`
|
||||
@@ -146,56 +132,54 @@ After bash validation, the model takes control to:
|
||||
```
|
||||
- Use Gemini for security analysis:
|
||||
```bash
|
||||
ccw cli -p "
|
||||
cd .workflow/active/${sessionId} && gemini -p "
|
||||
PURPOSE: Security audit of completed implementation
|
||||
TASK: Review code for security vulnerabilities, insecure patterns, auth/authz issues
|
||||
CONTEXT: @.summaries/IMPL-*.md,../.. @../../project-tech.json @../../project-guidelines.json
|
||||
CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
|
||||
EXPECTED: Security findings report with severity levels
|
||||
RULES: Focus on OWASP Top 10, authentication, authorization, data validation, injection risks
|
||||
" --tool gemini --mode write --cd ${sessionPath}
|
||||
" --approval-mode yolo
|
||||
```
|
||||
|
||||
**Architecture Review** (`--type=architecture`):
|
||||
- Use Qwen for architecture analysis:
|
||||
```bash
|
||||
ccw cli -p "
|
||||
cd .workflow/active/${sessionId} && qwen -p "
|
||||
PURPOSE: Architecture compliance review
|
||||
TASK: Evaluate adherence to architectural patterns, identify technical debt, review design decisions
|
||||
CONTEXT: @.summaries/IMPL-*.md,../.. @../../project-tech.json @../../project-guidelines.json
|
||||
CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
|
||||
EXPECTED: Architecture assessment with recommendations
|
||||
RULES: Check for patterns, separation of concerns, modularity, scalability
|
||||
" --tool qwen --mode write --cd ${sessionPath}
|
||||
" --approval-mode yolo
|
||||
```
|
||||
|
||||
**Quality Review** (`--type=quality`):
|
||||
- Use Gemini for code quality:
|
||||
```bash
|
||||
ccw cli -p "
|
||||
cd .workflow/active/${sessionId} && gemini -p "
|
||||
PURPOSE: Code quality and best practices review
|
||||
TASK: Assess code readability, maintainability, adherence to best practices
|
||||
CONTEXT: @.summaries/IMPL-*.md,../.. @../../project-tech.json @../../project-guidelines.json
|
||||
CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
|
||||
EXPECTED: Quality assessment with improvement suggestions
|
||||
RULES: Check for code smells, duplication, complexity, naming conventions
|
||||
" --tool gemini --mode write --cd ${sessionPath}
|
||||
" --approval-mode yolo
|
||||
```
|
||||
|
||||
**Action Items Review** (`--type=action-items`):
|
||||
- Verify all requirements and acceptance criteria met:
|
||||
```bash
|
||||
# Load task requirements and acceptance criteria
|
||||
for task_file in ${sessionPath}/.task/*.json; do
|
||||
cat "$task_file" | jq -r '
|
||||
"Task: " + .id + "\n" +
|
||||
"Requirements: " + (.context.requirements | join(", ")) + "\n" +
|
||||
"Acceptance: " + (.context.acceptance | join(", "))
|
||||
'
|
||||
done
|
||||
find .workflow/active/${sessionId}/.task -name "IMPL-*.json" -exec jq -r '
|
||||
"Task: " + .id + "\n" +
|
||||
"Requirements: " + (.context.requirements | join(", ")) + "\n" +
|
||||
"Acceptance: " + (.context.acceptance | join(", "))
|
||||
' {} \;
|
||||
|
||||
# Check implementation summaries against requirements
|
||||
ccw cli -p "
|
||||
cd .workflow/active/${sessionId} && gemini -p "
|
||||
PURPOSE: Verify all requirements and acceptance criteria are met
|
||||
TASK: Cross-check implementation summaries against original requirements
|
||||
CONTEXT: @.task/IMPL-*.json,.summaries/IMPL-*.md,../.. @../../project-tech.json @../../project-guidelines.json
|
||||
CONTEXT: @.task/IMPL-*.json,.summaries/IMPL-*.md,../.. @../../CLAUDE.md
|
||||
EXPECTED:
|
||||
- Requirements coverage matrix
|
||||
- Acceptance criteria verification
|
||||
@@ -206,7 +190,7 @@ After bash validation, the model takes control to:
|
||||
- Verify all acceptance criteria are met
|
||||
- Flag any incomplete or missing action items
|
||||
- Assess deployment readiness
|
||||
" --tool gemini --mode write --cd ${sessionPath}
|
||||
" --approval-mode yolo
|
||||
```
|
||||
|
||||
|
||||
@@ -244,7 +228,7 @@ After bash validation, the model takes control to:
|
||||
4. **Output Files**:
|
||||
```bash
|
||||
# Save review report
|
||||
Write(${sessionPath}/REVIEW-${review_type}.md)
|
||||
Write(.workflow/active/${sessionId}/REVIEW-${review_type}.md)
|
||||
|
||||
# Update session metadata
|
||||
# (optional) Update workflow-session.json with review status
|
||||
@@ -271,12 +255,6 @@ After bash validation, the model takes control to:
|
||||
# Architecture review for specific session
|
||||
/workflow:review --type=architecture WFS-payment-integration
|
||||
|
||||
# Review an archived session (auto-detects if not in active)
|
||||
/workflow:review --type=security WFS-old-feature
|
||||
|
||||
# Explicitly review archived session
|
||||
/workflow:review --archived --type=quality WFS-completed-feature
|
||||
|
||||
# Documentation review
|
||||
/workflow:review --type=docs
|
||||
```
|
||||
@@ -286,7 +264,6 @@ After bash validation, the model takes control to:
|
||||
- **Simple Validation**: Check session exists and has completed tasks
|
||||
- **No Complex Orchestration**: Direct analysis, no multi-phase pipeline
|
||||
- **Specialized Reviews**: Different prompts and tools for different review types
|
||||
- **Archived Session Support**: Review archived sessions with `--archived` flag or auto-detection
|
||||
- **MCP Integration**: Fast code search for security and architecture patterns
|
||||
- **CLI Tool Integration**: Gemini for analysis, Qwen for architecture
|
||||
- **Structured Output**: Markdown reports with severity levels and action items
|
||||
@@ -312,11 +289,3 @@ Optional Review (when needed):
|
||||
- Regular development (tests are sufficient)
|
||||
- Simple bug fixes (test-fix-agent handles it)
|
||||
- Minor changes (update-memory-related is enough)
|
||||
|
||||
## Post-Review Action
|
||||
|
||||
After review completion, prompt user:
|
||||
```
|
||||
Review complete. Would you like to complete and archive this session?
|
||||
→ Run /workflow:session:complete to archive with lessons learned
|
||||
```
|
||||
|
||||
@@ -1,203 +1,500 @@
|
||||
---
|
||||
name: complete
|
||||
description: Mark active workflow session as complete, archive with lessons learned, update manifest, remove active flag
|
||||
argument-hint: "[-y|--yes] [--detailed]"
|
||||
examples:
|
||||
- /workflow:session:complete
|
||||
- /workflow:session:complete --yes
|
||||
- /workflow:session:complete --detailed
|
||||
---
|
||||
|
||||
# Complete Workflow Session (/workflow:session:complete)
|
||||
|
||||
Mark the currently active workflow session as complete, archive it, and update manifests.
|
||||
|
||||
## Pre-defined Commands
|
||||
## Overview
|
||||
Mark the currently active workflow session as complete, analyze it for lessons learned, move it to the archive directory, and remove the active flag marker.
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
# Phase 1: Find active session
|
||||
SESSION_PATH=$(find .workflow/active/ -maxdepth 1 -name "WFS-*" -type d | head -1)
|
||||
SESSION_ID=$(basename "$SESSION_PATH")
|
||||
|
||||
# Phase 3: Move to archive
|
||||
mkdir -p .workflow/archives/
|
||||
mv .workflow/active/$SESSION_ID .workflow/archives/$SESSION_ID
|
||||
|
||||
# Cleanup marker
|
||||
rm -f .workflow/archives/$SESSION_ID/.archiving
|
||||
/workflow:session:complete # Complete current active session
|
||||
/workflow:session:complete --detailed # Show detailed completion summary
|
||||
```
|
||||
|
||||
## Key Files to Read
|
||||
## Implementation Flow
|
||||
|
||||
**For manifest.json generation**, read ONLY these files:
|
||||
### Phase 1: Pre-Archival Preparation (Transactional Setup)
|
||||
|
||||
| File | Extract |
|
||||
|------|---------|
|
||||
| `$SESSION_PATH/workflow-session.json` | session_id, description, started_at, status |
|
||||
| `$SESSION_PATH/IMPL_PLAN.md` | title (first # heading), description (first paragraph) |
|
||||
| `$SESSION_PATH/.tasks/*.json` | count files |
|
||||
| `$SESSION_PATH/.summaries/*.md` | count files |
|
||||
| `$SESSION_PATH/.review/dimensions/*.json` | count + findings summary (optional) |
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Phase 1: Find Session (2 commands)
|
||||
**Purpose**: Find active session, create archiving marker to prevent concurrent operations. Session remains in active location for agent processing.
|
||||
|
||||
#### Step 1.1: Find Active Session and Get Name
|
||||
```bash
|
||||
# 1. Find and extract session
|
||||
SESSION_PATH=$(find .workflow/active/ -maxdepth 1 -name "WFS-*" -type d | head -1)
|
||||
SESSION_ID=$(basename "$SESSION_PATH")
|
||||
# Find active session directory
|
||||
bash(find .workflow/active/ -name "WFS-*" -type d | head -1)
|
||||
|
||||
# 2. Check/create archiving marker
|
||||
test -f "$SESSION_PATH/.archiving" && echo "RESUMING" || touch "$SESSION_PATH/.archiving"
|
||||
# Extract session name from directory path
|
||||
bash(basename .workflow/active/WFS-session-name)
|
||||
```
|
||||
**Output**: Session name `WFS-session-name`
|
||||
|
||||
#### Step 1.2: Check for Existing Archiving Marker (Resume Detection)
|
||||
```bash
|
||||
# Check if session is already being archived
|
||||
bash(test -f .workflow/active/WFS-session-name/.archiving && echo "RESUMING" || echo "NEW")
|
||||
```
|
||||
|
||||
**Output**: `SESSION_ID` = e.g., `WFS-auth-feature`
|
||||
**If RESUMING**:
|
||||
- Previous archival attempt was interrupted
|
||||
- Skip to Phase 2 to resume agent analysis
|
||||
|
||||
### Phase 2: Generate Manifest Entry (Read-only)
|
||||
**If NEW**:
|
||||
- Continue to Step 1.3
|
||||
|
||||
Read the key files above, then build this structure:
|
||||
#### Step 1.3: Create Archiving Marker
|
||||
```bash
|
||||
# Mark session as "archiving in progress"
|
||||
bash(touch .workflow/active/WFS-session-name/.archiving)
|
||||
```
|
||||
**Purpose**:
|
||||
- Prevents concurrent operations on this session
|
||||
- Enables recovery if archival fails
|
||||
- Session remains in `.workflow/active/` for agent analysis
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "<from workflow-session.json>",
|
||||
"description": "<from workflow-session.json>",
|
||||
"archived_at": "<current ISO timestamp>",
|
||||
"archive_path": ".workflow/archives/<SESSION_ID>",
|
||||
"metrics": {
|
||||
"duration_hours": "<(completed_at - started_at) / 3600000>",
|
||||
"tasks_completed": "<count .tasks/*.json>",
|
||||
"summaries_generated": "<count .summaries/*.md>",
|
||||
"review_metrics": {
|
||||
"dimensions_analyzed": "<count .review/dimensions/*.json>",
|
||||
"total_findings": "<sum from dimension JSONs>"
|
||||
}
|
||||
**Result**: Session still at `.workflow/active/WFS-session-name/` with `.archiving` marker
|
||||
|
||||
### Phase 2: Agent Analysis (In-Place Processing)
|
||||
|
||||
**Purpose**: Agent analyzes session WHILE STILL IN ACTIVE LOCATION. Generates metadata but does NOT move files or update manifest.
|
||||
|
||||
#### Agent Invocation
|
||||
|
||||
Invoke `universal-executor` agent to analyze session and prepare archive metadata.
|
||||
|
||||
**Agent Task**:
|
||||
```
|
||||
Task(
|
||||
subagent_type="universal-executor",
|
||||
description="Analyze session for archival",
|
||||
prompt=`
|
||||
Analyze workflow session for archival preparation. Session is STILL in active location.
|
||||
|
||||
## Context
|
||||
- Session: .workflow/active/WFS-session-name/
|
||||
- Status: Marked as archiving (.archiving marker present)
|
||||
- Location: Active sessions directory (NOT archived yet)
|
||||
|
||||
## Tasks
|
||||
|
||||
1. **Extract session data** from workflow-session.json
|
||||
- session_id, description/topic, started_at, completed_at, status
|
||||
- If status != "completed", update it with timestamp
|
||||
|
||||
2. **Count files**: tasks (.task/*.json) and summaries (.summaries/*.md)
|
||||
|
||||
3. **Extract review data** (if .review/ exists):
|
||||
- Count dimension results: .review/dimensions/*.json
|
||||
- Count deep-dive results: .review/iterations/*.json
|
||||
- Extract findings summary from dimension JSONs (total, critical, high, medium, low)
|
||||
- Check fix results if .review/fixes/ exists (fixed_count, failed_count)
|
||||
- Build review_metrics: {dimensions_analyzed, total_findings, severity_distribution, fix_success_rate}
|
||||
|
||||
4. **Generate lessons**: Use gemini with ~/.claude/workflows/cli-templates/prompts/archive/analysis-simple.txt
|
||||
- Return: {successes, challenges, watch_patterns}
|
||||
- If review data exists, include review-specific lessons (common issue patterns, effective fixes)
|
||||
|
||||
5. **Build archive entry**:
|
||||
- Calculate: duration_hours, success_rate, tags (3-5 keywords)
|
||||
- Construct complete JSON with session_id, description, archived_at, metrics, tags, lessons
|
||||
- Include archive_path: ".workflow/archives/WFS-session-name" (future location)
|
||||
- If review data exists, include review_metrics in metrics object
|
||||
|
||||
6. **Extract feature metadata** (for Phase 4):
|
||||
- Parse IMPL_PLAN.md for title (first # heading)
|
||||
- Extract description (first paragraph, max 200 chars)
|
||||
- Generate feature tags (3-5 keywords from content)
|
||||
|
||||
7. **Return result**: Complete metadata package for atomic commit
|
||||
{
|
||||
"status": "success",
|
||||
"session_id": "WFS-session-name",
|
||||
"archive_entry": {
|
||||
"session_id": "...",
|
||||
"description": "...",
|
||||
"archived_at": "...",
|
||||
"archive_path": ".workflow/archives/WFS-session-name",
|
||||
"metrics": {
|
||||
"duration_hours": 2.5,
|
||||
"tasks_completed": 5,
|
||||
"summaries_generated": 3,
|
||||
"review_metrics": { // Optional, only if .review/ exists
|
||||
"dimensions_analyzed": 4,
|
||||
"total_findings": 15,
|
||||
"severity_distribution": {"critical": 1, "high": 3, "medium": 8, "low": 3},
|
||||
"fix_success_rate": 0.87 // Optional, only if .review/fixes/ exists
|
||||
}
|
||||
},
|
||||
"tags": [...],
|
||||
"lessons": {...}
|
||||
},
|
||||
"feature_metadata": {
|
||||
"title": "...",
|
||||
"description": "...",
|
||||
"tags": [...]
|
||||
}
|
||||
}
|
||||
|
||||
## Important Constraints
|
||||
- DO NOT move or delete any files
|
||||
- DO NOT update manifest.json yet
|
||||
- Session remains in .workflow/active/ during analysis
|
||||
- Return complete metadata package for orchestrator to commit atomically
|
||||
|
||||
## Error Handling
|
||||
- On failure: return {"status": "error", "task": "...", "message": "..."}
|
||||
- Do NOT modify any files on error
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**Expected Output**:
|
||||
- Agent returns complete metadata package
|
||||
- Session remains in `.workflow/active/` with `.archiving` marker
|
||||
- No files moved or manifests updated yet
|
||||
|
||||
### Phase 3: Atomic Commit (Transactional File Operations)
|
||||
|
||||
**Purpose**: Atomically commit all changes. Only execute if Phase 2 succeeds.
|
||||
|
||||
#### Step 3.1: Create Archive Directory
|
||||
```bash
|
||||
bash(mkdir -p .workflow/archives/)
|
||||
```
|
||||
|
||||
#### Step 3.2: Move Session to Archive
|
||||
```bash
|
||||
bash(mv .workflow/active/WFS-session-name .workflow/archives/WFS-session-name)
|
||||
```
|
||||
**Result**: Session now at `.workflow/archives/WFS-session-name/`
|
||||
|
||||
#### Step 3.3: Update Manifest
|
||||
```bash
|
||||
# Read current manifest (or create empty array if not exists)
|
||||
bash(test -f .workflow/archives/manifest.json && cat .workflow/archives/manifest.json || echo "[]")
|
||||
```
|
||||
|
||||
**JSON Update Logic**:
|
||||
```javascript
|
||||
// Read agent result from Phase 2
|
||||
const agentResult = JSON.parse(agentOutput);
|
||||
const archiveEntry = agentResult.archive_entry;
|
||||
|
||||
// Read existing manifest
|
||||
let manifest = [];
|
||||
try {
|
||||
const manifestContent = Read('.workflow/archives/manifest.json');
|
||||
manifest = JSON.parse(manifestContent);
|
||||
} catch {
|
||||
manifest = []; // Initialize if not exists
|
||||
}
|
||||
|
||||
// Append new entry
|
||||
manifest.push(archiveEntry);
|
||||
|
||||
// Write back
|
||||
Write('.workflow/archives/manifest.json', JSON.stringify(manifest, null, 2));
|
||||
```
|
||||
|
||||
#### Step 3.4: Remove Archiving Marker
|
||||
```bash
|
||||
bash(rm .workflow/archives/WFS-session-name/.archiving)
|
||||
```
|
||||
**Result**: Clean archived session without temporary markers
|
||||
|
||||
**Output Confirmation**:
|
||||
```
|
||||
✓ Session "${sessionId}" archived successfully
|
||||
Location: .workflow/archives/WFS-session-name/
|
||||
Lessons: ${archiveEntry.lessons.successes.length} successes, ${archiveEntry.lessons.challenges.length} challenges
|
||||
Manifest: Updated with ${manifest.length} total sessions
|
||||
${reviewMetrics ? `Review: ${reviewMetrics.total_findings} findings across ${reviewMetrics.dimensions_analyzed} dimensions, ${Math.round(reviewMetrics.fix_success_rate * 100)}% fixed` : ''}
|
||||
```
|
||||
|
||||
### Phase 4: Update Project Feature Registry
|
||||
|
||||
**Purpose**: Record completed session as a project feature in `.workflow/project.json`.
|
||||
|
||||
**Execution**: Uses feature metadata from Phase 2 agent result to update project registry.
|
||||
|
||||
#### Step 4.1: Check Project State Exists
|
||||
```bash
|
||||
bash(test -f .workflow/project.json && echo "EXISTS" || echo "SKIP")
|
||||
```
|
||||
|
||||
**If SKIP**: Output warning and skip Phase 4
|
||||
```
|
||||
WARNING: No project.json found. Run /workflow:session:start to initialize.
|
||||
```
|
||||
|
||||
#### Step 4.2: Extract Feature Information from Agent Result
|
||||
|
||||
**Data Processing** (Uses Phase 2 agent output):
|
||||
```javascript
|
||||
// Extract feature metadata from agent result
|
||||
const agentResult = JSON.parse(agentOutput);
|
||||
const featureMeta = agentResult.feature_metadata;
|
||||
|
||||
// Data already prepared by agent:
|
||||
const title = featureMeta.title;
|
||||
const description = featureMeta.description;
|
||||
const tags = featureMeta.tags;
|
||||
|
||||
// Create feature ID (lowercase slug)
|
||||
const featureId = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 50);
|
||||
```
|
||||
|
||||
#### Step 4.3: Update project.json
|
||||
|
||||
```bash
|
||||
# Read current project state
|
||||
bash(cat .workflow/project.json)
|
||||
```
|
||||
|
||||
**JSON Update Logic**:
|
||||
```javascript
|
||||
// Read existing project.json (created by /workflow:init)
|
||||
// Note: overview field is managed by /workflow:init, not modified here
|
||||
const projectMeta = JSON.parse(Read('.workflow/project.json'));
|
||||
const currentTimestamp = new Date().toISOString();
|
||||
const currentDate = currentTimestamp.split('T')[0]; // YYYY-MM-DD
|
||||
|
||||
// Extract tags from IMPL_PLAN.md (simple keyword extraction)
|
||||
const tags = extractTags(planContent); // e.g., ["auth", "security"]
|
||||
|
||||
// Build feature object with complete metadata
|
||||
const newFeature = {
|
||||
id: featureId,
|
||||
title: title,
|
||||
description: description,
|
||||
status: "completed",
|
||||
tags: tags,
|
||||
timeline: {
|
||||
created_at: currentTimestamp,
|
||||
implemented_at: currentDate,
|
||||
updated_at: currentTimestamp
|
||||
},
|
||||
"tags": ["<3-5 keywords from IMPL_PLAN.md>"],
|
||||
"lessons": {
|
||||
"successes": ["<key wins>"],
|
||||
"challenges": ["<difficulties>"],
|
||||
"watch_patterns": ["<patterns to monitor>"]
|
||||
traceability: {
|
||||
session_id: sessionId,
|
||||
archive_path: archivePath, // e.g., ".workflow/archives/WFS-auth-system"
|
||||
commit_hash: getLatestCommitHash() || "" // Optional: git rev-parse HEAD
|
||||
},
|
||||
docs: [], // Placeholder for future doc links
|
||||
relations: [] // Placeholder for feature dependencies
|
||||
};
|
||||
|
||||
// Add new feature to array
|
||||
projectMeta.features.push(newFeature);
|
||||
|
||||
// Update statistics
|
||||
projectMeta.statistics.total_features = projectMeta.features.length;
|
||||
projectMeta.statistics.total_sessions += 1;
|
||||
projectMeta.statistics.last_updated = currentTimestamp;
|
||||
|
||||
// Write back
|
||||
Write('.workflow/project.json', JSON.stringify(projectMeta, null, 2));
|
||||
```
|
||||
|
||||
**Helper Functions**:
|
||||
```javascript
|
||||
// Extract tags from IMPL_PLAN.md content
|
||||
function extractTags(planContent) {
|
||||
const tags = [];
|
||||
|
||||
// Look for common keywords
|
||||
const keywords = {
|
||||
'auth': /authentication|login|oauth|jwt/i,
|
||||
'security': /security|encrypt|hash|token/i,
|
||||
'api': /api|endpoint|rest|graphql/i,
|
||||
'ui': /component|page|interface|frontend/i,
|
||||
'database': /database|schema|migration|sql/i,
|
||||
'test': /test|testing|spec|coverage/i
|
||||
};
|
||||
|
||||
for (const [tag, pattern] of Object.entries(keywords)) {
|
||||
if (pattern.test(planContent)) {
|
||||
tags.push(tag);
|
||||
}
|
||||
}
|
||||
|
||||
return tags.slice(0, 5); // Max 5 tags
|
||||
}
|
||||
|
||||
// Get latest git commit hash (optional)
|
||||
function getLatestCommitHash() {
|
||||
try {
|
||||
const result = Bash({
|
||||
command: "git rev-parse --short HEAD 2>/dev/null",
|
||||
description: "Get latest commit hash"
|
||||
});
|
||||
return result.trim();
|
||||
} catch {
|
||||
return "";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Lessons Generation**: Use gemini with `~/.claude/workflows/cli-templates/prompts/archive/analysis-simple.txt`
|
||||
#### Step 4.4: Output Confirmation
|
||||
|
||||
### Phase 3: Atomic Commit (4 commands)
|
||||
|
||||
```bash
|
||||
# 1. Create archive directory
|
||||
mkdir -p .workflow/archives/
|
||||
|
||||
# 2. Move session
|
||||
mv .workflow/active/$SESSION_ID .workflow/archives/$SESSION_ID
|
||||
|
||||
# 3. Update manifest.json (Read → Append → Write)
|
||||
# Read: .workflow/archives/manifest.json (or [])
|
||||
# Append: archive_entry from Phase 2
|
||||
# Write: updated JSON
|
||||
|
||||
# 4. Remove marker
|
||||
rm -f .workflow/archives/$SESSION_ID/.archiving
|
||||
```
|
||||
✓ Feature "${title}" added to project registry
|
||||
ID: ${featureId}
|
||||
Session: ${sessionId}
|
||||
Location: .workflow/project.json
|
||||
```
|
||||
|
||||
**Output**:
|
||||
```
|
||||
✓ Session "$SESSION_ID" archived successfully
|
||||
Location: .workflow/archives/$SESSION_ID/
|
||||
Manifest: Updated with N total sessions
|
||||
```
|
||||
**Error Handling**:
|
||||
- If project.json malformed: Output error, skip update
|
||||
- If feature_metadata missing from agent result: Skip Phase 4
|
||||
- If extraction fails: Use minimal defaults
|
||||
|
||||
### Phase 4: Update project-tech.json (Optional)
|
||||
|
||||
**Skip if**: `.workflow/project-tech.json` doesn't exist
|
||||
|
||||
```bash
|
||||
# Check
|
||||
test -f .workflow/project-tech.json || echo "SKIP"
|
||||
```
|
||||
|
||||
**If exists**, add feature entry:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "<slugified title>",
|
||||
"title": "<from IMPL_PLAN.md>",
|
||||
"status": "completed",
|
||||
"tags": ["<from Phase 2>"],
|
||||
"timeline": { "implemented_at": "<date>" },
|
||||
"traceability": { "session_id": "<SESSION_ID>", "archive_path": "<path>" }
|
||||
}
|
||||
```
|
||||
|
||||
**Output**:
|
||||
```
|
||||
✓ Feature added to project registry
|
||||
```
|
||||
|
||||
### Phase 5: Ask About Solidify (Always)
|
||||
|
||||
After successful archival, prompt user to capture learnings:
|
||||
|
||||
```javascript
|
||||
// Parse --yes flag
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
|
||||
if (autoYes) {
|
||||
// Auto mode: Skip solidify
|
||||
console.log(`[--yes] Auto-selecting: Skip solidify`)
|
||||
console.log(`Session archived successfully.`)
|
||||
// Done - no solidify
|
||||
} else {
|
||||
// Interactive mode: Ask user
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Would you like to solidify learnings from this session into project guidelines?",
|
||||
header: "Solidify",
|
||||
options: [
|
||||
{ label: "Yes, solidify now", description: "Extract learnings and update project-guidelines.json" },
|
||||
{ label: "Skip", description: "Archive complete, no learnings to capture" }
|
||||
],
|
||||
multiSelect: false
|
||||
}]
|
||||
})
|
||||
|
||||
// **If "Yes, solidify now"**: Execute `/workflow:session:solidify` with the archived session ID.
|
||||
}
|
||||
```
|
||||
|
||||
## Auto Mode Defaults
|
||||
|
||||
When `--yes` or `-y` flag is used:
|
||||
- **Solidify Learnings**: Auto-selected "Skip" (archive only, no solidify)
|
||||
|
||||
**Flag Parsing**:
|
||||
```javascript
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
```
|
||||
|
||||
**Output**:
|
||||
```
|
||||
Session archived successfully.
|
||||
→ Run /workflow:session:solidify to capture learnings (recommended)
|
||||
```
|
||||
**Phase 4 Total Commands**: 1 bash read + JSON manipulation
|
||||
|
||||
## Error Recovery
|
||||
|
||||
| Phase | Symptom | Recovery |
|
||||
|-------|---------|----------|
|
||||
| 1 | No active session | `No active session found` |
|
||||
| 2 | Analysis fails | Remove marker: `rm $SESSION_PATH/.archiving`, retry |
|
||||
| 3 | Move fails | Session safe in active/, fix issue, retry |
|
||||
| 3 | Manifest fails | Session in archives/, manually add entry, remove marker |
|
||||
### If Agent Fails (Phase 2)
|
||||
|
||||
## Quick Reference
|
||||
**Symptoms**:
|
||||
- Agent returns `{"status": "error", ...}`
|
||||
- Agent crashes or times out
|
||||
- Analysis incomplete
|
||||
|
||||
**Recovery Steps**:
|
||||
```bash
|
||||
# Session still in .workflow/active/WFS-session-name
|
||||
# Remove archiving marker
|
||||
bash(rm .workflow/active/WFS-session-name/.archiving)
|
||||
```
|
||||
Phase 1: find session → create .archiving marker
|
||||
Phase 2: read key files → build manifest entry (no writes)
|
||||
Phase 3: mkdir → mv → update manifest.json → rm marker
|
||||
Phase 4: update project-tech.json features array (optional)
|
||||
Phase 5: ask user → solidify learnings (optional)
|
||||
|
||||
**User Notification**:
|
||||
```
|
||||
ERROR: Session archival failed during analysis phase
|
||||
Reason: [error message from agent]
|
||||
Session remains active in: .workflow/active/WFS-session-name
|
||||
|
||||
Recovery:
|
||||
1. Fix any issues identified in error message
|
||||
2. Retry: /workflow:session:complete
|
||||
|
||||
Session state: SAFE (no changes committed)
|
||||
```
|
||||
|
||||
### If Move Fails (Phase 3)
|
||||
|
||||
**Symptoms**:
|
||||
- `mv` command fails
|
||||
- Permission denied
|
||||
- Disk full
|
||||
|
||||
**Recovery Steps**:
|
||||
```bash
|
||||
# Archiving marker still present
|
||||
# Session still in .workflow/active/ (move failed)
|
||||
# No manifest updated yet
|
||||
```
|
||||
|
||||
**User Notification**:
|
||||
```
|
||||
ERROR: Session archival failed during move operation
|
||||
Reason: [mv error message]
|
||||
Session remains in: .workflow/active/WFS-session-name
|
||||
|
||||
Recovery:
|
||||
1. Fix filesystem issues (permissions, disk space)
|
||||
2. Retry: /workflow:session:complete
|
||||
- System will detect .archiving marker
|
||||
- Will resume from Phase 2 (agent analysis)
|
||||
|
||||
Session state: SAFE (analysis complete, ready to retry move)
|
||||
```
|
||||
|
||||
### If Manifest Update Fails (Phase 3)
|
||||
|
||||
**Symptoms**:
|
||||
- JSON parsing error
|
||||
- Write permission denied
|
||||
- Session moved but manifest not updated
|
||||
|
||||
**Recovery Steps**:
|
||||
```bash
|
||||
# Session moved to .workflow/archives/WFS-session-name
|
||||
# Manifest NOT updated
|
||||
# Archiving marker still present in archived location
|
||||
```
|
||||
|
||||
**User Notification**:
|
||||
```
|
||||
ERROR: Session archived but manifest update failed
|
||||
Reason: [error message]
|
||||
Session location: .workflow/archives/WFS-session-name
|
||||
|
||||
Recovery:
|
||||
1. Fix manifest.json issues (syntax, permissions)
|
||||
2. Manual manifest update:
|
||||
- Add archive entry from agent output
|
||||
- Remove .archiving marker: rm .workflow/archives/WFS-session-name/.archiving
|
||||
|
||||
Session state: PARTIALLY COMPLETE (session archived, manifest needs update)
|
||||
```
|
||||
|
||||
## Workflow Execution Strategy
|
||||
|
||||
### Transactional Four-Phase Approach
|
||||
|
||||
**Phase 1: Pre-Archival Preparation** (Marker creation)
|
||||
- Find active session and extract name
|
||||
- Check for existing `.archiving` marker (resume detection)
|
||||
- Create `.archiving` marker if new
|
||||
- **No data processing** - just state tracking
|
||||
- **Total**: 2-3 bash commands (find + marker check/create)
|
||||
|
||||
**Phase 2: Agent Analysis** (Read-only data processing)
|
||||
- Extract all session data from active location
|
||||
- Count tasks and summaries
|
||||
- Extract review data if .review/ exists (dimension results, findings, fix results)
|
||||
- Generate lessons learned analysis (including review-specific lessons if applicable)
|
||||
- Extract feature metadata from IMPL_PLAN.md
|
||||
- Build complete archive + feature metadata package (with review_metrics if applicable)
|
||||
- **No file modifications** - pure analysis
|
||||
- **Total**: 1 agent invocation
|
||||
|
||||
**Phase 3: Atomic Commit** (Transactional file operations)
|
||||
- Create archive directory
|
||||
- Move session to archive location
|
||||
- Update manifest.json with archive entry
|
||||
- Remove `.archiving` marker
|
||||
- **All-or-nothing**: Either all succeed or session remains in safe state
|
||||
- **Total**: 4 bash commands + JSON manipulation
|
||||
|
||||
**Phase 4: Project Registry Update** (Optional feature tracking)
|
||||
- Check project.json exists
|
||||
- Use feature metadata from Phase 2 agent result
|
||||
- Build feature object with complete traceability
|
||||
- Update project statistics
|
||||
- **Independent**: Can fail without affecting archival
|
||||
- **Total**: 1 bash read + JSON manipulation
|
||||
|
||||
### Transactional Guarantees
|
||||
|
||||
**State Consistency**:
|
||||
- Session NEVER in inconsistent state
|
||||
- `.archiving` marker enables safe resume
|
||||
- Agent failure leaves session in recoverable state
|
||||
- Move/manifest operations grouped in Phase 3
|
||||
|
||||
**Failure Isolation**:
|
||||
- Phase 1 failure: No changes made
|
||||
- Phase 2 failure: Session still active, can retry
|
||||
- Phase 3 failure: Clear error state, manual recovery documented
|
||||
- Phase 4 failure: Does not affect archival success
|
||||
|
||||
**Resume Capability**:
|
||||
- Detect interrupted archival via `.archiving` marker
|
||||
- Resume from Phase 2 (skip marker creation)
|
||||
- Idempotent operations (safe to retry)
|
||||
|
||||
|
||||
|
||||
@@ -1,303 +0,0 @@
|
||||
---
|
||||
name: solidify
|
||||
description: Crystallize session learnings and user-defined constraints into permanent project guidelines
|
||||
argument-hint: "[-y|--yes] [--type <convention|constraint|learning>] [--category <category>] \"rule or insight\""
|
||||
examples:
|
||||
- /workflow:session:solidify "Use functional components for all React code" --type convention
|
||||
- /workflow:session:solidify -y "No direct DB access from controllers" --type constraint --category architecture
|
||||
- /workflow:session:solidify "Cache invalidation requires event sourcing" --type learning --category architecture
|
||||
- /workflow:session:solidify --interactive
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-categorize and add guideline without confirmation.
|
||||
|
||||
# Session Solidify Command (/workflow:session:solidify)
|
||||
|
||||
## Overview
|
||||
|
||||
Crystallizes ephemeral session context (insights, decisions, constraints) into permanent project guidelines stored in `.workflow/project-guidelines.json`. This ensures valuable learnings persist across sessions and inform future planning.
|
||||
|
||||
## Use Cases
|
||||
|
||||
1. **During Session**: Capture important decisions as they're made
|
||||
2. **After Session**: Reflect on lessons learned before archiving
|
||||
3. **Proactive**: Add team conventions or architectural rules
|
||||
|
||||
## Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `rule` | string | ✅ (unless --interactive) | The rule, convention, or insight to solidify |
|
||||
| `--type` | enum | ❌ | Type: `convention`, `constraint`, `learning` (default: auto-detect) |
|
||||
| `--category` | string | ❌ | Category for organization (see categories below) |
|
||||
| `--interactive` | flag | ❌ | Launch guided wizard for adding rules |
|
||||
|
||||
### Type Categories
|
||||
|
||||
**convention** → Coding style preferences (goes to `conventions` section)
|
||||
- Subcategories: `coding_style`, `naming_patterns`, `file_structure`, `documentation`
|
||||
|
||||
**constraint** → Hard rules that must not be violated (goes to `constraints` section)
|
||||
- Subcategories: `architecture`, `tech_stack`, `performance`, `security`
|
||||
|
||||
**learning** → Session-specific insights (goes to `learnings` array)
|
||||
- Subcategories: `architecture`, `performance`, `security`, `testing`, `process`, `other`
|
||||
|
||||
## Execution Process
|
||||
|
||||
```
|
||||
Input Parsing:
|
||||
├─ Parse: rule text (required unless --interactive)
|
||||
├─ Parse: --type (convention|constraint|learning)
|
||||
├─ Parse: --category (subcategory)
|
||||
└─ Parse: --interactive (flag)
|
||||
|
||||
Step 1: Ensure Guidelines File Exists
|
||||
└─ If not exists → Create with empty structure
|
||||
|
||||
Step 2: Auto-detect Type (if not specified)
|
||||
└─ Analyze rule text for keywords
|
||||
|
||||
Step 3: Validate and Format Entry
|
||||
└─ Build entry object based on type
|
||||
|
||||
Step 4: Update Guidelines File
|
||||
└─ Add entry to appropriate section
|
||||
|
||||
Step 5: Display Confirmation
|
||||
└─ Show what was added and where
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
### Step 1: Ensure Guidelines File Exists
|
||||
|
||||
```bash
|
||||
bash(test -f .workflow/project-guidelines.json && echo "EXISTS" || echo "NOT_FOUND")
|
||||
```
|
||||
|
||||
**If NOT_FOUND**, create scaffold:
|
||||
|
||||
```javascript
|
||||
const scaffold = {
|
||||
conventions: {
|
||||
coding_style: [],
|
||||
naming_patterns: [],
|
||||
file_structure: [],
|
||||
documentation: []
|
||||
},
|
||||
constraints: {
|
||||
architecture: [],
|
||||
tech_stack: [],
|
||||
performance: [],
|
||||
security: []
|
||||
},
|
||||
quality_rules: [],
|
||||
learnings: [],
|
||||
_metadata: {
|
||||
created_at: new Date().toISOString(),
|
||||
version: "1.0.0"
|
||||
}
|
||||
};
|
||||
|
||||
Write('.workflow/project-guidelines.json', JSON.stringify(scaffold, null, 2));
|
||||
```
|
||||
|
||||
### Step 2: Auto-detect Type (if not specified)
|
||||
|
||||
```javascript
|
||||
function detectType(ruleText) {
|
||||
const text = ruleText.toLowerCase();
|
||||
|
||||
// Constraint indicators
|
||||
if (/\b(no|never|must not|forbidden|prohibited|always must)\b/.test(text)) {
|
||||
return 'constraint';
|
||||
}
|
||||
|
||||
// Learning indicators
|
||||
if (/\b(learned|discovered|realized|found that|turns out)\b/.test(text)) {
|
||||
return 'learning';
|
||||
}
|
||||
|
||||
// Default to convention
|
||||
return 'convention';
|
||||
}
|
||||
|
||||
function detectCategory(ruleText, type) {
|
||||
const text = ruleText.toLowerCase();
|
||||
|
||||
if (type === 'constraint' || type === 'learning') {
|
||||
if (/\b(architecture|layer|module|dependency|circular)\b/.test(text)) return 'architecture';
|
||||
if (/\b(security|auth|permission|sanitize|xss|sql)\b/.test(text)) return 'security';
|
||||
if (/\b(performance|cache|lazy|async|sync|slow)\b/.test(text)) return 'performance';
|
||||
if (/\b(test|coverage|mock|stub)\b/.test(text)) return 'testing';
|
||||
}
|
||||
|
||||
if (type === 'convention') {
|
||||
if (/\b(name|naming|prefix|suffix|camel|pascal)\b/.test(text)) return 'naming_patterns';
|
||||
if (/\b(file|folder|directory|structure|organize)\b/.test(text)) return 'file_structure';
|
||||
if (/\b(doc|comment|jsdoc|readme)\b/.test(text)) return 'documentation';
|
||||
return 'coding_style';
|
||||
}
|
||||
|
||||
return type === 'constraint' ? 'tech_stack' : 'other';
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Build Entry
|
||||
|
||||
```javascript
|
||||
function buildEntry(rule, type, category, sessionId) {
|
||||
if (type === 'learning') {
|
||||
return {
|
||||
date: new Date().toISOString().split('T')[0],
|
||||
session_id: sessionId || null,
|
||||
insight: rule,
|
||||
category: category,
|
||||
context: null
|
||||
};
|
||||
}
|
||||
|
||||
// For conventions and constraints, just return the rule string
|
||||
return rule;
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Update Guidelines File
|
||||
|
||||
```javascript
|
||||
const guidelines = JSON.parse(Read('.workflow/project-guidelines.json'));
|
||||
|
||||
if (type === 'convention') {
|
||||
if (!guidelines.conventions[category]) {
|
||||
guidelines.conventions[category] = [];
|
||||
}
|
||||
if (!guidelines.conventions[category].includes(rule)) {
|
||||
guidelines.conventions[category].push(rule);
|
||||
}
|
||||
} else if (type === 'constraint') {
|
||||
if (!guidelines.constraints[category]) {
|
||||
guidelines.constraints[category] = [];
|
||||
}
|
||||
if (!guidelines.constraints[category].includes(rule)) {
|
||||
guidelines.constraints[category].push(rule);
|
||||
}
|
||||
} else if (type === 'learning') {
|
||||
guidelines.learnings.push(buildEntry(rule, type, category, sessionId));
|
||||
}
|
||||
|
||||
guidelines._metadata.updated_at = new Date().toISOString();
|
||||
guidelines._metadata.last_solidified_by = sessionId;
|
||||
|
||||
Write('.workflow/project-guidelines.json', JSON.stringify(guidelines, null, 2));
|
||||
```
|
||||
|
||||
### Step 5: Display Confirmation
|
||||
|
||||
```
|
||||
✓ Guideline solidified
|
||||
|
||||
Type: ${type}
|
||||
Category: ${category}
|
||||
Rule: "${rule}"
|
||||
|
||||
Location: .workflow/project-guidelines.json → ${type}s.${category}
|
||||
|
||||
Total ${type}s in ${category}: ${count}
|
||||
```
|
||||
|
||||
## Interactive Mode
|
||||
|
||||
When `--interactive` flag is provided:
|
||||
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "What type of guideline are you adding?",
|
||||
header: "Type",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Convention", description: "Coding style preference (e.g., use functional components)" },
|
||||
{ label: "Constraint", description: "Hard rule that must not be violated (e.g., no direct DB access)" },
|
||||
{ label: "Learning", description: "Insight from this session (e.g., cache invalidation needs events)" }
|
||||
]
|
||||
}
|
||||
]
|
||||
});
|
||||
|
||||
// Follow-up based on type selection...
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Add a Convention
|
||||
```bash
|
||||
/workflow:session:solidify "Use async/await instead of callbacks" --type convention --category coding_style
|
||||
```
|
||||
|
||||
Result in `project-guidelines.json`:
|
||||
```json
|
||||
{
|
||||
"conventions": {
|
||||
"coding_style": ["Use async/await instead of callbacks"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Add an Architectural Constraint
|
||||
```bash
|
||||
/workflow:session:solidify "No direct DB access from controllers" --type constraint --category architecture
|
||||
```
|
||||
|
||||
Result:
|
||||
```json
|
||||
{
|
||||
"constraints": {
|
||||
"architecture": ["No direct DB access from controllers"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Capture a Session Learning
|
||||
```bash
|
||||
/workflow:session:solidify "Cache invalidation requires event sourcing for consistency" --type learning
|
||||
```
|
||||
|
||||
Result:
|
||||
```json
|
||||
{
|
||||
"learnings": [
|
||||
{
|
||||
"date": "2024-12-28",
|
||||
"session_id": "WFS-auth-feature",
|
||||
"insight": "Cache invalidation requires event sourcing for consistency",
|
||||
"category": "architecture"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Integration with Planning
|
||||
|
||||
The `project-guidelines.json` is consumed by:
|
||||
|
||||
1. **`/workflow:tools:context-gather`**: Loads guidelines into context-package.json
|
||||
2. **`/workflow:plan`**: Passes guidelines to task generation agent
|
||||
3. **`task-generate-agent`**: Includes guidelines as "CRITICAL CONSTRAINTS" in system prompt
|
||||
|
||||
This ensures all future planning respects solidified rules without users needing to re-state them.
|
||||
|
||||
## Error Handling
|
||||
|
||||
- **Duplicate Rule**: Warn and skip if exact rule already exists
|
||||
- **Invalid Category**: Suggest valid categories for the type
|
||||
- **File Corruption**: Backup existing file before modification
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/workflow:session:start` - Start a session (may prompt for solidify at end)
|
||||
- `/workflow:session:complete` - Complete session (prompts for learnings to solidify)
|
||||
- `/workflow:init` - Creates project-guidelines.json scaffold if missing
|
||||
@@ -16,7 +16,7 @@ examples:
|
||||
Manages workflow sessions with three operation modes: discovery (manual), auto (intelligent), and force-new.
|
||||
|
||||
**Dual Responsibility**:
|
||||
1. **Project-level initialization** (first-time only): Creates `.workflow/project-tech.json` for feature registry
|
||||
1. **Project-level initialization** (first-time only): Creates `.workflow/project.json` for feature registry
|
||||
2. **Session-level initialization** (always): Creates session directory structure
|
||||
|
||||
## Session Types
|
||||
@@ -38,29 +38,26 @@ ERROR: Invalid session type. Valid types: workflow, review, tdd, test, docs
|
||||
|
||||
## Step 0: Initialize Project State (First-time Only)
|
||||
|
||||
**Executed before all modes** - Ensures project-level state files exist by calling `/workflow:init`.
|
||||
**Executed before all modes** - Ensures project-level state file exists by calling `/workflow:init`.
|
||||
|
||||
### Check and Initialize
|
||||
```bash
|
||||
# Check if project state exists (both files required)
|
||||
bash(test -f .workflow/project-tech.json && echo "TECH_EXISTS" || echo "TECH_NOT_FOUND")
|
||||
bash(test -f .workflow/project-guidelines.json && echo "GUIDELINES_EXISTS" || echo "GUIDELINES_NOT_FOUND")
|
||||
# Check if project state exists
|
||||
bash(test -f .workflow/project.json && echo "EXISTS" || echo "NOT_FOUND")
|
||||
```
|
||||
|
||||
**If either NOT_FOUND**, delegate to `/workflow:init`:
|
||||
**If NOT_FOUND**, delegate to `/workflow:init`:
|
||||
```javascript
|
||||
// Call workflow:init for intelligent project analysis
|
||||
SlashCommand({command: "/workflow:init"});
|
||||
|
||||
// Wait for init completion
|
||||
// project-tech.json and project-guidelines.json will be created
|
||||
// project.json will be created with comprehensive project overview
|
||||
```
|
||||
|
||||
**Output**:
|
||||
- If BOTH_EXIST: `PROJECT_STATE: initialized`
|
||||
- If NOT_FOUND: Calls `/workflow:init` → creates:
|
||||
- `.workflow/project-tech.json` with full technical analysis
|
||||
- `.workflow/project-guidelines.json` with empty scaffold
|
||||
- If EXISTS: `PROJECT_STATE: initialized`
|
||||
- If NOT_FOUND: Calls `/workflow:init` → creates `.workflow/project.json` with full project analysis
|
||||
|
||||
**Note**: `/workflow:init` uses cli-explore-agent to build comprehensive project understanding (technology stack, architecture, key components). This step runs once per project. Subsequent executions skip initialization.
|
||||
|
||||
|
||||
@@ -9,77 +9,39 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
|
||||
|
||||
## Coordinator Role
|
||||
|
||||
**This command is a pure orchestrator**: Executes 6 slash commands in sequence, parse outputs, pass context, and ensure complete TDD workflow creation with Red-Green-Refactor task generation.
|
||||
**This command is a pure orchestrator**: Dispatches 6 slash commands in sequence, parse outputs, pass context, and ensure complete TDD workflow creation with Red-Green-Refactor task generation.
|
||||
|
||||
**CLI Tool Selection**: CLI tool usage is determined semantically from user's task description. Include "use Codex/Gemini/Qwen" in your request for CLI execution.
|
||||
|
||||
**Task Attachment Model**:
|
||||
- SlashCommand execute **expands workflow** by attaching sub-tasks to current TodoWrite
|
||||
- When executing a sub-command (e.g., `/workflow:tools:test-context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
|
||||
- SlashCommand dispatch **expands workflow** by attaching sub-tasks to current TodoWrite
|
||||
- When dispatching a sub-command (e.g., `/workflow:tools:test-context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
|
||||
- Orchestrator **executes these attached tasks** sequentially
|
||||
- After completion, attached tasks are **collapsed** back to high-level phase summary
|
||||
- This is **task expansion**, not external delegation
|
||||
|
||||
**Auto-Continue Mechanism**:
|
||||
- TodoList tracks current phase status and dynamically manages task attachment/collapse
|
||||
- When each phase finishes executing, automatically execute next pending phase
|
||||
- When each phase finishes executing, automatically dispatch next pending phase
|
||||
- All phases run autonomously without user interaction
|
||||
- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Start Immediately**: First action is TodoWrite initialization, second action is execute Phase 1
|
||||
1. **Start Immediately**: First action is TodoWrite initialization, second action is dispatch Phase 1
|
||||
2. **No Preliminary Analysis**: Do not read files before Phase 1
|
||||
3. **Parse Every Output**: Extract required data for next phase
|
||||
4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
|
||||
4. **Auto-Continue via TodoList**: Check TodoList status to dispatch next pending phase automatically
|
||||
5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
|
||||
6. **TDD Context**: All descriptions include "TDD:" prefix
|
||||
7. **Task Attachment Model**: SlashCommand execute **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
|
||||
8. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
|
||||
|
||||
## TDD Compliance Requirements
|
||||
|
||||
### The Iron Law
|
||||
|
||||
```
|
||||
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
|
||||
```
|
||||
|
||||
**Enforcement Method**:
|
||||
- Phase 5: `implementation_approach` includes test-first steps (Red → Green → Refactor)
|
||||
- Green phase: Includes test-fix-cycle configuration (max 3 iterations)
|
||||
- Auto-revert: Triggered when max iterations reached without passing tests
|
||||
|
||||
**Verification**: Phase 6 validates Red-Green-Refactor structure in all generated tasks
|
||||
|
||||
### TDD Compliance Checkpoint
|
||||
|
||||
| Checkpoint | Validation Phase | Evidence Required |
|
||||
|------------|------------------|-------------------|
|
||||
| Test-first structure | Phase 5 | `implementation_approach` has 3 steps |
|
||||
| Red phase exists | Phase 6 | Step 1: `tdd_phase: "red"` |
|
||||
| Green phase with test-fix | Phase 6 | Step 2: `tdd_phase: "green"` + test-fix-cycle |
|
||||
| Refactor phase exists | Phase 6 | Step 3: `tdd_phase: "refactor"` |
|
||||
|
||||
### Core TDD Principles (from ref skills)
|
||||
|
||||
**Red Flags - STOP and Reassess**:
|
||||
- Code written before test
|
||||
- Test passes immediately (no Red phase witnessed)
|
||||
- Cannot explain why test should fail
|
||||
- "Just this once" rationalization
|
||||
- "Tests after achieve same goals" thinking
|
||||
|
||||
**Why Order Matters**:
|
||||
- Tests written after code pass immediately → proves nothing
|
||||
- Test-first forces edge case discovery before implementation
|
||||
- Tests-after verify what was built, not what's required
|
||||
7. **Task Attachment Model**: SlashCommand dispatch **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
|
||||
8. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and dispatch next phase
|
||||
|
||||
## 6-Phase Execution (with Conflict Resolution)
|
||||
|
||||
### Phase 1: Session Discovery
|
||||
|
||||
**Step 1.1: Execute** - Session discovery and initialization
|
||||
**Step 1.1: Dispatch** - Session discovery and initialization
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:session:start --type tdd --auto \"TDD: [structured-description]\"")
|
||||
@@ -104,7 +66,7 @@ TEST_FOCUS: [Test scenarios]
|
||||
|
||||
### Phase 2: Context Gathering
|
||||
|
||||
**Step 2.1: Execute** - Context gathering and analysis
|
||||
**Step 2.1: Dispatch** - Context gathering and analysis
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:tools:context-gather --session [sessionId] \"TDD: [structured-description]\"")
|
||||
@@ -130,7 +92,7 @@ SlashCommand(command="/workflow:tools:context-gather --session [sessionId] \"TDD
|
||||
|
||||
### Phase 3: Test Coverage Analysis
|
||||
|
||||
**Step 3.1: Execute** - Test coverage analysis and framework detection
|
||||
**Step 3.1: Dispatch** - Test coverage analysis and framework detection
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:tools:test-context-gather --session [sessionId]")
|
||||
@@ -146,9 +108,9 @@ SlashCommand(command="/workflow:tools:test-context-gather --session [sessionId]"
|
||||
|
||||
|
||||
|
||||
<!-- TodoWrite: When test-context-gather executed, INSERT 3 test-context-gather tasks -->
|
||||
<!-- TodoWrite: When test-context-gather dispatched, INSERT 3 test-context-gather tasks -->
|
||||
|
||||
**TodoWrite Update (Phase 3 SlashCommand executed - tasks attached)**:
|
||||
**TodoWrite Update (Phase 3 SlashCommand dispatched - tasks attached)**:
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
@@ -162,7 +124,7 @@ SlashCommand(command="/workflow:tools:test-context-gather --session [sessionId]"
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: SlashCommand execute **attaches** test-context-gather's 3 tasks. Orchestrator **executes** these tasks.
|
||||
**Note**: SlashCommand dispatch **attaches** test-context-gather's 3 tasks. Orchestrator **executes** these tasks.
|
||||
|
||||
**Next Action**: Tasks attached → **Execute Phase 3.1-3.3** sequentially
|
||||
|
||||
@@ -189,7 +151,7 @@ SlashCommand(command="/workflow:tools:test-context-gather --session [sessionId]"
|
||||
|
||||
**Trigger**: Only execute when context-package.json indicates conflict_risk is "medium" or "high"
|
||||
|
||||
**Step 4.1: Execute** - Conflict detection and resolution
|
||||
**Step 4.1: Dispatch** - Conflict detection and resolution
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId] --context [contextPath]")
|
||||
@@ -202,18 +164,18 @@ SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId]
|
||||
|
||||
**Parse Output**:
|
||||
- Extract: Execution status (success/skipped/failed)
|
||||
- Verify: conflict-resolution.json file path (if executed)
|
||||
- Verify: CONFLICT_RESOLUTION.md file path (if executed)
|
||||
|
||||
**Validation**:
|
||||
- File `.workflow/active/[sessionId]/.process/conflict-resolution.json` exists (if executed)
|
||||
- File `.workflow/active/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed)
|
||||
|
||||
**Skip Behavior**:
|
||||
- If conflict_risk is "none" or "low", skip directly to Phase 5
|
||||
- Display: "No significant conflicts detected, proceeding to TDD task generation"
|
||||
|
||||
<!-- TodoWrite: If conflict_risk ≥ medium, INSERT 3 conflict-resolution tasks when executed -->
|
||||
<!-- TodoWrite: If conflict_risk ≥ medium, INSERT 3 conflict-resolution tasks when dispatched -->
|
||||
|
||||
**TodoWrite Update (Phase 4 SlashCommand executed - tasks attached, if conflict_risk ≥ medium)**:
|
||||
**TodoWrite Update (Phase 4 SlashCommand dispatched - tasks attached, if conflict_risk ≥ medium)**:
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
@@ -221,14 +183,14 @@ SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId]
|
||||
{"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
|
||||
{"content": "Phase 4: Conflict Resolution", "status": "in_progress", "activeForm": "Executing conflict resolution"},
|
||||
{"content": " → Detect conflicts with CLI analysis", "status": "in_progress", "activeForm": "Detecting conflicts"},
|
||||
{"content": " → Log and analyze detected conflicts", "status": "pending", "activeForm": "Analyzing conflicts"},
|
||||
{"content": " → Present conflicts to user", "status": "pending", "activeForm": "Presenting conflicts"},
|
||||
{"content": " → Apply resolution strategies", "status": "pending", "activeForm": "Applying resolution strategies"},
|
||||
{"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"},
|
||||
{"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: SlashCommand execute **attaches** conflict-resolution's 3 tasks. Orchestrator **executes** these tasks.
|
||||
**Note**: SlashCommand dispatch **attaches** conflict-resolution's 3 tasks. Orchestrator **executes** these tasks.
|
||||
|
||||
**Next Action**: Tasks attached → **Execute Phase 4.1-4.3** sequentially
|
||||
|
||||
@@ -254,7 +216,7 @@ SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId]
|
||||
- Evaluate current context window usage and memory state
|
||||
- If memory usage is high (>110K tokens or approaching context limits):
|
||||
|
||||
**Step 4.5: Execute** - Memory compaction
|
||||
**Step 4.5: Dispatch** - Memory compaction
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/compact")
|
||||
@@ -268,19 +230,15 @@ SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId]
|
||||
|
||||
### Phase 5: TDD Task Generation
|
||||
|
||||
**Step 5.1: Execute** - TDD task generation via action-planning-agent with Phase 0 user configuration
|
||||
**Step 5.1: Dispatch** - TDD task generation via action-planning-agent
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:tools:task-generate-tdd --session [sessionId]")
|
||||
```
|
||||
|
||||
**Note**: Phase 0 now includes:
|
||||
- Supplementary materials collection (file paths or inline content)
|
||||
- Execution method preference (Agent/Hybrid/CLI)
|
||||
- CLI tool preference (Codex/Gemini/Qwen/Auto)
|
||||
- These preferences are passed to agent for task generation
|
||||
**Note**: CLI tool usage is determined semantically from user's task description.
|
||||
|
||||
**Parse**: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles), CLI execution IDs assigned
|
||||
**Parse**: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles)
|
||||
|
||||
**Validate**:
|
||||
- IMPL_PLAN.md exists (unified plan with TDD Implementation Tasks section)
|
||||
@@ -288,30 +246,14 @@ SlashCommand(command="/workflow:tools:task-generate-tdd --session [sessionId]")
|
||||
- TODO_LIST.md exists with internal TDD phase indicators
|
||||
- Each IMPL task includes:
|
||||
- `meta.tdd_workflow: true`
|
||||
- `meta.cli_execution_id: {session_id}-{task_id}`
|
||||
- `meta.cli_execution: { "strategy": "new|resume|fork|merge_fork", ... }`
|
||||
- `flow_control.implementation_approach` with exactly 3 steps (red/green/refactor)
|
||||
- `flow_control.implementation_approach` with 3 steps (red/green/refactor)
|
||||
- Green phase includes test-fix-cycle configuration
|
||||
- `context.focus_paths`: absolute or clear relative paths (enhanced with exploration critical_files)
|
||||
- `flow_control.pre_analysis`: includes exploration integration_points analysis
|
||||
- IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
|
||||
- User configuration applied:
|
||||
- If executionMethod == "cli" or "hybrid": command field added to steps
|
||||
- CLI tool preference reflected in execution guidance
|
||||
- Task count ≤18 (compliance with hard limit)
|
||||
- Task count ≤10 (compliance with task limit)
|
||||
|
||||
**Red Flag Detection** (Non-Blocking Warnings):
|
||||
- Task count >18: `⚠️ Task count exceeds hard limit - request re-scope`
|
||||
- Missing cli_execution_id: `⚠️ Task lacks CLI execution ID for resume support`
|
||||
- Missing test-fix-cycle: `⚠️ Green phase lacks auto-revert configuration`
|
||||
- Generic task names: `⚠️ Vague task names suggest unclear TDD cycles`
|
||||
- Missing focus_paths: `⚠️ Task lacks clear file scope for implementation`
|
||||
<!-- TodoWrite: When task-generate-tdd dispatched, INSERT 3 task-generate-tdd tasks -->
|
||||
|
||||
**Action**: Log warnings to `.workflow/active/[sessionId]/.process/tdd-warnings.log` (non-blocking)
|
||||
|
||||
<!-- TodoWrite: When task-generate-tdd executed, INSERT 3 task-generate-tdd tasks -->
|
||||
|
||||
**TodoWrite Update (Phase 5 SlashCommand executed - tasks attached)**:
|
||||
**TodoWrite Update (Phase 5 SlashCommand dispatched - tasks attached)**:
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
@@ -325,7 +267,7 @@ SlashCommand(command="/workflow:tools:task-generate-tdd --session [sessionId]")
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: SlashCommand execute **attaches** task-generate-tdd's 3 tasks. Orchestrator **executes** these tasks. Each generated IMPL task will contain internal Red-Green-Refactor cycle.
|
||||
**Note**: SlashCommand dispatch **attaches** task-generate-tdd's 3 tasks. Orchestrator **executes** these tasks. Each generated IMPL task will contain internal Red-Green-Refactor cycle.
|
||||
|
||||
**Next Action**: Tasks attached → **Execute Phase 5.1-5.3** sequentially
|
||||
|
||||
@@ -351,59 +293,14 @@ SlashCommand(command="/workflow:tools:task-generate-tdd --session [sessionId]")
|
||||
1. Each task contains complete TDD workflow (Red-Green-Refactor internally)
|
||||
2. Task structure validation:
|
||||
- `meta.tdd_workflow: true` in all IMPL tasks
|
||||
- `meta.cli_execution_id` present (format: {session_id}-{task_id})
|
||||
- `meta.cli_execution` strategy assigned (new/resume/fork/merge_fork)
|
||||
- `flow_control.implementation_approach` has exactly 3 steps
|
||||
- Each step has correct `tdd_phase`: "red", "green", "refactor"
|
||||
- `context.focus_paths` are absolute or clear relative paths
|
||||
- `flow_control.pre_analysis` includes exploration integration analysis
|
||||
3. Dependency validation:
|
||||
- Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed
|
||||
- Complex features: IMPL-N.M depends_on ["IMPL-N.(M-1)"] for subtasks
|
||||
- CLI execution strategies correctly assigned based on dependency graph
|
||||
4. Agent assignment: All IMPL tasks use @code-developer
|
||||
5. Test-fix cycle: Green phase step includes test-fix-cycle logic with max_iterations
|
||||
6. Task count: Total tasks ≤18 (simple + subtasks hard limit)
|
||||
7. User configuration:
|
||||
- Execution method choice reflected in task structure
|
||||
- CLI tool preference documented in implementation guidance (if CLI selected)
|
||||
|
||||
**Red Flag Checklist** (from TDD best practices):
|
||||
- [ ] No tasks skip Red phase (`tdd_phase: "red"` exists in step 1)
|
||||
- [ ] Test files referenced in Red phase (explicit paths, not placeholders)
|
||||
- [ ] Green phase has test-fix-cycle with `max_iterations` configured
|
||||
- [ ] Refactor phase has clear completion criteria
|
||||
|
||||
**Non-Compliance Warning Format**:
|
||||
```
|
||||
⚠️ TDD Red Flag: [issue description]
|
||||
Task: [IMPL-N]
|
||||
Recommendation: [action to fix]
|
||||
```
|
||||
|
||||
**Evidence Gathering** (Before Completion Claims):
|
||||
|
||||
```bash
|
||||
# Verify session artifacts exist
|
||||
ls -la .workflow/active/[sessionId]/{IMPL_PLAN.md,TODO_LIST.md}
|
||||
ls -la .workflow/active/[sessionId]/.task/IMPL-*.json
|
||||
|
||||
# Count generated artifacts
|
||||
echo "IMPL tasks: $(ls .workflow/active/[sessionId]/.task/IMPL-*.json 2>/dev/null | wc -l)"
|
||||
|
||||
# Sample task structure verification (first task)
|
||||
jq '{id, tdd: .meta.tdd_workflow, cli_id: .meta.cli_execution_id, phases: [.flow_control.implementation_approach[].tdd_phase]}' \
|
||||
"$(ls .workflow/active/[sessionId]/.task/IMPL-*.json | head -1)"
|
||||
```
|
||||
|
||||
**Evidence Required Before Summary**:
|
||||
| Evidence Type | Verification Method | Pass Criteria |
|
||||
|---------------|---------------------|---------------|
|
||||
| File existence | `ls -la` artifacts | All files present |
|
||||
| Task count | Count IMPL-*.json | Count matches claims (≤18) |
|
||||
| TDD structure | jq sample extraction | Shows red/green/refactor + cli_execution_id |
|
||||
| CLI execution IDs | jq extraction | All tasks have cli_execution_id assigned |
|
||||
| Warning log | Check tdd-warnings.log | Logged (may be empty) |
|
||||
6. Task count: Total tasks ≤10 (simple + subtasks)
|
||||
|
||||
**Return Summary**:
|
||||
```
|
||||
@@ -415,7 +312,7 @@ Total tasks: [M] (1 task per simple feature + subtasks for complex features)
|
||||
Task breakdown:
|
||||
- Simple features: [K] tasks (IMPL-1 to IMPL-K)
|
||||
- Complex features: [L] features with [P] subtasks
|
||||
- Total task count: [M] (within 18-task hard limit)
|
||||
- Total task count: [M] (within 10-task limit)
|
||||
|
||||
Structure:
|
||||
- IMPL-1: {Feature 1 Name} (Internal: Red → Green → Refactor)
|
||||
@@ -429,31 +326,19 @@ Plans generated:
|
||||
- Unified Implementation Plan: .workflow/active/[sessionId]/IMPL_PLAN.md
|
||||
(includes TDD Implementation Tasks section with workflow_type: "tdd")
|
||||
- Task List: .workflow/active/[sessionId]/TODO_LIST.md
|
||||
(with internal TDD phase indicators and CLI execution strategies)
|
||||
- Task JSONs: .workflow/active/[sessionId]/.task/IMPL-*.json
|
||||
(with cli_execution_id and execution strategies for resume support)
|
||||
(with internal TDD phase indicators)
|
||||
|
||||
TDD Configuration:
|
||||
- Each task contains complete Red-Green-Refactor cycle
|
||||
- Green phase includes test-fix cycle (max 3 iterations)
|
||||
- Auto-revert on max iterations reached
|
||||
- CLI execution strategies: new/resume/fork/merge_fork based on dependency graph
|
||||
|
||||
User Configuration Applied:
|
||||
- Execution Method: [agent|hybrid|cli]
|
||||
- CLI Tool Preference: [codex|gemini|qwen|auto]
|
||||
- Supplementary Materials: [included|none]
|
||||
- Task generation follows cli-tools-usage.md guidelines
|
||||
|
||||
⚠️ ACTION REQUIRED: Before execution, ensure you understand WHY each Red phase test is expected to fail.
|
||||
This is crucial for valid TDD - if you don't know why the test fails, you can't verify it tests the right thing.
|
||||
|
||||
Recommended Next Steps:
|
||||
1. /workflow:plan-verify --session [sessionId] # Verify TDD plan quality and dependencies
|
||||
2. /workflow:execute --session [sessionId] # Start TDD execution with CLI strategies
|
||||
1. /workflow:action-plan-verify --session [sessionId] # Verify TDD plan quality and dependencies
|
||||
2. /workflow:execute --session [sessionId] # Start TDD execution
|
||||
3. /workflow:tdd-verify [sessionId] # Post-execution TDD compliance check
|
||||
|
||||
Quality Gate: Consider running /workflow:plan-verify to validate TDD task structure, dependencies, and CLI execution strategies
|
||||
Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task structure and dependencies
|
||||
```
|
||||
|
||||
## TodoWrite Pattern
|
||||
@@ -462,7 +347,7 @@ Quality Gate: Consider running /workflow:plan-verify to validate TDD task struct
|
||||
|
||||
### Key Principles
|
||||
|
||||
1. **Task Attachment** (when SlashCommand executed):
|
||||
1. **Task Attachment** (when SlashCommand dispatched):
|
||||
- Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
|
||||
- Example: `/workflow:tools:test-context-gather` attaches 3 sub-tasks (Phase 3.1, 3.2, 3.3)
|
||||
- First attached task marked as `in_progress`, others as `pending`
|
||||
@@ -479,7 +364,7 @@ Quality Gate: Consider running /workflow:plan-verify to validate TDD task struct
|
||||
- No user intervention required between phases
|
||||
- TodoWrite dynamically reflects current execution state
|
||||
|
||||
**Lifecycle Summary**: Initial pending tasks → Phase executed (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins (conditional Phase 4 if conflict_risk ≥ medium) → Repeat until all phases complete.
|
||||
**Lifecycle Summary**: Initial pending tasks → Phase dispatched (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins (conditional Phase 4 if conflict_risk ≥ medium) → Repeat until all phases complete.
|
||||
|
||||
### TDD-Specific Features
|
||||
|
||||
@@ -515,9 +400,9 @@ TDD Workflow Orchestrator
|
||||
│ IF conflict_risk ≥ medium:
|
||||
│ └─ /workflow:tools:conflict-resolution ← ATTACHED (3 tasks)
|
||||
│ ├─ Phase 4.1: Detect conflicts with CLI
|
||||
│ ├─ Phase 4.2: Log and analyze detected conflicts
|
||||
│ ├─ Phase 4.2: Present conflicts to user
|
||||
│ └─ Phase 4.3: Apply resolution strategies
|
||||
│ └─ Returns: conflict-resolution.json ← COLLAPSED
|
||||
│ └─ Returns: CONFLICT_RESOLUTION.md ← COLLAPSED
|
||||
│ ELSE:
|
||||
│ └─ Skip to Phase 5
|
||||
│
|
||||
@@ -531,7 +416,7 @@ TDD Workflow Orchestrator
|
||||
│
|
||||
└─ Phase 6: TDD Structure Validation
|
||||
└─ Internal validation + summary returned
|
||||
└─ Recommend: /workflow:plan-verify
|
||||
└─ Recommend: /workflow:action-plan-verify
|
||||
|
||||
Key Points:
|
||||
• ← ATTACHED: SlashCommand attaches sub-tasks to orchestrator TodoWrite
|
||||
@@ -554,36 +439,6 @@ Convert user input to TDD-structured format:
|
||||
- **Command failure**: Keep phase in_progress, report error
|
||||
- **TDD validation failure**: Report incomplete chains or wrong dependencies
|
||||
|
||||
### TDD Warning Patterns
|
||||
|
||||
| Pattern | Warning Message | Recommended Action |
|
||||
|---------|----------------|-------------------|
|
||||
| Task count >10 | High task count detected | Consider splitting into multiple sessions |
|
||||
| Missing test-fix-cycle | Green phase lacks auto-revert | Add `max_iterations: 3` to task config |
|
||||
| Red phase missing test path | Test file path not specified | Add explicit test file paths |
|
||||
| Generic task names | Vague names like "Add feature" | Use specific behavior descriptions |
|
||||
| No refactor criteria | Refactor phase lacks completion criteria | Define clear refactor scope |
|
||||
|
||||
### Non-Blocking Warning Policy
|
||||
|
||||
**All warnings are advisory** - they do not halt execution:
|
||||
1. Warnings logged to `.process/tdd-warnings.log`
|
||||
2. Summary displayed in Phase 6 output
|
||||
3. User decides whether to address before `/workflow:execute`
|
||||
|
||||
### Error Handling Quick Reference
|
||||
|
||||
| Error Type | Detection | Recovery Action |
|
||||
|------------|-----------|-----------------|
|
||||
| Parsing failure | Empty/malformed output | Retry once, then report |
|
||||
| Missing context-package | File read error | Re-run `/workflow:tools:context-gather` |
|
||||
| Invalid task JSON | jq parse error | Report malformed file path |
|
||||
| Task count exceeds 18 | Count validation ≥19 | Request re-scope, split into multiple sessions |
|
||||
| Missing cli_execution_id | All tasks lack ID | Regenerate tasks with phase 0 user config |
|
||||
| Test-context missing | File not found | Re-run `/workflow:tools:test-context-gather` |
|
||||
| Phase timeout | No response | Retry phase, check CLI connectivity |
|
||||
| CLI tool not available | Tool not in cli-tools.json | Fall back to alternative preferred tool |
|
||||
|
||||
## Related Commands
|
||||
|
||||
**Prerequisite Commands**:
|
||||
@@ -598,33 +453,8 @@ Convert user input to TDD-structured format:
|
||||
- `/workflow:tools:task-generate-tdd` - Phase 5: Generate TDD tasks (CLI tool usage determined semantically)
|
||||
|
||||
**Follow-up Commands**:
|
||||
- `/workflow:plan-verify` - Recommended: Verify TDD plan quality and structure before execution
|
||||
- `/workflow:action-plan-verify` - Recommended: Verify TDD plan quality and structure before execution
|
||||
- `/workflow:status` - Review TDD task breakdown
|
||||
- `/workflow:execute` - Begin TDD implementation
|
||||
- `/workflow:tdd-verify` - Post-execution: Verify TDD compliance and generate quality report
|
||||
|
||||
## Next Steps Decision Table
|
||||
|
||||
| Situation | Recommended Command | Purpose |
|
||||
|-----------|---------------------|---------|
|
||||
| First time planning | `/workflow:plan-verify` | Validate task structure before execution |
|
||||
| Warnings in tdd-warnings.log | Review log, refine tasks | Address Red Flags before proceeding |
|
||||
| High task count warning | Consider `/workflow:session:start` | Split into focused sub-sessions |
|
||||
| Ready to implement | `/workflow:execute` | Begin TDD Red-Green-Refactor cycles |
|
||||
| After implementation | `/workflow:tdd-verify` | Generate TDD compliance report |
|
||||
| Need to review tasks | `/workflow:status --session [id]` | Inspect current task breakdown |
|
||||
| Plan needs changes | `/task:replan` | Update task JSON with new requirements |
|
||||
|
||||
### TDD Workflow State Transitions
|
||||
|
||||
```
|
||||
/workflow:tdd-plan
|
||||
↓
|
||||
[Planning Complete] ──→ /workflow:plan-verify (recommended)
|
||||
↓
|
||||
[Verified/Ready] ─────→ /workflow:execute
|
||||
↓
|
||||
[Implementation] ─────→ /workflow:tdd-verify (post-execution)
|
||||
↓
|
||||
[Quality Report] ─────→ Done or iterate
|
||||
```
|
||||
|
||||
@@ -1,301 +1,200 @@
|
||||
---
|
||||
name: 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.
|
||||
argument-hint: "[optional: --session WFS-session-id]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
|
||||
description: Verify TDD workflow compliance against Red-Green-Refactor cycles, generate quality report with coverage analysis
|
||||
|
||||
argument-hint: "[optional: WFS-session-id]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini:*)
|
||||
---
|
||||
|
||||
# TDD Verification Command (/workflow:tdd-verify)
|
||||
|
||||
## Goal
|
||||
|
||||
Verify TDD workflow execution quality by validating Red-Green-Refactor cycle compliance, test coverage completeness, and task chain structure integrity. This command orchestrates multiple analysis phases and generates a comprehensive compliance report with quality gate recommendation.
|
||||
|
||||
**Output**: A structured Markdown report saved to `.workflow/active/WFS-{session}/TDD_COMPLIANCE_REPORT.md` containing:
|
||||
- Executive summary with compliance score and quality gate recommendation
|
||||
- Task chain validation (TEST → IMPL → REFACTOR structure)
|
||||
- Test coverage metrics (line, branch, function)
|
||||
- Red-Green-Refactor cycle verification
|
||||
- Best practices adherence assessment
|
||||
- Actionable improvement recommendations
|
||||
|
||||
## Operating Constraints
|
||||
|
||||
**ORCHESTRATOR MODE**:
|
||||
- This command coordinates multiple sub-commands (`/workflow:tools:tdd-coverage-analysis`, `ccw cli`)
|
||||
- MAY write output files: TDD_COMPLIANCE_REPORT.md (primary report), .process/*.json (intermediate artifacts)
|
||||
- MUST NOT modify source task files or implementation code
|
||||
- MUST NOT create or delete tasks in the workflow
|
||||
|
||||
**Quality Gate Authority**: The compliance report provides a binding recommendation (BLOCK_MERGE / REQUIRE_FIXES / PROCEED_WITH_CAVEATS / APPROVED) based on objective compliance criteria.
|
||||
|
||||
## Coordinator Role
|
||||
|
||||
**This command is a pure orchestrator**: Execute 4 phases to verify TDD workflow compliance, test coverage, and Red-Green-Refactor cycle execution.
|
||||
|
||||
## Core Responsibilities
|
||||
- Verify TDD task chain structure (TEST → IMPL → REFACTOR)
|
||||
- Analyze test coverage metrics
|
||||
- Validate TDD cycle execution quality
|
||||
- Generate compliance report with quality gate recommendation
|
||||
- Verify TDD task chain structure
|
||||
- Analyze test coverage
|
||||
- Validate TDD cycle execution
|
||||
- Generate compliance report
|
||||
|
||||
## Execution Process
|
||||
|
||||
```
|
||||
Input Parsing:
|
||||
└─ Decision (session argument):
|
||||
├─ --session provided → Use provided session
|
||||
└─ No session → Auto-detect active session
|
||||
├─ session-id provided → Use provided session
|
||||
└─ No session-id → Auto-detect active session
|
||||
|
||||
Phase 1: Session Discovery & Validation
|
||||
├─ Detect or validate session directory
|
||||
├─ Check required artifacts exist (.task/*.json, .summaries/*)
|
||||
└─ ERROR if invalid or incomplete
|
||||
Phase 1: Session Discovery
|
||||
├─ Validate session directory exists
|
||||
└─ TodoWrite: Mark phase 1 completed
|
||||
|
||||
Phase 2: Task Chain Structure Validation
|
||||
Phase 2: Task Chain Validation
|
||||
├─ Load all task JSONs from .task/
|
||||
├─ Validate TDD structure: TEST-N.M → IMPL-N.M → REFACTOR-N.M
|
||||
├─ Verify dependencies (depends_on)
|
||||
├─ Validate meta fields (tdd_phase, agent)
|
||||
└─ Extract chain validation data
|
||||
├─ Extract task IDs and group by feature
|
||||
├─ Validate TDD structure:
|
||||
│ ├─ TEST-N.M → IMPL-N.M → REFACTOR-N.M chain
|
||||
│ ├─ Dependency verification
|
||||
│ └─ Meta field validation (tdd_phase, agent)
|
||||
└─ TodoWrite: Mark phase 2 completed
|
||||
|
||||
Phase 3: Coverage & Cycle Analysis
|
||||
├─ Call: /workflow:tools:tdd-coverage-analysis
|
||||
├─ Parse: test-results.json, coverage-report.json, tdd-cycle-report.md
|
||||
└─ Extract coverage metrics and TDD cycle verification
|
||||
Phase 3: Test Execution Analysis
|
||||
└─ /workflow:tools:tdd-coverage-analysis
|
||||
├─ Coverage metrics extraction
|
||||
├─ TDD cycle verification
|
||||
└─ Compliance score calculation
|
||||
|
||||
Phase 4: Compliance Report Generation
|
||||
├─ Aggregate findings from Phases 1-3
|
||||
├─ Calculate compliance score (0-100)
|
||||
├─ Determine quality gate recommendation
|
||||
├─ Gemini analysis for comprehensive report
|
||||
├─ Generate TDD_COMPLIANCE_REPORT.md
|
||||
└─ Display summary to user
|
||||
└─ Return summary to user
|
||||
```
|
||||
|
||||
## 4-Phase Execution
|
||||
|
||||
### Phase 1: Session Discovery & Validation
|
||||
### Phase 1: Session Discovery
|
||||
**Auto-detect or use provided session**
|
||||
|
||||
**Step 1.1: Detect Session**
|
||||
```bash
|
||||
IF --session parameter provided:
|
||||
session_id = provided session
|
||||
ELSE:
|
||||
# Auto-detect active session
|
||||
active_sessions = bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null)
|
||||
IF active_sessions is empty:
|
||||
ERROR: "No active workflow session found. Use --session <session-id>"
|
||||
EXIT
|
||||
ELSE IF active_sessions has multiple entries:
|
||||
# Use most recently modified session
|
||||
session_id = bash(ls -td .workflow/active/WFS-*/ 2>/dev/null | head -1 | xargs basename)
|
||||
ELSE:
|
||||
session_id = basename(active_sessions[0])
|
||||
# If session-id provided
|
||||
sessionId = argument
|
||||
|
||||
# Derive paths
|
||||
session_dir = .workflow/active/WFS-{session_id}
|
||||
task_dir = session_dir/.task
|
||||
summaries_dir = session_dir/.summaries
|
||||
process_dir = session_dir/.process
|
||||
# Else auto-detect active session
|
||||
find .workflow/active/ -name "WFS-*" -type d | head -1 | sed 's/.*\///'
|
||||
```
|
||||
|
||||
**Step 1.2: Validate Required Artifacts**
|
||||
```bash
|
||||
# Check task files exist
|
||||
task_files = Glob(task_dir/*.json)
|
||||
IF task_files.count == 0:
|
||||
ERROR: "No task JSON files found. Run /workflow:tdd-plan first"
|
||||
EXIT
|
||||
**Extract**: sessionId
|
||||
|
||||
# Check summaries exist (optional but recommended for full analysis)
|
||||
summaries_exist = EXISTS(summaries_dir)
|
||||
IF NOT summaries_exist:
|
||||
WARNING: "No .summaries/ directory found. Some analysis may be limited."
|
||||
```
|
||||
**Validation**: Session directory exists
|
||||
|
||||
**Output**: session_id, session_dir, task_files list
|
||||
**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Task Chain Structure Validation
|
||||
### Phase 2: Task Chain Validation
|
||||
**Validate TDD structure using bash commands**
|
||||
|
||||
**Step 2.1: Load and Parse Task JSONs**
|
||||
```bash
|
||||
# Single-pass JSON extraction using jq
|
||||
validation_data = bash("""
|
||||
# Load all tasks and extract structured data
|
||||
cd '{session_dir}/.task'
|
||||
# Load all task JSONs
|
||||
find .workflow/active/{sessionId}/.task/ -name '*.json'
|
||||
|
||||
# Extract all task IDs
|
||||
task_ids=$(jq -r '.id' *.json 2>/dev/null | sort)
|
||||
# Extract task IDs
|
||||
find .workflow/active/{sessionId}/.task/ -name '*.json' -exec jq -r '.id' {} \;
|
||||
|
||||
# Extract dependencies for IMPL tasks
|
||||
impl_deps=$(jq -r 'select(.id | startswith("IMPL")) | .id + ":" + (.context.depends_on[]? // "none")' *.json 2>/dev/null)
|
||||
# Check dependencies
|
||||
find .workflow/active/{sessionId}/.task/ -name 'IMPL-*.json' -exec jq -r '.context.depends_on[]?' {} \;
|
||||
find .workflow/active/{sessionId}/.task/ -name 'REFACTOR-*.json' -exec jq -r '.context.depends_on[]?' {} \;
|
||||
|
||||
# Extract dependencies for REFACTOR tasks
|
||||
refactor_deps=$(jq -r 'select(.id | startswith("REFACTOR")) | .id + ":" + (.context.depends_on[]? // "none")' *.json 2>/dev/null)
|
||||
|
||||
# Extract meta fields
|
||||
meta_tdd=$(jq -r '.id + ":" + (.meta.tdd_phase // "missing")' *.json 2>/dev/null)
|
||||
meta_agent=$(jq -r '.id + ":" + (.meta.agent // "missing")' *.json 2>/dev/null)
|
||||
|
||||
# Output as JSON
|
||||
jq -n --arg ids "$task_ids" \\
|
||||
--arg impl "$impl_deps" \\
|
||||
--arg refactor "$refactor_deps" \\
|
||||
--arg tdd "$meta_tdd" \\
|
||||
--arg agent "$meta_agent" \\
|
||||
'{ids: $ids, impl_deps: $impl, refactor_deps: $refactor, tdd: $tdd, agent: $agent}'
|
||||
""")
|
||||
# Check meta fields
|
||||
find .workflow/active/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.tdd_phase' {} \;
|
||||
find .workflow/active/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.agent' {} \;
|
||||
```
|
||||
|
||||
**Step 2.2: Validate TDD Chain Structure**
|
||||
```
|
||||
Parse validation_data JSON and validate:
|
||||
**Validation**:
|
||||
- For each feature N, verify TEST-N.M → IMPL-N.M → REFACTOR-N.M exists
|
||||
- IMPL-N.M.context.depends_on includes TEST-N.M
|
||||
- REFACTOR-N.M.context.depends_on includes IMPL-N.M
|
||||
- TEST tasks have tdd_phase="red" and agent="@code-review-test-agent"
|
||||
- IMPL/REFACTOR tasks have tdd_phase="green"/"refactor" and agent="@code-developer"
|
||||
|
||||
For each feature N (extracted from task IDs):
|
||||
1. TEST-N.M exists?
|
||||
2. IMPL-N.M exists?
|
||||
3. REFACTOR-N.M exists? (optional but recommended)
|
||||
4. IMPL-N.M.context.depends_on contains TEST-N.M?
|
||||
5. REFACTOR-N.M.context.depends_on contains IMPL-N.M?
|
||||
6. TEST-N.M.meta.tdd_phase == "red"?
|
||||
7. TEST-N.M.meta.agent == "@code-review-test-agent"?
|
||||
8. IMPL-N.M.meta.tdd_phase == "green"?
|
||||
9. IMPL-N.M.meta.agent == "@code-developer"?
|
||||
10. REFACTOR-N.M.meta.tdd_phase == "refactor"?
|
||||
**Extract**: Chain validation report
|
||||
|
||||
Calculate:
|
||||
- chain_completeness_score = (complete_chains / total_chains) * 100
|
||||
- dependency_accuracy = (correct_deps / total_deps) * 100
|
||||
- meta_field_accuracy = (correct_meta / total_meta) * 100
|
||||
```
|
||||
|
||||
**Output**: chain_validation_report (JSON structure with validation results)
|
||||
**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Coverage & Cycle Analysis
|
||||
### Phase 3: Test Execution Analysis
|
||||
**Command**: `SlashCommand(command="/workflow:tools:tdd-coverage-analysis --session [sessionId]")`
|
||||
|
||||
**Step 3.1: Call Coverage Analysis Sub-command**
|
||||
```bash
|
||||
SlashCommand(command="/workflow:tools:tdd-coverage-analysis --session {session_id}")
|
||||
```
|
||||
**Input**: sessionId from Phase 1
|
||||
|
||||
**Step 3.2: Parse Output Files**
|
||||
```bash
|
||||
# Check required outputs exist
|
||||
IF NOT EXISTS(process_dir/test-results.json):
|
||||
WARNING: "test-results.json not found. Coverage analysis incomplete."
|
||||
coverage_data = null
|
||||
ELSE:
|
||||
coverage_data = Read(process_dir/test-results.json)
|
||||
**Parse Output**:
|
||||
- Coverage metrics (line, branch, function percentages)
|
||||
- TDD cycle verification results
|
||||
- Compliance score
|
||||
|
||||
IF NOT EXISTS(process_dir/coverage-report.json):
|
||||
WARNING: "coverage-report.json not found. Coverage metrics incomplete."
|
||||
metrics = null
|
||||
ELSE:
|
||||
metrics = Read(process_dir/coverage-report.json)
|
||||
**Validation**:
|
||||
- `.workflow/active/{sessionId}/.process/test-results.json` exists
|
||||
- `.workflow/active/{sessionId}/.process/coverage-report.json` exists
|
||||
- `.workflow/active/{sessionId}/.process/tdd-cycle-report.md` exists
|
||||
|
||||
IF NOT EXISTS(process_dir/tdd-cycle-report.md):
|
||||
WARNING: "tdd-cycle-report.md not found. Cycle validation incomplete."
|
||||
cycle_data = null
|
||||
ELSE:
|
||||
cycle_data = Read(process_dir/tdd-cycle-report.md)
|
||||
```
|
||||
|
||||
**Step 3.3: Extract Coverage Metrics**
|
||||
```
|
||||
If coverage_data exists:
|
||||
- line_coverage_percent
|
||||
- branch_coverage_percent
|
||||
- function_coverage_percent
|
||||
- uncovered_files (list)
|
||||
- uncovered_lines (map: file -> line ranges)
|
||||
|
||||
If cycle_data exists:
|
||||
- red_phase_compliance (tests failed initially?)
|
||||
- green_phase_compliance (tests pass after impl?)
|
||||
- refactor_phase_compliance (tests stay green during refactor?)
|
||||
- minimal_implementation_score (was impl minimal?)
|
||||
```
|
||||
|
||||
**Output**: coverage_analysis, cycle_analysis
|
||||
**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Compliance Report Generation
|
||||
**Gemini analysis for comprehensive TDD compliance report**
|
||||
|
||||
**Step 4.1: Calculate Compliance Score**
|
||||
```
|
||||
Base Score: 100 points
|
||||
|
||||
Deductions:
|
||||
Chain Structure:
|
||||
- Missing TEST task: -30 points per feature
|
||||
- Missing IMPL task: -30 points per feature
|
||||
- Missing REFACTOR task: -10 points per feature
|
||||
- Wrong dependency: -15 points per error
|
||||
- Wrong agent: -5 points per error
|
||||
- Wrong tdd_phase: -5 points per error
|
||||
|
||||
TDD Cycle Compliance:
|
||||
- Test didn't fail initially: -10 points per feature
|
||||
- Tests didn't pass after IMPL: -20 points per feature
|
||||
- Tests broke during REFACTOR: -15 points per feature
|
||||
- Over-engineered IMPL: -10 points per feature
|
||||
|
||||
Coverage Quality:
|
||||
- Line coverage < 80%: -5 points
|
||||
- Branch coverage < 70%: -5 points
|
||||
- Function coverage < 80%: -5 points
|
||||
- Critical paths uncovered: -10 points
|
||||
|
||||
Final Score: Max(0, Base Score - Total Deductions)
|
||||
```
|
||||
|
||||
**Step 4.2: Determine Quality Gate**
|
||||
```
|
||||
IF score >= 90 AND no_critical_violations:
|
||||
recommendation = "APPROVED"
|
||||
ELSE IF score >= 70 AND critical_violations == 0:
|
||||
recommendation = "PROCEED_WITH_CAVEATS"
|
||||
ELSE IF score >= 50:
|
||||
recommendation = "REQUIRE_FIXES"
|
||||
ELSE:
|
||||
recommendation = "BLOCK_MERGE"
|
||||
```
|
||||
|
||||
**Step 4.3: Generate Report**
|
||||
```bash
|
||||
report_content = Generate markdown report (see structure below)
|
||||
report_path = "{session_dir}/TDD_COMPLIANCE_REPORT.md"
|
||||
Write(report_path, report_content)
|
||||
cd project-root && gemini -p "
|
||||
PURPOSE: Generate TDD compliance report
|
||||
TASK: Analyze TDD workflow execution and generate quality report
|
||||
CONTEXT: @{.workflow/active/{sessionId}/.task/*.json,.workflow/active/{sessionId}/.summaries/*,.workflow/active/{sessionId}/.process/tdd-cycle-report.md}
|
||||
EXPECTED:
|
||||
- TDD compliance score (0-100)
|
||||
- Chain completeness verification
|
||||
- Test coverage analysis summary
|
||||
- Quality recommendations
|
||||
- Red-Green-Refactor cycle validation
|
||||
- Best practices adherence assessment
|
||||
RULES: Focus on TDD best practices and workflow adherence. Be specific about violations and improvements.
|
||||
" > .workflow/active/{sessionId}/TDD_COMPLIANCE_REPORT.md
|
||||
```
|
||||
|
||||
**Step 4.4: Display Summary to User**
|
||||
```bash
|
||||
echo "=== TDD Verification Complete ==="
|
||||
echo "Session: {session_id}"
|
||||
echo "Report: {report_path}"
|
||||
echo ""
|
||||
echo "Quality Gate: {recommendation}"
|
||||
echo "Compliance Score: {score}/100"
|
||||
echo ""
|
||||
echo "Chain Validation: {chain_completeness_score}%"
|
||||
echo "Line Coverage: {line_coverage}%"
|
||||
echo "Branch Coverage: {branch_coverage}%"
|
||||
echo ""
|
||||
echo "Next: Review full report for detailed findings"
|
||||
**Output**: TDD_COMPLIANCE_REPORT.md
|
||||
|
||||
**TodoWrite**: Mark phase 4 completed
|
||||
|
||||
**Return to User**:
|
||||
```
|
||||
TDD Verification Report - Session: {sessionId}
|
||||
|
||||
## Chain Validation
|
||||
[COMPLETE] Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1 (Complete)
|
||||
[COMPLETE] Feature 2: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1 (Complete)
|
||||
[INCOMPLETE] Feature 3: TEST-3.1 → IMPL-3.1 (Missing REFACTOR phase)
|
||||
|
||||
## Test Execution
|
||||
All TEST tasks produced failing tests
|
||||
All IMPL tasks made tests pass
|
||||
All REFACTOR tasks maintained green tests
|
||||
|
||||
## Coverage Metrics
|
||||
Line Coverage: {percentage}%
|
||||
Branch Coverage: {percentage}%
|
||||
Function Coverage: {percentage}%
|
||||
|
||||
## Compliance Score: {score}/100
|
||||
|
||||
Detailed report: .workflow/active/{sessionId}/TDD_COMPLIANCE_REPORT.md
|
||||
|
||||
Recommendations:
|
||||
- Complete missing REFACTOR-3.1 task
|
||||
- Consider additional edge case tests for Feature 2
|
||||
- Improve test failure message clarity in Feature 1
|
||||
```
|
||||
|
||||
## TodoWrite Pattern (Optional)
|
||||
|
||||
**Note**: As an orchestrator command, TodoWrite tracking is optional and primarily useful for long-running verification processes. For most cases, the 4-phase execution is fast enough that progress tracking adds noise without value.
|
||||
## TodoWrite Pattern
|
||||
|
||||
```javascript
|
||||
// Only use TodoWrite for complex multi-session verification
|
||||
// Skip for single-session verification
|
||||
// Initialize (before Phase 1)
|
||||
TodoWrite({todos: [
|
||||
{"content": "Identify target session", "status": "in_progress", "activeForm": "Identifying target session"},
|
||||
{"content": "Validate task chain structure", "status": "pending", "activeForm": "Validating task chain structure"},
|
||||
{"content": "Analyze test execution", "status": "pending", "activeForm": "Analyzing test execution"},
|
||||
{"content": "Generate compliance report", "status": "pending", "activeForm": "Generating compliance report"}
|
||||
]})
|
||||
|
||||
// After Phase 1
|
||||
TodoWrite({todos: [
|
||||
{"content": "Identify target session", "status": "completed", "activeForm": "Identifying target session"},
|
||||
{"content": "Validate task chain structure", "status": "in_progress", "activeForm": "Validating task chain structure"},
|
||||
{"content": "Analyze test execution", "status": "pending", "activeForm": "Analyzing test execution"},
|
||||
{"content": "Generate compliance report", "status": "pending", "activeForm": "Generating compliance report"}
|
||||
]})
|
||||
|
||||
// Continue pattern for Phase 2, 3, 4...
|
||||
```
|
||||
|
||||
## Validation Logic
|
||||
@@ -316,24 +215,27 @@ echo "Next: Review full report for detailed findings"
|
||||
5. Report incomplete or invalid chains
|
||||
```
|
||||
|
||||
### Quality Gate Criteria
|
||||
### Compliance Scoring
|
||||
```
|
||||
Base Score: 100 points
|
||||
|
||||
| Recommendation | Score Range | Critical Violations | Action |
|
||||
|----------------|-------------|---------------------|--------|
|
||||
| **APPROVED** | ≥90 | 0 | Safe to merge |
|
||||
| **PROCEED_WITH_CAVEATS** | ≥70 | 0 | Can proceed, address minor issues |
|
||||
| **REQUIRE_FIXES** | ≥50 | Any | Must fix before merge |
|
||||
| **BLOCK_MERGE** | <50 | Any | Block merge until resolved |
|
||||
Deductions:
|
||||
- Missing TEST task: -30 points per feature
|
||||
- Missing IMPL task: -30 points per feature
|
||||
- Missing REFACTOR task: -10 points per feature
|
||||
- Wrong dependency: -15 points per error
|
||||
- Wrong agent: -5 points per error
|
||||
- Wrong tdd_phase: -5 points per error
|
||||
- Test didn't fail initially: -10 points per feature
|
||||
- Tests didn't pass after IMPL: -20 points per feature
|
||||
- Tests broke during REFACTOR: -15 points per feature
|
||||
|
||||
**Critical Violations**:
|
||||
- Missing TEST or IMPL task for any feature
|
||||
- Tests didn't fail initially (Red phase violation)
|
||||
- Tests didn't pass after IMPL (Green phase violation)
|
||||
- Tests broke during REFACTOR (Refactor phase violation)
|
||||
Final Score: Max(0, Base Score - Deductions)
|
||||
```
|
||||
|
||||
## Output Files
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/
|
||||
.workflow/active/{session-id}/
|
||||
├── TDD_COMPLIANCE_REPORT.md # Comprehensive compliance report ⭐
|
||||
└── .process/
|
||||
├── test-results.json # From tdd-coverage-analysis
|
||||
@@ -346,14 +248,14 @@ echo "Next: Review full report for detailed findings"
|
||||
### Session Discovery Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| No active session | No WFS-* directories | Provide --session explicitly |
|
||||
| Multiple active sessions | Multiple WFS-* directories | Provide --session explicitly |
|
||||
| No active session | No WFS-* directories | Provide session-id explicitly |
|
||||
| Multiple active sessions | Multiple WFS-* directories | Provide session-id explicitly |
|
||||
| Session not found | Invalid session-id | Check available sessions |
|
||||
|
||||
### Validation Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Task files missing | Incomplete planning | Run /workflow:tdd-plan first |
|
||||
| Task files missing | Incomplete planning | Run tdd-plan first |
|
||||
| Invalid JSON | Corrupted task files | Regenerate tasks |
|
||||
| Missing summaries | Tasks not executed | Execute tasks before verify |
|
||||
|
||||
@@ -362,13 +264,13 @@ echo "Next: Review full report for detailed findings"
|
||||
|-------|-------|------------|
|
||||
| Coverage tool missing | No test framework | Configure testing first |
|
||||
| Tests fail to run | Code errors | Fix errors before verify |
|
||||
| Sub-command fails | tdd-coverage-analysis error | Check sub-command logs |
|
||||
| Gemini analysis fails | Token limit / API error | Retry or reduce context |
|
||||
|
||||
## Integration & Usage
|
||||
|
||||
### Command Chain
|
||||
- **Called After**: `/workflow:execute` (when TDD tasks completed)
|
||||
- **Calls**: `/workflow:tools:tdd-coverage-analysis`
|
||||
- **Calls**: `/workflow:tools:tdd-coverage-analysis`, Gemini CLI
|
||||
- **Related**: `/workflow:tdd-plan`, `/workflow:status`
|
||||
|
||||
### Basic Usage
|
||||
@@ -377,7 +279,7 @@ echo "Next: Review full report for detailed findings"
|
||||
/workflow:tdd-verify
|
||||
|
||||
# Specify session
|
||||
/workflow:tdd-verify --session WFS-auth
|
||||
/workflow:tdd-verify WFS-auth
|
||||
```
|
||||
|
||||
### When to Use
|
||||
@@ -392,125 +294,61 @@ echo "Next: Review full report for detailed findings"
|
||||
# TDD Compliance Report - {Session ID}
|
||||
|
||||
**Generated**: {timestamp}
|
||||
**Session**: WFS-{sessionId}
|
||||
**Session**: {sessionId}
|
||||
**Workflow Type**: TDD
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
### Quality Gate Decision
|
||||
|
||||
| Metric | Value | Status |
|
||||
|--------|-------|--------|
|
||||
| Compliance Score | {score}/100 | {status_emoji} |
|
||||
| Chain Completeness | {percentage}% | {status} |
|
||||
| Line Coverage | {percentage}% | {status} |
|
||||
| Branch Coverage | {percentage}% | {status} |
|
||||
| Function Coverage | {percentage}% | {status} |
|
||||
|
||||
### Recommendation
|
||||
|
||||
**{RECOMMENDATION}**
|
||||
|
||||
**Decision Rationale**:
|
||||
{brief explanation based on score and violations}
|
||||
|
||||
**Quality Gate Criteria**:
|
||||
- **APPROVED**: Score ≥90, no critical violations
|
||||
- **PROCEED_WITH_CAVEATS**: Score ≥70, no critical violations
|
||||
- **REQUIRE_FIXES**: Score ≥50 or critical violations exist
|
||||
- **BLOCK_MERGE**: Score <50
|
||||
|
||||
---
|
||||
Overall Compliance Score: {score}/100
|
||||
Status: {EXCELLENT | GOOD | NEEDS IMPROVEMENT | FAILED}
|
||||
|
||||
## Chain Analysis
|
||||
|
||||
### Feature 1: {Feature Name}
|
||||
**Status**: ✅ Complete
|
||||
**Status**: Complete
|
||||
**Chain**: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
|
||||
|
||||
| Phase | Task | Status | Details |
|
||||
|-------|------|--------|---------|
|
||||
| Red | TEST-1.1 | ✅ Pass | Test created and failed with clear message |
|
||||
| Green | IMPL-1.1 | ✅ Pass | Minimal implementation made test pass |
|
||||
| Refactor | REFACTOR-1.1 | ✅ Pass | Code improved, tests remained green |
|
||||
- **Red Phase**: Test created and failed with clear message
|
||||
- **Green Phase**: Minimal implementation made test pass
|
||||
- **Refactor Phase**: Code improved, tests remained green
|
||||
|
||||
### Feature 2: {Feature Name}
|
||||
**Status**: ⚠️ Incomplete
|
||||
**Status**: Incomplete
|
||||
**Chain**: TEST-2.1 → IMPL-2.1 (Missing REFACTOR-2.1)
|
||||
|
||||
| Phase | Task | Status | Details |
|
||||
|-------|------|--------|---------|
|
||||
| Red | TEST-2.1 | ✅ Pass | Test created and failed |
|
||||
| Green | IMPL-2.1 | ⚠️ Warning | Implementation seems over-engineered |
|
||||
| Refactor | REFACTOR-2.1 | ❌ Missing | Task not completed |
|
||||
- **Red Phase**: Test created and failed
|
||||
- **Green Phase**: Implementation seems over-engineered
|
||||
- **Refactor Phase**: Missing
|
||||
|
||||
**Issues**:
|
||||
- REFACTOR-2.1 task not completed (-10 points)
|
||||
- IMPL-2.1 implementation exceeded minimal scope (-10 points)
|
||||
- REFACTOR-2.1 task not completed
|
||||
- IMPL-2.1 implementation exceeded minimal scope
|
||||
|
||||
### Chain Validation Summary
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Total Features | {count} |
|
||||
| Complete Chains | {count} ({percent}%) |
|
||||
| Incomplete Chains | {count} |
|
||||
| Missing TEST | {count} |
|
||||
| Missing IMPL | {count} |
|
||||
| Missing REFACTOR | {count} |
|
||||
| Dependency Errors | {count} |
|
||||
| Meta Field Errors | {count} |
|
||||
|
||||
---
|
||||
[Repeat for all features]
|
||||
|
||||
## Test Coverage Analysis
|
||||
|
||||
### Coverage Metrics
|
||||
|
||||
| Metric | Coverage | Target | Status |
|
||||
|--------|----------|--------|--------|
|
||||
| Line Coverage | {percentage}% | ≥80% | {status} |
|
||||
| Branch Coverage | {percentage}% | ≥70% | {status} |
|
||||
| Function Coverage | {percentage}% | ≥80% | {status} |
|
||||
- Line Coverage: {percentage}% {status}
|
||||
- Branch Coverage: {percentage}% {status}
|
||||
- Function Coverage: {percentage}% {status}
|
||||
|
||||
### Coverage Gaps
|
||||
|
||||
| File | Lines | Issue | Priority |
|
||||
|------|-------|-------|----------|
|
||||
| src/auth/service.ts | 45-52 | Uncovered error handling | HIGH |
|
||||
| src/utils/parser.ts | 78-85 | Uncovered edge case | MEDIUM |
|
||||
|
||||
---
|
||||
- {file}:{lines} - Uncovered error handling
|
||||
- {file}:{lines} - Uncovered edge case
|
||||
|
||||
## TDD Cycle Validation
|
||||
|
||||
### Red Phase (Write Failing Test)
|
||||
- {N}/{total} features had failing tests initially ({percent}%)
|
||||
- ✅ Compliant features: {list}
|
||||
- ❌ Non-compliant features: {list}
|
||||
|
||||
**Violations**:
|
||||
- Feature 3: No evidence of initial test failure (-10 points)
|
||||
- {N}/{total} features had failing tests initially
|
||||
- Feature 3: No evidence of initial test failure
|
||||
|
||||
### Green Phase (Make Test Pass)
|
||||
- {N}/{total} implementations made tests pass ({percent}%)
|
||||
- ✅ Compliant features: {list}
|
||||
- ❌ Non-compliant features: {list}
|
||||
|
||||
**Violations**:
|
||||
- Feature 2: Implementation over-engineered (-10 points)
|
||||
- {N}/{total} implementations made tests pass
|
||||
- All implementations minimal and focused
|
||||
|
||||
### Refactor Phase (Improve Quality)
|
||||
- {N}/{total} features completed refactoring ({percent}%)
|
||||
- ✅ Compliant features: {list}
|
||||
- ❌ Non-compliant features: {list}
|
||||
|
||||
**Violations**:
|
||||
- Feature 2, 4: Refactoring step skipped (-20 points total)
|
||||
|
||||
---
|
||||
- {N}/{total} features completed refactoring
|
||||
- Feature 2, 4: Refactoring step skipped
|
||||
|
||||
## Best Practices Assessment
|
||||
|
||||
@@ -525,61 +363,24 @@ echo "Next: Review full report for detailed findings"
|
||||
- Missing refactoring steps
|
||||
- Test failure messages could be more descriptive
|
||||
|
||||
---
|
||||
|
||||
## Detailed Findings by Severity
|
||||
|
||||
### Critical Issues ({count})
|
||||
{List of critical issues with impact and remediation}
|
||||
|
||||
### High Priority Issues ({count})
|
||||
{List of high priority issues with impact and remediation}
|
||||
|
||||
### Medium Priority Issues ({count})
|
||||
{List of medium priority issues with impact and remediation}
|
||||
|
||||
### Low Priority Issues ({count})
|
||||
{List of low priority issues with impact and remediation}
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Required Fixes (Before Merge)
|
||||
### High Priority
|
||||
1. Complete missing REFACTOR tasks (Features 2, 4)
|
||||
2. Verify initial test failures for Feature 3
|
||||
3. Fix tests that broke during refactoring
|
||||
3. Simplify over-engineered implementations
|
||||
|
||||
### Recommended Improvements
|
||||
1. Simplify over-engineered implementations
|
||||
2. Add edge case tests for Features 1, 3
|
||||
3. Improve test failure message clarity
|
||||
4. Increase branch coverage to >85%
|
||||
### Medium Priority
|
||||
1. Add edge case tests for Features 1, 3
|
||||
2. Improve test failure message clarity
|
||||
3. Increase branch coverage to >85%
|
||||
|
||||
### Optional Enhancements
|
||||
### Low Priority
|
||||
1. Add more descriptive test names
|
||||
2. Consider parameterized tests for similar scenarios
|
||||
3. Document TDD process learnings
|
||||
|
||||
---
|
||||
|
||||
## Metrics Summary
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Total Features | {count} |
|
||||
| Complete Chains | {count} ({percent}%) |
|
||||
| Compliance Score | {score}/100 |
|
||||
| Critical Issues | {count} |
|
||||
| High Issues | {count} |
|
||||
| Medium Issues | {count} |
|
||||
| Low Issues | {count} |
|
||||
| Line Coverage | {percent}% |
|
||||
| Branch Coverage | {percent}% |
|
||||
| Function Coverage | {percent}% |
|
||||
|
||||
---
|
||||
|
||||
**Report End**
|
||||
## Conclusion
|
||||
{Summary of compliance status and next steps}
|
||||
```
|
||||
|
||||
|
||||
@@ -221,7 +221,6 @@ return "conservative";
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-planning-agent",
|
||||
run_in_background=false,
|
||||
description=`Analyze test failures (iteration ${N}) - ${strategy} strategy`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
@@ -272,7 +271,6 @@ Task(
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="test-fix-agent",
|
||||
run_in_background=false,
|
||||
description=`Execute ${task.meta.type}: ${task.title}`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
@@ -491,10 +489,6 @@ The orchestrator automatically creates git commits at key checkpoints to enable
|
||||
|
||||
**Note**: Final session completion creates additional commit with full summary.
|
||||
|
||||
## Post-Completion Expansion
|
||||
|
||||
完成后询问用户是否扩展为issue(test/enhance/refactor/doc)，选中项调用 `/issue:new "{summary} - {dimension}"`
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Default Settings Work**: 10 iterations sufficient for most cases
|
||||
|
||||
@@ -59,8 +59,8 @@ This command is a **pure planning coordinator**:
|
||||
- **All execution delegated to `/workflow:test-cycle-execute`**
|
||||
|
||||
**Task Attachment Model**:
|
||||
- SlashCommand execute **expands workflow** by attaching sub-tasks to current TodoWrite
|
||||
- When executing a sub-command (e.g., `/workflow:tools:test-context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
|
||||
- SlashCommand dispatch **expands workflow** by attaching sub-tasks to current TodoWrite
|
||||
- When dispatching a sub-command (e.g., `/workflow:tools:test-context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
|
||||
- Orchestrator **executes these attached tasks** sequentially
|
||||
- After completion, attached tasks are **collapsed** back to high-level phase summary
|
||||
- This is **task expansion**, not external delegation
|
||||
@@ -128,7 +128,7 @@ This command is a **pure planning coordinator**:
|
||||
|
||||
### Core Execution Rules
|
||||
|
||||
1. **Start Immediately**: First action is TodoWrite, second is execute Phase 1 session creation
|
||||
1. **Start Immediately**: First action is TodoWrite, second is dispatch Phase 1 session creation
|
||||
2. **No Preliminary Analysis**: Do not read files before Phase 1
|
||||
3. **Parse Every Output**: Extract required data from each phase for next phase
|
||||
4. **Sequential Execution**: Each phase depends on previous phase's output
|
||||
@@ -136,7 +136,7 @@ This command is a **pure planning coordinator**:
|
||||
6. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
|
||||
7. **Automatic Detection**: Mode auto-detected from input pattern
|
||||
8. **Semantic CLI Detection**: CLI tool usage determined from user's task description for Phase 4
|
||||
9. **Task Attachment Model**: SlashCommand execute **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
|
||||
9. **Task Attachment Model**: SlashCommand dispatch **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
|
||||
10. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
|
||||
|
||||
### 5-Phase Execution
|
||||
@@ -155,7 +155,7 @@ Read(".workflow/active/[sourceSessionId]/.process/context-package.json")
|
||||
// This preserves user's CLI tool preferences (e.g., "use Codex for fixes")
|
||||
```
|
||||
|
||||
**Step 1.1: Execute** - Create test workflow session with preserved intent
|
||||
**Step 1.1: Dispatch** - Create test workflow session with preserved intent
|
||||
|
||||
```javascript
|
||||
// Session Mode - Include original task description to enable semantic CLI selection
|
||||
@@ -187,7 +187,7 @@ SlashCommand(command="/workflow:session:start --type test --new \"Test generatio
|
||||
|
||||
#### Phase 2: Gather Test Context
|
||||
|
||||
**Step 2.1: Execute** - Gather test context via appropriate method
|
||||
**Step 2.1: Dispatch** - Gather test context via appropriate method
|
||||
|
||||
```javascript
|
||||
// Session Mode
|
||||
@@ -224,7 +224,7 @@ SlashCommand(command="/workflow:tools:context-gather --session [testSessionId] \
|
||||
|
||||
#### Phase 3: Test Generation Analysis
|
||||
|
||||
**Step 3.1: Execute** - Generate test requirements using Gemini
|
||||
**Step 3.1: Dispatch** - Generate test requirements using Gemini
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:tools:test-concept-enhanced --session [testSessionId] --context [contextPath]")
|
||||
@@ -284,7 +284,7 @@ For each targeted file/function, Gemini MUST generate:
|
||||
|
||||
#### Phase 4: Generate Test Tasks
|
||||
|
||||
**Step 4.1: Execute** - Generate test task JSONs
|
||||
**Step 4.1: Dispatch** - Generate test task JSONs
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:tools:test-task-generate --session [testSessionId]")
|
||||
@@ -381,7 +381,7 @@ CRITICAL - Next Steps:
|
||||
|
||||
#### Key Principles
|
||||
|
||||
1. **Task Attachment** (when SlashCommand executed):
|
||||
1. **Task Attachment** (when SlashCommand dispatched):
|
||||
- Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
|
||||
- Example - Phase 2 with sub-tasks:
|
||||
```json
|
||||
@@ -416,7 +416,7 @@ CRITICAL - Next Steps:
|
||||
- No user intervention required between phases
|
||||
- TodoWrite dynamically reflects current execution state
|
||||
|
||||
**Lifecycle Summary**: Initial pending tasks → Phase executed (tasks ATTACHED with mode-specific context gathering) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
|
||||
**Lifecycle Summary**: Initial pending tasks → Phase dispatched (tasks ATTACHED with mode-specific context gathering) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
|
||||
|
||||
#### Test-Fix-Gen Specific Features
|
||||
|
||||
|
||||
@@ -20,7 +20,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
|
||||
|
||||
**Task Attachment Model**:
|
||||
- SlashCommand dispatch **expands workflow** by attaching sub-tasks to current TodoWrite
|
||||
- When a sub-command is executed (e.g., `/workflow:tools:test-context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
|
||||
- When a sub-command is dispatched (e.g., `/workflow:tools:test-context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
|
||||
- Orchestrator **executes these attached tasks** sequentially
|
||||
- After completion, attached tasks are **collapsed** back to high-level phase summary
|
||||
- This is **task expansion**, not external delegation
|
||||
@@ -69,7 +69,7 @@ Read(".workflow/active/[sourceSessionId]/.process/context-package.json")
|
||||
// This preserves user's CLI tool preferences (e.g., "use Codex for fixes")
|
||||
```
|
||||
|
||||
**Step 1.1: Execute** - Create new test workflow session with preserved intent
|
||||
**Step 1.1: Dispatch** - Create new test workflow session with preserved intent
|
||||
|
||||
```javascript
|
||||
// Include original task description to enable semantic CLI selection
|
||||
@@ -104,7 +104,7 @@ SlashCommand(command="/workflow:session:start --new \"Test validation for [sourc
|
||||
|
||||
### Phase 2: Gather Test Context
|
||||
|
||||
**Step 2.1: Execute** - Gather test coverage context from source session
|
||||
**Step 2.1: Dispatch** - Gather test coverage context from source session
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:tools:test-context-gather --session [testSessionId]")
|
||||
@@ -130,9 +130,9 @@ SlashCommand(command="/workflow:tools:test-context-gather --session [testSession
|
||||
- Test framework detected
|
||||
- Test conventions documented
|
||||
|
||||
<!-- TodoWrite: When test-context-gather executed, INSERT 3 test-context-gather tasks -->
|
||||
<!-- TodoWrite: When test-context-gather dispatched, INSERT 3 test-context-gather tasks -->
|
||||
|
||||
**TodoWrite Update (Phase 2 SlashCommand executed - tasks attached)**:
|
||||
**TodoWrite Update (Phase 2 SlashCommand dispatched - tasks attached)**:
|
||||
```json
|
||||
[
|
||||
{"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
|
||||
@@ -168,7 +168,7 @@ SlashCommand(command="/workflow:tools:test-context-gather --session [testSession
|
||||
|
||||
### Phase 3: Test Generation Analysis
|
||||
|
||||
**Step 3.1: Execute** - Analyze test requirements with Gemini
|
||||
**Step 3.1: Dispatch** - Analyze test requirements with Gemini
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:tools:test-concept-enhanced --session [testSessionId] --context [testContextPath]")
|
||||
@@ -199,9 +199,9 @@ SlashCommand(command="/workflow:tools:test-concept-enhanced --session [testSessi
|
||||
- Implementation Targets (test files to create)
|
||||
- Success Criteria
|
||||
|
||||
<!-- TodoWrite: When test-concept-enhanced executed, INSERT 3 concept-enhanced tasks -->
|
||||
<!-- TodoWrite: When test-concept-enhanced dispatched, INSERT 3 concept-enhanced tasks -->
|
||||
|
||||
**TodoWrite Update (Phase 3 SlashCommand executed - tasks attached)**:
|
||||
**TodoWrite Update (Phase 3 SlashCommand dispatched - tasks attached)**:
|
||||
```json
|
||||
[
|
||||
{"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
|
||||
@@ -237,7 +237,7 @@ SlashCommand(command="/workflow:tools:test-concept-enhanced --session [testSessi
|
||||
|
||||
### Phase 4: Generate Test Tasks
|
||||
|
||||
**Step 4.1: Execute** - Generate test task JSON files and planning documents
|
||||
**Step 4.1: Dispatch** - Generate test task JSON files and planning documents
|
||||
|
||||
```javascript
|
||||
SlashCommand(command="/workflow:tools:test-task-generate --session [testSessionId]")
|
||||
@@ -287,9 +287,9 @@ SlashCommand(command="/workflow:tools:test-task-generate --session [testSessionI
|
||||
- Phase 2: Iterative Gemini diagnosis + fixes (agent or CLI based on step's `command` field)
|
||||
- Phase 3: Final validation and certification
|
||||
|
||||
<!-- TodoWrite: When test-task-generate executed, INSERT 3 test-task-generate tasks -->
|
||||
<!-- TodoWrite: When test-task-generate dispatched, INSERT 3 test-task-generate tasks -->
|
||||
|
||||
**TodoWrite Update (Phase 4 SlashCommand executed - tasks attached)**:
|
||||
**TodoWrite Update (Phase 4 SlashCommand dispatched - tasks attached)**:
|
||||
```json
|
||||
[
|
||||
{"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
|
||||
@@ -364,7 +364,7 @@ Ready for execution. Use appropriate workflow commands to proceed.
|
||||
|
||||
### Key Principles
|
||||
|
||||
1. **Task Attachment** (when SlashCommand executed):
|
||||
1. **Task Attachment** (when SlashCommand dispatched):
|
||||
- Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
|
||||
- Example: `/workflow:tools:test-context-gather` attaches 3 sub-tasks (Phase 2.1, 2.2, 2.3)
|
||||
- First attached task marked as `in_progress`, others as `pending`
|
||||
@@ -381,7 +381,7 @@ Ready for execution. Use appropriate workflow commands to proceed.
|
||||
- No user intervention required between phases
|
||||
- TodoWrite dynamically reflects current execution state
|
||||
|
||||
**Lifecycle Summary**: Initial pending tasks → Phase executed (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
|
||||
**Lifecycle Summary**: Initial pending tasks → Phase dispatched (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
|
||||
|
||||
### Test-Gen Specific Features
|
||||
|
||||
@@ -517,7 +517,7 @@ See `/workflow:tools:test-task-generate` for complete JSON schemas.
|
||||
**Prerequisite Commands**:
|
||||
- `/workflow:plan` or `/workflow:execute` - Complete implementation session that needs test validation
|
||||
|
||||
**Executed by This Command** (4 phases):
|
||||
**Dispatched by This Command** (4 phases):
|
||||
- `/workflow:session:start` - Phase 1: Create independent test workflow session
|
||||
- `/workflow:tools:test-context-gather` - Phase 2: Analyze test coverage and gather source session context
|
||||
- `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements and strategy using Gemini
|
||||
|
||||
@@ -1,16 +1,12 @@
|
||||
---
|
||||
name: conflict-resolution
|
||||
description: Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis with Gemini/Qwen
|
||||
argument-hint: "[-y|--yes] --session WFS-session-id --context path/to/context-package.json"
|
||||
argument-hint: "--session WFS-session-id --context path/to/context-package.json"
|
||||
examples:
|
||||
- /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/active/WFS-auth/.process/context-package.json
|
||||
- /workflow:tools:conflict-resolution -y --session WFS-payment --context .workflow/active/WFS-payment/.process/context-package.json
|
||||
- /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/active/WFS-payment/.process/context-package.json
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-select recommended strategy for each conflict, skip clarification questions.
|
||||
|
||||
# Conflict Resolution Command
|
||||
|
||||
## Purpose
|
||||
@@ -112,7 +108,7 @@ Phase 4: Apply Modifications
|
||||
|
||||
**Agent Delegation**:
|
||||
```javascript
|
||||
Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=`
|
||||
Task(subagent_type="cli-execution-agent", prompt=`
|
||||
## Context
|
||||
- Session: {session_id}
|
||||
- Risk: {conflict_risk}
|
||||
@@ -128,9 +124,6 @@ Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=`
|
||||
|
||||
## Analysis Steps
|
||||
|
||||
### 0. Load Output Schema (MANDATORY)
|
||||
Execute: cat ~/.claude/workflows/cli-templates/schemas/conflict-resolution-schema.json
|
||||
|
||||
### 1. Load Context
|
||||
- Read existing files from conflict_detection.existing_files
|
||||
- Load plan from .workflow/active/{session_id}/.process/context-package.json
|
||||
@@ -140,7 +133,7 @@ Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=`
|
||||
### 2. Execute CLI Analysis (Enhanced with Exploration + Scenario Uniqueness)
|
||||
|
||||
Primary (Gemini):
|
||||
ccw cli -p "
|
||||
cd {project_root} && gemini -p "
|
||||
PURPOSE: Detect conflicts between plan and codebase, using exploration insights
|
||||
TASK:
|
||||
• **Review pre-identified conflict_indicators from exploration results**
|
||||
@@ -158,8 +151,8 @@ Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=`
|
||||
- Validation of exploration conflict_indicators
|
||||
- ModuleOverlap conflicts with overlap_analysis
|
||||
- Targeted clarification questions
|
||||
CONSTRAINTS: Focus on breaking changes, migration needs, and functional overlaps | Prioritize exploration-identified conflicts | analysis=READ-ONLY
|
||||
" --tool gemini --mode analysis --rule analysis-code-patterns --cd {project_root}
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on breaking changes, migration needs, and functional overlaps | Prioritize exploration-identified conflicts | analysis=READ-ONLY
|
||||
"
|
||||
|
||||
Fallback: Qwen (same prompt) → Claude (manual analysis)
|
||||
|
||||
@@ -176,16 +169,125 @@ Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=`
|
||||
|
||||
### 4. Return Structured Conflict Data
|
||||
|
||||
⚠️ Output to conflict-resolution.json (generated in Phase 4)
|
||||
⚠️ DO NOT generate CONFLICT_RESOLUTION.md file
|
||||
|
||||
**Schema Reference**: Execute \`cat ~/.claude/workflows/cli-templates/schemas/conflict-resolution-schema.json\` to get full schema
|
||||
Return JSON format for programmatic processing:
|
||||
|
||||
Return JSON following the schema above. Key requirements:
|
||||
\`\`\`json
|
||||
{
|
||||
"conflicts": [
|
||||
{
|
||||
"id": "CON-001",
|
||||
"brief": "一行中文冲突摘要",
|
||||
"severity": "Critical|High|Medium",
|
||||
"category": "Architecture|API|Data|Dependency|ModuleOverlap",
|
||||
"affected_files": [
|
||||
".workflow/active/{session}/.brainstorm/guidance-specification.md",
|
||||
".workflow/active/{session}/.brainstorm/system-architect/analysis.md"
|
||||
],
|
||||
"description": "详细描述冲突 - 什么不兼容",
|
||||
"impact": {
|
||||
"scope": "影响的模块/组件",
|
||||
"compatibility": "Yes|No|Partial",
|
||||
"migration_required": true|false,
|
||||
"estimated_effort": "人天估计"
|
||||
},
|
||||
"overlap_analysis": {
|
||||
"// NOTE": "仅当 category=ModuleOverlap 时需要此字段",
|
||||
"new_module": {
|
||||
"name": "新模块名称",
|
||||
"scenarios": ["场景1", "场景2", "场景3"],
|
||||
"responsibilities": "职责描述"
|
||||
},
|
||||
"existing_modules": [
|
||||
{
|
||||
"file": "src/existing/module.ts",
|
||||
"name": "现有模块名称",
|
||||
"scenarios": ["场景A", "场景B"],
|
||||
"overlap_scenarios": ["重叠场景1", "重叠场景2"],
|
||||
"responsibilities": "现有模块职责"
|
||||
}
|
||||
]
|
||||
},
|
||||
"strategies": [
|
||||
{
|
||||
"name": "策略名称（中文）",
|
||||
"approach": "实现方法简述",
|
||||
"complexity": "Low|Medium|High",
|
||||
"risk": "Low|Medium|High",
|
||||
"effort": "时间估计",
|
||||
"pros": ["优点1", "优点2"],
|
||||
"cons": ["缺点1", "缺点2"],
|
||||
"clarification_needed": [
|
||||
"// NOTE: 仅当需要用户进一步澄清时需要此字段（尤其是 ModuleOverlap）",
|
||||
"新模块的核心职责边界是什么？",
|
||||
"如何与现有模块 X 协作？",
|
||||
"哪些场景应该由新模块处理？"
|
||||
],
|
||||
"modifications": [
|
||||
{
|
||||
"file": ".workflow/active/{session}/.brainstorm/guidance-specification.md",
|
||||
"section": "## 2. System Architect Decisions",
|
||||
"change_type": "update",
|
||||
"old_content": "原始内容片段（用于定位）",
|
||||
"new_content": "修改后的内容",
|
||||
"rationale": "为什么这样改"
|
||||
},
|
||||
{
|
||||
"file": ".workflow/active/{session}/.brainstorm/system-architect/analysis.md",
|
||||
"section": "## Design Decisions",
|
||||
"change_type": "update",
|
||||
"old_content": "原始内容片段",
|
||||
"new_content": "修改后的内容",
|
||||
"rationale": "修改理由"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "策略2名称",
|
||||
"approach": "...",
|
||||
"complexity": "Medium",
|
||||
"risk": "Low",
|
||||
"effort": "1-2天",
|
||||
"pros": ["优点"],
|
||||
"cons": ["缺点"],
|
||||
"modifications": [...]
|
||||
}
|
||||
],
|
||||
"recommended": 0,
|
||||
"modification_suggestions": [
|
||||
"建议1：具体的修改方向或注意事项",
|
||||
"建议2：可能需要考虑的边界情况",
|
||||
"建议3：相关的最佳实践或模式"
|
||||
]
|
||||
}
|
||||
],
|
||||
"summary": {
|
||||
"total": 2,
|
||||
"critical": 1,
|
||||
"high": 1,
|
||||
"medium": 0
|
||||
}
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
⚠️ CRITICAL Requirements for modifications field:
|
||||
- old_content: Must be exact text from target file (20-100 chars for unique match)
|
||||
- new_content: Complete replacement text (maintains formatting)
|
||||
- change_type: "update" (replace), "add" (insert), "remove" (delete)
|
||||
- file: Full path relative to project root
|
||||
- section: Markdown heading for context (helps locate position)
|
||||
- Minimum 2 strategies per conflict, max 4
|
||||
- All text in Chinese for user-facing fields (brief, name, pros, cons, modification_suggestions)
|
||||
- modifications.old_content: 20-100 chars for unique Edit tool matching
|
||||
- modifications.new_content: preserves markdown formatting
|
||||
- modification_suggestions: 2-5 actionable suggestions for custom handling
|
||||
- All text in Chinese for user-facing fields (brief, name, pros, cons)
|
||||
- modification_suggestions: 2-5 actionable suggestions for custom handling (Chinese)
|
||||
|
||||
Quality Standards:
|
||||
- Each strategy must have actionable modifications
|
||||
- old_content must be precise enough for Edit tool matching
|
||||
- new_content preserves markdown formatting and structure
|
||||
- Recommended strategy (index) based on lowest complexity + risk
|
||||
- modification_suggestions must be specific, actionable, and context-aware
|
||||
- Each suggestion should address a specific aspect (compatibility, migration, testing, etc.)
|
||||
`)
|
||||
```
|
||||
|
||||
@@ -210,93 +312,143 @@ Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=`
|
||||
8. Return execution log path
|
||||
```
|
||||
|
||||
### Phase 3: User Interaction Loop
|
||||
### Phase 3: Iterative User Interaction with Clarification Loop
|
||||
|
||||
```javascript
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
**Execution Flow**:
|
||||
```
|
||||
FOR each conflict (逐个处理，无数量限制):
|
||||
clarified = false
|
||||
round = 0
|
||||
userClarifications = []
|
||||
|
||||
FOR each conflict:
|
||||
round = 0, clarified = false, userClarifications = []
|
||||
WHILE (!clarified && round < 10):
|
||||
round++
|
||||
|
||||
WHILE (!clarified && round++ < 10):
|
||||
// 1. Display conflict info (text output for context)
|
||||
displayConflictSummary(conflict) // id, brief, severity, overlap_analysis if ModuleOverlap
|
||||
// 1. Display conflict (包含所有关键字段)
|
||||
- category, id, brief, severity, description
|
||||
- IF ModuleOverlap: 展示 overlap_analysis
|
||||
* new_module: {name, scenarios, responsibilities}
|
||||
* existing_modules[]: {file, name, scenarios, overlap_scenarios, responsibilities}
|
||||
|
||||
// 2. Strategy selection
|
||||
if (autoYes) {
|
||||
console.log(`[--yes] Auto-selecting recommended strategy`)
|
||||
selectedStrategy = conflict.strategies[conflict.recommended || 0]
|
||||
clarified = true // Skip clarification loop
|
||||
} else {
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: formatStrategiesForDisplay(conflict.strategies),
|
||||
header: "策略选择",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
...conflict.strategies.map((s, i) => ({
|
||||
label: `${s.name}${i === conflict.recommended ? ' (推荐)' : ''}`,
|
||||
description: `${s.complexity}复杂度 | ${s.risk}风险${s.clarification_needed?.length ? ' | ⚠️需澄清' : ''}`
|
||||
})),
|
||||
{ label: "自定义修改", description: `建议: ${conflict.modification_suggestions?.slice(0,2).join('; ')}` }
|
||||
]
|
||||
}]
|
||||
})
|
||||
// 2. Display strategies (2-4个策略 + 自定义选项)
|
||||
- FOR each strategy: {name, approach, complexity, risk, effort, pros, cons}
|
||||
* IF clarification_needed: 展示待澄清问题列表
|
||||
- 自定义选项: {suggestions: modification_suggestions[]}
|
||||
|
||||
// 3. Handle selection
|
||||
if (userChoice === "自定义修改") {
|
||||
customConflicts.push({ id, brief, category, suggestions, overlap_analysis })
|
||||
break
|
||||
}
|
||||
// 3. User selects strategy
|
||||
userChoice = readInput()
|
||||
|
||||
selectedStrategy = findStrategyByName(userChoice)
|
||||
}
|
||||
|
||||
// 4. Clarification (if needed) - batched max 4 per call
|
||||
if (!autoYes && selectedStrategy.clarification_needed?.length > 0) {
|
||||
for (batch of chunk(selectedStrategy.clarification_needed, 4)) {
|
||||
AskUserQuestion({
|
||||
questions: batch.map((q, i) => ({
|
||||
question: q, header: `澄清${i+1}`, multiSelect: false,
|
||||
options: [{ label: "详细说明", description: "提供答案" }]
|
||||
}))
|
||||
})
|
||||
userClarifications.push(...collectAnswers(batch))
|
||||
}
|
||||
|
||||
// 5. Agent re-analysis
|
||||
reanalysisResult = Task({
|
||||
subagent_type: "cli-execution-agent",
|
||||
run_in_background: false,
|
||||
prompt: `Conflict: ${conflict.id}, Strategy: ${selectedStrategy.name}
|
||||
User Clarifications: ${JSON.stringify(userClarifications)}
|
||||
Output: { uniqueness_confirmed, rationale, updated_strategy, remaining_questions }`
|
||||
})
|
||||
|
||||
if (reanalysisResult.uniqueness_confirmed) {
|
||||
selectedStrategy = { ...reanalysisResult.updated_strategy, clarifications: userClarifications }
|
||||
clarified = true
|
||||
} else {
|
||||
selectedStrategy.clarification_needed = reanalysisResult.remaining_questions
|
||||
}
|
||||
} else {
|
||||
IF userChoice == "自定义":
|
||||
customConflicts.push({id, brief, category, suggestions, overlap_analysis})
|
||||
clarified = true
|
||||
}
|
||||
BREAK
|
||||
|
||||
if (clarified) resolvedConflicts.push({ conflict, strategy: selectedStrategy })
|
||||
selectedStrategy = strategies[userChoice]
|
||||
|
||||
// 4. Clarification loop
|
||||
IF selectedStrategy.clarification_needed.length > 0:
|
||||
// 收集澄清答案
|
||||
FOR each question:
|
||||
answer = readInput()
|
||||
userClarifications.push({question, answer})
|
||||
|
||||
// Agent 重新分析
|
||||
reanalysisResult = Task(cli-execution-agent, prompt={
|
||||
冲突信息: {id, brief, category, 策略}
|
||||
用户澄清: userClarifications[]
|
||||
场景分析: overlap_analysis (if ModuleOverlap)
|
||||
|
||||
输出: {
|
||||
uniqueness_confirmed: bool,
|
||||
rationale: string,
|
||||
updated_strategy: {name, approach, complexity, risk, effort, modifications[]},
|
||||
remaining_questions: [] (如果仍有歧义)
|
||||
}
|
||||
})
|
||||
|
||||
IF reanalysisResult.uniqueness_confirmed:
|
||||
selectedStrategy = updated_strategy
|
||||
selectedStrategy.clarifications = userClarifications
|
||||
clarified = true
|
||||
ELSE:
|
||||
// 更新澄清问题，继续下一轮
|
||||
selectedStrategy.clarification_needed = remaining_questions
|
||||
ELSE:
|
||||
clarified = true
|
||||
|
||||
resolvedConflicts.push({conflict, strategy: selectedStrategy})
|
||||
END WHILE
|
||||
END FOR
|
||||
|
||||
// Build output
|
||||
selectedStrategies = resolvedConflicts.map(r => ({
|
||||
conflict_id: r.conflict.id, strategy: r.strategy, clarifications: r.strategy.clarifications || []
|
||||
conflict_id, strategy, clarifications[]
|
||||
}))
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
- AskUserQuestion: max 4 questions/call, batch if more
|
||||
- Strategy options: 2-4 strategies + "自定义修改"
|
||||
- Clarification loop: max 10 rounds, agent判断 uniqueness_confirmed
|
||||
- Custom conflicts: 记录 overlap_analysis 供后续手动处理
|
||||
**Key Data Structures**:
|
||||
|
||||
```javascript
|
||||
// Custom conflict tracking
|
||||
customConflicts[] = {
|
||||
id, brief, category,
|
||||
suggestions: modification_suggestions[],
|
||||
overlap_analysis: { new_module{}, existing_modules[] } // ModuleOverlap only
|
||||
}
|
||||
|
||||
// Agent re-analysis prompt output
|
||||
{
|
||||
uniqueness_confirmed: bool,
|
||||
rationale: string,
|
||||
updated_strategy: {
|
||||
name, approach, complexity, risk, effort,
|
||||
modifications: [{file, section, change_type, old_content, new_content, rationale}]
|
||||
},
|
||||
remaining_questions: string[]
|
||||
}
|
||||
```
|
||||
|
||||
**Text Output Example** (展示关键字段):
|
||||
|
||||
```markdown
|
||||
============================================================
|
||||
冲突 1/3 - 第 1 轮
|
||||
============================================================
|
||||
【ModuleOverlap】CON-001: 新增用户认证服务与现有模块功能重叠
|
||||
严重程度: High | 描述: 计划中的 UserAuthService 与现有 AuthManager 场景重叠
|
||||
|
||||
--- 场景重叠分析 ---
|
||||
新模块: UserAuthService | 场景: 登录, Token验证, 权限, MFA
|
||||
现有模块: AuthManager (src/auth/AuthManager.ts) | 重叠: 登录, Token验证
|
||||
|
||||
--- 解决策略 ---
|
||||
1) 合并 (Low复杂度 | Low风险 | 2-3天)
|
||||
⚠️ 需澄清: AuthManager是否能承担MFA？
|
||||
|
||||
2) 拆分边界 (Medium复杂度 | Medium风险 | 4-5天)
|
||||
⚠️ 需澄清: 基础/高级认证边界? Token验证归谁?
|
||||
|
||||
3) 自定义修改
|
||||
建议: 评估扩展性; 策略模式分离; 定义接口边界
|
||||
|
||||
请选择 (1-3): > 2
|
||||
|
||||
--- 澄清问答 (第1轮) ---
|
||||
Q: 基础/高级认证边界?
|
||||
A: 基础=密码登录+token验证, 高级=MFA+OAuth+SSO
|
||||
|
||||
Q: Token验证归谁?
|
||||
A: 统一由 AuthManager 负责
|
||||
|
||||
🔄 重新分析...
|
||||
✅ 唯一性已确认 | 理由: 边界清晰 - AuthManager(基础+token), UserAuthService(MFA+OAuth+SSO)
|
||||
|
||||
============================================================
|
||||
冲突 2/3 - 第 1 轮 [下一个冲突]
|
||||
============================================================
|
||||
```
|
||||
|
||||
**Loop Characteristics**: 逐个处理 | 无限轮次(max 10) | 动态问题生成 | Agent重新分析判断唯一性 | ModuleOverlap场景边界澄清
|
||||
|
||||
### Phase 4: Apply Modifications
|
||||
|
||||
@@ -315,30 +467,14 @@ selectedStrategies.forEach(item => {
|
||||
|
||||
console.log(`\n正在应用 ${modifications.length} 个修改...`);
|
||||
|
||||
// 2. Apply each modification using Edit tool (with fallback to context-package.json)
|
||||
// 2. Apply each modification using Edit tool
|
||||
const appliedModifications = [];
|
||||
const failedModifications = [];
|
||||
const fallbackConstraints = []; // For files that don't exist
|
||||
|
||||
modifications.forEach((mod, idx) => {
|
||||
try {
|
||||
console.log(`[${idx + 1}/${modifications.length}] 修改 ${mod.file}...`);
|
||||
|
||||
// Check if target file exists (brainstorm files may not exist in lite workflow)
|
||||
if (!file_exists(mod.file)) {
|
||||
console.log(` ⚠️ 文件不存在，写入 context-package.json 作为约束`);
|
||||
fallbackConstraints.push({
|
||||
source: "conflict-resolution",
|
||||
conflict_id: mod.conflict_id,
|
||||
target_file: mod.file,
|
||||
section: mod.section,
|
||||
change_type: mod.change_type,
|
||||
content: mod.new_content,
|
||||
rationale: mod.rationale
|
||||
});
|
||||
return; // Skip to next modification
|
||||
}
|
||||
|
||||
if (mod.change_type === "update") {
|
||||
Edit({
|
||||
file_path: mod.file,
|
||||
@@ -366,45 +502,14 @@ modifications.forEach((mod, idx) => {
|
||||
}
|
||||
});
|
||||
|
||||
// 2b. Generate conflict-resolution.json output file
|
||||
const resolutionOutput = {
|
||||
session_id: sessionId,
|
||||
resolved_at: new Date().toISOString(),
|
||||
summary: {
|
||||
total_conflicts: conflicts.length,
|
||||
resolved_with_strategy: selectedStrategies.length,
|
||||
custom_handling: customConflicts.length,
|
||||
fallback_constraints: fallbackConstraints.length
|
||||
},
|
||||
resolved_conflicts: selectedStrategies.map(s => ({
|
||||
conflict_id: s.conflict_id,
|
||||
strategy_name: s.strategy.name,
|
||||
strategy_approach: s.strategy.approach,
|
||||
clarifications: s.clarifications || [],
|
||||
modifications_applied: s.strategy.modifications?.filter(m =>
|
||||
appliedModifications.some(am => am.conflict_id === s.conflict_id)
|
||||
) || []
|
||||
})),
|
||||
custom_conflicts: customConflicts.map(c => ({
|
||||
id: c.id,
|
||||
brief: c.brief,
|
||||
category: c.category,
|
||||
suggestions: c.suggestions,
|
||||
overlap_analysis: c.overlap_analysis || null
|
||||
})),
|
||||
planning_constraints: fallbackConstraints, // Constraints for files that don't exist
|
||||
failed_modifications: failedModifications
|
||||
};
|
||||
|
||||
const resolutionPath = `.workflow/active/${sessionId}/.process/conflict-resolution.json`;
|
||||
Write(resolutionPath, JSON.stringify(resolutionOutput, null, 2));
|
||||
console.log(`\n📄 冲突解决结果已保存: ${resolutionPath}`);
|
||||
|
||||
// 3. Update context-package.json with resolution details (reference to JSON file)
|
||||
// 3. Update context-package.json with resolution details
|
||||
const contextPackage = JSON.parse(Read(contextPath));
|
||||
contextPackage.conflict_detection.conflict_risk = "resolved";
|
||||
contextPackage.conflict_detection.resolution_file = resolutionPath; // Reference to detailed JSON
|
||||
contextPackage.conflict_detection.resolved_conflicts = selectedStrategies.map(s => s.conflict_id);
|
||||
contextPackage.conflict_detection.resolved_conflicts = selectedStrategies.map(s => ({
|
||||
conflict_id: s.conflict_id,
|
||||
strategy_name: s.strategy.name,
|
||||
clarifications: s.clarifications
|
||||
}));
|
||||
contextPackage.conflict_detection.custom_conflicts = customConflicts.map(c => c.id);
|
||||
contextPackage.conflict_detection.resolved_at = new Date().toISOString();
|
||||
Write(contextPath, JSON.stringify(contextPackage, null, 2));
|
||||
@@ -477,50 +582,12 @@ return {
|
||||
✓ Agent log saved to .workflow/active/{session_id}/.chat/
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
### Primary Output: conflict-resolution.json
|
||||
|
||||
**Path**: `.workflow/active/{session_id}/.process/conflict-resolution.json`
|
||||
|
||||
**Schema**:
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-xxx",
|
||||
"resolved_at": "ISO timestamp",
|
||||
"summary": {
|
||||
"total_conflicts": 3,
|
||||
"resolved_with_strategy": 2,
|
||||
"custom_handling": 1,
|
||||
"fallback_constraints": 0
|
||||
},
|
||||
"resolved_conflicts": [
|
||||
{
|
||||
"conflict_id": "CON-001",
|
||||
"strategy_name": "策略名称",
|
||||
"strategy_approach": "实现方法",
|
||||
"clarifications": [],
|
||||
"modifications_applied": []
|
||||
}
|
||||
],
|
||||
"custom_conflicts": [
|
||||
{
|
||||
"id": "CON-002",
|
||||
"brief": "冲突摘要",
|
||||
"category": "ModuleOverlap",
|
||||
"suggestions": ["建议1", "建议2"],
|
||||
"overlap_analysis": null
|
||||
}
|
||||
],
|
||||
"planning_constraints": [],
|
||||
"failed_modifications": []
|
||||
}
|
||||
```
|
||||
|
||||
### Secondary: Agent JSON Response (stdout)
|
||||
## Output Format: Agent JSON Response
|
||||
|
||||
**Focus**: Structured conflict data with actionable modifications for programmatic processing.
|
||||
|
||||
**Format**: JSON to stdout (NO file generation)
|
||||
|
||||
**Structure**: Defined in Phase 2, Step 4 (agent prompt)
|
||||
|
||||
### Key Requirements
|
||||
@@ -568,12 +635,11 @@ If Edit tool fails mid-application:
|
||||
- Requires: `conflict_risk ≥ medium`
|
||||
|
||||
**Output**:
|
||||
- Generated file:
|
||||
- `.workflow/active/{session_id}/.process/conflict-resolution.json` (primary output)
|
||||
- Modified files (if exist):
|
||||
- Modified files:
|
||||
- `.workflow/active/{session_id}/.brainstorm/guidance-specification.md`
|
||||
- `.workflow/active/{session_id}/.brainstorm/{role}/analysis.md`
|
||||
- `.workflow/active/{session_id}/.process/context-package.json` (conflict_risk → resolved, resolution_file reference)
|
||||
- `.workflow/active/{session_id}/.process/context-package.json` (conflict_risk → resolved)
|
||||
- NO report file generation
|
||||
|
||||
**User Interaction**:
|
||||
- **Iterative conflict processing**: One conflict at a time, not in batches
|
||||
@@ -601,7 +667,7 @@ If Edit tool fails mid-application:
|
||||
✓ guidance-specification.md updated with resolved conflicts
|
||||
✓ Role analyses (*.md) updated with resolved conflicts
|
||||
✓ context-package.json marked as "resolved" with clarification records
|
||||
✓ conflict-resolution.json generated with full resolution details
|
||||
✓ No CONFLICT_RESOLUTION.md file generated
|
||||
✓ Modification summary includes:
|
||||
- Total conflicts
|
||||
- Resolved with strategy (count)
|
||||
|
||||
@@ -15,6 +15,7 @@ allowed-tools: Task(*), Read(*), Glob(*)
|
||||
|
||||
Orchestrator command that invokes `context-search-agent` to gather comprehensive project context for implementation planning. Generates standardized `context-package.json` with codebase analysis, dependencies, and conflict detection.
|
||||
|
||||
**Agent**: `context-search-agent` (`.claude/agents/context-search-agent.md`)
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
@@ -120,7 +121,6 @@ const sessionFolder = `.workflow/active/${session_id}/.process`;
|
||||
const explorationTasks = selectedAngles.map((angle, index) =>
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
run_in_background=false,
|
||||
description=`Explore: ${angle}`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
@@ -135,7 +135,7 @@ Execute **${angle}** exploration for task planning context. Analyze codebase fro
|
||||
|
||||
## MANDATORY FIRST STEPS (Execute by Agent)
|
||||
**You (cli-explore-agent) MUST execute these steps in order:**
|
||||
1. Run: ccw tool exec get_modules_by_depth '{}' (project structure)
|
||||
1. Run: ~/.claude/scripts/get_modules_by_depth.sh (project structure)
|
||||
2. Run: rg -l "{keyword_from_task}" --type ts (locate relevant files)
|
||||
3. Execute: cat ~/.claude/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference)
|
||||
|
||||
@@ -215,7 +215,6 @@ Write(`${sessionFolder}/explorations-manifest.json`, JSON.stringify(explorationM
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="context-search-agent",
|
||||
run_in_background=false,
|
||||
description="Gather comprehensive context for plan",
|
||||
prompt=`
|
||||
## Execution Mode
|
||||
@@ -236,12 +235,9 @@ Task(
|
||||
Execute complete context-search-agent workflow for implementation planning:
|
||||
|
||||
### Phase 1: Initialization & Pre-Analysis
|
||||
1. **Project State Loading**:
|
||||
- Read and parse `.workflow/project-tech.json`. Use its `overview` section as the foundational `project_context`. This is your primary source for architecture, tech stack, and key components.
|
||||
- Read and parse `.workflow/project-guidelines.json`. Load `conventions`, `constraints`, and `learnings` into a `project_guidelines` section.
|
||||
- If files don't exist, proceed with fresh analysis.
|
||||
1. **Project State Loading**: Read and parse `.workflow/project.json`. Use its `overview` section as the foundational `project_context`. This is your primary source for architecture, tech stack, and key components. If file doesn't exist, proceed with fresh analysis.
|
||||
2. **Detection**: Check for existing context-package (early exit if valid)
|
||||
3. **Foundation**: Initialize CodexLens, get project structure, load docs
|
||||
3. **Foundation**: Initialize code-index, get project structure, load docs
|
||||
4. **Analysis**: Extract keywords, determine scope, classify complexity based on task description and project state
|
||||
|
||||
### Phase 2: Multi-Source Context Discovery
|
||||
@@ -254,19 +250,17 @@ Execute all discovery tracks:
|
||||
|
||||
### Phase 3: Synthesis, Assessment & Packaging
|
||||
1. Apply relevance scoring and build dependency graph
|
||||
2. **Synthesize 4-source data**: Merge findings from all sources (archive > docs > code > web). **Prioritize the context from `project-tech.json`** for architecture and tech stack unless code analysis reveals it's outdated.
|
||||
3. **Populate `project_context`**: Directly use the `overview` from `project-tech.json` to fill the `project_context` section. Include description, technology_stack, architecture, and key_components.
|
||||
4. **Populate `project_guidelines`**: Load conventions, constraints, and learnings from `project-guidelines.json` into a dedicated section.
|
||||
5. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
|
||||
6. Perform conflict detection with risk assessment
|
||||
7. **Inject historical conflicts** from archive analysis into conflict_detection
|
||||
8. Generate and validate context-package.json
|
||||
2. **Synthesize 4-source data**: Merge findings from all sources (archive > docs > code > web). **Prioritize the context from `project.json`** for architecture and tech stack unless code analysis reveals it's outdated.
|
||||
3. **Populate `project_context`**: Directly use the `overview` from `project.json` to fill the `project_context` section of the output `context-package.json`. Include description, technology_stack, architecture, and key_components.
|
||||
4. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
|
||||
5. Perform conflict detection with risk assessment
|
||||
6. **Inject historical conflicts** from archive analysis into conflict_detection
|
||||
7. Generate and validate context-package.json
|
||||
|
||||
## Output Requirements
|
||||
Complete context-package.json with:
|
||||
- **metadata**: task_description, keywords, complexity, tech_stack, session_id
|
||||
- **project_context**: description, technology_stack, architecture, key_components (sourced from `project-tech.json`)
|
||||
- **project_guidelines**: {conventions, constraints, quality_rules, learnings} (sourced from `project-guidelines.json`)
|
||||
- **project_context**: description, technology_stack, architecture, key_components (sourced from `project.json` overview)
|
||||
- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
|
||||
- **dependencies**: {internal[], external[]} with dependency graph
|
||||
- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
|
||||
@@ -319,8 +313,7 @@ Refer to `context-search-agent.md` Phase 3.7 for complete `context-package.json`
|
||||
|
||||
**Key Sections**:
|
||||
- **metadata**: Session info, keywords, complexity, tech stack
|
||||
- **project_context**: Architecture patterns, conventions, tech stack (populated from `project-tech.json`)
|
||||
- **project_guidelines**: Conventions, constraints, quality rules, learnings (populated from `project-guidelines.json`)
|
||||
- **project_context**: Architecture patterns, conventions, tech stack (populated from `project.json` overview)
|
||||
- **assets**: Categorized files with relevance scores (documentation, source_code, config, tests)
|
||||
- **dependencies**: Internal and external dependency graphs
|
||||
- **brainstorm_artifacts**: Brainstorm documents with full content (if exists)
|
||||
@@ -435,7 +428,7 @@ if (historicalConflicts.length > 0 && currentRisk === "low") {
|
||||
## Notes
|
||||
|
||||
- **Detection-first**: Always check for existing package before invoking agent
|
||||
- **Dual project file integration**: Agent reads both `.workflow/project-tech.json` (tech analysis) and `.workflow/project-guidelines.json` (user constraints) as primary sources
|
||||
- **Guidelines injection**: Project guidelines are included in context-package to ensure task generation respects user-defined constraints
|
||||
- **Project.json integration**: Agent reads `.workflow/project.json` as primary source for project context, avoiding redundant analysis
|
||||
- **Agent autonomy**: Agent handles all discovery logic per `.claude/agents/context-search-agent.md`
|
||||
- **No redundancy**: This command is a thin orchestrator, all logic in agent
|
||||
- **Plan-specific**: Use this for implementation planning; brainstorm mode uses direct agent call
|
||||
|
||||
@@ -1,16 +1,11 @@
|
||||
---
|
||||
name: 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
|
||||
argument-hint: "[-y|--yes] --session WFS-session-id"
|
||||
argument-hint: "--session WFS-session-id"
|
||||
examples:
|
||||
- /workflow:tools:task-generate-agent --session WFS-auth
|
||||
- /workflow:tools:task-generate-agent -y --session WFS-auth
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Skip user questions, use defaults (no materials, Agent executor, Codex CLI tool).
|
||||
|
||||
# Generate Implementation Plan Command
|
||||
|
||||
## Overview
|
||||
@@ -33,12 +28,6 @@ Input Parsing:
|
||||
├─ Parse flags: --session
|
||||
└─ Validation: session_id REQUIRED
|
||||
|
||||
Phase 0: User Configuration (Interactive)
|
||||
├─ Question 1: Supplementary materials/guidelines?
|
||||
├─ Question 2: Execution method preference (Agent/CLI/Hybrid)
|
||||
├─ Question 3: CLI tool preference (if CLI selected)
|
||||
└─ Store: userConfig for agent prompt
|
||||
|
||||
Phase 1: Context Preparation & Module Detection (Command)
|
||||
├─ Assemble session paths (metadata, context package, output dirs)
|
||||
├─ Provide metadata (session_id, execution_mode, mcp_capabilities)
|
||||
@@ -68,97 +57,6 @@ Phase 3: Integration (+1 Coordinator, Multi-Module Only)
|
||||
|
||||
## Document Generation Lifecycle
|
||||
|
||||
### Phase 0: User Configuration (Interactive)
|
||||
|
||||
**Purpose**: Collect user preferences before task generation to ensure generated tasks match execution expectations.
|
||||
|
||||
**Auto Mode Check**:
|
||||
```javascript
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
|
||||
if (autoYes) {
|
||||
console.log(`[--yes] Using defaults: No materials, Agent executor, Codex CLI`)
|
||||
userConfig = {
|
||||
supplementaryMaterials: { type: "none", content: [] },
|
||||
executionMethod: "agent",
|
||||
preferredCliTool: "codex",
|
||||
enableResume: true
|
||||
}
|
||||
// Skip to Phase 1
|
||||
}
|
||||
```
|
||||
|
||||
**User Questions** (skipped if autoYes):
|
||||
```javascript
|
||||
if (!autoYes) AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "Do you have supplementary materials or guidelines to include?",
|
||||
header: "Materials",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "No additional materials", description: "Use existing context only" },
|
||||
{ label: "Provide file paths", description: "I'll specify paths to include" },
|
||||
{ label: "Provide inline content", description: "I'll paste content directly" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Select execution method for generated tasks:",
|
||||
header: "Execution",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Agent (Recommended)", description: "Claude agent executes tasks directly" },
|
||||
{ label: "Hybrid", description: "Agent orchestrates, calls CLI for complex steps" },
|
||||
{ label: "CLI Only", description: "All execution via CLI tools (codex/gemini/qwen)" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "If using CLI, which tool do you prefer?",
|
||||
header: "CLI Tool",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Codex (Recommended)", description: "Best for implementation tasks" },
|
||||
{ label: "Gemini", description: "Best for analysis and large context" },
|
||||
{ label: "Qwen", description: "Alternative analysis tool" },
|
||||
{ label: "Auto", description: "Let agent decide per-task" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
|
||||
**Handle Materials Response** (skipped if autoYes):
|
||||
```javascript
|
||||
if (!autoYes && userConfig.materials === "Provide file paths") {
|
||||
// Follow-up question for file paths
|
||||
const pathsResponse = AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Enter file paths to include (comma-separated or one per line):",
|
||||
header: "Paths",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Enter paths", description: "Provide paths in text input" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
userConfig.supplementaryPaths = parseUserPaths(pathsResponse)
|
||||
}
|
||||
```
|
||||
|
||||
**Build userConfig**:
|
||||
```javascript
|
||||
const userConfig = {
|
||||
supplementaryMaterials: {
|
||||
type: "none|paths|inline",
|
||||
content: [...], // Parsed paths or inline content
|
||||
},
|
||||
executionMethod: "agent|hybrid|cli",
|
||||
preferredCliTool: "codex|gemini|qwen|auto",
|
||||
enableResume: true // Always enable resume for CLI executions
|
||||
}
|
||||
```
|
||||
|
||||
**Pass to Agent**: Include `userConfig` in agent prompt for Phase 2A/2B.
|
||||
|
||||
### Phase 1: Context Preparation & Module Detection (Command Responsibility)
|
||||
|
||||
**Command prepares session paths, metadata, and detects module structure.**
|
||||
@@ -191,14 +89,6 @@ const userConfig = {
|
||||
3. **Auto Module Detection** (determines single vs parallel mode):
|
||||
```javascript
|
||||
function autoDetectModules(contextPackage, projectRoot) {
|
||||
// === Complexity Gate: Only parallelize for High complexity ===
|
||||
const complexity = contextPackage.metadata?.complexity || 'Medium';
|
||||
if (complexity !== 'High') {
|
||||
// Force single agent mode for Low/Medium complexity
|
||||
// This maximizes agent context reuse for related tasks
|
||||
return [{ name: 'main', prefix: '', paths: ['.'] }];
|
||||
}
|
||||
|
||||
// Priority 1: Explicit frontend/backend separation
|
||||
if (exists('src/frontend') && exists('src/backend')) {
|
||||
return [
|
||||
@@ -222,9 +112,8 @@ const userConfig = {
|
||||
```
|
||||
|
||||
**Decision Logic**:
|
||||
- `complexity !== 'High'` → Force Phase 2A (Single Agent, maximize context reuse)
|
||||
- `modules.length == 1` → Phase 2A (Single Agent, original flow)
|
||||
- `modules.length >= 2 && complexity == 'High'` → Phase 2B + Phase 3 (N+1 Parallel)
|
||||
- `modules.length >= 2` → Phase 2B + Phase 3 (N+1 Parallel)
|
||||
|
||||
**Note**: CLI tool usage is now determined semantically by action-planning-agent based on user's task description, not by flags.
|
||||
|
||||
@@ -238,7 +127,6 @@ const userConfig = {
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="action-planning-agent",
|
||||
run_in_background=false,
|
||||
description="Generate planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)",
|
||||
prompt=`
|
||||
## TASK OBJECTIVE
|
||||
@@ -262,21 +150,10 @@ Output:
|
||||
Session ID: {session-id}
|
||||
MCP Capabilities: {exa_code, exa_web, code_index}
|
||||
|
||||
## USER CONFIGURATION (from Phase 0)
|
||||
Execution Method: ${userConfig.executionMethod} // agent|hybrid|cli
|
||||
Preferred CLI Tool: ${userConfig.preferredCliTool} // codex|gemini|qwen|auto
|
||||
Supplementary Materials: ${userConfig.supplementaryMaterials}
|
||||
|
||||
## CLI TOOL SELECTION
|
||||
Based on userConfig.executionMethod:
|
||||
- "agent": No command field in implementation_approach steps
|
||||
- "hybrid": Add command field to complex steps only (agent handles simple steps)
|
||||
- "cli": Add command field to ALL implementation_approach steps
|
||||
|
||||
CLI Resume Support (MANDATORY for all CLI commands):
|
||||
- Use --resume parameter to continue from previous task execution
|
||||
- Read previous task's cliExecutionId from session state
|
||||
- Format: ccw cli -p "[prompt]" --resume ${previousCliId} --tool ${tool} --mode write
|
||||
Determine CLI tool usage per-step based on user's task description:
|
||||
- If user specifies "use Codex/Gemini/Qwen for X" → Add command field to relevant steps
|
||||
- Default: Agent execution (no command field) unless user explicitly requests CLI
|
||||
|
||||
## EXPLORATION CONTEXT (from context-package.exploration_results)
|
||||
- Load exploration_results from context-package.json
|
||||
@@ -286,13 +163,6 @@ CLI Resume Support (MANDATORY for all CLI commands):
|
||||
- Use aggregated_insights.all_integration_points for precise modification locations
|
||||
- Use conflict_indicators for risk-aware task sequencing
|
||||
|
||||
## CONFLICT RESOLUTION CONTEXT (if exists)
|
||||
- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path
|
||||
- If exists, load .process/conflict-resolution.json:
|
||||
- Apply planning_constraints as task constraints (for brainstorm-less workflows)
|
||||
- Reference resolved_conflicts for implementation approach alignment
|
||||
- Handle custom_conflicts with explicit task notes
|
||||
|
||||
## EXPECTED DELIVERABLES
|
||||
1. Task JSON Files (.task/IMPL-*.json)
|
||||
- 6-field schema (id, title, status, context_package_path, meta, context, flow_control)
|
||||
@@ -300,7 +170,6 @@ CLI Resume Support (MANDATORY for all CLI commands):
|
||||
- Artifacts integration from context package
|
||||
- **focus_paths enhanced with exploration critical_files**
|
||||
- Flow control with pre_analysis steps (include exploration integration_points analysis)
|
||||
- **CLI Execution IDs and strategies (MANDATORY)**
|
||||
|
||||
2. Implementation Plan (IMPL_PLAN.md)
|
||||
- Context analysis and artifact references
|
||||
@@ -312,27 +181,6 @@ CLI Resume Support (MANDATORY for all CLI commands):
|
||||
- Links to task JSONs and summaries
|
||||
- Matches task JSON hierarchy
|
||||
|
||||
## CLI EXECUTION ID REQUIREMENTS (MANDATORY)
|
||||
Each task JSON MUST include:
|
||||
- **cli_execution_id**: Unique ID for CLI execution (format: `{session_id}-{task_id}`)
|
||||
- **cli_execution**: Strategy object based on depends_on:
|
||||
- No deps → `{ "strategy": "new" }`
|
||||
- 1 dep (single child) → `{ "strategy": "resume", "resume_from": "parent-cli-id" }`
|
||||
- 1 dep (multiple children) → `{ "strategy": "fork", "resume_from": "parent-cli-id" }`
|
||||
- N deps → `{ "strategy": "merge_fork", "merge_from": ["id1", "id2", ...] }`
|
||||
|
||||
**CLI Execution Strategy Rules**:
|
||||
1. **new**: Task has no dependencies - starts fresh CLI conversation
|
||||
2. **resume**: Task has 1 parent AND that parent has only this child - continues same conversation
|
||||
3. **fork**: Task has 1 parent BUT parent has multiple children - creates new branch with parent context
|
||||
4. **merge_fork**: Task has multiple parents - merges all parent contexts into new conversation
|
||||
|
||||
**Execution Command Patterns**:
|
||||
- new: `ccw cli -p "[prompt]" --tool [tool] --mode write --id [cli_execution_id]`
|
||||
- resume: `ccw cli -p "[prompt]" --resume [resume_from] --tool [tool] --mode write`
|
||||
- fork: `ccw cli -p "[prompt]" --resume [resume_from] --id [cli_execution_id] --tool [tool] --mode write`
|
||||
- merge_fork: `ccw cli -p "[prompt]" --resume [merge_from.join(',')] --id [cli_execution_id] --tool [tool] --mode write`
|
||||
|
||||
## QUALITY STANDARDS
|
||||
Hard Constraints:
|
||||
- Task count <= 18 (hard limit - request re-scope if exceeded)
|
||||
@@ -355,9 +203,7 @@ Hard Constraints:
|
||||
|
||||
**Condition**: `modules.length >= 2` (multi-module detected)
|
||||
|
||||
**Purpose**: Launch N action-planning-agents simultaneously, one per module, for parallel task JSON generation.
|
||||
|
||||
**Note**: Phase 2B agents generate Task JSONs ONLY. IMPL_PLAN.md and TODO_LIST.md are generated by Phase 3 Coordinator.
|
||||
**Purpose**: Launch N action-planning-agents simultaneously, one per module, for parallel task generation.
|
||||
|
||||
**Parallel Agent Invocation**:
|
||||
```javascript
|
||||
@@ -365,123 +211,27 @@ Hard Constraints:
|
||||
const planningTasks = modules.map(module =>
|
||||
Task(
|
||||
subagent_type="action-planning-agent",
|
||||
run_in_background=false,
|
||||
description=`Generate ${module.name} module task JSONs`,
|
||||
description=`Plan ${module.name} module`,
|
||||
prompt=`
|
||||
## TASK OBJECTIVE
|
||||
Generate task JSON files for ${module.name} module within workflow session
|
||||
|
||||
IMPORTANT: This is PLANNING ONLY - generate task JSONs, NOT implementing code.
|
||||
IMPORTANT: Generate Task JSONs ONLY. IMPL_PLAN.md and TODO_LIST.md by Phase 3 Coordinator.
|
||||
|
||||
CRITICAL: Follow the progressive loading strategy defined in agent specification (load analysis.md files incrementally due to file size)
|
||||
|
||||
## MODULE SCOPE
|
||||
## SCOPE
|
||||
- Module: ${module.name} (${module.type})
|
||||
- Focus Paths: ${module.paths.join(', ')}
|
||||
- Task ID Prefix: IMPL-${module.prefix}
|
||||
- Task Limit: ≤9 tasks (hard limit for this module)
|
||||
- Other Modules: ${otherModules.join(', ')} (reference only, do NOT generate tasks for them)
|
||||
- Task Limit: ≤9 tasks
|
||||
- Other Modules: ${otherModules.join(', ')}
|
||||
- Cross-module deps format: "CROSS::{module}::{pattern}"
|
||||
|
||||
## SESSION PATHS
|
||||
Input:
|
||||
- Session Metadata: .workflow/active/{session-id}/workflow-session.json
|
||||
- Context Package: .workflow/active/{session-id}/.process/context-package.json
|
||||
|
||||
Output:
|
||||
- Task Dir: .workflow/active/{session-id}/.task/
|
||||
|
||||
## CONTEXT METADATA
|
||||
Session ID: {session-id}
|
||||
MCP Capabilities: {exa_code, exa_web, code_index}
|
||||
|
||||
## USER CONFIGURATION (from Phase 0)
|
||||
Execution Method: ${userConfig.executionMethod} // agent|hybrid|cli
|
||||
Preferred CLI Tool: ${userConfig.preferredCliTool} // codex|gemini|qwen|auto
|
||||
Supplementary Materials: ${userConfig.supplementaryMaterials}
|
||||
|
||||
## CLI TOOL SELECTION
|
||||
Based on userConfig.executionMethod:
|
||||
- "agent": No command field in implementation_approach steps
|
||||
- "hybrid": Add command field to complex steps only (agent handles simple steps)
|
||||
- "cli": Add command field to ALL implementation_approach steps
|
||||
|
||||
CLI Resume Support (MANDATORY for all CLI commands):
|
||||
- Use --resume parameter to continue from previous task execution
|
||||
- Read previous task's cliExecutionId from session state
|
||||
- Format: ccw cli -p "[prompt]" --resume ${previousCliId} --tool ${tool} --mode write
|
||||
|
||||
## EXPLORATION CONTEXT (from context-package.exploration_results)
|
||||
- Load exploration_results from context-package.json
|
||||
- Filter for ${module.name} module: Use aggregated_insights.critical_files matching ${module.paths.join(', ')}
|
||||
- Apply module-relevant constraints from aggregated_insights.constraints
|
||||
- Reference aggregated_insights.all_patterns applicable to ${module.name}
|
||||
- Use aggregated_insights.all_integration_points for precise modification locations within module scope
|
||||
- Use conflict_indicators for risk-aware task sequencing
|
||||
|
||||
## CONFLICT RESOLUTION CONTEXT (if exists)
|
||||
- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path
|
||||
- If exists, load .process/conflict-resolution.json:
|
||||
- Apply planning_constraints relevant to ${module.name} as task constraints
|
||||
- Reference resolved_conflicts affecting ${module.name} for implementation approach alignment
|
||||
- Handle custom_conflicts with explicit task notes
|
||||
|
||||
## CROSS-MODULE DEPENDENCIES
|
||||
- For dependencies ON other modules: Use placeholder depends_on: ["CROSS::{module}::{pattern}"]
|
||||
- Example: depends_on: ["CROSS::B::api-endpoint"] (this module depends on B's api-endpoint task)
|
||||
- Phase 3 Coordinator resolves to actual task IDs
|
||||
- For dependencies FROM other modules: Document in task context as "provides_for" annotation
|
||||
|
||||
## EXPECTED DELIVERABLES
|
||||
Task JSON Files (.task/IMPL-${module.prefix}*.json):
|
||||
- 6-field schema (id, title, status, context_package_path, meta, context, flow_control)
|
||||
- Task ID format: IMPL-${module.prefix}1, IMPL-${module.prefix}2, ...
|
||||
- Quantified requirements with explicit counts
|
||||
- Artifacts integration from context package (filtered for ${module.name})
|
||||
- **focus_paths enhanced with exploration critical_files (module-scoped)**
|
||||
- Flow control with pre_analysis steps (include exploration integration_points analysis)
|
||||
- **CLI Execution IDs and strategies (MANDATORY)**
|
||||
- Focus ONLY on ${module.name} module scope
|
||||
|
||||
## CLI EXECUTION ID REQUIREMENTS (MANDATORY)
|
||||
Each task JSON MUST include:
|
||||
- **cli_execution_id**: Unique ID for CLI execution (format: `{session_id}-IMPL-${module.prefix}{seq}`)
|
||||
- **cli_execution**: Strategy object based on depends_on:
|
||||
- No deps → `{ "strategy": "new" }`
|
||||
- 1 dep (single child) → `{ "strategy": "resume", "resume_from": "parent-cli-id" }`
|
||||
- 1 dep (multiple children) → `{ "strategy": "fork", "resume_from": "parent-cli-id" }`
|
||||
- N deps → `{ "strategy": "merge_fork", "merge_from": ["id1", "id2", ...] }`
|
||||
- Cross-module dep → `{ "strategy": "cross_module_fork", "resume_from": "CROSS::{module}::{pattern}" }`
|
||||
|
||||
**CLI Execution Strategy Rules**:
|
||||
1. **new**: Task has no dependencies - starts fresh CLI conversation
|
||||
2. **resume**: Task has 1 parent AND that parent has only this child - continues same conversation
|
||||
3. **fork**: Task has 1 parent BUT parent has multiple children - creates new branch with parent context
|
||||
4. **merge_fork**: Task has multiple parents - merges all parent contexts into new conversation
|
||||
5. **cross_module_fork**: Task depends on task from another module - Phase 3 resolves placeholder
|
||||
|
||||
**Execution Command Patterns**:
|
||||
- new: `ccw cli -p "[prompt]" --tool [tool] --mode write --id [cli_execution_id]`
|
||||
- resume: `ccw cli -p "[prompt]" --resume [resume_from] --tool [tool] --mode write`
|
||||
- fork: `ccw cli -p "[prompt]" --resume [resume_from] --id [cli_execution_id] --tool [tool] --mode write`
|
||||
- merge_fork: `ccw cli -p "[prompt]" --resume [merge_from.join(',')] --id [cli_execution_id] --tool [tool] --mode write`
|
||||
- cross_module_fork: (Phase 3 resolves placeholder, then uses fork pattern)
|
||||
|
||||
## QUALITY STANDARDS
|
||||
Hard Constraints:
|
||||
- Task count <= 9 for this module (hard limit - coordinate with Phase 3 if exceeded)
|
||||
- All requirements quantified (explicit counts and enumerated lists)
|
||||
- Acceptance criteria measurable (include verification commands)
|
||||
- Artifact references mapped from context package (module-scoped filter)
|
||||
- Focus paths use absolute paths or clear relative paths from project root
|
||||
- Cross-module dependencies use CROSS:: placeholder format
|
||||
|
||||
## SUCCESS CRITERIA
|
||||
- Task JSONs saved to .task/ with IMPL-${module.prefix}* naming
|
||||
- All task JSONs include cli_execution_id and cli_execution strategy
|
||||
- Cross-module dependencies use CROSS:: placeholder format consistently
|
||||
- Focus paths scoped to ${module.paths.join(', ')} only
|
||||
- Return: task count, task IDs, dependency summary (internal + cross-module)
|
||||
## INSTRUCTIONS
|
||||
- Generate tasks ONLY for ${module.name} module
|
||||
- Use task ID format: IMPL-${module.prefix}1, IMPL-${module.prefix}2, ...
|
||||
- For cross-module dependencies, use: depends_on: ["CROSS::B::api-endpoint"]
|
||||
- Maximum 9 tasks per module
|
||||
`
|
||||
)
|
||||
);
|
||||
@@ -505,79 +255,37 @@ await Promise.all(planningTasks);
|
||||
- Prefix: A, B, C... (assigned by detection order)
|
||||
- Sequence: 1, 2, 3... (per-module increment)
|
||||
|
||||
### Phase 3: Integration (+1 Coordinator Agent, Multi-Module Only)
|
||||
### Phase 3: Integration (+1 Coordinator, Multi-Module Only)
|
||||
|
||||
**Condition**: Only executed when `modules.length >= 2`
|
||||
|
||||
**Purpose**: Collect all module tasks, resolve cross-module dependencies, generate unified IMPL_PLAN.md and TODO_LIST.md documents.
|
||||
**Purpose**: Collect all module tasks, resolve cross-module dependencies, generate unified documents.
|
||||
|
||||
**Coordinator Agent Invocation**:
|
||||
**Integration Logic**:
|
||||
```javascript
|
||||
// Wait for all Phase 2B agents to complete
|
||||
const moduleResults = await Promise.all(planningTasks);
|
||||
// 1. Collect all module task JSONs
|
||||
const allTasks = glob('.task/IMPL-*.json').map(loadJson);
|
||||
|
||||
// Launch +1 Coordinator Agent
|
||||
Task(
|
||||
subagent_type="action-planning-agent",
|
||||
run_in_background=false,
|
||||
description="Integrate module tasks and generate unified documents",
|
||||
prompt=`
|
||||
## TASK OBJECTIVE
|
||||
Integrate all module task JSONs, resolve cross-module dependencies, and generate unified IMPL_PLAN.md and TODO_LIST.md
|
||||
|
||||
IMPORTANT: This is INTEGRATION ONLY - consolidate existing task JSONs, NOT creating new tasks.
|
||||
|
||||
## SESSION PATHS
|
||||
Input:
|
||||
- Session Metadata: .workflow/active/{session-id}/workflow-session.json
|
||||
- Context Package: .workflow/active/{session-id}/.process/context-package.json
|
||||
- Task JSONs: .workflow/active/{session-id}/.task/IMPL-*.json (from Phase 2B)
|
||||
Output:
|
||||
- Updated Task JSONs: .workflow/active/{session-id}/.task/IMPL-*.json (resolved dependencies)
|
||||
- IMPL_PLAN: .workflow/active/{session-id}/IMPL_PLAN.md
|
||||
- TODO_LIST: .workflow/active/{session-id}/TODO_LIST.md
|
||||
|
||||
## CONTEXT METADATA
|
||||
Session ID: {session-id}
|
||||
Modules: ${modules.map(m => m.name + '(' + m.prefix + ')').join(', ')}
|
||||
Module Count: ${modules.length}
|
||||
|
||||
## INTEGRATION STEPS
|
||||
1. Collect all .task/IMPL-*.json, group by module prefix
|
||||
2. Resolve CROSS:: dependencies → actual task IDs, update task JSONs
|
||||
3. Generate IMPL_PLAN.md (multi-module format per agent specification)
|
||||
4. Generate TODO_LIST.md (hierarchical format per agent specification)
|
||||
|
||||
## CROSS-MODULE DEPENDENCY RESOLUTION
|
||||
- Pattern: CROSS::{module}::{pattern} → IMPL-{module}* matching title/context
|
||||
- Example: CROSS::B::api-endpoint → IMPL-B1 (if B1 title contains "api-endpoint")
|
||||
- Log unresolved as warnings
|
||||
|
||||
## EXPECTED DELIVERABLES
|
||||
1. Updated Task JSONs with resolved dependency IDs
|
||||
2. IMPL_PLAN.md - multi-module format with cross-dependency section
|
||||
3. TODO_LIST.md - hierarchical by module with cross-dependency section
|
||||
|
||||
## SUCCESS CRITERIA
|
||||
- No CROSS:: placeholders remaining in task JSONs
|
||||
- IMPL_PLAN.md and TODO_LIST.md generated with multi-module structure
|
||||
- Return: task count, per-module breakdown, resolved dependency count
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**Dependency Resolution Algorithm**:
|
||||
```javascript
|
||||
function resolveCrossModuleDependency(placeholder, allTasks) {
|
||||
const [, targetModule, pattern] = placeholder.match(/CROSS::(\w+)::(.+)/);
|
||||
const candidates = allTasks.filter(t =>
|
||||
t.id.startsWith(`IMPL-${targetModule}`) &&
|
||||
(t.title.toLowerCase().includes(pattern.toLowerCase()) ||
|
||||
t.context?.description?.toLowerCase().includes(pattern.toLowerCase()))
|
||||
);
|
||||
return candidates.length > 0
|
||||
? candidates.sort((a, b) => a.id.localeCompare(b.id))[0].id
|
||||
: placeholder; // Keep for manual resolution
|
||||
// 2. Resolve cross-module dependencies
|
||||
for (const task of allTasks) {
|
||||
if (task.depends_on) {
|
||||
task.depends_on = task.depends_on.map(dep => {
|
||||
if (dep.startsWith('CROSS::')) {
|
||||
// CROSS::B::api-endpoint → find matching IMPL-B* task
|
||||
const [, targetModule, pattern] = dep.match(/CROSS::(\w+)::(.+)/);
|
||||
return findTaskByModuleAndPattern(allTasks, targetModule, pattern);
|
||||
}
|
||||
return dep;
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// 3. Generate unified IMPL_PLAN.md (grouped by module)
|
||||
generateIMPL_PLAN(allTasks, modules);
|
||||
|
||||
// 4. Generate TODO_LIST.md (hierarchical structure)
|
||||
generateTODO_LIST(allTasks, modules);
|
||||
```
|
||||
|
||||
**Note**: IMPL_PLAN.md and TODO_LIST.md structure definitions are in `action-planning-agent.md`.
|
||||
|
||||
|
||||
@@ -1,16 +1,11 @@
|
||||
---
|
||||
name: task-generate-tdd
|
||||
description: Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation
|
||||
argument-hint: "[-y|--yes] --session WFS-session-id"
|
||||
argument-hint: "--session WFS-session-id"
|
||||
examples:
|
||||
- /workflow:tools:task-generate-tdd --session WFS-auth
|
||||
- /workflow:tools:task-generate-tdd -y --session WFS-auth
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Skip user questions, use defaults (no materials, Agent executor).
|
||||
|
||||
# Autonomous TDD Task Generation Command
|
||||
|
||||
## Overview
|
||||
@@ -83,176 +78,44 @@ Phase 2: Agent Execution (Document Generation)
|
||||
|
||||
## Execution Lifecycle
|
||||
|
||||
### Phase 0: User Configuration (Interactive)
|
||||
|
||||
**Purpose**: Collect user preferences before TDD task generation to ensure generated tasks match execution expectations and provide necessary supplementary context.
|
||||
|
||||
**User Questions**:
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "Do you have supplementary materials or guidelines to include?",
|
||||
header: "Materials",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "No additional materials", description: "Use existing context only" },
|
||||
{ label: "Provide file paths", description: "I'll specify paths to include" },
|
||||
{ label: "Provide inline content", description: "I'll paste content directly" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Select execution method for generated TDD tasks:",
|
||||
header: "Execution",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Agent (Recommended)", description: "Claude agent executes Red-Green-Refactor cycles directly" },
|
||||
{ label: "Hybrid", description: "Agent orchestrates, calls CLI for complex steps (Red/Green phases)" },
|
||||
{ label: "CLI Only", description: "All TDD cycles via CLI tools (codex/gemini/qwen)" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "If using CLI, which tool do you prefer?",
|
||||
header: "CLI Tool",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Codex (Recommended)", description: "Best for TDD Red-Green-Refactor cycles" },
|
||||
{ label: "Gemini", description: "Best for analysis and large context" },
|
||||
{ label: "Qwen", description: "Alternative analysis tool" },
|
||||
{ label: "Auto", description: "Let agent decide per-task" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**Handle Materials Response**:
|
||||
```javascript
|
||||
if (userConfig.materials === "Provide file paths") {
|
||||
// Follow-up question for file paths
|
||||
const pathsResponse = AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Enter file paths to include (comma-separated or one per line):",
|
||||
header: "Paths",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Enter paths", description: "Provide paths in text input" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
userConfig.supplementaryPaths = parseUserPaths(pathsResponse)
|
||||
}
|
||||
```
|
||||
|
||||
**Build userConfig**:
|
||||
```javascript
|
||||
const userConfig = {
|
||||
supplementaryMaterials: {
|
||||
type: "none|paths|inline",
|
||||
content: [...], // Parsed paths or inline content
|
||||
},
|
||||
executionMethod: "agent|hybrid|cli",
|
||||
preferredCliTool: "codex|gemini|qwen|auto",
|
||||
enableResume: true // Always enable resume for CLI executions
|
||||
}
|
||||
```
|
||||
|
||||
**Pass to Agent**: Include `userConfig` in agent prompt for Phase 2.
|
||||
|
||||
---
|
||||
|
||||
### Phase 1: Context Preparation & Discovery
|
||||
|
||||
**Command Responsibility**: Command prepares session paths and metadata, provides to agent for autonomous context loading.
|
||||
|
||||
### Phase 1: Discovery & Context Loading
|
||||
**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
|
||||
|
||||
**📊 Progressive Loading Strategy**: Load context incrementally due to large analysis.md file sizes:
|
||||
- **Core**: session metadata + context-package.json (always load)
|
||||
- **Selective**: synthesis_output OR (guidance + relevant role analyses) - NOT all role analyses
|
||||
- **On-Demand**: conflict resolution (if conflict_risk >= medium), test context
|
||||
|
||||
**🛤️ Path Clarity Requirement**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
|
||||
|
||||
**Session Path Structure** (Provided by Command to Agent):
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/
|
||||
├── workflow-session.json # Session metadata
|
||||
├── .process/
|
||||
│ ├── context-package.json # Context package with artifact catalog
|
||||
│ ├── test-context-package.json # Test coverage analysis
|
||||
│ └── conflict-resolution.json # Conflict resolution (if exists)
|
||||
├── .task/ # Output: Task JSON files
|
||||
│ ├── IMPL-1.json
|
||||
│ ├── IMPL-2.json
|
||||
│ └── ...
|
||||
├── IMPL_PLAN.md # Output: TDD implementation plan
|
||||
└── TODO_LIST.md # Output: TODO list with TDD phases
|
||||
```
|
||||
|
||||
**Command Preparation**:
|
||||
1. **Assemble Session Paths** for agent prompt:
|
||||
- `session_metadata_path`: `.workflow/active/{session-id}/workflow-session.json`
|
||||
- `context_package_path`: `.workflow/active/{session-id}/.process/context-package.json`
|
||||
- `test_context_package_path`: `.workflow/active/{session-id}/.process/test-context-package.json`
|
||||
- Output directory paths
|
||||
|
||||
2. **Provide Metadata** (simple values):
|
||||
- `session_id`: WFS-{session-id}
|
||||
- `workflow_type`: "tdd"
|
||||
- `mcp_capabilities`: {exa_code, exa_web, code_index}
|
||||
|
||||
3. **Pass userConfig** from Phase 0
|
||||
|
||||
**Agent Context Package** (Agent loads autonomously):
|
||||
**Agent Context Package**:
|
||||
```javascript
|
||||
{
|
||||
"session_id": "WFS-[session-id]",
|
||||
"workflow_type": "tdd",
|
||||
|
||||
// Core (ALWAYS load)
|
||||
// Note: CLI tool usage is determined semantically by action-planning-agent based on user's task description
|
||||
"session_metadata": {
|
||||
// If in memory: use cached content
|
||||
// Else: Load from workflow-session.json
|
||||
// Else: Load from .workflow/active//{session-id}/workflow-session.json
|
||||
},
|
||||
"context_package": {
|
||||
// If in memory: use cached content
|
||||
// Else: Load from context-package.json
|
||||
},
|
||||
|
||||
// Selective (load based on progressive strategy)
|
||||
"brainstorm_artifacts": {
|
||||
// Loaded from context-package.json → brainstorm_artifacts section
|
||||
"synthesis_output": {"path": "...", "exists": true}, // Load if exists (highest priority)
|
||||
"guidance_specification": {"path": "...", "exists": true}, // Load if no synthesis
|
||||
"role_analyses": [ // Load SELECTIVELY based on task relevance
|
||||
"role_analyses": [
|
||||
{
|
||||
"role": "system-architect",
|
||||
"files": [{"path": "...", "type": "primary|supplementary"}]
|
||||
}
|
||||
]
|
||||
],
|
||||
"guidance_specification": {"path": "...", "exists": true},
|
||||
"synthesis_output": {"path": "...", "exists": true},
|
||||
"conflict_resolution": {"path": "...", "exists": true} // if conflict_risk >= medium
|
||||
},
|
||||
|
||||
// On-Demand (load if exists)
|
||||
"context_package_path": ".workflow/active//{session-id}/.process/context-package.json",
|
||||
"context_package": {
|
||||
// If in memory: use cached content
|
||||
// Else: Load from .workflow/active//{session-id}/.process/context-package.json
|
||||
},
|
||||
"test_context_package_path": ".workflow/active//{session-id}/.process/test-context-package.json",
|
||||
"test_context_package": {
|
||||
// Load from test-context-package.json
|
||||
// Contains existing test patterns and coverage analysis
|
||||
// Existing test patterns and coverage analysis
|
||||
},
|
||||
"conflict_resolution": {
|
||||
// Load from conflict-resolution.json if conflict_risk >= medium
|
||||
// Check context-package.conflict_detection.resolution_file
|
||||
},
|
||||
|
||||
// Capabilities
|
||||
"mcp_capabilities": {
|
||||
"code_index": true,
|
||||
"exa_code": true,
|
||||
"exa_web": true,
|
||||
"code_index": true
|
||||
},
|
||||
|
||||
// User configuration from Phase 0
|
||||
"user_config": {
|
||||
// From Phase 0 AskUserQuestion
|
||||
"exa_web": true
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -261,21 +124,21 @@ const userConfig = {
|
||||
1. **Load Session Context** (if not in memory)
|
||||
```javascript
|
||||
if (!memory.has("workflow-session.json")) {
|
||||
Read(.workflow/active/{session-id}/workflow-session.json)
|
||||
Read(.workflow/active//{session-id}/workflow-session.json)
|
||||
}
|
||||
```
|
||||
|
||||
2. **Load Context Package** (if not in memory)
|
||||
```javascript
|
||||
if (!memory.has("context-package.json")) {
|
||||
Read(.workflow/active/{session-id}/.process/context-package.json)
|
||||
Read(.workflow/active//{session-id}/.process/context-package.json)
|
||||
}
|
||||
```
|
||||
|
||||
3. **Load Test Context Package** (if not in memory)
|
||||
```javascript
|
||||
if (!memory.has("test-context-package.json")) {
|
||||
Read(.workflow/active/{session-id}/.process/test-context-package.json)
|
||||
Read(.workflow/active//{session-id}/.process/test-context-package.json)
|
||||
}
|
||||
```
|
||||
|
||||
@@ -289,14 +152,9 @@ const userConfig = {
|
||||
roleAnalysisPaths.forEach(path => Read(path));
|
||||
```
|
||||
|
||||
5. **Load Conflict Resolution** (from conflict-resolution.json, if exists)
|
||||
5. **Load Conflict Resolution** (from context-package.json, if exists)
|
||||
```javascript
|
||||
// Check for new conflict-resolution.json format
|
||||
if (contextPackage.conflict_detection?.resolution_file) {
|
||||
Read(contextPackage.conflict_detection.resolution_file) // .process/conflict-resolution.json
|
||||
}
|
||||
// Fallback: legacy brainstorm_artifacts path
|
||||
else if (contextPackage.brainstorm_artifacts?.conflict_resolution?.exists) {
|
||||
if (contextPackage.brainstorm_artifacts.conflict_resolution?.exists) {
|
||||
Read(contextPackage.brainstorm_artifacts.conflict_resolution.path)
|
||||
}
|
||||
```
|
||||
@@ -317,84 +175,73 @@ const userConfig = {
|
||||
)
|
||||
```
|
||||
|
||||
### Phase 2: Agent Execution (TDD Document Generation)
|
||||
### Phase 2: Agent Execution (Document Generation)
|
||||
|
||||
**Purpose**: Generate TDD planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) - planning only, NOT code implementation.
|
||||
**Pre-Agent Template Selection** (Command decides path before invoking agent):
|
||||
```javascript
|
||||
// Command checks flag and selects template PATH (not content)
|
||||
const templatePath = hasCliExecuteFlag
|
||||
? "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt"
|
||||
: "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt";
|
||||
```
|
||||
|
||||
**Agent Invocation**:
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="action-planning-agent",
|
||||
run_in_background=false,
|
||||
description="Generate TDD planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)",
|
||||
description="Generate TDD task JSON and implementation plan",
|
||||
prompt=`
|
||||
## TASK OBJECTIVE
|
||||
Generate TDD implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for workflow session
|
||||
## Execution Context
|
||||
|
||||
IMPORTANT: This is PLANNING ONLY - you are generating planning documents, NOT implementing code.
|
||||
**Session ID**: WFS-{session-id}
|
||||
**Workflow Type**: TDD
|
||||
**Note**: CLI tool usage is determined semantically from user's task description
|
||||
|
||||
CRITICAL: Follow the progressive loading strategy (load analysis.md files incrementally due to file size):
|
||||
- **Core**: session metadata + context-package.json (always)
|
||||
- **Selective**: synthesis_output OR (guidance + relevant role analyses) - NOT all
|
||||
- **On-Demand**: conflict resolution (if conflict_risk >= medium), test context
|
||||
## Phase 1: Discovery Results (Provided Context)
|
||||
|
||||
## SESSION PATHS
|
||||
Input:
|
||||
- Session Metadata: .workflow/active/{session-id}/workflow-session.json
|
||||
- Context Package: .workflow/active/{session-id}/.process/context-package.json
|
||||
- Test Context: .workflow/active/{session-id}/.process/test-context-package.json
|
||||
### Session Metadata
|
||||
{session_metadata_content}
|
||||
|
||||
Output:
|
||||
- Task Dir: .workflow/active/{session-id}/.task/
|
||||
- IMPL_PLAN: .workflow/active/{session-id}/IMPL_PLAN.md
|
||||
- TODO_LIST: .workflow/active/{session-id}/TODO_LIST.md
|
||||
### Role Analyses (Enhanced by Synthesis)
|
||||
{role_analyses_content}
|
||||
- Includes requirements, design specs, enhancements, and clarifications from synthesis phase
|
||||
|
||||
## CONTEXT METADATA
|
||||
Session ID: {session-id}
|
||||
Workflow Type: TDD
|
||||
MCP Capabilities: {exa_code, exa_web, code_index}
|
||||
### Artifacts Inventory
|
||||
- **Guidance Specification**: {guidance_spec_path}
|
||||
- **Role Analyses**: {role_analyses_list}
|
||||
|
||||
## USER CONFIGURATION (from Phase 0)
|
||||
Execution Method: ${userConfig.executionMethod} // agent|hybrid|cli
|
||||
Preferred CLI Tool: ${userConfig.preferredCliTool} // codex|gemini|qwen|auto
|
||||
Supplementary Materials: ${userConfig.supplementaryMaterials}
|
||||
### Context Package
|
||||
{context_package_summary}
|
||||
- Includes conflict_risk assessment
|
||||
|
||||
## CLI TOOL SELECTION
|
||||
Based on userConfig.executionMethod:
|
||||
- "agent": No command field in implementation_approach steps
|
||||
- "hybrid": Add command field to complex steps only (Red/Green phases recommended for CLI)
|
||||
- "cli": Add command field to ALL Red-Green-Refactor steps
|
||||
### Test Context Package
|
||||
{test_context_package_summary}
|
||||
- Existing test patterns, framework config, coverage analysis
|
||||
|
||||
CLI Resume Support (MANDATORY for all CLI commands):
|
||||
- Use --resume parameter to continue from previous task execution
|
||||
- Read previous task's cliExecutionId from session state
|
||||
- Format: ccw cli -p "[prompt]" --resume [previousCliId] --tool [tool] --mode write
|
||||
### Conflict Resolution (Conditional)
|
||||
If conflict_risk was medium/high, modifications have been applied to:
|
||||
- **guidance-specification.md**: Design decisions updated to resolve conflicts
|
||||
- **Role analyses (*.md)**: Recommendations adjusted for compatibility
|
||||
- **context-package.json**: Marked as "resolved" with conflict IDs
|
||||
- NO separate CONFLICT_RESOLUTION.md file (conflicts resolved in-place)
|
||||
|
||||
## EXPLORATION CONTEXT (from context-package.exploration_results)
|
||||
- Load exploration_results from context-package.json
|
||||
- Use aggregated_insights.critical_files for focus_paths generation
|
||||
- Apply aggregated_insights.constraints to acceptance criteria
|
||||
- Reference aggregated_insights.all_patterns for implementation approach
|
||||
- Use aggregated_insights.all_integration_points for precise modification locations
|
||||
- Use conflict_indicators for risk-aware task sequencing
|
||||
### MCP Analysis Results (Optional)
|
||||
**Code Structure**: {mcp_code_index_results}
|
||||
**External Research**: {mcp_exa_research_results}
|
||||
|
||||
## CONFLICT RESOLUTION CONTEXT (if exists)
|
||||
- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path
|
||||
- If exists, load .process/conflict-resolution.json:
|
||||
- Apply planning_constraints as task constraints (for brainstorm-less workflows)
|
||||
- Reference resolved_conflicts for implementation approach alignment
|
||||
- Handle custom_conflicts with explicit task notes
|
||||
|
||||
## TEST CONTEXT INTEGRATION
|
||||
- Load test-context-package.json for existing test patterns and coverage analysis
|
||||
- Extract test framework configuration (Jest/Pytest/etc.)
|
||||
- Identify existing test conventions and patterns
|
||||
- Map coverage gaps to TDD Red phase test targets
|
||||
|
||||
## TDD DOCUMENT GENERATION TASK
|
||||
## Phase 2: TDD Document Generation Task
|
||||
|
||||
**Agent Configuration Reference**: All TDD task generation rules, quantification requirements, Red-Green-Refactor cycle structure, quality standards, and execution details are defined in action-planning-agent.
|
||||
|
||||
Refer to: @.claude/agents/action-planning-agent.md for:
|
||||
- TDD Task Decomposition Standards
|
||||
- Red-Green-Refactor Cycle Requirements
|
||||
- Quantification Requirements (MANDATORY)
|
||||
- 5-Field Task JSON Schema
|
||||
- IMPL_PLAN.md Structure (TDD variant)
|
||||
- TODO_LIST.md Format
|
||||
- TDD Execution Flow & Quality Validation
|
||||
|
||||
### TDD-Specific Requirements Summary
|
||||
|
||||
#### Task Structure Philosophy
|
||||
@@ -412,61 +259,31 @@ CLI Resume Support (MANDATORY for all CLI commands):
|
||||
#### Required Outputs Summary
|
||||
|
||||
##### 1. TDD Task JSON Files (.task/IMPL-*.json)
|
||||
- **Location**: `.workflow/active/{session-id}/.task/`
|
||||
- **Schema**: 6-field structure with TDD-specific metadata
|
||||
- `id, title, status, context_package_path, meta, context, flow_control`
|
||||
- **Location**: `.workflow/active//{session-id}/.task/`
|
||||
- **Schema**: 5-field structure with TDD-specific metadata
|
||||
- `meta.tdd_workflow`: true (REQUIRED)
|
||||
- `meta.max_iterations`: 3 (Green phase test-fix cycle limit)
|
||||
- `meta.cli_execution_id`: Unique CLI execution ID (format: `{session_id}-{task_id}`)
|
||||
- `meta.cli_execution`: Strategy object (new|resume|fork|merge_fork)
|
||||
- `context.tdd_cycles`: Array with quantified test cases and coverage
|
||||
- `context.focus_paths`: Absolute or clear relative paths (enhanced with exploration critical_files)
|
||||
- `flow_control.implementation_approach`: Exactly 3 steps with `tdd_phase` field
|
||||
1. Red Phase (`tdd_phase: "red"`): Write failing tests
|
||||
2. Green Phase (`tdd_phase: "green"`): Implement to pass tests
|
||||
3. Refactor Phase (`tdd_phase: "refactor"`): Improve code quality
|
||||
- `flow_control.pre_analysis`: Include exploration integration_points analysis
|
||||
- CLI tool usage based on userConfig (add `command` field per executionMethod)
|
||||
- CLI tool usage determined semantically (add `command` field when user requests CLI execution)
|
||||
- **Details**: See action-planning-agent.md § TDD Task JSON Generation
|
||||
|
||||
##### 2. IMPL_PLAN.md (TDD Variant)
|
||||
- **Location**: `.workflow/active/{session-id}/IMPL_PLAN.md`
|
||||
- **Location**: `.workflow/active//{session-id}/IMPL_PLAN.md`
|
||||
- **Template**: `~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt`
|
||||
- **TDD-Specific Frontmatter**: workflow_type="tdd", tdd_workflow=true, feature_count, task_breakdown
|
||||
- **TDD Implementation Tasks Section**: Feature-by-feature with internal Red-Green-Refactor cycles
|
||||
- **Context Analysis**: Artifact references and exploration insights
|
||||
- **Details**: See action-planning-agent.md § TDD Implementation Plan Creation
|
||||
|
||||
##### 3. TODO_LIST.md
|
||||
- **Location**: `.workflow/active/{session-id}/TODO_LIST.md`
|
||||
- **Location**: `.workflow/active//{session-id}/TODO_LIST.md`
|
||||
- **Format**: Hierarchical task list with internal TDD phase indicators (Red → Green → Refactor)
|
||||
- **Status**: ▸ (container), [ ] (pending), [x] (completed)
|
||||
- **Links**: Task JSON references and summaries
|
||||
- **Details**: See action-planning-agent.md § TODO List Generation
|
||||
|
||||
### CLI EXECUTION ID REQUIREMENTS (MANDATORY)
|
||||
|
||||
Each task JSON MUST include:
|
||||
- **meta.cli_execution_id**: Unique ID for CLI execution (format: `{session_id}-{task_id}`)
|
||||
- **meta.cli_execution**: Strategy object based on depends_on:
|
||||
- No deps → `{ "strategy": "new" }`
|
||||
- 1 dep (single child) → `{ "strategy": "resume", "resume_from": "parent-cli-id" }`
|
||||
- 1 dep (multiple children) → `{ "strategy": "fork", "resume_from": "parent-cli-id" }`
|
||||
- N deps → `{ "strategy": "merge_fork", "resume_from": ["id1", "id2", ...] }`
|
||||
- **Type**: `resume_from: string | string[]` (string for resume/fork, array for merge_fork)
|
||||
|
||||
**CLI Execution Strategy Rules**:
|
||||
1. **new**: Task has no dependencies - starts fresh CLI conversation
|
||||
2. **resume**: Task has 1 parent AND that parent has only this child - continues same conversation
|
||||
3. **fork**: Task has 1 parent BUT parent has multiple children - creates new branch with parent context
|
||||
4. **merge_fork**: Task has multiple parents - merges all parent contexts into new conversation
|
||||
|
||||
**Execution Command Patterns**:
|
||||
- new: `ccw cli -p "[prompt]" --tool [tool] --mode write --id [cli_execution_id]`
|
||||
- resume: `ccw cli -p "[prompt]" --resume [resume_from] --tool [tool] --mode write`
|
||||
- fork: `ccw cli -p "[prompt]" --resume [resume_from] --id [cli_execution_id] --tool [tool] --mode write`
|
||||
- merge_fork: `ccw cli -p "[prompt]" --resume [resume_from.join(',')] --id [cli_execution_id] --tool [tool] --mode write` (resume_from is array)
|
||||
|
||||
### Quantification Requirements (MANDATORY)
|
||||
|
||||
**Core Rules**:
|
||||
@@ -488,7 +305,6 @@ Each task JSON MUST include:
|
||||
- [ ] Every acceptance criterion includes measurable coverage percentage
|
||||
- [ ] tdd_cycles array contains test_count and test_cases for each cycle
|
||||
- [ ] No vague language ("comprehensive", "complete", "thorough")
|
||||
- [ ] cli_execution_id and cli_execution strategy assigned to each task
|
||||
|
||||
### Agent Execution Summary
|
||||
|
||||
@@ -504,34 +320,20 @@ Each task JSON MUST include:
|
||||
- ✓ Quantification requirements enforced (explicit counts, measurable acceptance, exact targets)
|
||||
- ✓ Task count ≤18 (hard limit)
|
||||
- ✓ Each task has meta.tdd_workflow: true
|
||||
- ✓ Each task has exactly 3 implementation steps with tdd_phase field ("red", "green", "refactor")
|
||||
- ✓ Each task has meta.cli_execution_id and meta.cli_execution strategy
|
||||
- ✓ Green phase includes test-fix cycle logic with max_iterations
|
||||
- ✓ focus_paths are absolute or clear relative paths (from exploration critical_files)
|
||||
- ✓ Artifact references mapped correctly from context package
|
||||
- ✓ Exploration context integrated (critical_files, constraints, patterns, integration_points)
|
||||
- ✓ Conflict resolution context applied (if conflict_risk >= medium)
|
||||
- ✓ Test context integrated (existing test patterns and coverage analysis)
|
||||
- ✓ Each task has exactly 3 implementation steps with tdd_phase field
|
||||
- ✓ Green phase includes test-fix cycle logic
|
||||
- ✓ Artifact references mapped correctly
|
||||
- ✓ MCP tool integration added
|
||||
- ✓ Documents follow TDD template structure
|
||||
- ✓ CLI tool selection based on userConfig.executionMethod
|
||||
|
||||
## SUCCESS CRITERIA
|
||||
- All planning documents generated successfully:
|
||||
- Task JSONs valid and saved to .task/ directory with cli_execution_id
|
||||
- IMPL_PLAN.md created with complete TDD structure
|
||||
- TODO_LIST.md generated matching task JSONs
|
||||
- CLI execution strategies assigned based on task dependencies
|
||||
- Return completion status with document count and task breakdown summary
|
||||
## Output
|
||||
|
||||
## OUTPUT SUMMARY
|
||||
Generate all three documents and report:
|
||||
- TDD task JSON files created: N files (IMPL-*.json) with cli_execution_id assigned
|
||||
Generate all three documents and report completion status:
|
||||
- TDD task JSON files created: N files (IMPL-*.json)
|
||||
- TDD cycles configured: N cycles with quantified test cases
|
||||
- CLI execution strategies: new/resume/fork/merge_fork assigned per dependency graph
|
||||
- Artifacts integrated: synthesis-spec/guidance-specification, relevant role analyses
|
||||
- Exploration context: critical_files, constraints, patterns, integration_points
|
||||
- Artifacts integrated: synthesis-spec, guidance-specification, N role analyses
|
||||
- Test context integrated: existing patterns and coverage
|
||||
- Conflict resolution: applied (if conflict_risk >= medium)
|
||||
- MCP enhancements: code-index, exa-research
|
||||
- Session ready for TDD execution: /workflow:execute
|
||||
`
|
||||
)
|
||||
@@ -539,64 +341,48 @@ Generate all three documents and report:
|
||||
|
||||
### Agent Context Passing
|
||||
|
||||
**Context Delegation Model**: Command provides paths and metadata, agent loads context autonomously using progressive loading strategy.
|
||||
|
||||
**Command Provides** (in agent prompt):
|
||||
**Memory-Aware Context Assembly**:
|
||||
```javascript
|
||||
// Command assembles these simple values and paths for agent
|
||||
const commandProvides = {
|
||||
// Session paths
|
||||
session_metadata_path: ".workflow/active/WFS-{id}/workflow-session.json",
|
||||
context_package_path: ".workflow/active/WFS-{id}/.process/context-package.json",
|
||||
test_context_package_path: ".workflow/active/WFS-{id}/.process/test-context-package.json",
|
||||
output_task_dir: ".workflow/active/WFS-{id}/.task/",
|
||||
output_impl_plan: ".workflow/active/WFS-{id}/IMPL_PLAN.md",
|
||||
output_todo_list: ".workflow/active/WFS-{id}/TODO_LIST.md",
|
||||
|
||||
// Simple metadata
|
||||
session_id: "WFS-{id}",
|
||||
// Assemble context package for agent
|
||||
const agentContext = {
|
||||
session_id: "WFS-[id]",
|
||||
workflow_type: "tdd",
|
||||
mcp_capabilities: { exa_code: true, exa_web: true, code_index: true },
|
||||
|
||||
// User configuration from Phase 0
|
||||
user_config: {
|
||||
supplementaryMaterials: { type: "...", content: [...] },
|
||||
executionMethod: "agent|hybrid|cli",
|
||||
preferredCliTool: "codex|gemini|qwen|auto",
|
||||
enableResume: true
|
||||
}
|
||||
// Use memory if available, else load
|
||||
session_metadata: memory.has("workflow-session.json")
|
||||
? memory.get("workflow-session.json")
|
||||
: Read(.workflow/active/WFS-[id]/workflow-session.json),
|
||||
|
||||
context_package_path: ".workflow/active/WFS-[id]/.process/context-package.json",
|
||||
|
||||
context_package: memory.has("context-package.json")
|
||||
? memory.get("context-package.json")
|
||||
: Read(".workflow/active/WFS-[id]/.process/context-package.json"),
|
||||
|
||||
test_context_package_path: ".workflow/active/WFS-[id]/.process/test-context-package.json",
|
||||
|
||||
test_context_package: memory.has("test-context-package.json")
|
||||
? memory.get("test-context-package.json")
|
||||
: Read(".workflow/active/WFS-[id]/.process/test-context-package.json"),
|
||||
|
||||
// Extract brainstorm artifacts from context package
|
||||
brainstorm_artifacts: extractBrainstormArtifacts(context_package),
|
||||
|
||||
// Load role analyses using paths from context package
|
||||
role_analyses: brainstorm_artifacts.role_analyses
|
||||
.flatMap(role => role.files)
|
||||
.map(file => Read(file.path)),
|
||||
|
||||
// Load conflict resolution if exists (from context package)
|
||||
conflict_resolution: brainstorm_artifacts.conflict_resolution?.exists
|
||||
? Read(brainstorm_artifacts.conflict_resolution.path)
|
||||
: null,
|
||||
|
||||
// Optional MCP enhancements
|
||||
mcp_analysis: executeMcpDiscovery()
|
||||
}
|
||||
```
|
||||
|
||||
**Agent Loads Autonomously** (progressive loading):
|
||||
```javascript
|
||||
// Agent executes progressive loading based on memory state
|
||||
const agentLoads = {
|
||||
// Core (ALWAYS load if not in memory)
|
||||
session_metadata: loadIfNotInMemory(session_metadata_path),
|
||||
context_package: loadIfNotInMemory(context_package_path),
|
||||
|
||||
// Selective (based on progressive strategy)
|
||||
// Priority: synthesis_output > guidance + relevant_role_analyses
|
||||
brainstorm_content: loadSelectiveBrainstormArtifacts(context_package),
|
||||
|
||||
// On-Demand (load if exists and relevant)
|
||||
test_context: loadIfExists(test_context_package_path),
|
||||
conflict_resolution: loadConflictResolution(context_package),
|
||||
|
||||
// Optional (if MCP available)
|
||||
exploration_results: extractExplorationResults(context_package),
|
||||
external_research: executeMcpResearch() // If needed
|
||||
}
|
||||
```
|
||||
|
||||
**Progressive Loading Implementation** (agent responsibility):
|
||||
1. **Check memory first** - skip if already loaded
|
||||
2. **Load core files** - session metadata + context-package.json
|
||||
3. **Smart selective loading** - synthesis_output OR (guidance + task-relevant role analyses)
|
||||
4. **On-demand loading** - test context, conflict resolution (if conflict_risk >= medium)
|
||||
5. **Extract references** - exploration results, artifact paths from context package
|
||||
|
||||
## TDD Task Structure Reference
|
||||
|
||||
This section provides quick reference for TDD task JSON structure. For complete implementation details, see the agent invocation prompt in Phase 2 above.
|
||||
@@ -604,31 +390,14 @@ This section provides quick reference for TDD task JSON structure. For complete
|
||||
**Quick Reference**:
|
||||
- Each TDD task contains complete Red-Green-Refactor cycle
|
||||
- Task ID format: `IMPL-N` (simple) or `IMPL-N.M` (complex subtasks)
|
||||
- Required metadata:
|
||||
- `meta.tdd_workflow: true`
|
||||
- `meta.max_iterations: 3`
|
||||
- `meta.cli_execution_id: "{session_id}-{task_id}"`
|
||||
- `meta.cli_execution: { "strategy": "new|resume|fork|merge_fork", ... }`
|
||||
- Context: `tdd_cycles` array with quantified test cases and coverage:
|
||||
```javascript
|
||||
tdd_cycles: [
|
||||
{
|
||||
test_count: 5, // Number of test cases to write
|
||||
test_cases: ["case1", "case2"], // Enumerated test scenarios
|
||||
implementation_scope: "...", // Files and functions to implement
|
||||
expected_coverage: ">=85%" // Coverage target
|
||||
}
|
||||
]
|
||||
```
|
||||
- Context: `focus_paths` use absolute or clear relative paths
|
||||
- Flow control: Exactly 3 steps with `tdd_phase` field ("red", "green", "refactor")
|
||||
- Flow control: `pre_analysis` includes exploration integration_points analysis
|
||||
- Command field: Added per `userConfig.executionMethod` (agent/hybrid/cli)
|
||||
- Required metadata: `meta.tdd_workflow: true`, `meta.max_iterations: 3`
|
||||
- Flow control: Exactly 3 steps with `tdd_phase` field (red, green, refactor)
|
||||
- Context: `tdd_cycles` array with quantified test cases and coverage
|
||||
- See Phase 2 agent prompt for full schema and requirements
|
||||
|
||||
## Output Files Structure
|
||||
```
|
||||
.workflow/active/{session-id}/
|
||||
.workflow/active//{session-id}/
|
||||
├── IMPL_PLAN.md # Unified plan with TDD Implementation Tasks section
|
||||
├── TODO_LIST.md # Progress tracking with internal TDD phase indicators
|
||||
├── .task/
|
||||
@@ -639,7 +408,7 @@ This section provides quick reference for TDD task JSON structure. For complete
|
||||
│ ├── IMPL-3.2.json # Complex feature subtask (if needed)
|
||||
│ └── ...
|
||||
└── .process/
|
||||
├── conflict-resolution.json # Conflict resolution results (if conflict_risk ≥ medium)
|
||||
├── CONFLICT_RESOLUTION.md # Conflict resolution strategies (if conflict_risk ≥ medium)
|
||||
├── test-context-package.json # Test coverage analysis
|
||||
├── context-package.json # Input from context-gather
|
||||
├── context_package_path # Path to smart context package
|
||||
@@ -664,9 +433,9 @@ This section provides quick reference for TDD task JSON structure. For complete
|
||||
- No circular dependencies allowed
|
||||
|
||||
### Task Limits
|
||||
- Maximum 18 total tasks (simple + subtasks) - hard limit for TDD workflows
|
||||
- Flat hierarchy (≤5 tasks) or two-level (6-18 tasks with containers)
|
||||
- Re-scope requirements if >18 tasks needed
|
||||
- Maximum 10 total tasks (simple + subtasks)
|
||||
- Flat hierarchy (≤5 tasks) or two-level (6-10 tasks with containers)
|
||||
- Re-scope requirements if >10 tasks needed
|
||||
|
||||
### TDD Workflow Validation
|
||||
- `meta.tdd_workflow` must be true
|
||||
@@ -686,7 +455,7 @@ This section provides quick reference for TDD task JSON structure. For complete
|
||||
### TDD Generation Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Task count exceeds 18 | Too many features or subtasks | Re-scope requirements or merge features into multiple TDD sessions |
|
||||
| Task count exceeds 10 | Too many features or subtasks | Re-scope requirements or merge features |
|
||||
| Missing test framework | No test config | Configure testing first |
|
||||
| Invalid TDD workflow | Missing tdd_phase or incomplete flow_control | Fix TDD structure in ANALYSIS_RESULTS.md |
|
||||
| Missing tdd_workflow flag | Task doesn't have meta.tdd_workflow: true | Add TDD workflow metadata |
|
||||
@@ -744,6 +513,6 @@ IMPL (Green phase) tasks include automatic test-fix cycle:
|
||||
|
||||
|
||||
## Configuration Options
|
||||
- **meta.max_iterations**: Number of fix attempts in Green phase (default: 3)
|
||||
- **meta.max_iterations**: Number of fix attempts (default: 3 for TDD, 5 for test-gen)
|
||||
- **CLI tool usage**: Determined semantically from user's task description via `command` field in implementation_approach
|
||||
|
||||
|
||||
@@ -76,7 +76,6 @@ Phase 3: Output Validation (Command)
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-execution-agent",
|
||||
run_in_background=false,
|
||||
description="Analyze test coverage gaps and generate test strategy",
|
||||
prompt=`
|
||||
## TASK OBJECTIVE
|
||||
@@ -90,7 +89,7 @@ Template: ~/.claude/workflows/cli-templates/prompts/test/test-concept-analysis.t
|
||||
|
||||
## EXECUTION STEPS
|
||||
1. Execute Gemini analysis:
|
||||
ccw cli -p "..." --tool gemini --mode write --rule test-test-concept-analysis --cd .workflow/active/{test_session_id}/.process
|
||||
cd .workflow/active/{test_session_id}/.process && gemini -p "$(cat ~/.claude/workflows/cli-templates/prompts/test/test-concept-analysis.txt)" --approval-mode yolo
|
||||
|
||||
2. Generate TEST_ANALYSIS_RESULTS.md:
|
||||
Synthesize gemini-test-analysis.md into standardized format for task generation
|
||||
|
||||
@@ -14,7 +14,7 @@ allowed-tools: Task(*), Read(*), Glob(*)
|
||||
|
||||
Orchestrator command that invokes `test-context-search-agent` to gather comprehensive test coverage context for test generation workflows. Generates standardized `test-context-package.json` with coverage analysis, framework detection, and source implementation context.
|
||||
|
||||
|
||||
**Agent**: `test-context-search-agent` (`.claude/agents/test-context-search-agent.md`)
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
@@ -86,9 +86,9 @@ if (file_exists(testContextPath)) {
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="test-context-search-agent",
|
||||
run_in_background=false,
|
||||
description="Gather test coverage context",
|
||||
prompt=`
|
||||
You are executing as test-context-search-agent (.claude/agents/test-context-search-agent.md).
|
||||
|
||||
## Execution Mode
|
||||
**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
|
||||
@@ -228,7 +228,7 @@ Refer to `test-context-search-agent.md` Phase 3.2 for complete `test-context-pac
|
||||
## Notes
|
||||
|
||||
- **Detection-first**: Always check for existing test-context-package before invoking agent
|
||||
|
||||
- **Agent autonomy**: Agent handles all coverage analysis logic per `.claude/agents/test-context-search-agent.md`
|
||||
- **No redundancy**: This command is a thin orchestrator, all logic in agent
|
||||
- **Framework agnostic**: Supports Jest, Mocha, pytest, RSpec, Go testing, etc.
|
||||
- **Coverage focus**: Primary goal is identifying implementation files without tests
|
||||
|
||||
@@ -94,7 +94,6 @@ Phase 2: Test Document Generation (Agent)
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="action-planning-agent",
|
||||
run_in_background=false,
|
||||
description="Generate test planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)",
|
||||
prompt=`
|
||||
## TASK OBJECTIVE
|
||||
@@ -107,6 +106,8 @@ CRITICAL:
|
||||
- Follow the progressive loading strategy defined in your agent specification (load context incrementally from memory-first approach)
|
||||
|
||||
## AGENT CONFIGURATION REFERENCE
|
||||
All test task generation rules, schemas, and quality standards are defined in your agent specification:
|
||||
@.claude/agents/action-planning-agent.md
|
||||
|
||||
Refer to your specification for:
|
||||
- Test Task JSON Schema (6-field structure with test-specific metadata)
|
||||
|
||||
@@ -1,14 +1,10 @@
|
||||
---
|
||||
name: animation-extract
|
||||
description: Extract animation and transition patterns from prompt inference and image references for design system documentation
|
||||
argument-hint: "[-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--focus "<types>"] [--interactive] [--refine]"
|
||||
argument-hint: "[--design-id <id>] [--session <id>] [--images "<glob>"] [--focus "<types>"] [--interactive] [--refine]"
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), AskUserQuestion(*), Task(ui-design-agent)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Skip all clarification questions, use AI-inferred animation decisions.
|
||||
|
||||
# Animation Extraction Command
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -27,8 +27,8 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
|
||||
6. **Phase 10 (ui-assembly)** → **Attach tasks → Execute → Collapse** → Workflow complete
|
||||
|
||||
**Phase Transition Mechanism**:
|
||||
- **Phase 5 (User Interaction)**: User confirms targets → IMMEDIATELY executes Phase 7
|
||||
- **Phase 7-10 (Autonomous)**: SlashCommand execute **ATTACHES** tasks to current workflow
|
||||
- **Phase 5 (User Interaction)**: User confirms targets → IMMEDIATELY dispatches Phase 7
|
||||
- **Phase 7-10 (Autonomous)**: SlashCommand dispatch **ATTACHES** tasks to current workflow
|
||||
- **Task Execution**: Orchestrator **EXECUTES** these attached tasks itself
|
||||
- **Task Collapse**: After tasks complete, collapse them into phase summary
|
||||
- **Phase Transition**: Automatically execute next phase after collapsing
|
||||
@@ -36,7 +36,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
|
||||
|
||||
**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until Phase 10 (UI assembly) finishes.
|
||||
|
||||
**Task Attachment Model**: SlashCommand execute is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
|
||||
**Task Attachment Model**: SlashCommand dispatch is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
|
||||
|
||||
**Target Type Detection**: Automatically inferred from prompt/targets, or explicitly set via `--target-type`.
|
||||
|
||||
@@ -63,26 +63,26 @@ Phase 5: Unified Target Inference
|
||||
|
||||
Phase 6: Code Import (Conditional)
|
||||
└─ Decision (design_source):
|
||||
├─ code_only | hybrid → Execute /workflow:ui-design:import-from-code
|
||||
├─ code_only | hybrid → Dispatch /workflow:ui-design:import-from-code
|
||||
└─ visual_only → Skip to Phase 7
|
||||
|
||||
Phase 7: Style Extraction
|
||||
└─ Decision (needs_visual_supplement):
|
||||
├─ visual_only OR supplement needed → Execute /workflow:ui-design:style-extract
|
||||
├─ visual_only OR supplement needed → Dispatch /workflow:ui-design:style-extract
|
||||
└─ code_only AND style_complete → Use code import
|
||||
|
||||
Phase 8: Animation Extraction
|
||||
└─ Decision (should_extract_animation):
|
||||
├─ visual_only OR incomplete OR regenerate → Execute /workflow:ui-design:animation-extract
|
||||
├─ visual_only OR incomplete OR regenerate → Dispatch /workflow:ui-design:animation-extract
|
||||
└─ code_only AND animation_complete → Use code import
|
||||
|
||||
Phase 9: Layout Extraction
|
||||
└─ Decision (needs_visual_supplement OR NOT layout_complete):
|
||||
├─ True → Execute /workflow:ui-design:layout-extract
|
||||
├─ True → Dispatch /workflow:ui-design:layout-extract
|
||||
└─ False → Use code import
|
||||
|
||||
Phase 10: UI Assembly
|
||||
└─ Execute /workflow:ui-design:generate → Workflow complete
|
||||
└─ Dispatch /workflow:ui-design:generate → Workflow complete
|
||||
```
|
||||
|
||||
## Core Rules
|
||||
@@ -92,7 +92,7 @@ Phase 10: UI Assembly
|
||||
3. **Parse & Pass**: Extract data from each output for next phase
|
||||
4. **Default to All**: When selecting variants/prototypes, use ALL generated items
|
||||
5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
|
||||
6. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand execute **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
|
||||
6. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand dispatch **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
|
||||
7. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 10 (UI assembly) finishes.
|
||||
|
||||
## Parameter Requirements
|
||||
@@ -356,7 +356,7 @@ detect_target_type(target_list):
|
||||
|
||||
### Phase 6: Code Import & Completeness Assessment (Conditional)
|
||||
|
||||
**Step 6.1: Execute** - Import design system from code files
|
||||
**Step 6.1: Dispatch** - Import design system from code files
|
||||
|
||||
```javascript
|
||||
IF design_source IN ["code_only", "hybrid"]:
|
||||
@@ -364,7 +364,7 @@ IF design_source IN ["code_only", "hybrid"]:
|
||||
command = "/workflow:ui-design:import-from-code --design-id \"{design_id}\" --source \"{code_base_path}\""
|
||||
|
||||
TRY:
|
||||
# SlashCommand execute ATTACHES import-from-code's tasks to current workflow
|
||||
# SlashCommand dispatch ATTACHES import-from-code's tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself:
|
||||
# - Phase 0: Discover and categorize code files
|
||||
# - Phase 1.1-1.3: Style/Animation/Layout Agent extraction
|
||||
@@ -469,7 +469,7 @@ IF design_source IN ["code_only", "hybrid"]:
|
||||
|
||||
### Phase 7: Style Extraction
|
||||
|
||||
**Step 7.1: Execute** - Extract style design systems
|
||||
**Step 7.1: Dispatch** - Extract style design systems
|
||||
|
||||
```javascript
|
||||
IF design_source == "visual_only" OR needs_visual_supplement:
|
||||
@@ -479,7 +479,7 @@ IF design_source == "visual_only" OR needs_visual_supplement:
|
||||
(prompt_text ? "--prompt \"{prompt_text}\" " : "") +
|
||||
"--variants {style_variants} --interactive"
|
||||
|
||||
# SlashCommand execute ATTACHES style-extract's tasks to current workflow
|
||||
# SlashCommand dispatch ATTACHES style-extract's tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself
|
||||
SlashCommand(command)
|
||||
|
||||
@@ -490,7 +490,7 @@ ELSE:
|
||||
|
||||
### Phase 8: Animation Extraction
|
||||
|
||||
**Step 8.1: Execute** - Extract animation patterns
|
||||
**Step 8.1: Dispatch** - Extract animation patterns
|
||||
|
||||
```javascript
|
||||
# Determine if animation extraction is needed
|
||||
@@ -522,7 +522,7 @@ IF should_extract_animation:
|
||||
|
||||
command = " ".join(command_parts)
|
||||
|
||||
# SlashCommand execute ATTACHES animation-extract's tasks to current workflow
|
||||
# SlashCommand dispatch ATTACHES animation-extract's tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself
|
||||
SlashCommand(command)
|
||||
|
||||
@@ -536,7 +536,7 @@ ELSE:
|
||||
|
||||
### Phase 9: Layout Extraction
|
||||
|
||||
**Step 9.1: Execute** - Extract layout templates
|
||||
**Step 9.1: Dispatch** - Extract layout templates
|
||||
|
||||
```javascript
|
||||
targets_string = ",".join(inferred_target_list)
|
||||
@@ -548,7 +548,7 @@ IF (design_source == "visual_only" OR needs_visual_supplement) OR (NOT layout_co
|
||||
(prompt_text ? "--prompt \"{prompt_text}\" " : "") +
|
||||
"--targets \"{targets_string}\" --variants {layout_variants} --device-type \"{device_type}\" --interactive"
|
||||
|
||||
# SlashCommand execute ATTACHES layout-extract's tasks to current workflow
|
||||
# SlashCommand dispatch ATTACHES layout-extract's tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself
|
||||
SlashCommand(command)
|
||||
|
||||
@@ -559,7 +559,7 @@ ELSE:
|
||||
|
||||
### Phase 10: UI Assembly
|
||||
|
||||
**Step 10.1: Execute** - Assemble UI prototypes from design tokens and layout templates
|
||||
**Step 10.1: Dispatch** - Assemble UI prototypes from design tokens and layout templates
|
||||
|
||||
```javascript
|
||||
command = "/workflow:ui-design:generate --design-id \"{design_id}\"" + (--session ? " --session {session_id}" : "")
|
||||
@@ -571,7 +571,7 @@ REPORT: " → Pure assembly: Combining layout templates + design tokens"
|
||||
REPORT: " → Device: {device_type} (from layout templates)"
|
||||
REPORT: " → Assembly tasks: {total} combinations"
|
||||
|
||||
# SlashCommand execute ATTACHES generate's tasks to current workflow
|
||||
# SlashCommand dispatch ATTACHES generate's tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself
|
||||
SlashCommand(command)
|
||||
|
||||
@@ -596,10 +596,10 @@ TodoWrite({todos: [
|
||||
|
||||
// ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
|
||||
//
|
||||
// **Key Concept**: SlashCommand execute ATTACHES tasks to current workflow.
|
||||
// **Key Concept**: SlashCommand dispatch ATTACHES tasks to current workflow.
|
||||
// Orchestrator EXECUTES these attached tasks itself, not waiting for external completion.
|
||||
//
|
||||
// Phase 7-10 SlashCommand Execute Pattern (when tasks are attached):
|
||||
// Phase 7-10 SlashCommand Dispatch Pattern (when tasks are attached):
|
||||
// Example - Phase 7 with sub-tasks:
|
||||
// [
|
||||
// {"content": "Phase 7: Style Extraction", "status": "in_progress", "activeForm": "Executing style extraction"},
|
||||
|
||||
@@ -320,7 +320,7 @@ Read({base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html)
|
||||
|
||||
### Step 1: Run Preview Generation Script
|
||||
```bash
|
||||
bash(ccw tool exec ui_generate_preview '{"prototypesDir":"{base_path}/prototypes"}')
|
||||
bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
|
||||
```
|
||||
|
||||
**Script generates**:
|
||||
@@ -432,7 +432,7 @@ bash(test -f {base_path}/prototypes/compare.html && echo "exists")
|
||||
bash(mkdir -p {base_path}/prototypes)
|
||||
|
||||
# Run preview script
|
||||
bash(ccw tool exec ui_generate_preview '{"prototypesDir":"{base_path}/prototypes"}')
|
||||
bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
|
||||
```
|
||||
|
||||
## Output Structure
|
||||
@@ -467,7 +467,7 @@ ERROR: Agent assembly failed
|
||||
→ Check inputs exist, validate JSON structure
|
||||
|
||||
ERROR: Script permission denied
|
||||
→ Verify ccw tool is available: ccw tool list
|
||||
→ chmod +x ~/.claude/scripts/ui-generate-preview.sh
|
||||
```
|
||||
|
||||
### Recovery Strategies
|
||||
|
||||
@@ -26,7 +26,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
|
||||
7. Phase 4: Design system integration → **Execute orchestrator task** → Reports completion
|
||||
|
||||
**Phase Transition Mechanism**:
|
||||
- **Task Attachment**: SlashCommand execute **ATTACHES** tasks to current workflow
|
||||
- **Task Attachment**: SlashCommand dispatch **ATTACHES** tasks to current workflow
|
||||
- **Task Execution**: Orchestrator **EXECUTES** these attached tasks itself
|
||||
- **Task Collapse**: After tasks complete, collapse them into phase summary
|
||||
- **Phase Transition**: Automatically execute next phase after collapsing
|
||||
@@ -34,7 +34,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
|
||||
|
||||
**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until reaching Phase 4.
|
||||
|
||||
**Task Attachment Model**: SlashCommand execute is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
|
||||
**Task Attachment Model**: SlashCommand dispatch is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
|
||||
|
||||
## Execution Process
|
||||
|
||||
@@ -53,30 +53,30 @@ Phase 0: Parameter Parsing & Input Detection
|
||||
|
||||
Phase 0.5: Code Import (Conditional)
|
||||
└─ Decision (design_source):
|
||||
├─ hybrid → Execute /workflow:ui-design:import-from-code
|
||||
├─ hybrid → Dispatch /workflow:ui-design:import-from-code
|
||||
└─ Other → Skip to Phase 2
|
||||
|
||||
Phase 2: Style Extraction
|
||||
└─ Decision (skip_style):
|
||||
├─ code_only AND style_complete → Use code import
|
||||
└─ Otherwise → Execute /workflow:ui-design:style-extract
|
||||
└─ Otherwise → Dispatch /workflow:ui-design:style-extract
|
||||
|
||||
Phase 2.3: Animation Extraction
|
||||
└─ Decision (skip_animation):
|
||||
├─ code_only AND animation_complete → Use code import
|
||||
└─ Otherwise → Execute /workflow:ui-design:animation-extract
|
||||
└─ Otherwise → Dispatch /workflow:ui-design:animation-extract
|
||||
|
||||
Phase 2.5: Layout Extraction
|
||||
└─ Decision (skip_layout):
|
||||
├─ code_only AND layout_complete → Use code import
|
||||
└─ Otherwise → Execute /workflow:ui-design:layout-extract
|
||||
└─ Otherwise → Dispatch /workflow:ui-design:layout-extract
|
||||
|
||||
Phase 3: UI Assembly
|
||||
└─ Execute /workflow:ui-design:generate
|
||||
└─ Dispatch /workflow:ui-design:generate
|
||||
|
||||
Phase 4: Design System Integration
|
||||
└─ Decision (session_id):
|
||||
├─ Provided → Execute /workflow:ui-design:update
|
||||
├─ Provided → Dispatch /workflow:ui-design:update
|
||||
└─ Not provided → Standalone completion
|
||||
```
|
||||
|
||||
@@ -86,7 +86,7 @@ Phase 4: Design System Integration
|
||||
2. **No Preliminary Validation**: Sub-commands handle their own validation
|
||||
3. **Parse & Pass**: Extract data from each output for next phase
|
||||
4. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
|
||||
5. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand execute **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
|
||||
5. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand dispatch **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
|
||||
6. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 4.
|
||||
|
||||
## Parameter Requirements
|
||||
@@ -276,7 +276,7 @@ TodoWrite({todos: [
|
||||
|
||||
### Phase 0.5: Code Import & Completeness Assessment (Conditional)
|
||||
|
||||
**Step 0.5.1: Execute** - Import design system from code files
|
||||
**Step 0.5.1: Dispatch** - Import design system from code files
|
||||
|
||||
```javascript
|
||||
# Only execute if code files detected
|
||||
@@ -291,7 +291,7 @@ IF design_source == "hybrid":
|
||||
"--source \"{code_base_path}\""
|
||||
|
||||
TRY:
|
||||
# SlashCommand execute ATTACHES import-from-code's tasks to current workflow
|
||||
# SlashCommand dispatch ATTACHES import-from-code's tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself:
|
||||
# - Phase 0: Discover and categorize code files
|
||||
# - Phase 1.1-1.3: Style/Animation/Layout Agent extraction
|
||||
@@ -382,7 +382,7 @@ TodoWrite(mark_completed: "Initialize and detect design source",
|
||||
|
||||
### Phase 2: Style Extraction
|
||||
|
||||
**Step 2.1: Execute** - Extract style design system
|
||||
**Step 2.1: Dispatch** - Extract style design system
|
||||
|
||||
```javascript
|
||||
# Determine if style extraction needed
|
||||
@@ -409,7 +409,7 @@ ELSE:
|
||||
|
||||
extract_command = " ".join(command_parts)
|
||||
|
||||
# SlashCommand execute ATTACHES style-extract's tasks to current workflow
|
||||
# SlashCommand dispatch ATTACHES style-extract's tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself
|
||||
SlashCommand(extract_command)
|
||||
|
||||
@@ -419,7 +419,7 @@ ELSE:
|
||||
|
||||
### Phase 2.3: Animation Extraction
|
||||
|
||||
**Step 2.3.1: Execute** - Extract animation patterns
|
||||
**Step 2.3.1: Dispatch** - Extract animation patterns
|
||||
|
||||
```javascript
|
||||
skip_animation = (design_source == "code_only" AND animation_complete)
|
||||
@@ -442,7 +442,7 @@ ELSE:
|
||||
|
||||
animation_extract_command = " ".join(command_parts)
|
||||
|
||||
# SlashCommand execute ATTACHES animation-extract's tasks to current workflow
|
||||
# SlashCommand dispatch ATTACHES animation-extract's tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself
|
||||
SlashCommand(animation_extract_command)
|
||||
|
||||
@@ -452,7 +452,7 @@ ELSE:
|
||||
|
||||
### Phase 2.5: Layout Extraction
|
||||
|
||||
**Step 2.5.1: Execute** - Extract layout templates
|
||||
**Step 2.5.1: Dispatch** - Extract layout templates
|
||||
|
||||
```javascript
|
||||
skip_layout = (design_source == "code_only" AND layout_complete)
|
||||
@@ -477,7 +477,7 @@ ELSE:
|
||||
|
||||
layout_extract_command = " ".join(command_parts)
|
||||
|
||||
# SlashCommand execute ATTACHES layout-extract's tasks to current workflow
|
||||
# SlashCommand dispatch ATTACHES layout-extract's tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself
|
||||
SlashCommand(layout_extract_command)
|
||||
|
||||
@@ -487,13 +487,13 @@ ELSE:
|
||||
|
||||
### Phase 3: UI Assembly
|
||||
|
||||
**Step 3.1: Execute** - Assemble UI prototypes from design tokens and layout templates
|
||||
**Step 3.1: Dispatch** - Assemble UI prototypes from design tokens and layout templates
|
||||
|
||||
```javascript
|
||||
REPORT: "🚀 Phase 3: UI Assembly"
|
||||
generate_command = f"/workflow:ui-design:generate --design-id \"{design_id}\""
|
||||
|
||||
# SlashCommand execute ATTACHES generate's tasks to current workflow
|
||||
# SlashCommand dispatch ATTACHES generate's tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself
|
||||
SlashCommand(generate_command)
|
||||
|
||||
@@ -503,14 +503,14 @@ TodoWrite(mark_completed: "Assemble UI", mark_in_progress: session_id ? "Integra
|
||||
|
||||
### Phase 4: Design System Integration
|
||||
|
||||
**Step 4.1: Execute** - Integrate design system into workflow session
|
||||
**Step 4.1: Dispatch** - Integrate design system into workflow session
|
||||
|
||||
```javascript
|
||||
IF session_id:
|
||||
REPORT: "🚀 Phase 4: Design System Integration"
|
||||
update_command = f"/workflow:ui-design:update --session {session_id}"
|
||||
|
||||
# SlashCommand execute ATTACHES update's tasks to current workflow
|
||||
# SlashCommand dispatch ATTACHES update's tasks to current workflow
|
||||
# Orchestrator will EXECUTE these attached tasks itself
|
||||
SlashCommand(update_command)
|
||||
|
||||
@@ -636,10 +636,10 @@ TodoWrite({todos: [
|
||||
|
||||
// ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
|
||||
//
|
||||
// **Key Concept**: SlashCommand execute ATTACHES tasks to current workflow.
|
||||
// **Key Concept**: SlashCommand dispatch ATTACHES tasks to current workflow.
|
||||
// Orchestrator EXECUTES these attached tasks itself, not waiting for external completion.
|
||||
//
|
||||
// Phase 2-4 SlashCommand Execute Pattern (when tasks are attached):
|
||||
// Phase 2-4 SlashCommand Dispatch Pattern (when tasks are attached):
|
||||
// Example - Phase 2 with sub-tasks:
|
||||
// [
|
||||
// {"content": "Phase 0: Initialize and Detect Design Source", "status": "completed", "activeForm": "Initializing"},
|
||||
@@ -702,7 +702,7 @@ TodoWrite({todos: [
|
||||
|
||||
- **Input**: `--images` (glob pattern) and/or `--prompt` (text/file paths) + optional `--session`
|
||||
- **Output**: Complete design system in `{base_path}/` (style-extraction, layout-extraction, prototypes)
|
||||
- **Sub-commands Executeed**:
|
||||
- **Sub-commands Dispatched**:
|
||||
1. `/workflow:ui-design:import-from-code` (Phase 0.5, conditional - if code files detected)
|
||||
2. `/workflow:ui-design:style-extract` (Phase 2 - complete design systems)
|
||||
3. `/workflow:ui-design:animation-extract` (Phase 2.3 - animation tokens)
|
||||
|
||||
@@ -106,7 +106,7 @@ echo " Output: $base_path"
|
||||
|
||||
# 3. Discover files using script
|
||||
discovery_file="${intermediates_dir}/discovered-files.json"
|
||||
ccw tool exec discover_design_files '{"sourceDir":"'"$source"'","outputPath":"'"$discovery_file"'"}'
|
||||
~/.claude/scripts/discover-design-files.sh "$source" "$discovery_file"
|
||||
|
||||
echo " Output: $discovery_file"
|
||||
```
|
||||
@@ -161,7 +161,6 @@ echo "[Phase 1] Starting parallel agent analysis (3 agents)"
|
||||
|
||||
```javascript
|
||||
Task(subagent_type="ui-design-agent",
|
||||
run_in_background=false,
|
||||
prompt="[STYLE_TOKENS_EXTRACTION]
|
||||
Extract visual design tokens from code files using code import extraction pattern.
|
||||
|
||||
@@ -181,14 +180,14 @@ Task(subagent_type="ui-design-agent",
|
||||
- Pattern: rg → Extract values → Compare → If different → Read full context with comments → Record conflict
|
||||
- Alternative (if many files): Execute CLI analysis for comprehensive report:
|
||||
\`\`\`bash
|
||||
ccw cli -p \"
|
||||
cd ${source} && gemini -p \"
|
||||
PURPOSE: Detect color token conflicts across all CSS/SCSS/JS files
|
||||
TASK: • Scan all files for color definitions • Identify conflicting values • Extract semantic comments
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*.css @**/*.scss @**/*.js @**/*.ts
|
||||
EXPECTED: JSON report listing conflicts with file:line, values, semantic context
|
||||
RULES: Focus on core tokens | Report ALL variants | analysis=READ-ONLY
|
||||
\" --tool gemini --mode analysis --cd ${source}
|
||||
\"
|
||||
\`\`\`
|
||||
|
||||
**Step 1: Load file list**
|
||||
@@ -277,7 +276,6 @@ Task(subagent_type="ui-design-agent",
|
||||
|
||||
```javascript
|
||||
Task(subagent_type="ui-design-agent",
|
||||
run_in_background=false,
|
||||
prompt="[ANIMATION_TOKEN_GENERATION_TASK]
|
||||
Extract animation tokens from code files using code import extraction pattern.
|
||||
|
||||
@@ -297,14 +295,14 @@ Task(subagent_type="ui-design-agent",
|
||||
- Pattern: rg → Identify animation types → Map framework usage → Prioritize extraction targets
|
||||
- Alternative (if complex framework mix): Execute CLI analysis for comprehensive report:
|
||||
\`\`\`bash
|
||||
ccw cli -p \"
|
||||
cd ${source} && gemini -p \"
|
||||
PURPOSE: Detect animation frameworks and patterns
|
||||
TASK: • Identify frameworks • Map animation patterns • Categorize by complexity
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*.css @**/*.scss @**/*.js @**/*.ts
|
||||
EXPECTED: JSON report listing frameworks, animation types, file locations
|
||||
RULES: Focus on framework consistency | Map all animations | analysis=READ-ONLY
|
||||
\" --tool gemini --mode analysis --cd ${source}
|
||||
\"
|
||||
\`\`\`
|
||||
|
||||
**Step 1: Load file list**
|
||||
@@ -357,7 +355,6 @@ Task(subagent_type="ui-design-agent",
|
||||
|
||||
```javascript
|
||||
Task(subagent_type="ui-design-agent",
|
||||
run_in_background=false,
|
||||
prompt="[LAYOUT_TEMPLATE_GENERATION_TASK]
|
||||
Extract layout patterns from code files using code import extraction pattern.
|
||||
|
||||
@@ -377,14 +374,14 @@ Task(subagent_type="ui-design-agent",
|
||||
- Pattern: rg → Count occurrences → Classify by frequency → Prioritize universal components
|
||||
- Alternative (if large codebase): Execute CLI analysis for comprehensive categorization:
|
||||
\`\`\`bash
|
||||
ccw cli -p \"
|
||||
cd ${source} && gemini -p \"
|
||||
PURPOSE: Classify components as universal vs specialized
|
||||
TASK: • Identify UI components • Classify reusability • Map layout systems
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*.css @**/*.scss @**/*.js @**/*.ts @**/*.html
|
||||
EXPECTED: JSON report categorizing components, layout patterns, naming conventions
|
||||
RULES: Focus on component reusability | Identify layout systems | analysis=READ-ONLY
|
||||
\" --tool gemini --mode analysis --cd ${source}
|
||||
\"
|
||||
\`\`\`
|
||||
|
||||
**Step 1: Load file list**
|
||||
|
||||
@@ -1,14 +1,10 @@
|
||||
---
|
||||
name: layout-extract
|
||||
description: Extract structural layout information from reference images or text prompts using Claude analysis with variant generation or refinement mode
|
||||
argument-hint: "[-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--targets "<list>"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]"
|
||||
argument-hint: [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--targets "<list>"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), AskUserQuestion(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Skip all clarification questions, use AI-inferred layout decisions.
|
||||
|
||||
# Layout Extraction Command
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -1,14 +1,10 @@
|
||||
---
|
||||
name: style-extract
|
||||
description: Extract design style from reference images or text prompts using Claude analysis with variant generation or refinement mode
|
||||
argument-hint: "[-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--variants <count>] [--interactive] [--refine]"
|
||||
argument-hint: "[--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--variants <count>] [--interactive] [--refine]"
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), AskUserQuestion(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Skip all clarification questions, use AI-inferred design decisions.
|
||||
|
||||
# Style Extraction Command
|
||||
|
||||
## Overview
|
||||
|
||||
35
.claude/scripts/classify-folders.sh
Normal file
35
.claude/scripts/classify-folders.sh
Normal file
@@ -0,0 +1,35 @@
|
||||
#!/bin/bash
|
||||
# Classify folders by type for documentation generation
|
||||
# Usage: get_modules_by_depth.sh | classify-folders.sh
|
||||
# Output: folder_path|folder_type|code:N|dirs:N
|
||||
|
||||
while IFS='|' read -r depth_info path_info files_info types_info claude_info; do
|
||||
# Extract folder path from format "path:./src/modules"
|
||||
folder_path=$(echo "$path_info" | cut -d':' -f2-)
|
||||
|
||||
# Skip if path extraction failed
|
||||
[[ -z "$folder_path" || ! -d "$folder_path" ]] && continue
|
||||
|
||||
# Count code files (maxdepth 1)
|
||||
code_files=$(find "$folder_path" -maxdepth 1 -type f \
|
||||
\( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \
|
||||
-o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rs" \
|
||||
-o -name "*.c" -o -name "*.cpp" -o -name "*.cs" \) \
|
||||
2>/dev/null | wc -l)
|
||||
|
||||
# Count subdirectories
|
||||
subfolders=$(find "$folder_path" -maxdepth 1 -type d \
|
||||
-not -path "$folder_path" 2>/dev/null | wc -l)
|
||||
|
||||
# Determine folder type
|
||||
if [[ $code_files -gt 0 ]]; then
|
||||
folder_type="code" # API.md + README.md
|
||||
elif [[ $subfolders -gt 0 ]]; then
|
||||
folder_type="navigation" # README.md only
|
||||
else
|
||||
folder_type="skip" # Empty or no relevant content
|
||||
fi
|
||||
|
||||
# Output classification result
|
||||
echo "${folder_path}|${folder_type}|code:${code_files}|dirs:${subfolders}"
|
||||
done
|
||||
225
.claude/scripts/convert_tokens_to_css.sh
Normal file
225
.claude/scripts/convert_tokens_to_css.sh
Normal file
@@ -0,0 +1,225 @@
|
||||
#!/bin/bash
|
||||
# Convert design-tokens.json to tokens.css with Google Fonts import and global font rules
|
||||
# Usage: cat design-tokens.json | ./convert_tokens_to_css.sh > tokens.css
|
||||
# Or: ./convert_tokens_to_css.sh < design-tokens.json > tokens.css
|
||||
|
||||
# Read JSON from stdin
|
||||
json_input=$(cat)
|
||||
|
||||
# Extract metadata for header comment
|
||||
style_name=$(echo "$json_input" | jq -r '.meta.name // "Unknown Style"' 2>/dev/null || echo "Design Tokens")
|
||||
|
||||
# Generate header
|
||||
cat <<EOF
|
||||
/* ========================================
|
||||
Design Tokens: ${style_name}
|
||||
Auto-generated from design-tokens.json
|
||||
======================================== */
|
||||
|
||||
EOF
|
||||
|
||||
# ========================================
|
||||
# Google Fonts Import Generation
|
||||
# ========================================
|
||||
# Extract font families and generate Google Fonts import URL
|
||||
fonts=$(echo "$json_input" | jq -r '
|
||||
.typography.font_family | to_entries[] | .value
|
||||
' 2>/dev/null | sed "s/'//g" | cut -d',' -f1 | sort -u)
|
||||
|
||||
# Build Google Fonts URL
|
||||
google_fonts_url="https://fonts.googleapis.com/css2?"
|
||||
font_params=""
|
||||
|
||||
while IFS= read -r font; do
|
||||
# Skip system fonts and empty lines
|
||||
if [[ -z "$font" ]] || [[ "$font" =~ ^(system-ui|sans-serif|serif|monospace|cursive|fantasy)$ ]]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
# Special handling for common web fonts with weights
|
||||
case "$font" in
|
||||
"Comic Neue")
|
||||
font_params+="family=Comic+Neue:wght@300;400;700&"
|
||||
;;
|
||||
"Patrick Hand"|"Caveat"|"Dancing Script"|"Architects Daughter"|"Indie Flower"|"Shadows Into Light"|"Permanent Marker")
|
||||
# URL-encode font name and add common weights
|
||||
encoded_font=$(echo "$font" | sed 's/ /+/g')
|
||||
font_params+="family=${encoded_font}:wght@400;700&"
|
||||
;;
|
||||
"Segoe Print"|"Bradley Hand"|"Chilanka")
|
||||
# These are system fonts, skip
|
||||
;;
|
||||
*)
|
||||
# Generic font: add with default weights
|
||||
encoded_font=$(echo "$font" | sed 's/ /+/g')
|
||||
font_params+="family=${encoded_font}:wght@400;500;600;700&"
|
||||
;;
|
||||
esac
|
||||
done <<< "$fonts"
|
||||
|
||||
# Generate @import if we have fonts
|
||||
if [[ -n "$font_params" ]]; then
|
||||
# Remove trailing &
|
||||
font_params="${font_params%&}"
|
||||
echo "/* Import Web Fonts */"
|
||||
echo "@import url('${google_fonts_url}${font_params}&display=swap');"
|
||||
echo ""
|
||||
fi
|
||||
|
||||
# ========================================
|
||||
# CSS Custom Properties Generation
|
||||
# ========================================
|
||||
echo ":root {"
|
||||
|
||||
# Colors - Brand
|
||||
echo " /* Colors - Brand */"
|
||||
echo "$json_input" | jq -r '
|
||||
.colors.brand | to_entries[] |
|
||||
" --color-brand-\(.key): \(.value);"
|
||||
' 2>/dev/null
|
||||
|
||||
echo ""
|
||||
|
||||
# Colors - Surface
|
||||
echo " /* Colors - Surface */"
|
||||
echo "$json_input" | jq -r '
|
||||
.colors.surface | to_entries[] |
|
||||
" --color-surface-\(.key): \(.value);"
|
||||
' 2>/dev/null
|
||||
|
||||
echo ""
|
||||
|
||||
# Colors - Semantic
|
||||
echo " /* Colors - Semantic */"
|
||||
echo "$json_input" | jq -r '
|
||||
.colors.semantic | to_entries[] |
|
||||
" --color-semantic-\(.key): \(.value);"
|
||||
' 2>/dev/null
|
||||
|
||||
echo ""
|
||||
|
||||
# Colors - Text
|
||||
echo " /* Colors - Text */"
|
||||
echo "$json_input" | jq -r '
|
||||
.colors.text | to_entries[] |
|
||||
" --color-text-\(.key): \(.value);"
|
||||
' 2>/dev/null
|
||||
|
||||
echo ""
|
||||
|
||||
# Colors - Border
|
||||
echo " /* Colors - Border */"
|
||||
echo "$json_input" | jq -r '
|
||||
.colors.border | to_entries[] |
|
||||
" --color-border-\(.key): \(.value);"
|
||||
' 2>/dev/null
|
||||
|
||||
echo ""
|
||||
|
||||
# Typography - Font Family
|
||||
echo " /* Typography - Font Family */"
|
||||
echo "$json_input" | jq -r '
|
||||
.typography.font_family | to_entries[] |
|
||||
" --font-family-\(.key): \(.value);"
|
||||
' 2>/dev/null
|
||||
|
||||
echo ""
|
||||
|
||||
# Typography - Font Size
|
||||
echo " /* Typography - Font Size */"
|
||||
echo "$json_input" | jq -r '
|
||||
.typography.font_size | to_entries[] |
|
||||
" --font-size-\(.key): \(.value);"
|
||||
' 2>/dev/null
|
||||
|
||||
echo ""
|
||||
|
||||
# Typography - Font Weight
|
||||
echo " /* Typography - Font Weight */"
|
||||
echo "$json_input" | jq -r '
|
||||
.typography.font_weight | to_entries[] |
|
||||
" --font-weight-\(.key): \(.value);"
|
||||
' 2>/dev/null
|
||||
|
||||
echo ""
|
||||
|
||||
# Typography - Line Height
|
||||
echo " /* Typography - Line Height */"
|
||||
echo "$json_input" | jq -r '
|
||||
.typography.line_height | to_entries[] |
|
||||
" --line-height-\(.key): \(.value);"
|
||||
' 2>/dev/null
|
||||
|
||||
echo ""
|
||||
|
||||
# Typography - Letter Spacing
|
||||
echo " /* Typography - Letter Spacing */"
|
||||
echo "$json_input" | jq -r '
|
||||
.typography.letter_spacing | to_entries[] |
|
||||
" --letter-spacing-\(.key): \(.value);"
|
||||
' 2>/dev/null
|
||||
|
||||
echo ""
|
||||
|
||||
# Spacing
|
||||
echo " /* Spacing */"
|
||||
echo "$json_input" | jq -r '
|
||||
.spacing | to_entries[] |
|
||||
" --spacing-\(.key): \(.value);"
|
||||
' 2>/dev/null
|
||||
|
||||
echo ""
|
||||
|
||||
# Border Radius
|
||||
echo " /* Border Radius */"
|
||||
echo "$json_input" | jq -r '
|
||||
.border_radius | to_entries[] |
|
||||
" --border-radius-\(.key): \(.value);"
|
||||
' 2>/dev/null
|
||||
|
||||
echo ""
|
||||
|
||||
# Shadows
|
||||
echo " /* Shadows */"
|
||||
echo "$json_input" | jq -r '
|
||||
.shadows | to_entries[] |
|
||||
" --shadow-\(.key): \(.value);"
|
||||
' 2>/dev/null
|
||||
|
||||
echo ""
|
||||
|
||||
# Breakpoints
|
||||
echo " /* Breakpoints */"
|
||||
echo "$json_input" | jq -r '
|
||||
.breakpoints | to_entries[] |
|
||||
" --breakpoint-\(.key): \(.value);"
|
||||
' 2>/dev/null
|
||||
|
||||
echo "}"
|
||||
echo ""
|
||||
|
||||
# ========================================
|
||||
# Global Font Application
|
||||
# ========================================
|
||||
echo "/* ========================================"
|
||||
echo " Global Font Application"
|
||||
echo " ======================================== */"
|
||||
echo ""
|
||||
echo "body {"
|
||||
echo " font-family: var(--font-family-body);"
|
||||
echo " font-size: var(--font-size-base);"
|
||||
echo " line-height: var(--line-height-normal);"
|
||||
echo " color: var(--color-text-primary);"
|
||||
echo " background-color: var(--color-surface-background);"
|
||||
echo "}"
|
||||
echo ""
|
||||
echo "h1, h2, h3, h4, h5, h6, legend {"
|
||||
echo " font-family: var(--font-family-heading);"
|
||||
echo "}"
|
||||
echo ""
|
||||
echo "/* Reset default margins for better control */"
|
||||
echo "* {"
|
||||
echo " margin: 0;"
|
||||
echo " padding: 0;"
|
||||
echo " box-sizing: border-box;"
|
||||
echo "}"
|
||||
157
.claude/scripts/detect_changed_modules.sh
Normal file
157
.claude/scripts/detect_changed_modules.sh
Normal file
@@ -0,0 +1,157 @@
|
||||
#!/bin/bash
|
||||
# Detect modules affected by git changes or recent modifications
|
||||
# Usage: detect_changed_modules.sh [format]
|
||||
# format: list|grouped|paths (default: paths)
|
||||
#
|
||||
# Features:
|
||||
# - Respects .gitignore patterns (current directory or git root)
|
||||
# - Detects git changes (staged, unstaged, or last commit)
|
||||
# - Falls back to recently modified files (last 24 hours)
|
||||
|
||||
# Build exclusion filters from .gitignore
|
||||
build_exclusion_filters() {
|
||||
local filters=""
|
||||
|
||||
# Common system/cache directories to exclude
|
||||
local system_excludes=(
|
||||
".git" "__pycache__" "node_modules" ".venv" "venv" "env"
|
||||
"dist" "build" ".cache" ".pytest_cache" ".mypy_cache"
|
||||
"coverage" ".nyc_output" "logs" "tmp" "temp"
|
||||
)
|
||||
|
||||
for exclude in "${system_excludes[@]}"; do
|
||||
filters+=" -not -path '*/$exclude' -not -path '*/$exclude/*'"
|
||||
done
|
||||
|
||||
# Find and parse .gitignore (current dir first, then git root)
|
||||
local gitignore_file=""
|
||||
|
||||
# Check current directory first
|
||||
if [ -f ".gitignore" ]; then
|
||||
gitignore_file=".gitignore"
|
||||
else
|
||||
# Try to find git root and check for .gitignore there
|
||||
local git_root=$(git rev-parse --show-toplevel 2>/dev/null)
|
||||
if [ -n "$git_root" ] && [ -f "$git_root/.gitignore" ]; then
|
||||
gitignore_file="$git_root/.gitignore"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Parse .gitignore if found
|
||||
if [ -n "$gitignore_file" ]; then
|
||||
while IFS= read -r line; do
|
||||
# Skip empty lines and comments
|
||||
[[ -z "$line" || "$line" =~ ^[[:space:]]*# ]] && continue
|
||||
|
||||
# Remove trailing slash and whitespace
|
||||
line=$(echo "$line" | sed 's|/$||' | xargs)
|
||||
|
||||
# Skip wildcards patterns (too complex for simple find)
|
||||
[[ "$line" =~ \* ]] && continue
|
||||
|
||||
# Add to filters
|
||||
filters+=" -not -path '*/$line' -not -path '*/$line/*'"
|
||||
done < "$gitignore_file"
|
||||
fi
|
||||
|
||||
echo "$filters"
|
||||
}
|
||||
|
||||
detect_changed_modules() {
|
||||
local format="${1:-paths}"
|
||||
local changed_files=""
|
||||
local affected_dirs=""
|
||||
local exclusion_filters=$(build_exclusion_filters)
|
||||
|
||||
# Step 1: Try to get git changes (staged + unstaged)
|
||||
if git rev-parse --git-dir > /dev/null 2>&1; then
|
||||
changed_files=$(git diff --name-only HEAD 2>/dev/null; git diff --name-only --cached 2>/dev/null)
|
||||
|
||||
# If no changes in working directory, check last commit
|
||||
if [ -z "$changed_files" ]; then
|
||||
changed_files=$(git diff --name-only HEAD~1 HEAD 2>/dev/null)
|
||||
fi
|
||||
fi
|
||||
|
||||
# Step 2: If no git changes, find recently modified source files (last 24 hours)
|
||||
# Apply exclusion filters from .gitignore
|
||||
if [ -z "$changed_files" ]; then
|
||||
changed_files=$(eval "find . -type f \( \
|
||||
-name '*.md' -o \
|
||||
-name '*.js' -o -name '*.ts' -o -name '*.jsx' -o -name '*.tsx' -o \
|
||||
-name '*.py' -o -name '*.go' -o -name '*.rs' -o \
|
||||
-name '*.java' -o -name '*.cpp' -o -name '*.c' -o -name '*.h' -o \
|
||||
-name '*.sh' -o -name '*.ps1' -o \
|
||||
-name '*.json' -o -name '*.yaml' -o -name '*.yml' \
|
||||
\) $exclusion_filters -mtime -1 2>/dev/null")
|
||||
fi
|
||||
|
||||
# Step 3: Extract unique parent directories
|
||||
if [ -n "$changed_files" ]; then
|
||||
affected_dirs=$(echo "$changed_files" | \
|
||||
sed 's|/[^/]*$||' | \
|
||||
grep -v '^\.$' | \
|
||||
sort -u)
|
||||
|
||||
# Add current directory if files are in root
|
||||
if echo "$changed_files" | grep -q '^[^/]*$'; then
|
||||
affected_dirs=$(echo -e ".\n$affected_dirs" | sort -u)
|
||||
fi
|
||||
fi
|
||||
|
||||
# Step 4: Output in requested format
|
||||
case "$format" in
|
||||
"list")
|
||||
if [ -n "$affected_dirs" ]; then
|
||||
echo "$affected_dirs" | while read dir; do
|
||||
if [ -d "$dir" ]; then
|
||||
local file_count=$(find "$dir" -maxdepth 1 -type f 2>/dev/null | wc -l)
|
||||
local depth=$(echo "$dir" | tr -cd '/' | wc -c)
|
||||
if [ "$dir" = "." ]; then depth=0; fi
|
||||
|
||||
local types=$(find "$dir" -maxdepth 1 -type f -name "*.*" 2>/dev/null | \
|
||||
grep -E '\.[^/]*$' | sed 's/.*\.//' | sort -u | tr '\n' ',' | sed 's/,$//')
|
||||
local has_claude="no"
|
||||
[ -f "$dir/CLAUDE.md" ] && has_claude="yes"
|
||||
echo "depth:$depth|path:$dir|files:$file_count|types:[$types]|has_claude:$has_claude|status:changed"
|
||||
fi
|
||||
done
|
||||
fi
|
||||
;;
|
||||
|
||||
"grouped")
|
||||
if [ -n "$affected_dirs" ]; then
|
||||
echo "📊 Affected modules by changes:"
|
||||
# Group by depth
|
||||
echo "$affected_dirs" | while read dir; do
|
||||
if [ -d "$dir" ]; then
|
||||
local depth=$(echo "$dir" | tr -cd '/' | wc -c)
|
||||
if [ "$dir" = "." ]; then depth=0; fi
|
||||
local claude_indicator=""
|
||||
[ -f "$dir/CLAUDE.md" ] && claude_indicator=" [✓]"
|
||||
echo "$depth:$dir$claude_indicator"
|
||||
fi
|
||||
done | sort -n | awk -F: '
|
||||
{
|
||||
if ($1 != prev_depth) {
|
||||
if (prev_depth != "") print ""
|
||||
print " 📁 Depth " $1 ":"
|
||||
prev_depth = $1
|
||||
}
|
||||
print " - " $2 " (changed)"
|
||||
}'
|
||||
else
|
||||
echo "📊 No recent changes detected"
|
||||
fi
|
||||
;;
|
||||
|
||||
"paths"|*)
|
||||
echo "$affected_dirs"
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
# Execute function if script is run directly
|
||||
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
|
||||
detect_changed_modules "$@"
|
||||
fi
|
||||
83
.claude/scripts/discover-design-files.sh
Normal file
83
.claude/scripts/discover-design-files.sh
Normal file
@@ -0,0 +1,83 @@
|
||||
#!/usr/bin/env bash
|
||||
# discover-design-files.sh - Discover design-related files and output JSON
|
||||
# Usage: discover-design-files.sh <source_dir> <output_json>
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
source_dir="${1:-.}"
|
||||
output_json="${2:-discovered-files.json}"
|
||||
|
||||
# Function to find and format files as JSON array
|
||||
find_files() {
|
||||
local pattern="$1"
|
||||
local files
|
||||
files=$(eval "find \"$source_dir\" -type f $pattern \
|
||||
! -path \"*/node_modules/*\" \
|
||||
! -path \"*/dist/*\" \
|
||||
! -path \"*/.git/*\" \
|
||||
! -path \"*/build/*\" \
|
||||
! -path \"*/coverage/*\" \
|
||||
2>/dev/null | sort || true")
|
||||
|
||||
local count
|
||||
if [ -z "$files" ]; then
|
||||
count=0
|
||||
else
|
||||
count=$(echo "$files" | grep -c . || echo 0)
|
||||
fi
|
||||
local json_files=""
|
||||
|
||||
if [ "$count" -gt 0 ]; then
|
||||
json_files=$(echo "$files" | awk '{printf "\"%s\"%s\n", $0, (NR<'$count'?",":"")}' | tr '\n' ' ')
|
||||
fi
|
||||
|
||||
echo "$count|$json_files"
|
||||
}
|
||||
|
||||
# Discover CSS/SCSS files
|
||||
css_result=$(find_files '\( -name "*.css" -o -name "*.scss" \)')
|
||||
css_count=${css_result%%|*}
|
||||
css_files=${css_result#*|}
|
||||
|
||||
# Discover JS/TS files (all framework files)
|
||||
js_result=$(find_files '\( -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" -o -name "*.mjs" -o -name "*.cjs" -o -name "*.vue" -o -name "*.svelte" \)')
|
||||
js_count=${js_result%%|*}
|
||||
js_files=${js_result#*|}
|
||||
|
||||
# Discover HTML files
|
||||
html_result=$(find_files '-name "*.html"')
|
||||
html_count=${html_result%%|*}
|
||||
html_files=${html_result#*|}
|
||||
|
||||
# Calculate total
|
||||
total_count=$((css_count + js_count + html_count))
|
||||
|
||||
# Generate JSON
|
||||
cat > "$output_json" << EOF
|
||||
{
|
||||
"discovery_time": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
|
||||
"source_directory": "$(cd "$source_dir" && pwd)",
|
||||
"file_types": {
|
||||
"css": {
|
||||
"count": $css_count,
|
||||
"files": [${css_files}]
|
||||
},
|
||||
"js": {
|
||||
"count": $js_count,
|
||||
"files": [${js_files}]
|
||||
},
|
||||
"html": {
|
||||
"count": $html_count,
|
||||
"files": [${html_files}]
|
||||
}
|
||||
},
|
||||
"total_files": $total_count
|
||||
}
|
||||
EOF
|
||||
|
||||
# Ensure file is fully written and synchronized to disk
|
||||
# This prevents race conditions when the file is immediately read by another process
|
||||
sync "$output_json" 2>/dev/null || sync # Sync specific file, fallback to full sync
|
||||
sleep 0.1 # Additional safety: 100ms delay for filesystem metadata update
|
||||
|
||||
echo "Discovered: CSS=$css_count, JS=$js_count, HTML=$html_count (Total: $total_count)" >&2
|
||||
243
.claude/scripts/extract-animations.js
Normal file
243
.claude/scripts/extract-animations.js
Normal file
@@ -0,0 +1,243 @@
|
||||
/**
|
||||
* Animation & Transition Extraction Script
|
||||
*
|
||||
* Extracts CSS animations, transitions, and transform patterns from a live web page.
|
||||
* This script runs in the browser context via Chrome DevTools Protocol.
|
||||
*
|
||||
* @returns {Object} Structured animation data
|
||||
*/
|
||||
(() => {
|
||||
const extractionTimestamp = new Date().toISOString();
|
||||
const currentUrl = window.location.href;
|
||||
|
||||
/**
|
||||
* Parse transition shorthand or individual properties
|
||||
*/
|
||||
function parseTransition(element, computedStyle) {
|
||||
const transition = computedStyle.transition || computedStyle.webkitTransition;
|
||||
|
||||
if (!transition || transition === 'none' || transition === 'all 0s ease 0s') {
|
||||
return null;
|
||||
}
|
||||
|
||||
// Parse shorthand: "property duration easing delay"
|
||||
const transitions = [];
|
||||
const parts = transition.split(/,\s*/);
|
||||
|
||||
parts.forEach(part => {
|
||||
const match = part.match(/^(\S+)\s+([\d.]+m?s)\s+(\S+)(?:\s+([\d.]+m?s))?/);
|
||||
if (match) {
|
||||
transitions.push({
|
||||
property: match[1],
|
||||
duration: match[2],
|
||||
easing: match[3],
|
||||
delay: match[4] || '0s'
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
return transitions.length > 0 ? transitions : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract animation name and properties
|
||||
*/
|
||||
function parseAnimation(element, computedStyle) {
|
||||
const animationName = computedStyle.animationName || computedStyle.webkitAnimationName;
|
||||
|
||||
if (!animationName || animationName === 'none') {
|
||||
return null;
|
||||
}
|
||||
|
||||
return {
|
||||
name: animationName,
|
||||
duration: computedStyle.animationDuration || computedStyle.webkitAnimationDuration,
|
||||
easing: computedStyle.animationTimingFunction || computedStyle.webkitAnimationTimingFunction,
|
||||
delay: computedStyle.animationDelay || computedStyle.webkitAnimationDelay || '0s',
|
||||
iterationCount: computedStyle.animationIterationCount || computedStyle.webkitAnimationIterationCount || '1',
|
||||
direction: computedStyle.animationDirection || computedStyle.webkitAnimationDirection || 'normal',
|
||||
fillMode: computedStyle.animationFillMode || computedStyle.webkitAnimationFillMode || 'none'
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract transform value
|
||||
*/
|
||||
function parseTransform(computedStyle) {
|
||||
const transform = computedStyle.transform || computedStyle.webkitTransform;
|
||||
|
||||
if (!transform || transform === 'none') {
|
||||
return null;
|
||||
}
|
||||
|
||||
return transform;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get element selector (simplified for readability)
|
||||
*/
|
||||
function getSelector(element) {
|
||||
if (element.id) {
|
||||
return `#${element.id}`;
|
||||
}
|
||||
|
||||
if (element.className && typeof element.className === 'string') {
|
||||
const classes = element.className.trim().split(/\s+/).slice(0, 2).join('.');
|
||||
if (classes) {
|
||||
return `.${classes}`;
|
||||
}
|
||||
}
|
||||
|
||||
return element.tagName.toLowerCase();
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract all stylesheets and find @keyframes rules
|
||||
*/
|
||||
function extractKeyframes() {
|
||||
const keyframes = {};
|
||||
|
||||
try {
|
||||
// Iterate through all stylesheets
|
||||
Array.from(document.styleSheets).forEach(sheet => {
|
||||
try {
|
||||
// Skip external stylesheets due to CORS
|
||||
if (sheet.href && !sheet.href.startsWith(window.location.origin)) {
|
||||
return;
|
||||
}
|
||||
|
||||
Array.from(sheet.cssRules || sheet.rules || []).forEach(rule => {
|
||||
// Check for @keyframes rules
|
||||
if (rule.type === CSSRule.KEYFRAMES_RULE || rule.type === CSSRule.WEBKIT_KEYFRAMES_RULE) {
|
||||
const name = rule.name;
|
||||
const frames = {};
|
||||
|
||||
Array.from(rule.cssRules || []).forEach(keyframe => {
|
||||
const key = keyframe.keyText; // e.g., "0%", "50%", "100%"
|
||||
frames[key] = keyframe.style.cssText;
|
||||
});
|
||||
|
||||
keyframes[name] = frames;
|
||||
}
|
||||
});
|
||||
} catch (e) {
|
||||
// Skip stylesheets that can't be accessed (CORS)
|
||||
console.warn('Cannot access stylesheet:', sheet.href, e.message);
|
||||
}
|
||||
});
|
||||
} catch (e) {
|
||||
console.error('Error extracting keyframes:', e);
|
||||
}
|
||||
|
||||
return keyframes;
|
||||
}
|
||||
|
||||
/**
|
||||
* Scan visible elements for animations and transitions
|
||||
*/
|
||||
function scanElements() {
|
||||
const elements = document.querySelectorAll('*');
|
||||
const transitionData = [];
|
||||
const animationData = [];
|
||||
const transformData = [];
|
||||
|
||||
const uniqueTransitions = new Set();
|
||||
const uniqueAnimations = new Set();
|
||||
const uniqueEasings = new Set();
|
||||
const uniqueDurations = new Set();
|
||||
|
||||
elements.forEach(element => {
|
||||
// Skip invisible elements
|
||||
const rect = element.getBoundingClientRect();
|
||||
if (rect.width === 0 && rect.height === 0) {
|
||||
return;
|
||||
}
|
||||
|
||||
const computedStyle = window.getComputedStyle(element);
|
||||
|
||||
// Extract transitions
|
||||
const transitions = parseTransition(element, computedStyle);
|
||||
if (transitions) {
|
||||
const selector = getSelector(element);
|
||||
transitions.forEach(t => {
|
||||
const key = `${t.property}-${t.duration}-${t.easing}`;
|
||||
if (!uniqueTransitions.has(key)) {
|
||||
uniqueTransitions.add(key);
|
||||
transitionData.push({
|
||||
selector,
|
||||
...t
|
||||
});
|
||||
uniqueEasings.add(t.easing);
|
||||
uniqueDurations.add(t.duration);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// Extract animations
|
||||
const animation = parseAnimation(element, computedStyle);
|
||||
if (animation) {
|
||||
const selector = getSelector(element);
|
||||
const key = `${animation.name}-${animation.duration}`;
|
||||
if (!uniqueAnimations.has(key)) {
|
||||
uniqueAnimations.add(key);
|
||||
animationData.push({
|
||||
selector,
|
||||
...animation
|
||||
});
|
||||
uniqueEasings.add(animation.easing);
|
||||
uniqueDurations.add(animation.duration);
|
||||
}
|
||||
}
|
||||
|
||||
// Extract transforms (on hover/active, we only get current state)
|
||||
const transform = parseTransform(computedStyle);
|
||||
if (transform) {
|
||||
const selector = getSelector(element);
|
||||
transformData.push({
|
||||
selector,
|
||||
transform
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
return {
|
||||
transitions: transitionData,
|
||||
animations: animationData,
|
||||
transforms: transformData,
|
||||
uniqueEasings: Array.from(uniqueEasings),
|
||||
uniqueDurations: Array.from(uniqueDurations)
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Main extraction function
|
||||
*/
|
||||
function extractAnimations() {
|
||||
const elementData = scanElements();
|
||||
const keyframes = extractKeyframes();
|
||||
|
||||
return {
|
||||
metadata: {
|
||||
timestamp: extractionTimestamp,
|
||||
url: currentUrl,
|
||||
method: 'chrome-devtools',
|
||||
version: '1.0.0'
|
||||
},
|
||||
transitions: elementData.transitions,
|
||||
animations: elementData.animations,
|
||||
transforms: elementData.transforms,
|
||||
keyframes: keyframes,
|
||||
summary: {
|
||||
total_transitions: elementData.transitions.length,
|
||||
total_animations: elementData.animations.length,
|
||||
total_transforms: elementData.transforms.length,
|
||||
total_keyframes: Object.keys(keyframes).length,
|
||||
unique_easings: elementData.uniqueEasings,
|
||||
unique_durations: elementData.uniqueDurations
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
// Execute extraction
|
||||
return extractAnimations();
|
||||
})();
|
||||
118
.claude/scripts/extract-computed-styles.js
Normal file
118
.claude/scripts/extract-computed-styles.js
Normal file
@@ -0,0 +1,118 @@
|
||||
/**
|
||||
* Extract Computed Styles from DOM
|
||||
*
|
||||
* This script extracts real CSS computed styles from a webpage's DOM
|
||||
* to provide accurate design tokens for UI replication.
|
||||
*
|
||||
* Usage: Execute this function via Chrome DevTools evaluate_script
|
||||
*/
|
||||
|
||||
(() => {
|
||||
/**
|
||||
* Extract unique values from a set and sort them
|
||||
*/
|
||||
const uniqueSorted = (set) => {
|
||||
return Array.from(set)
|
||||
.filter(v => v && v !== 'none' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)')
|
||||
.sort();
|
||||
};
|
||||
|
||||
/**
|
||||
* Parse rgb/rgba to OKLCH format (placeholder - returns original for now)
|
||||
*/
|
||||
const toOKLCH = (color) => {
|
||||
// TODO: Implement actual RGB to OKLCH conversion
|
||||
// For now, return the original color with a note
|
||||
return `${color} /* TODO: Convert to OKLCH */`;
|
||||
};
|
||||
|
||||
/**
|
||||
* Extract only key styles from an element
|
||||
*/
|
||||
const extractKeyStyles = (element) => {
|
||||
const s = window.getComputedStyle(element);
|
||||
return {
|
||||
color: s.color,
|
||||
bg: s.backgroundColor,
|
||||
borderRadius: s.borderRadius,
|
||||
boxShadow: s.boxShadow,
|
||||
fontSize: s.fontSize,
|
||||
fontWeight: s.fontWeight,
|
||||
padding: s.padding,
|
||||
margin: s.margin
|
||||
};
|
||||
};
|
||||
|
||||
/**
|
||||
* Main extraction function - extract all critical design tokens
|
||||
*/
|
||||
const extractDesignTokens = () => {
|
||||
// Include all key UI elements
|
||||
const selectors = [
|
||||
'button', '.btn', '[role="button"]',
|
||||
'input', 'textarea', 'select',
|
||||
'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
|
||||
'.card', 'article', 'section',
|
||||
'a', 'p', 'nav', 'header', 'footer'
|
||||
];
|
||||
|
||||
// Collect all design tokens
|
||||
const tokens = {
|
||||
colors: new Set(),
|
||||
borderRadii: new Set(),
|
||||
shadows: new Set(),
|
||||
fontSizes: new Set(),
|
||||
fontWeights: new Set(),
|
||||
spacing: new Set()
|
||||
};
|
||||
|
||||
// Extract from all elements
|
||||
selectors.forEach(selector => {
|
||||
try {
|
||||
const elements = document.querySelectorAll(selector);
|
||||
elements.forEach(element => {
|
||||
const s = extractKeyStyles(element);
|
||||
|
||||
// Collect all tokens (no limits)
|
||||
if (s.color && s.color !== 'rgba(0, 0, 0, 0)') tokens.colors.add(s.color);
|
||||
if (s.bg && s.bg !== 'rgba(0, 0, 0, 0)') tokens.colors.add(s.bg);
|
||||
if (s.borderRadius && s.borderRadius !== '0px') tokens.borderRadii.add(s.borderRadius);
|
||||
if (s.boxShadow && s.boxShadow !== 'none') tokens.shadows.add(s.boxShadow);
|
||||
if (s.fontSize) tokens.fontSizes.add(s.fontSize);
|
||||
if (s.fontWeight) tokens.fontWeights.add(s.fontWeight);
|
||||
|
||||
// Extract all spacing values
|
||||
[s.padding, s.margin].forEach(val => {
|
||||
if (val && val !== '0px') {
|
||||
val.split(' ').forEach(v => {
|
||||
if (v && v !== '0px') tokens.spacing.add(v);
|
||||
});
|
||||
}
|
||||
});
|
||||
});
|
||||
} catch (e) {
|
||||
console.warn(`Error: ${selector}`, e);
|
||||
}
|
||||
});
|
||||
|
||||
// Return all tokens (no element details to save context)
|
||||
return {
|
||||
metadata: {
|
||||
extractedAt: new Date().toISOString(),
|
||||
url: window.location.href,
|
||||
method: 'computed-styles'
|
||||
},
|
||||
tokens: {
|
||||
colors: uniqueSorted(tokens.colors),
|
||||
borderRadii: uniqueSorted(tokens.borderRadii), // ALL radius values
|
||||
shadows: uniqueSorted(tokens.shadows), // ALL shadows
|
||||
fontSizes: uniqueSorted(tokens.fontSizes),
|
||||
fontWeights: uniqueSorted(tokens.fontWeights),
|
||||
spacing: uniqueSorted(tokens.spacing)
|
||||
}
|
||||
};
|
||||
};
|
||||
|
||||
// Execute and return results
|
||||
return extractDesignTokens();
|
||||
})();
|
||||
411
.claude/scripts/extract-layout-structure.js
Normal file
411
.claude/scripts/extract-layout-structure.js
Normal file
@@ -0,0 +1,411 @@
|
||||
/**
|
||||
* Extract Layout Structure from DOM - Enhanced Version
|
||||
*
|
||||
* Extracts real layout information from DOM to provide accurate
|
||||
* structural data for UI replication.
|
||||
*
|
||||
* Features:
|
||||
* - Framework detection (Nuxt.js, Next.js, React, Vue, Angular)
|
||||
* - Multi-strategy container detection (strict → relaxed → class-based → framework-specific)
|
||||
* - Intelligent main content detection with common class names support
|
||||
* - Supports modern SPA frameworks
|
||||
* - Detects non-semantic main containers (.main, .content, etc.)
|
||||
* - Progressive exploration: Auto-discovers missing selectors when standard patterns fail
|
||||
* - Suggests new class names to add to script based on actual page structure
|
||||
*
|
||||
* Progressive Exploration:
|
||||
* When fewer than 3 main containers are found, the script automatically:
|
||||
* 1. Analyzes all large visible containers (≥500×300px)
|
||||
* 2. Extracts class name patterns (main/content/wrapper/container/page/etc.)
|
||||
* 3. Suggests new selectors to add to the script
|
||||
* 4. Returns exploration data in result.exploration
|
||||
*
|
||||
* Usage: Execute via Chrome DevTools evaluate_script
|
||||
* Version: 2.2.0
|
||||
*/
|
||||
|
||||
(() => {
|
||||
/**
|
||||
* Get element's bounding box relative to viewport
|
||||
*/
|
||||
const getBounds = (element) => {
|
||||
const rect = element.getBoundingClientRect();
|
||||
return {
|
||||
x: Math.round(rect.x),
|
||||
y: Math.round(rect.y),
|
||||
width: Math.round(rect.width),
|
||||
height: Math.round(rect.height)
|
||||
};
|
||||
};
|
||||
|
||||
/**
|
||||
* Extract layout properties from an element
|
||||
*/
|
||||
const extractLayoutProps = (element) => {
|
||||
const s = window.getComputedStyle(element);
|
||||
|
||||
return {
|
||||
// Core layout
|
||||
display: s.display,
|
||||
position: s.position,
|
||||
|
||||
// Flexbox
|
||||
flexDirection: s.flexDirection,
|
||||
justifyContent: s.justifyContent,
|
||||
alignItems: s.alignItems,
|
||||
flexWrap: s.flexWrap,
|
||||
gap: s.gap,
|
||||
|
||||
// Grid
|
||||
gridTemplateColumns: s.gridTemplateColumns,
|
||||
gridTemplateRows: s.gridTemplateRows,
|
||||
gridAutoFlow: s.gridAutoFlow,
|
||||
|
||||
// Dimensions
|
||||
width: s.width,
|
||||
height: s.height,
|
||||
maxWidth: s.maxWidth,
|
||||
minWidth: s.minWidth,
|
||||
|
||||
// Spacing
|
||||
padding: s.padding,
|
||||
margin: s.margin
|
||||
};
|
||||
};
|
||||
|
||||
/**
|
||||
* Identify layout pattern for an element
|
||||
*/
|
||||
const identifyPattern = (props) => {
|
||||
const { display, flexDirection, gridTemplateColumns } = props;
|
||||
|
||||
if (display === 'flex' || display === 'inline-flex') {
|
||||
if (flexDirection === 'column') return 'flex-column';
|
||||
if (flexDirection === 'row') return 'flex-row';
|
||||
return 'flex';
|
||||
}
|
||||
|
||||
if (display === 'grid') {
|
||||
const cols = gridTemplateColumns;
|
||||
if (cols && cols !== 'none') {
|
||||
const colCount = cols.split(' ').length;
|
||||
return `grid-${colCount}col`;
|
||||
}
|
||||
return 'grid';
|
||||
}
|
||||
|
||||
if (display === 'block') return 'block';
|
||||
|
||||
return display;
|
||||
};
|
||||
|
||||
/**
|
||||
* Detect frontend framework
|
||||
*/
|
||||
const detectFramework = () => {
|
||||
if (document.querySelector('#__nuxt')) return { name: 'Nuxt.js', version: 'unknown' };
|
||||
if (document.querySelector('#__next')) return { name: 'Next.js', version: 'unknown' };
|
||||
if (document.querySelector('[data-reactroot]')) return { name: 'React', version: 'unknown' };
|
||||
if (document.querySelector('[ng-version]')) return { name: 'Angular', version: 'unknown' };
|
||||
if (window.Vue) return { name: 'Vue.js', version: window.Vue.version || 'unknown' };
|
||||
return { name: 'Unknown', version: 'unknown' };
|
||||
};
|
||||
|
||||
/**
|
||||
* Build layout tree recursively
|
||||
*/
|
||||
const buildLayoutTree = (element, depth = 0, maxDepth = 3) => {
|
||||
if (depth > maxDepth) return null;
|
||||
|
||||
const props = extractLayoutProps(element);
|
||||
const bounds = getBounds(element);
|
||||
const pattern = identifyPattern(props);
|
||||
|
||||
// Get semantic role
|
||||
const tagName = element.tagName.toLowerCase();
|
||||
const classes = Array.from(element.classList).slice(0, 3); // Max 3 classes
|
||||
const role = element.getAttribute('role');
|
||||
|
||||
// Build node
|
||||
const node = {
|
||||
tag: tagName,
|
||||
classes: classes,
|
||||
role: role,
|
||||
pattern: pattern,
|
||||
bounds: bounds,
|
||||
layout: {
|
||||
display: props.display,
|
||||
position: props.position
|
||||
}
|
||||
};
|
||||
|
||||
// Add flex/grid specific properties
|
||||
if (props.display === 'flex' || props.display === 'inline-flex') {
|
||||
node.layout.flexDirection = props.flexDirection;
|
||||
node.layout.justifyContent = props.justifyContent;
|
||||
node.layout.alignItems = props.alignItems;
|
||||
node.layout.gap = props.gap;
|
||||
}
|
||||
|
||||
if (props.display === 'grid') {
|
||||
node.layout.gridTemplateColumns = props.gridTemplateColumns;
|
||||
node.layout.gridTemplateRows = props.gridTemplateRows;
|
||||
node.layout.gap = props.gap;
|
||||
}
|
||||
|
||||
// Process children for container elements
|
||||
if (props.display === 'flex' || props.display === 'grid' || props.display === 'block') {
|
||||
const children = Array.from(element.children);
|
||||
if (children.length > 0 && children.length < 50) { // Limit to 50 children
|
||||
node.children = children
|
||||
.map(child => buildLayoutTree(child, depth + 1, maxDepth))
|
||||
.filter(child => child !== null);
|
||||
}
|
||||
}
|
||||
|
||||
return node;
|
||||
};
|
||||
|
||||
/**
|
||||
* Find main layout containers with multi-strategy approach
|
||||
*/
|
||||
const findMainContainers = () => {
|
||||
const containers = [];
|
||||
const found = new Set();
|
||||
|
||||
// Strategy 1: Strict selectors (body direct children)
|
||||
const strictSelectors = [
|
||||
'body > header',
|
||||
'body > nav',
|
||||
'body > main',
|
||||
'body > footer'
|
||||
];
|
||||
|
||||
// Strategy 2: Relaxed selectors (any level)
|
||||
const relaxedSelectors = [
|
||||
'header',
|
||||
'nav',
|
||||
'main',
|
||||
'footer',
|
||||
'[role="banner"]',
|
||||
'[role="navigation"]',
|
||||
'[role="main"]',
|
||||
'[role="contentinfo"]'
|
||||
];
|
||||
|
||||
// Strategy 3: Common class-based main content selectors
|
||||
const commonClassSelectors = [
|
||||
'.main',
|
||||
'.content',
|
||||
'.main-content',
|
||||
'.page-content',
|
||||
'.container.main',
|
||||
'.wrapper > .main',
|
||||
'div[class*="main-wrapper"]',
|
||||
'div[class*="content-wrapper"]'
|
||||
];
|
||||
|
||||
// Strategy 4: Framework-specific selectors
|
||||
const frameworkSelectors = [
|
||||
'#__nuxt header', '#__nuxt .main', '#__nuxt main', '#__nuxt footer',
|
||||
'#__next header', '#__next .main', '#__next main', '#__next footer',
|
||||
'#app header', '#app .main', '#app main', '#app footer',
|
||||
'[data-app] header', '[data-app] .main', '[data-app] main', '[data-app] footer'
|
||||
];
|
||||
|
||||
// Try all strategies
|
||||
const allSelectors = [...strictSelectors, ...relaxedSelectors, ...commonClassSelectors, ...frameworkSelectors];
|
||||
|
||||
allSelectors.forEach(selector => {
|
||||
try {
|
||||
const elements = document.querySelectorAll(selector);
|
||||
elements.forEach(element => {
|
||||
// Avoid duplicates and invisible elements
|
||||
if (!found.has(element) && element.offsetParent !== null) {
|
||||
found.add(element);
|
||||
const tree = buildLayoutTree(element, 0, 3);
|
||||
if (tree && tree.bounds.width > 0 && tree.bounds.height > 0) {
|
||||
containers.push(tree);
|
||||
}
|
||||
}
|
||||
});
|
||||
} catch (e) {
|
||||
console.warn(`Selector failed: ${selector}`, e);
|
||||
}
|
||||
});
|
||||
|
||||
// Fallback: If no containers found, use body's direct children
|
||||
if (containers.length === 0) {
|
||||
Array.from(document.body.children).forEach(child => {
|
||||
if (child.offsetParent !== null && !found.has(child)) {
|
||||
const tree = buildLayoutTree(child, 0, 2);
|
||||
if (tree && tree.bounds.width > 100 && tree.bounds.height > 100) {
|
||||
containers.push(tree);
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
return containers;
|
||||
};
|
||||
|
||||
/**
|
||||
* Progressive exploration: Discover main containers when standard selectors fail
|
||||
* Analyzes large visible containers and suggests class name patterns
|
||||
*/
|
||||
const exploreMainContainers = () => {
|
||||
const candidates = [];
|
||||
const minWidth = 500;
|
||||
const minHeight = 300;
|
||||
|
||||
// Find all large visible divs
|
||||
const allDivs = document.querySelectorAll('div');
|
||||
allDivs.forEach(div => {
|
||||
const rect = div.getBoundingClientRect();
|
||||
const style = window.getComputedStyle(div);
|
||||
|
||||
// Filter: large size, visible, not header/footer
|
||||
if (rect.width >= minWidth &&
|
||||
rect.height >= minHeight &&
|
||||
div.offsetParent !== null &&
|
||||
!div.closest('header') &&
|
||||
!div.closest('footer')) {
|
||||
|
||||
const classes = Array.from(div.classList);
|
||||
const area = rect.width * rect.height;
|
||||
|
||||
candidates.push({
|
||||
element: div,
|
||||
classes: classes,
|
||||
area: area,
|
||||
bounds: {
|
||||
width: Math.round(rect.width),
|
||||
height: Math.round(rect.height)
|
||||
},
|
||||
display: style.display,
|
||||
depth: getElementDepth(div)
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
// Sort by area (largest first) and take top candidates
|
||||
candidates.sort((a, b) => b.area - a.area);
|
||||
|
||||
// Extract unique class patterns from top candidates
|
||||
const classPatterns = new Set();
|
||||
candidates.slice(0, 20).forEach(c => {
|
||||
c.classes.forEach(cls => {
|
||||
// Identify potential main content class patterns
|
||||
if (cls.match(/main|content|container|wrapper|page|body|layout|app/i)) {
|
||||
classPatterns.add(cls);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
return {
|
||||
candidates: candidates.slice(0, 10).map(c => ({
|
||||
classes: c.classes,
|
||||
bounds: c.bounds,
|
||||
display: c.display,
|
||||
depth: c.depth
|
||||
})),
|
||||
suggestedSelectors: Array.from(classPatterns).map(cls => `.${cls}`)
|
||||
};
|
||||
};
|
||||
|
||||
/**
|
||||
* Get element depth in DOM tree
|
||||
*/
|
||||
const getElementDepth = (element) => {
|
||||
let depth = 0;
|
||||
let current = element;
|
||||
while (current.parentElement) {
|
||||
depth++;
|
||||
current = current.parentElement;
|
||||
}
|
||||
return depth;
|
||||
};
|
||||
|
||||
/**
|
||||
* Analyze layout patterns
|
||||
*/
|
||||
const analyzePatterns = (containers) => {
|
||||
const patterns = {
|
||||
flexColumn: 0,
|
||||
flexRow: 0,
|
||||
grid: 0,
|
||||
sticky: 0,
|
||||
fixed: 0
|
||||
};
|
||||
|
||||
const analyze = (node) => {
|
||||
if (!node) return;
|
||||
|
||||
if (node.pattern === 'flex-column') patterns.flexColumn++;
|
||||
if (node.pattern === 'flex-row') patterns.flexRow++;
|
||||
if (node.pattern && node.pattern.startsWith('grid')) patterns.grid++;
|
||||
if (node.layout.position === 'sticky') patterns.sticky++;
|
||||
if (node.layout.position === 'fixed') patterns.fixed++;
|
||||
|
||||
if (node.children) {
|
||||
node.children.forEach(analyze);
|
||||
}
|
||||
};
|
||||
|
||||
containers.forEach(analyze);
|
||||
return patterns;
|
||||
};
|
||||
|
||||
/**
|
||||
* Main extraction function with progressive exploration
|
||||
*/
|
||||
const extractLayout = () => {
|
||||
const framework = detectFramework();
|
||||
const containers = findMainContainers();
|
||||
const patterns = analyzePatterns(containers);
|
||||
|
||||
// Progressive exploration: if too few containers found, explore and suggest
|
||||
let exploration = null;
|
||||
const minExpectedContainers = 3; // At least header, main, footer
|
||||
|
||||
if (containers.length < minExpectedContainers) {
|
||||
exploration = exploreMainContainers();
|
||||
|
||||
// Add warning message
|
||||
exploration.warning = `Only ${containers.length} containers found. Consider adding these selectors to the script:`;
|
||||
exploration.recommendation = exploration.suggestedSelectors.join(', ');
|
||||
}
|
||||
|
||||
const result = {
|
||||
metadata: {
|
||||
extractedAt: new Date().toISOString(),
|
||||
url: window.location.href,
|
||||
framework: framework,
|
||||
method: 'layout-structure-enhanced',
|
||||
version: '2.2.0'
|
||||
},
|
||||
statistics: {
|
||||
totalContainers: containers.length,
|
||||
patterns: patterns
|
||||
},
|
||||
structure: containers
|
||||
};
|
||||
|
||||
// Add exploration results if triggered
|
||||
if (exploration) {
|
||||
result.exploration = {
|
||||
triggered: true,
|
||||
reason: 'Insufficient containers found with standard selectors',
|
||||
discoveredCandidates: exploration.candidates,
|
||||
suggestedSelectors: exploration.suggestedSelectors,
|
||||
warning: exploration.warning,
|
||||
recommendation: exploration.recommendation
|
||||
};
|
||||
}
|
||||
|
||||
return result;
|
||||
};
|
||||
|
||||
// Execute and return results
|
||||
return extractLayout();
|
||||
})();
|
||||
713
.claude/scripts/generate_module_docs.sh
Normal file
713
.claude/scripts/generate_module_docs.sh
Normal file
@@ -0,0 +1,713 @@
|
||||
#!/bin/bash
|
||||
# Generate documentation for modules and projects with multiple strategies
|
||||
# Usage: generate_module_docs.sh <strategy> <source_path> <project_name> [tool] [model]
|
||||
# strategy: full|single|project-readme|project-architecture|http-api
|
||||
# source_path: Path to the source module directory (or project root for project-level docs)
|
||||
# project_name: Project name for output path (e.g., "myproject")
|
||||
# tool: gemini|qwen|codex (default: gemini)
|
||||
# model: Model name (optional, uses tool defaults)
|
||||
#
|
||||
# Default Models:
|
||||
# gemini: gemini-2.5-flash
|
||||
# qwen: coder-model
|
||||
# codex: gpt5-codex
|
||||
#
|
||||
# Module-Level Strategies:
|
||||
# full: Full documentation generation
|
||||
# - Read: All files in current and subdirectories (@**/*)
|
||||
# - Generate: API.md + README.md for each directory containing code files
|
||||
# - Use: Deep directories (Layer 3), comprehensive documentation
|
||||
#
|
||||
# single: Single-layer documentation
|
||||
# - Read: Current directory code + child API.md/README.md files
|
||||
# - Generate: API.md + README.md only in current directory
|
||||
# - Use: Upper layers (Layer 1-2), incremental updates
|
||||
#
|
||||
# Project-Level Strategies:
|
||||
# project-readme: Project overview documentation
|
||||
# - Read: All module API.md and README.md files
|
||||
# - Generate: README.md (project root)
|
||||
# - Use: After all module docs are generated
|
||||
#
|
||||
# project-architecture: System design documentation
|
||||
# - Read: All module docs + project README
|
||||
# - Generate: ARCHITECTURE.md + EXAMPLES.md
|
||||
# - Use: After project README is generated
|
||||
#
|
||||
# http-api: HTTP API documentation
|
||||
# - Read: API route files + existing docs
|
||||
# - Generate: api/README.md
|
||||
# - Use: For projects with HTTP APIs
|
||||
#
|
||||
# Output Structure:
|
||||
# Module docs: .workflow/docs/{project_name}/{source_path}/API.md
|
||||
# Module docs: .workflow/docs/{project_name}/{source_path}/README.md
|
||||
# Project docs: .workflow/docs/{project_name}/README.md
|
||||
# Project docs: .workflow/docs/{project_name}/ARCHITECTURE.md
|
||||
# Project docs: .workflow/docs/{project_name}/EXAMPLES.md
|
||||
# API docs: .workflow/docs/{project_name}/api/README.md
|
||||
#
|
||||
# Features:
|
||||
# - Path mirroring: source structure → docs structure
|
||||
# - Template-driven generation
|
||||
# - Respects .gitignore patterns
|
||||
# - Detects code vs navigation folders
|
||||
# - Tool fallback support
|
||||
|
||||
# Build exclusion filters from .gitignore
|
||||
build_exclusion_filters() {
|
||||
local filters=""
|
||||
|
||||
# Common system/cache directories to exclude
|
||||
local system_excludes=(
|
||||
".git" "__pycache__" "node_modules" ".venv" "venv" "env"
|
||||
"dist" "build" ".cache" ".pytest_cache" ".mypy_cache"
|
||||
"coverage" ".nyc_output" "logs" "tmp" "temp" ".workflow"
|
||||
)
|
||||
|
||||
for exclude in "${system_excludes[@]}"; do
|
||||
filters+=" -not -path '*/$exclude' -not -path '*/$exclude/*'"
|
||||
done
|
||||
|
||||
# Find and parse .gitignore (current dir first, then git root)
|
||||
local gitignore_file=""
|
||||
|
||||
# Check current directory first
|
||||
if [ -f ".gitignore" ]; then
|
||||
gitignore_file=".gitignore"
|
||||
else
|
||||
# Try to find git root and check for .gitignore there
|
||||
local git_root=$(git rev-parse --show-toplevel 2>/dev/null)
|
||||
if [ -n "$git_root" ] && [ -f "$git_root/.gitignore" ]; then
|
||||
gitignore_file="$git_root/.gitignore"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Parse .gitignore if found
|
||||
if [ -n "$gitignore_file" ]; then
|
||||
while IFS= read -r line; do
|
||||
# Skip empty lines and comments
|
||||
[[ -z "$line" || "$line" =~ ^[[:space:]]*# ]] && continue
|
||||
|
||||
# Remove trailing slash and whitespace
|
||||
line=$(echo "$line" | sed 's|/$||' | xargs)
|
||||
|
||||
# Skip wildcards patterns (too complex for simple find)
|
||||
[[ "$line" =~ \* ]] && continue
|
||||
|
||||
# Add to filters
|
||||
filters+=" -not -path '*/$line' -not -path '*/$line/*'"
|
||||
done < "$gitignore_file"
|
||||
fi
|
||||
|
||||
echo "$filters"
|
||||
}
|
||||
|
||||
# Detect folder type (code vs navigation)
|
||||
detect_folder_type() {
|
||||
local target_path="$1"
|
||||
local exclusion_filters="$2"
|
||||
|
||||
# Count code files (primary indicators)
|
||||
local code_count=$(eval "find \"$target_path\" -maxdepth 1 -type f \\( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.py' -o -name '*.sh' -o -name '*.go' -o -name '*.rs' \\) $exclusion_filters 2>/dev/null" | wc -l)
|
||||
|
||||
if [ $code_count -gt 0 ]; then
|
||||
echo "code"
|
||||
else
|
||||
echo "navigation"
|
||||
fi
|
||||
}
|
||||
|
||||
# Scan directory structure and generate structured information
|
||||
scan_directory_structure() {
|
||||
local target_path="$1"
|
||||
local strategy="$2"
|
||||
|
||||
if [ ! -d "$target_path" ]; then
|
||||
echo "Directory not found: $target_path"
|
||||
return 1
|
||||
fi
|
||||
|
||||
local exclusion_filters=$(build_exclusion_filters)
|
||||
local structure_info=""
|
||||
|
||||
# Get basic directory info
|
||||
local dir_name=$(basename "$target_path")
|
||||
local total_files=$(eval "find \"$target_path\" -type f $exclusion_filters 2>/dev/null" | wc -l)
|
||||
local total_dirs=$(eval "find \"$target_path\" -type d $exclusion_filters 2>/dev/null" | wc -l)
|
||||
local folder_type=$(detect_folder_type "$target_path" "$exclusion_filters")
|
||||
|
||||
structure_info+="Directory: $dir_name\n"
|
||||
structure_info+="Total files: $total_files\n"
|
||||
structure_info+="Total directories: $total_dirs\n"
|
||||
structure_info+="Folder type: $folder_type\n\n"
|
||||
|
||||
if [ "$strategy" = "full" ]; then
|
||||
# For full: show all subdirectories with file counts
|
||||
structure_info+="Subdirectories with files:\n"
|
||||
while IFS= read -r dir; do
|
||||
if [ -n "$dir" ] && [ "$dir" != "$target_path" ]; then
|
||||
local rel_path=${dir#$target_path/}
|
||||
local file_count=$(eval "find \"$dir\" -maxdepth 1 -type f $exclusion_filters 2>/dev/null" | wc -l)
|
||||
if [ $file_count -gt 0 ]; then
|
||||
local subdir_type=$(detect_folder_type "$dir" "$exclusion_filters")
|
||||
structure_info+=" - $rel_path/ ($file_count files, type: $subdir_type)\n"
|
||||
fi
|
||||
fi
|
||||
done < <(eval "find \"$target_path\" -type d $exclusion_filters 2>/dev/null")
|
||||
else
|
||||
# For single: show direct children only
|
||||
structure_info+="Direct subdirectories:\n"
|
||||
while IFS= read -r dir; do
|
||||
if [ -n "$dir" ]; then
|
||||
local dir_name=$(basename "$dir")
|
||||
local file_count=$(eval "find \"$dir\" -maxdepth 1 -type f $exclusion_filters 2>/dev/null" | wc -l)
|
||||
local has_api=$([ -f "$dir/API.md" ] && echo " [has API.md]" || echo "")
|
||||
local has_readme=$([ -f "$dir/README.md" ] && echo " [has README.md]" || echo "")
|
||||
structure_info+=" - $dir_name/ ($file_count files)$has_api$has_readme\n"
|
||||
fi
|
||||
done < <(eval "find \"$target_path\" -maxdepth 1 -type d $exclusion_filters 2>/dev/null" | grep -v "^$target_path$")
|
||||
fi
|
||||
|
||||
# Show main file types in current directory
|
||||
structure_info+="\nCurrent directory files:\n"
|
||||
local code_files=$(eval "find \"$target_path\" -maxdepth 1 -type f \\( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.py' -o -name '*.sh' -o -name '*.go' -o -name '*.rs' \\) $exclusion_filters 2>/dev/null" | wc -l)
|
||||
local config_files=$(eval "find \"$target_path\" -maxdepth 1 -type f \\( -name '*.json' -o -name '*.yaml' -o -name '*.yml' -o -name '*.toml' \\) $exclusion_filters 2>/dev/null" | wc -l)
|
||||
local doc_files=$(eval "find \"$target_path\" -maxdepth 1 -type f -name '*.md' $exclusion_filters 2>/dev/null" | wc -l)
|
||||
|
||||
structure_info+=" - Code files: $code_files\n"
|
||||
structure_info+=" - Config files: $config_files\n"
|
||||
structure_info+=" - Documentation: $doc_files\n"
|
||||
|
||||
printf "%b" "$structure_info"
|
||||
}
|
||||
|
||||
# Calculate output path based on source path and project name
|
||||
calculate_output_path() {
|
||||
local source_path="$1"
|
||||
local project_name="$2"
|
||||
local project_root="$3"
|
||||
|
||||
# Get absolute path of source (normalize to Unix-style path)
|
||||
local abs_source=$(cd "$source_path" && pwd)
|
||||
|
||||
# Normalize project root to same format
|
||||
local norm_project_root=$(cd "$project_root" && pwd)
|
||||
|
||||
# Calculate relative path from project root
|
||||
local rel_path="${abs_source#$norm_project_root}"
|
||||
|
||||
# Remove leading slash if present
|
||||
rel_path="${rel_path#/}"
|
||||
|
||||
# If source is project root, use project name directly
|
||||
if [ "$abs_source" = "$norm_project_root" ] || [ -z "$rel_path" ]; then
|
||||
echo "$norm_project_root/.workflow/docs/$project_name"
|
||||
else
|
||||
echo "$norm_project_root/.workflow/docs/$project_name/$rel_path"
|
||||
fi
|
||||
}
|
||||
|
||||
generate_module_docs() {
|
||||
local strategy="$1"
|
||||
local source_path="$2"
|
||||
local project_name="$3"
|
||||
local tool="${4:-gemini}"
|
||||
local model="$5"
|
||||
|
||||
# Validate parameters
|
||||
if [ -z "$strategy" ] || [ -z "$source_path" ] || [ -z "$project_name" ]; then
|
||||
echo "❌ Error: Strategy, source path, and project name are required"
|
||||
echo "Usage: generate_module_docs.sh <strategy> <source_path> <project_name> [tool] [model]"
|
||||
echo "Module strategies: full, single"
|
||||
echo "Project strategies: project-readme, project-architecture, http-api"
|
||||
return 1
|
||||
fi
|
||||
|
||||
# Validate strategy
|
||||
local valid_strategies=("full" "single" "project-readme" "project-architecture" "http-api")
|
||||
local strategy_valid=false
|
||||
for valid_strategy in "${valid_strategies[@]}"; do
|
||||
if [ "$strategy" = "$valid_strategy" ]; then
|
||||
strategy_valid=true
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
if [ "$strategy_valid" = false ]; then
|
||||
echo "❌ Error: Invalid strategy '$strategy'"
|
||||
echo "Valid module strategies: full, single"
|
||||
echo "Valid project strategies: project-readme, project-architecture, http-api"
|
||||
return 1
|
||||
fi
|
||||
|
||||
if [ ! -d "$source_path" ]; then
|
||||
echo "❌ Error: Source directory '$source_path' does not exist"
|
||||
return 1
|
||||
fi
|
||||
|
||||
# Set default models if not specified
|
||||
if [ -z "$model" ]; then
|
||||
case "$tool" in
|
||||
gemini)
|
||||
model="gemini-2.5-flash"
|
||||
;;
|
||||
qwen)
|
||||
model="coder-model"
|
||||
;;
|
||||
codex)
|
||||
model="gpt5-codex"
|
||||
;;
|
||||
*)
|
||||
model=""
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
|
||||
# Build exclusion filters
|
||||
local exclusion_filters=$(build_exclusion_filters)
|
||||
|
||||
# Get project root
|
||||
local project_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||
|
||||
# Determine if this is a project-level strategy
|
||||
local is_project_level=false
|
||||
if [[ "$strategy" =~ ^project- ]] || [ "$strategy" = "http-api" ]; then
|
||||
is_project_level=true
|
||||
fi
|
||||
|
||||
# Calculate output path
|
||||
local output_path
|
||||
if [ "$is_project_level" = true ]; then
|
||||
# Project-level docs go to project root
|
||||
if [ "$strategy" = "http-api" ]; then
|
||||
output_path="$project_root/.workflow/docs/$project_name/api"
|
||||
else
|
||||
output_path="$project_root/.workflow/docs/$project_name"
|
||||
fi
|
||||
else
|
||||
output_path=$(calculate_output_path "$source_path" "$project_name" "$project_root")
|
||||
fi
|
||||
|
||||
# Create output directory
|
||||
mkdir -p "$output_path"
|
||||
|
||||
# Detect folder type (only for module-level strategies)
|
||||
local folder_type=""
|
||||
if [ "$is_project_level" = false ]; then
|
||||
folder_type=$(detect_folder_type "$source_path" "$exclusion_filters")
|
||||
fi
|
||||
|
||||
# Load templates based on strategy
|
||||
local api_template=""
|
||||
local readme_template=""
|
||||
local template_content=""
|
||||
|
||||
if [ "$is_project_level" = true ]; then
|
||||
# Project-level templates
|
||||
case "$strategy" in
|
||||
project-readme)
|
||||
local proj_readme_path="$HOME/.claude/workflows/cli-templates/prompts/documentation/project-readme.txt"
|
||||
if [ -f "$proj_readme_path" ]; then
|
||||
template_content=$(cat "$proj_readme_path")
|
||||
echo " 📋 Loaded Project README template: $(wc -l < "$proj_readme_path") lines"
|
||||
fi
|
||||
;;
|
||||
project-architecture)
|
||||
local arch_path="$HOME/.claude/workflows/cli-templates/prompts/documentation/project-architecture.txt"
|
||||
local examples_path="$HOME/.claude/workflows/cli-templates/prompts/documentation/project-examples.txt"
|
||||
if [ -f "$arch_path" ]; then
|
||||
template_content=$(cat "$arch_path")
|
||||
echo " 📋 Loaded Architecture template: $(wc -l < "$arch_path") lines"
|
||||
fi
|
||||
if [ -f "$examples_path" ]; then
|
||||
template_content="$template_content
|
||||
|
||||
EXAMPLES TEMPLATE:
|
||||
$(cat "$examples_path")"
|
||||
echo " 📋 Loaded Examples template: $(wc -l < "$examples_path") lines"
|
||||
fi
|
||||
;;
|
||||
http-api)
|
||||
local api_path="$HOME/.claude/workflows/cli-templates/prompts/documentation/api.txt"
|
||||
if [ -f "$api_path" ]; then
|
||||
template_content=$(cat "$api_path")
|
||||
echo " 📋 Loaded HTTP API template: $(wc -l < "$api_path") lines"
|
||||
fi
|
||||
;;
|
||||
esac
|
||||
else
|
||||
# Module-level templates
|
||||
local api_template_path="$HOME/.claude/workflows/cli-templates/prompts/documentation/api.txt"
|
||||
local readme_template_path="$HOME/.claude/workflows/cli-templates/prompts/documentation/module-readme.txt"
|
||||
local nav_template_path="$HOME/.claude/workflows/cli-templates/prompts/documentation/folder-navigation.txt"
|
||||
|
||||
if [ "$folder_type" = "code" ]; then
|
||||
if [ -f "$api_template_path" ]; then
|
||||
api_template=$(cat "$api_template_path")
|
||||
echo " 📋 Loaded API template: $(wc -l < "$api_template_path") lines"
|
||||
fi
|
||||
if [ -f "$readme_template_path" ]; then
|
||||
readme_template=$(cat "$readme_template_path")
|
||||
echo " 📋 Loaded README template: $(wc -l < "$readme_template_path") lines"
|
||||
fi
|
||||
else
|
||||
# Navigation folder uses navigation template
|
||||
if [ -f "$nav_template_path" ]; then
|
||||
readme_template=$(cat "$nav_template_path")
|
||||
echo " 📋 Loaded Navigation template: $(wc -l < "$nav_template_path") lines"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# Scan directory structure (only for module-level strategies)
|
||||
local structure_info=""
|
||||
if [ "$is_project_level" = false ]; then
|
||||
echo " 🔍 Scanning directory structure..."
|
||||
structure_info=$(scan_directory_structure "$source_path" "$strategy")
|
||||
fi
|
||||
|
||||
# Prepare logging info
|
||||
local module_name=$(basename "$source_path")
|
||||
|
||||
echo "⚡ Generating docs: $source_path → $output_path"
|
||||
echo " Strategy: $strategy | Tool: $tool | Model: $model | Type: $folder_type"
|
||||
echo " Output: $output_path"
|
||||
|
||||
# Build strategy-specific prompt
|
||||
local final_prompt=""
|
||||
|
||||
# Project-level strategies
|
||||
if [ "$strategy" = "project-readme" ]; then
|
||||
final_prompt="PURPOSE: Generate comprehensive project overview documentation
|
||||
|
||||
PROJECT: $project_name
|
||||
OUTPUT: Current directory (file will be moved to final location)
|
||||
|
||||
Read: @.workflow/docs/$project_name/**/*.md
|
||||
|
||||
Context: All module documentation files from the project
|
||||
|
||||
Generate ONE documentation file in current directory:
|
||||
- README.md - Project root documentation
|
||||
|
||||
Template:
|
||||
$template_content
|
||||
|
||||
Instructions:
|
||||
- Create README.md in CURRENT DIRECTORY
|
||||
- Synthesize information from all module docs
|
||||
- Include project overview, getting started, and navigation
|
||||
- Create clear module navigation with links
|
||||
- Follow template structure exactly"
|
||||
|
||||
elif [ "$strategy" = "project-architecture" ]; then
|
||||
final_prompt="PURPOSE: Generate system design and usage examples documentation
|
||||
|
||||
PROJECT: $project_name
|
||||
OUTPUT: Current directory (files will be moved to final location)
|
||||
|
||||
Read: @.workflow/docs/$project_name/**/*.md
|
||||
|
||||
Context: All project documentation including module docs and project README
|
||||
|
||||
Generate TWO documentation files in current directory:
|
||||
1. ARCHITECTURE.md - System architecture and design patterns
|
||||
2. EXAMPLES.md - End-to-end usage examples
|
||||
|
||||
Template:
|
||||
$template_content
|
||||
|
||||
Instructions:
|
||||
- Create both ARCHITECTURE.md and EXAMPLES.md in CURRENT DIRECTORY
|
||||
- Synthesize architectural patterns from module documentation
|
||||
- Document system structure, module relationships, and design decisions
|
||||
- Provide practical code examples and usage scenarios
|
||||
- Follow template structure for both files"
|
||||
|
||||
elif [ "$strategy" = "http-api" ]; then
|
||||
final_prompt="PURPOSE: Generate HTTP API reference documentation
|
||||
|
||||
PROJECT: $project_name
|
||||
OUTPUT: Current directory (file will be moved to final location)
|
||||
|
||||
Read: @**/*.{ts,js,py,go,rs} @.workflow/docs/$project_name/**/*.md
|
||||
|
||||
Context: API route files and existing documentation
|
||||
|
||||
Generate ONE documentation file in current directory:
|
||||
- README.md - HTTP API documentation (in api/ subdirectory)
|
||||
|
||||
Template:
|
||||
$template_content
|
||||
|
||||
Instructions:
|
||||
- Create README.md in CURRENT DIRECTORY
|
||||
- Document all HTTP endpoints (routes, methods, parameters, responses)
|
||||
- Include authentication requirements and error codes
|
||||
- Provide request/response examples
|
||||
- Follow template structure (Part B: HTTP API documentation)"
|
||||
|
||||
# Module-level strategies
|
||||
elif [ "$strategy" = "full" ]; then
|
||||
# Full strategy: read all files, generate for each directory
|
||||
if [ "$folder_type" = "code" ]; then
|
||||
final_prompt="PURPOSE: Generate comprehensive API and module documentation
|
||||
|
||||
Directory Structure Analysis:
|
||||
$structure_info
|
||||
|
||||
SOURCE: $source_path
|
||||
OUTPUT: Current directory (files will be moved to final location)
|
||||
|
||||
Read: @**/*
|
||||
|
||||
Generate TWO documentation files in current directory:
|
||||
1. API.md - Code API documentation (functions, classes, interfaces)
|
||||
Template:
|
||||
$api_template
|
||||
|
||||
2. README.md - Module overview documentation
|
||||
Template:
|
||||
$readme_template
|
||||
|
||||
Instructions:
|
||||
- Generate both API.md and README.md in CURRENT DIRECTORY
|
||||
- If subdirectories contain code files, generate their docs too (recursive)
|
||||
- Work bottom-up: deepest directories first
|
||||
- Follow template structure exactly
|
||||
- Use structure analysis for context"
|
||||
else
|
||||
# Navigation folder - README only
|
||||
final_prompt="PURPOSE: Generate navigation documentation for folder structure
|
||||
|
||||
Directory Structure Analysis:
|
||||
$structure_info
|
||||
|
||||
SOURCE: $source_path
|
||||
OUTPUT: Current directory (file will be moved to final location)
|
||||
|
||||
Read: @**/*
|
||||
|
||||
Generate ONE documentation file in current directory:
|
||||
- README.md - Navigation and folder overview
|
||||
|
||||
Template:
|
||||
$readme_template
|
||||
|
||||
Instructions:
|
||||
- Create README.md in CURRENT DIRECTORY
|
||||
- Focus on folder structure and navigation
|
||||
- Link to subdirectory documentation
|
||||
- Use structure analysis for context"
|
||||
fi
|
||||
else
|
||||
# Single strategy: read current + child docs only
|
||||
if [ "$folder_type" = "code" ]; then
|
||||
final_prompt="PURPOSE: Generate API and module documentation for current directory
|
||||
|
||||
Directory Structure Analysis:
|
||||
$structure_info
|
||||
|
||||
SOURCE: $source_path
|
||||
OUTPUT: Current directory (files will be moved to final location)
|
||||
|
||||
Read: @*/API.md @*/README.md @*.ts @*.tsx @*.js @*.jsx @*.py @*.sh @*.go @*.rs @*.md @*.json @*.yaml @*.yml
|
||||
|
||||
Generate TWO documentation files in current directory:
|
||||
1. API.md - Code API documentation
|
||||
Template:
|
||||
$api_template
|
||||
|
||||
2. README.md - Module overview
|
||||
Template:
|
||||
$readme_template
|
||||
|
||||
Instructions:
|
||||
- Generate both API.md and README.md in CURRENT DIRECTORY
|
||||
- Reference child documentation, do not duplicate
|
||||
- Follow template structure
|
||||
- Use structure analysis for current directory context"
|
||||
else
|
||||
# Navigation folder - README only
|
||||
final_prompt="PURPOSE: Generate navigation documentation
|
||||
|
||||
Directory Structure Analysis:
|
||||
$structure_info
|
||||
|
||||
SOURCE: $source_path
|
||||
OUTPUT: Current directory (file will be moved to final location)
|
||||
|
||||
Read: @*/API.md @*/README.md @*.md
|
||||
|
||||
Generate ONE documentation file in current directory:
|
||||
- README.md - Navigation and overview
|
||||
|
||||
Template:
|
||||
$readme_template
|
||||
|
||||
Instructions:
|
||||
- Create README.md in CURRENT DIRECTORY
|
||||
- Link to child documentation
|
||||
- Use structure analysis for navigation context"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Execute documentation generation
|
||||
local start_time=$(date +%s)
|
||||
echo " 🔄 Starting documentation generation..."
|
||||
|
||||
if cd "$source_path" 2>/dev/null; then
|
||||
local tool_result=0
|
||||
|
||||
# Store current output path for CLI context
|
||||
export DOC_OUTPUT_PATH="$output_path"
|
||||
|
||||
# Record git HEAD before CLI execution (to detect unwanted auto-commits)
|
||||
local git_head_before=""
|
||||
if git rev-parse --git-dir >/dev/null 2>&1; then
|
||||
git_head_before=$(git rev-parse HEAD 2>/dev/null)
|
||||
fi
|
||||
|
||||
# Execute with selected tool
|
||||
case "$tool" in
|
||||
qwen)
|
||||
if [ "$model" = "coder-model" ]; then
|
||||
qwen -p "$final_prompt" --yolo 2>&1
|
||||
else
|
||||
qwen -p "$final_prompt" -m "$model" --yolo 2>&1
|
||||
fi
|
||||
tool_result=$?
|
||||
;;
|
||||
codex)
|
||||
codex --full-auto exec "$final_prompt" -m "$model" --skip-git-repo-check -s danger-full-access 2>&1
|
||||
tool_result=$?
|
||||
;;
|
||||
gemini)
|
||||
gemini -p "$final_prompt" -m "$model" --yolo 2>&1
|
||||
tool_result=$?
|
||||
;;
|
||||
*)
|
||||
echo " ⚠️ Unknown tool: $tool, defaulting to gemini"
|
||||
gemini -p "$final_prompt" -m "$model" --yolo 2>&1
|
||||
tool_result=$?
|
||||
;;
|
||||
esac
|
||||
|
||||
# Move generated files to output directory
|
||||
local docs_created=0
|
||||
local moved_files=""
|
||||
|
||||
if [ $tool_result -eq 0 ]; then
|
||||
if [ "$is_project_level" = true ]; then
|
||||
# Project-level documentation files
|
||||
case "$strategy" in
|
||||
project-readme)
|
||||
if [ -f "README.md" ]; then
|
||||
mv "README.md" "$output_path/README.md" 2>/dev/null && {
|
||||
docs_created=$((docs_created + 1))
|
||||
moved_files+="README.md "
|
||||
}
|
||||
fi
|
||||
;;
|
||||
project-architecture)
|
||||
if [ -f "ARCHITECTURE.md" ]; then
|
||||
mv "ARCHITECTURE.md" "$output_path/ARCHITECTURE.md" 2>/dev/null && {
|
||||
docs_created=$((docs_created + 1))
|
||||
moved_files+="ARCHITECTURE.md "
|
||||
}
|
||||
fi
|
||||
if [ -f "EXAMPLES.md" ]; then
|
||||
mv "EXAMPLES.md" "$output_path/EXAMPLES.md" 2>/dev/null && {
|
||||
docs_created=$((docs_created + 1))
|
||||
moved_files+="EXAMPLES.md "
|
||||
}
|
||||
fi
|
||||
;;
|
||||
http-api)
|
||||
if [ -f "README.md" ]; then
|
||||
mv "README.md" "$output_path/README.md" 2>/dev/null && {
|
||||
docs_created=$((docs_created + 1))
|
||||
moved_files+="api/README.md "
|
||||
}
|
||||
fi
|
||||
;;
|
||||
esac
|
||||
else
|
||||
# Module-level documentation files
|
||||
# Check and move API.md if it exists
|
||||
if [ "$folder_type" = "code" ] && [ -f "API.md" ]; then
|
||||
mv "API.md" "$output_path/API.md" 2>/dev/null && {
|
||||
docs_created=$((docs_created + 1))
|
||||
moved_files+="API.md "
|
||||
}
|
||||
fi
|
||||
|
||||
# Check and move README.md if it exists
|
||||
if [ -f "README.md" ]; then
|
||||
mv "README.md" "$output_path/README.md" 2>/dev/null && {
|
||||
docs_created=$((docs_created + 1))
|
||||
moved_files+="README.md "
|
||||
}
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# Check if CLI tool auto-committed (and revert if needed)
|
||||
if [ -n "$git_head_before" ]; then
|
||||
local git_head_after=$(git rev-parse HEAD 2>/dev/null)
|
||||
if [ "$git_head_before" != "$git_head_after" ]; then
|
||||
echo " ⚠️ Detected unwanted auto-commit by CLI tool, reverting..."
|
||||
git reset --soft "$git_head_before" 2>/dev/null
|
||||
echo " ✅ Auto-commit reverted (files remain staged)"
|
||||
fi
|
||||
fi
|
||||
|
||||
if [ $docs_created -gt 0 ]; then
|
||||
local end_time=$(date +%s)
|
||||
local duration=$((end_time - start_time))
|
||||
echo " ✅ Generated $docs_created doc(s) in ${duration}s: $moved_files"
|
||||
cd - > /dev/null
|
||||
return 0
|
||||
else
|
||||
echo " ❌ Documentation generation failed for $source_path"
|
||||
cd - > /dev/null
|
||||
return 1
|
||||
fi
|
||||
else
|
||||
echo " ❌ Cannot access directory: $source_path"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
# Execute function if script is run directly
|
||||
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
|
||||
# Show help if no arguments or help requested
|
||||
if [ $# -eq 0 ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
|
||||
echo "Usage: generate_module_docs.sh <strategy> <source_path> <project_name> [tool] [model]"
|
||||
echo ""
|
||||
echo "Module-Level Strategies:"
|
||||
echo " full - Generate docs for all subdirectories with code"
|
||||
echo " single - Generate docs only for current directory"
|
||||
echo ""
|
||||
echo "Project-Level Strategies:"
|
||||
echo " project-readme - Generate project root README.md"
|
||||
echo " project-architecture - Generate ARCHITECTURE.md + EXAMPLES.md"
|
||||
echo " http-api - Generate HTTP API documentation (api/README.md)"
|
||||
echo ""
|
||||
echo "Tools: gemini (default), qwen, codex"
|
||||
echo "Models: Use tool defaults if not specified"
|
||||
echo ""
|
||||
echo "Module Examples:"
|
||||
echo " ./generate_module_docs.sh full ./src/auth myproject"
|
||||
echo " ./generate_module_docs.sh single ./components myproject gemini"
|
||||
echo ""
|
||||
echo "Project Examples:"
|
||||
echo " ./generate_module_docs.sh project-readme . myproject"
|
||||
echo " ./generate_module_docs.sh project-architecture . myproject qwen"
|
||||
echo " ./generate_module_docs.sh http-api . myproject"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
generate_module_docs "$@"
|
||||
fi
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user