@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/workflows/multi-workflow.md

@@ -1,191 +1,191 @@
-# Workflow - Multi-Model Collaborative Development
-
-Multi-model collaborative development workflow (Research → Ideation → Plan → Execute → Optimize → Review), with intelligent routing: Frontend → Gemini, Backend → Codex.
-
-Structured development workflow with quality gates, MCP services, and multi-model collaboration.
-
-## Usage
-
-```bash
-/workflow <task description>
-```
-
-## Context
-
-- Task to develop: $ARGUMENTS
-- Structured 6-phase workflow with quality gates
-- Multi-model collaboration: Codex (backend) + Gemini (frontend) + Claude (orchestration)
-- MCP service integration (ace-tool, optional) for enhanced capabilities
-
-## Your Role
-
-You are the **Orchestrator**, coordinating a multi-model collaborative system (Research → Ideation → Plan → Execute → Optimize → Review). Communicate concisely and professionally for experienced developers.
-
-**Collaborative Models**:
-- **ace-tool MCP** (optional) – Code retrieval + Prompt enhancement
-- **Codex** – Backend logic, algorithms, debugging (**Backend authority, trustworthy**)
-- **Gemini** – Frontend UI/UX, visual design (**Frontend expert, backend opinions for reference only**)
-- **Claude (self)** – Orchestration, planning, execution, delivery
-
----
-
-## Multi-Model Call Specification
-
-**Call syntax** (parallel: `run_in_background: true`, sequential: `false`):
-
-```
-# New session call
-Bash({
-  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
-ROLE_FILE: <role prompt path>
-<TASK>
-Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
-Context: <project context and analysis from previous phases>
-</TASK>
-OUTPUT: Expected output format
-EOF",
-  run_in_background: true,
-  timeout: 3600000,
-  description: "Brief description"
-})
-
-# Resume session call
-Bash({
-  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}resume <SESSION_ID> - \"$PWD\" <<'EOF'
-ROLE_FILE: <role prompt path>
-<TASK>
-Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
-Context: <project context and analysis from previous phases>
-</TASK>
-OUTPUT: Expected output format
-EOF",
-  run_in_background: true,
-  timeout: 3600000,
-  description: "Brief description"
-})
-```
-
-**Model Parameter Notes**:
-- `{{GEMINI_MODEL_FLAG}}`: When using `--backend gemini`, replace with `--gemini-model gemini-3-pro-preview` (note trailing space); use empty string for codex
-
-**Role Prompts**:
-
-| Phase | Codex | Gemini |
-|-------|-------|--------|
-| Analysis | `~/.claude/.ccg/prompts/codex/analyzer.md` | `~/.claude/.ccg/prompts/gemini/analyzer.md` |
-| Planning | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/architect.md` |
-| Review | `~/.claude/.ccg/prompts/codex/reviewer.md` | `~/.claude/.ccg/prompts/gemini/reviewer.md` |
-
-**Session Reuse**: Each call returns `SESSION_ID: xxx`, use `resume xxx` subcommand for subsequent phases (note: `resume`, not `--resume`).
-
-**Parallel Calls**: Use `run_in_background: true` to start, wait for results with `TaskOutput`. **Must wait for all models to return before proceeding to next phase**.
-
-**Wait for Background Tasks** (use max timeout 600000ms = 10 minutes):
-
-```
-TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
-```
-
-**IMPORTANT**:
-- Must specify `timeout: 600000`, otherwise default 30 seconds will cause premature timeout.
-- If still incomplete after 10 minutes, continue polling with `TaskOutput`, **NEVER kill the process**.
-- If waiting is skipped due to timeout, **MUST call `AskUserQuestion` to ask user whether to continue waiting or kill task. Never kill directly.**
-
----
-
-## Communication Guidelines
-
-1. Start responses with mode label `[Mode: X]`, initial is `[Mode: Research]`.
-2. Follow strict sequence: `Research → Ideation → Plan → Execute → Optimize → Review`.
-3. Request user confirmation after each phase completion.
-4. Force stop when score < 7 or user does not approve.
-5. Use `AskUserQuestion` tool for user interaction when needed (e.g., confirmation/selection/approval).
-
-## When to Use External Orchestration
-
-Use external tmux/worktree orchestration when the work must be split across parallel workers that need isolated git state, independent terminals, or separate build/test execution. Use in-process subagents for lightweight analysis, planning, or review where the main session remains the only writer.
-
-```bash
-node scripts/orchestrate-worktrees.js .claude/plan/workflow-e2e-test.json --execute
-```
-
----
-
-## Execution Workflow
-
-**Task Description**: $ARGUMENTS
-
-### Phase 1: Research & Analysis
-
-`[Mode: Research]` - Understand requirements and gather context:
-
-1. **Prompt Enhancement** (if ace-tool MCP available): Call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for all subsequent Codex/Gemini calls**. If unavailable, use `$ARGUMENTS` as-is.
-2. **Context Retrieval** (if ace-tool MCP available): Call `mcp__ace-tool__search_context`. If unavailable, use built-in tools: `Glob` for file discovery, `Grep` for symbol search, `Read` for context gathering, `Task` (Explore agent) for deeper exploration.
-3. **Requirement Completeness Score** (0-10):
-   - Goal clarity (0-3), Expected outcome (0-3), Scope boundaries (0-2), Constraints (0-2)
-   - ≥7: Continue | <7: Stop, ask clarifying questions
-
-### Phase 2: Solution Ideation
-
-`[Mode: Ideation]` - Multi-model parallel analysis:
-
-**Parallel Calls** (`run_in_background: true`):
-- Codex: Use analyzer prompt, output technical feasibility, solutions, risks
-- Gemini: Use analyzer prompt, output UI feasibility, solutions, UX evaluation
-
-Wait for results with `TaskOutput`. **Save SESSION_ID** (`CODEX_SESSION` and `GEMINI_SESSION`).
-
-**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**
-
-Synthesize both analyses, output solution comparison (at least 2 options), wait for user selection.
-
-### Phase 3: Detailed Planning
-
-`[Mode: Plan]` - Multi-model collaborative planning:
-
-**Parallel Calls** (resume session with `resume <SESSION_ID>`):
-- Codex: Use architect prompt + `resume $CODEX_SESSION`, output backend architecture
-- Gemini: Use architect prompt + `resume $GEMINI_SESSION`, output frontend architecture
-
-Wait for results with `TaskOutput`.
-
-**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**
-
-**Claude Synthesis**: Adopt Codex backend plan + Gemini frontend plan, save to `.claude/plan/task-name.md` after user approval.
-
-### Phase 4: Implementation
-
-`[Mode: Execute]` - Code development:
-
-- Strictly follow approved plan
-- Follow existing project code standards
-- Request feedback at key milestones
-
-### Phase 5: Code Optimization
-
-`[Mode: Optimize]` - Multi-model parallel review:
-
-**Parallel Calls**:
-- Codex: Use reviewer prompt, focus on security, performance, error handling
-- Gemini: Use reviewer prompt, focus on accessibility, design consistency
-
-Wait for results with `TaskOutput`. Integrate review feedback, execute optimization after user confirmation.
-
-**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**
-
-### Phase 6: Quality Review
-
-`[Mode: Review]` - Final evaluation:
-
-- Check completion against plan
-- Run tests to verify functionality
-- Report issues and recommendations
-- Request final user confirmation
-
----
-
-## Key Rules
-
-1. Phase sequence cannot be skipped (unless user explicitly instructs)
-2. External models have **zero filesystem write access**, all modifications by Claude
-3. **Force stop** when score < 7 or user does not approve
+# Workflow - Multi-Model Collaborative Development
+
+Multi-model collaborative development workflow (Research → Ideation → Plan → Execute → Optimize → Review), with intelligent routing: Frontend → Gemini, Backend → Codex.
+
+Structured development workflow with quality gates, MCP services, and multi-model collaboration.
+
+## Usage
+
+```bash
+/workflow <task description>
+```
+
+## Context
+
+- Task to develop: $ARGUMENTS
+- Structured 6-phase workflow with quality gates
+- Multi-model collaboration: Codex (backend) + Gemini (frontend) + Claude (orchestration)
+- MCP service integration (ace-tool, optional) for enhanced capabilities
+
+## Your Role
+
+You are the **Orchestrator**, coordinating a multi-model collaborative system (Research → Ideation → Plan → Execute → Optimize → Review). Communicate concisely and professionally for experienced developers.
+
+**Collaborative Models**:
+- **ace-tool MCP** (optional) – Code retrieval + Prompt enhancement
+- **Codex** – Backend logic, algorithms, debugging (**Backend authority, trustworthy**)
+- **Gemini** – Frontend UI/UX, visual design (**Frontend expert, backend opinions for reference only**)
+- **Claude (self)** – Orchestration, planning, execution, delivery
+
+---
+
+## Multi-Model Call Specification
+
+**Call syntax** (parallel: `run_in_background: true`, sequential: `false`):
+
+```
+# New session call
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
+ROLE_FILE: <role prompt path>
+<TASK>
+Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
+Context: <project context and analysis from previous phases>
+</TASK>
+OUTPUT: Expected output format
+EOF",
+  run_in_background: true,
+  timeout: 3600000,
+  description: "Brief description"
+})
+
+# Resume session call
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}resume <SESSION_ID> - \"$PWD\" <<'EOF'
+ROLE_FILE: <role prompt path>
+<TASK>
+Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
+Context: <project context and analysis from previous phases>
+</TASK>
+OUTPUT: Expected output format
+EOF",
+  run_in_background: true,
+  timeout: 3600000,
+  description: "Brief description"
+})
+```
+
+**Model Parameter Notes**:
+- `{{GEMINI_MODEL_FLAG}}`: When using `--backend gemini`, replace with `--gemini-model gemini-3-pro-preview` (note trailing space); use empty string for codex
+
+**Role Prompts**:
+
+| Phase | Codex | Gemini |
+|-------|-------|--------|
+| Analysis | `~/.claude/.ccg/prompts/codex/analyzer.md` | `~/.claude/.ccg/prompts/gemini/analyzer.md` |
+| Planning | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/architect.md` |
+| Review | `~/.claude/.ccg/prompts/codex/reviewer.md` | `~/.claude/.ccg/prompts/gemini/reviewer.md` |
+
+**Session Reuse**: Each call returns `SESSION_ID: xxx`, use `resume xxx` subcommand for subsequent phases (note: `resume`, not `--resume`).
+
+**Parallel Calls**: Use `run_in_background: true` to start, wait for results with `TaskOutput`. **Must wait for all models to return before proceeding to next phase**.
+
+**Wait for Background Tasks** (use max timeout 600000ms = 10 minutes):
+
+```
+TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
+```
+
+**IMPORTANT**:
+- Must specify `timeout: 600000`, otherwise default 30 seconds will cause premature timeout.
+- If still incomplete after 10 minutes, continue polling with `TaskOutput`, **NEVER kill the process**.
+- If waiting is skipped due to timeout, **MUST call `AskUserQuestion` to ask user whether to continue waiting or kill task. Never kill directly.**
+
+---
+
+## Communication Guidelines
+
+1. Start responses with mode label `[Mode: X]`, initial is `[Mode: Research]`.
+2. Follow strict sequence: `Research → Ideation → Plan → Execute → Optimize → Review`.
+3. Request user confirmation after each phase completion.
+4. Force stop when score < 7 or user does not approve.
+5. Use `AskUserQuestion` tool for user interaction when needed (e.g., confirmation/selection/approval).
+
+## When to Use External Orchestration
+
+Use external tmux/worktree orchestration when the work must be split across parallel workers that need isolated git state, independent terminals, or separate build/test execution. Use in-process subagents for lightweight analysis, planning, or review where the main session remains the only writer.
+
+```bash
+node scripts/orchestrate-worktrees.js .claude/plan/workflow-e2e-test.json --execute
+```
+
+---
+
+## Execution Workflow
+
+**Task Description**: $ARGUMENTS
+
+### Phase 1: Research & Analysis
+
+`[Mode: Research]` - Understand requirements and gather context:
+
+1. **Prompt Enhancement** (if ace-tool MCP available): Call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for all subsequent Codex/Gemini calls**. If unavailable, use `$ARGUMENTS` as-is.
+2. **Context Retrieval** (if ace-tool MCP available): Call `mcp__ace-tool__search_context`. If unavailable, use built-in tools: `Glob` for file discovery, `Grep` for symbol search, `Read` for context gathering, `Task` (Explore agent) for deeper exploration.
+3. **Requirement Completeness Score** (0-10):
+   - Goal clarity (0-3), Expected outcome (0-3), Scope boundaries (0-2), Constraints (0-2)
+   - ≥7: Continue | <7: Stop, ask clarifying questions
+
+### Phase 2: Solution Ideation
+
+`[Mode: Ideation]` - Multi-model parallel analysis:
+
+**Parallel Calls** (`run_in_background: true`):
+- Codex: Use analyzer prompt, output technical feasibility, solutions, risks
+- Gemini: Use analyzer prompt, output UI feasibility, solutions, UX evaluation
+
+Wait for results with `TaskOutput`. **Save SESSION_ID** (`CODEX_SESSION` and `GEMINI_SESSION`).
+
+**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**
+
+Synthesize both analyses, output solution comparison (at least 2 options), wait for user selection.
+
+### Phase 3: Detailed Planning
+
+`[Mode: Plan]` - Multi-model collaborative planning:
+
+**Parallel Calls** (resume session with `resume <SESSION_ID>`):
+- Codex: Use architect prompt + `resume $CODEX_SESSION`, output backend architecture
+- Gemini: Use architect prompt + `resume $GEMINI_SESSION`, output frontend architecture
+
+Wait for results with `TaskOutput`.
+
+**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**
+
+**Claude Synthesis**: Adopt Codex backend plan + Gemini frontend plan, save to `.claude/plan/task-name.md` after user approval.
+
+### Phase 4: Implementation
+
+`[Mode: Execute]` - Code development:
+
+- Strictly follow approved plan
+- Follow existing project code standards
+- Request feedback at key milestones
+
+### Phase 5: Code Optimization
+
+`[Mode: Optimize]` - Multi-model parallel review:
+
+**Parallel Calls**:
+- Codex: Use reviewer prompt, focus on security, performance, error handling
+- Gemini: Use reviewer prompt, focus on accessibility, design consistency
+
+Wait for results with `TaskOutput`. Integrate review feedback, execute optimization after user confirmation.
+
+**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**
+
+### Phase 6: Quality Review
+
+`[Mode: Review]` - Final evaluation:
+
+- Check completion against plan
+- Run tests to verify functionality
+- Report issues and recommendations
+- Request final user confirmation
+
+---
+
+## Key Rules
+
+1. Phase sequence cannot be skipped (unless user explicitly instructs)
+2. External models have **zero filesystem write access**, all modifications by Claude
+3. **Force stop** when score < 7 or user does not approve