diff --git a/commands/multi-backend.md b/commands/multi-backend.md new file mode 100644 index 0000000..c8bb7e1 --- /dev/null +++ b/commands/multi-backend.md @@ -0,0 +1,158 @@ +# Backend - Backend-Focused Development + +Backend-focused workflow (Research → Ideation → Plan → Execute → Optimize → Review), Codex-led. + +## Usage + +```bash +/backend +``` + +## Context + +- Backend task: $ARGUMENTS +- Codex-led, Gemini for auxiliary reference +- Applicable: API design, algorithm implementation, database optimization, business logic + +## Your Role + +You are the **Backend Orchestrator**, coordinating multi-model collaboration for server-side tasks (Research → Ideation → Plan → Execute → Optimize → Review). + +**Collaborative Models**: +- **Codex** – Backend logic, algorithms (**Backend authority, trustworthy**) +- **Gemini** – Frontend perspective (**Backend opinions for reference only**) +- **Claude (self)** – Orchestration, planning, execution, delivery + +--- + +## Multi-Model Call Specification + +**Call Syntax**: + +``` +# New session call +Bash({ + command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend codex - \"$PWD\" <<'EOF' +ROLE_FILE: + +Requirement: +Context: + +OUTPUT: Expected output format +EOF", + run_in_background: false, + timeout: 3600000, + description: "Brief description" +}) + +# Resume session call +Bash({ + command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend codex resume - \"$PWD\" <<'EOF' +ROLE_FILE: + +Requirement: +Context: + +OUTPUT: Expected output format +EOF", + run_in_background: false, + timeout: 3600000, + description: "Brief description" +}) +``` + +**Role Prompts**: + +| Phase | Codex | +|-------|-------| +| Analysis | `~/.claude/.ccg/prompts/codex/analyzer.md` | +| Planning | `~/.claude/.ccg/prompts/codex/architect.md` | +| Review | `~/.claude/.ccg/prompts/codex/reviewer.md` | + +**Session Reuse**: Each call returns `SESSION_ID: xxx`, use `resume xxx` for subsequent phases. Save `CODEX_SESSION` in Phase 2, use `resume` in Phases 3 and 5. + +--- + +## 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. Use `AskUserQuestion` tool for user interaction when needed (e.g., confirmation/selection/approval) + +--- + +## Core Workflow + +### Phase 0: Prompt Enhancement (Optional) + +`[Mode: Prepare]` - If ace-tool MCP available, call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for subsequent Codex calls** + +### Phase 1: Research + +`[Mode: Research]` - Understand requirements and gather context + +1. **Code Retrieval** (if ace-tool MCP available): Call `mcp__ace-tool__search_context` to retrieve existing APIs, data models, service architecture +2. Requirement completeness score (0-10): >=7 continue, <7 stop and supplement + +### Phase 2: Ideation + +`[Mode: Ideation]` - Codex-led analysis + +**MUST call Codex** (follow call specification above): +- ROLE_FILE: `~/.claude/.ccg/prompts/codex/analyzer.md` +- Requirement: Enhanced requirement (or $ARGUMENTS if not enhanced) +- Context: Project context from Phase 1 +- OUTPUT: Technical feasibility analysis, recommended solutions (at least 2), risk assessment + +**Save SESSION_ID** (`CODEX_SESSION`) for subsequent phase reuse. + +Output solutions (at least 2), wait for user selection. + +### Phase 3: Planning + +`[Mode: Plan]` - Codex-led planning + +**MUST call Codex** (use `resume ` to reuse session): +- ROLE_FILE: `~/.claude/.ccg/prompts/codex/architect.md` +- Requirement: User's selected solution +- Context: Analysis results from Phase 2 +- OUTPUT: File structure, function/class design, dependency relationships + +Claude synthesizes 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 +- Ensure error handling, security, performance optimization + +### Phase 5: Optimization + +`[Mode: Optimize]` - Codex-led review + +**MUST call Codex** (follow call specification above): +- ROLE_FILE: `~/.claude/.ccg/prompts/codex/reviewer.md` +- Requirement: Review the following backend code changes +- Context: git diff or code content +- OUTPUT: Security, performance, error handling, API compliance issues list + +Integrate review feedback, execute optimization after user confirmation. + +### Phase 6: Quality Review + +`[Mode: Review]` - Final evaluation + +- Check completion against plan +- Run tests to verify functionality +- Report issues and recommendations + +--- + +## Key Rules + +1. **Codex backend opinions are trustworthy** +2. **Gemini backend opinions for reference only** +3. External models have **zero filesystem write access** +4. Claude handles all code writes and file operations diff --git a/commands/multi-execute.md b/commands/multi-execute.md new file mode 100644 index 0000000..6e7ac82 --- /dev/null +++ b/commands/multi-execute.md @@ -0,0 +1,310 @@ +# Execute - Multi-Model Collaborative Execution + +Multi-model collaborative execution - Get prototype from plan → Claude refactors and implements → Multi-model audit and delivery. + +$ARGUMENTS + +--- + +## Core Protocols + +- **Language Protocol**: Use **English** when interacting with tools/models, communicate with user in their language +- **Code Sovereignty**: External models have **zero filesystem write access**, all modifications by Claude +- **Dirty Prototype Refactoring**: Treat Codex/Gemini Unified Diff as "dirty prototype", must refactor to production-grade code +- **Stop-Loss Mechanism**: Do not proceed to next phase until current phase output is validated +- **Prerequisite**: Only execute after user explicitly replies "Y" to `/ccg:plan` output (if missing, must confirm first) + +--- + +## Multi-Model Call Specification + +**Call Syntax** (parallel: use `run_in_background: true`): + +``` +# Resume session call (recommended) - Implementation Prototype +Bash({ + command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend {{GEMINI_MODEL_FLAG}}resume - \"$PWD\" <<'EOF' +ROLE_FILE: + +Requirement: +Context: + +OUTPUT: Unified Diff Patch ONLY. Strictly prohibit any actual modifications. +EOF", + run_in_background: true, + timeout: 3600000, + description: "Brief description" +}) + +# New session call - Implementation Prototype +Bash({ + command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF' +ROLE_FILE: + +Requirement: +Context: + +OUTPUT: Unified Diff Patch ONLY. Strictly prohibit any actual modifications. +EOF", + run_in_background: true, + timeout: 3600000, + description: "Brief description" +}) +``` + +**Audit Call Syntax** (Code Review / Audit): + +``` +Bash({ + command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend {{GEMINI_MODEL_FLAG}}resume - \"$PWD\" <<'EOF' +ROLE_FILE: + +Scope: Audit the final code changes. +Inputs: +- The applied patch (git diff / final unified diff) +- The touched files (relevant excerpts if needed) +Constraints: +- Do NOT modify any files. +- Do NOT output tool commands that assume filesystem access. + +OUTPUT: +1) A prioritized list of issues (severity, file, rationale) +2) Concrete fixes; if code changes are needed, include a Unified Diff Patch in a fenced code block. +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 | +|-------|-------|--------| +| Implementation | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/frontend.md` | +| Review | `~/.claude/.ccg/prompts/codex/reviewer.md` | `~/.claude/.ccg/prompts/gemini/reviewer.md` | + +**Session Reuse**: If `/ccg:plan` provided SESSION_ID, use `resume ` to reuse context. + +**Wait for Background Tasks** (max timeout 600000ms = 10 minutes): + +``` +TaskOutput({ 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** + +--- + +## Execution Workflow + +**Execute Task**: $ARGUMENTS + +### Phase 0: Read Plan + +`[Mode: Prepare]` + +1. **Identify Input Type**: + - Plan file path (e.g., `.claude/plan/xxx.md`) + - Direct task description + +2. **Read Plan Content**: + - If plan file path provided, read and parse + - Extract: task type, implementation steps, key files, SESSION_ID + +3. **Pre-Execution Confirmation**: + - If input is "direct task description" or plan missing `SESSION_ID` / key files: confirm with user first + - If cannot confirm user replied "Y" to plan: must confirm again before proceeding + +4. **Task Type Routing**: + + | Task Type | Detection | Route | + |-----------|-----------|-------| + | **Frontend** | Pages, components, UI, styles, layout | Gemini | + | **Backend** | API, interfaces, database, logic, algorithms | Codex | + | **Fullstack** | Contains both frontend and backend | Codex ∥ Gemini parallel | + +--- + +### Phase 1: Quick Context Retrieval + +`[Mode: Retrieval]` + +**Must use MCP tool for quick context retrieval, do NOT manually read files one by one** + +Based on "Key Files" list in plan, call `mcp__ace-tool__search_context`: + +``` +mcp__ace-tool__search_context({ + query: "", + project_root_path: "$PWD" +}) +``` + +**Retrieval Strategy**: +- Extract target paths from plan's "Key Files" table +- Build semantic query covering: entry files, dependency modules, related type definitions +- If results insufficient, add 1-2 recursive retrievals +- **NEVER** use Bash + find/ls to manually explore project structure + +**After Retrieval**: +- Organize retrieved code snippets +- Confirm complete context for implementation +- Proceed to Phase 3 + +--- + +### Phase 3: Prototype Acquisition + +`[Mode: Prototype]` + +**Route Based on Task Type**: + +#### Route A: Frontend/UI/Styles → Gemini + +**Limit**: Context < 32k tokens + +1. Call Gemini (use `~/.claude/.ccg/prompts/gemini/frontend.md`) +2. Input: Plan content + retrieved context + target files +3. OUTPUT: `Unified Diff Patch ONLY. Strictly prohibit any actual modifications.` +4. **Gemini is frontend design authority, its CSS/React/Vue prototype is the final visual baseline** +5. **WARNING**: Ignore Gemini's backend logic suggestions +6. If plan contains `GEMINI_SESSION`: prefer `resume ` + +#### Route B: Backend/Logic/Algorithms → Codex + +1. Call Codex (use `~/.claude/.ccg/prompts/codex/architect.md`) +2. Input: Plan content + retrieved context + target files +3. OUTPUT: `Unified Diff Patch ONLY. Strictly prohibit any actual modifications.` +4. **Codex is backend logic authority, leverage its logical reasoning and debug capabilities** +5. If plan contains `CODEX_SESSION`: prefer `resume ` + +#### Route C: Fullstack → Parallel Calls + +1. **Parallel Calls** (`run_in_background: true`): + - Gemini: Handle frontend part + - Codex: Handle backend part +2. Wait for both models' complete results with `TaskOutput` +3. Each uses corresponding `SESSION_ID` from plan for `resume` (create new session if missing) + +**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above** + +--- + +### Phase 4: Code Implementation + +`[Mode: Implement]` + +**Claude as Code Sovereign executes the following steps**: + +1. **Read Diff**: Parse Unified Diff Patch returned by Codex/Gemini + +2. **Mental Sandbox**: + - Simulate applying Diff to target files + - Check logical consistency + - Identify potential conflicts or side effects + +3. **Refactor and Clean**: + - Refactor "dirty prototype" to **highly readable, maintainable, enterprise-grade code** + - Remove redundant code + - Ensure compliance with project's existing code standards + - **Do not generate comments/docs unless necessary**, code should be self-explanatory + +4. **Minimal Scope**: + - Changes limited to requirement scope only + - **Mandatory review** for side effects + - Make targeted corrections + +5. **Apply Changes**: + - Use Edit/Write tools to execute actual modifications + - **Only modify necessary code**, never affect user's other existing functionality + +6. **Self-Verification** (strongly recommended): + - Run project's existing lint / typecheck / tests (prioritize minimal related scope) + - If failed: fix regressions first, then proceed to Phase 5 + +--- + +### Phase 5: Audit and Delivery + +`[Mode: Audit]` + +#### 5.1 Automatic Audit + +**After changes take effect, MUST immediately parallel call** Codex and Gemini for Code Review: + +1. **Codex Review** (`run_in_background: true`): + - ROLE_FILE: `~/.claude/.ccg/prompts/codex/reviewer.md` + - Input: Changed Diff + target files + - Focus: Security, performance, error handling, logic correctness + +2. **Gemini Review** (`run_in_background: true`): + - ROLE_FILE: `~/.claude/.ccg/prompts/gemini/reviewer.md` + - Input: Changed Diff + target files + - Focus: Accessibility, design consistency, user experience + +Wait for both models' complete review results with `TaskOutput`. Prefer reusing Phase 3 sessions (`resume `) for context consistency. + +#### 5.2 Integrate and Fix + +1. Synthesize Codex + Gemini review feedback +2. Weigh by trust rules: Backend follows Codex, Frontend follows Gemini +3. Execute necessary fixes +4. Repeat Phase 5.1 as needed (until risk is acceptable) + +#### 5.3 Delivery Confirmation + +After audit passes, report to user: + +```markdown +## Execution Complete + +### Change Summary +| File | Operation | Description | +|------|-----------|-------------| +| path/to/file.ts | Modified | Description | + +### Audit Results +- Codex: +- Gemini: + +### Recommendations +1. [ ] +2. [ ] +``` + +--- + +## Key Rules + +1. **Code Sovereignty** – All file modifications by Claude, external models have zero write access +2. **Dirty Prototype Refactoring** – Codex/Gemini output treated as draft, must refactor +3. **Trust Rules** – Backend follows Codex, Frontend follows Gemini +4. **Minimal Changes** – Only modify necessary code, no side effects +5. **Mandatory Audit** – Must perform multi-model Code Review after changes + +--- + +## Usage + +```bash +# Execute plan file +/ccg:execute .claude/plan/feature-name.md + +# Execute task directly (for plans already discussed in context) +/ccg:execute implement user authentication based on previous plan +``` + +--- + +## Relationship with /ccg:plan + +1. `/ccg:plan` generates plan + SESSION_ID +2. User confirms with "Y" +3. `/ccg:execute` reads plan, reuses SESSION_ID, executes implementation diff --git a/commands/multi-frontend.md b/commands/multi-frontend.md new file mode 100644 index 0000000..64b3b26 --- /dev/null +++ b/commands/multi-frontend.md @@ -0,0 +1,158 @@ +# Frontend - Frontend-Focused Development + +Frontend-focused workflow (Research → Ideation → Plan → Execute → Optimize → Review), Gemini-led. + +## Usage + +```bash +/frontend +``` + +## Context + +- Frontend task: $ARGUMENTS +- Gemini-led, Codex for auxiliary reference +- Applicable: Component design, responsive layout, UI animations, style optimization + +## Your Role + +You are the **Frontend Orchestrator**, coordinating multi-model collaboration for UI/UX tasks (Research → Ideation → Plan → Execute → Optimize → Review). + +**Collaborative Models**: +- **Gemini** – Frontend UI/UX (**Frontend authority, trustworthy**) +- **Codex** – Backend perspective (**Frontend opinions for reference only**) +- **Claude (self)** – Orchestration, planning, execution, delivery + +--- + +## Multi-Model Call Specification + +**Call Syntax**: + +``` +# New session call +Bash({ + command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend gemini --gemini-model gemini-3-pro-preview - \"$PWD\" <<'EOF' +ROLE_FILE: + +Requirement: +Context: + +OUTPUT: Expected output format +EOF", + run_in_background: false, + timeout: 3600000, + description: "Brief description" +}) + +# Resume session call +Bash({ + command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend gemini --gemini-model gemini-3-pro-preview resume - \"$PWD\" <<'EOF' +ROLE_FILE: + +Requirement: +Context: + +OUTPUT: Expected output format +EOF", + run_in_background: false, + timeout: 3600000, + description: "Brief description" +}) +``` + +**Role Prompts**: + +| Phase | Gemini | +|-------|--------| +| Analysis | `~/.claude/.ccg/prompts/gemini/analyzer.md` | +| Planning | `~/.claude/.ccg/prompts/gemini/architect.md` | +| Review | `~/.claude/.ccg/prompts/gemini/reviewer.md` | + +**Session Reuse**: Each call returns `SESSION_ID: xxx`, use `resume xxx` for subsequent phases. Save `GEMINI_SESSION` in Phase 2, use `resume` in Phases 3 and 5. + +--- + +## 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. Use `AskUserQuestion` tool for user interaction when needed (e.g., confirmation/selection/approval) + +--- + +## Core Workflow + +### Phase 0: Prompt Enhancement (Optional) + +`[Mode: Prepare]` - If ace-tool MCP available, call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for subsequent Gemini calls** + +### Phase 1: Research + +`[Mode: Research]` - Understand requirements and gather context + +1. **Code Retrieval** (if ace-tool MCP available): Call `mcp__ace-tool__search_context` to retrieve existing components, styles, design system +2. Requirement completeness score (0-10): >=7 continue, <7 stop and supplement + +### Phase 2: Ideation + +`[Mode: Ideation]` - Gemini-led analysis + +**MUST call Gemini** (follow call specification above): +- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/analyzer.md` +- Requirement: Enhanced requirement (or $ARGUMENTS if not enhanced) +- Context: Project context from Phase 1 +- OUTPUT: UI feasibility analysis, recommended solutions (at least 2), UX evaluation + +**Save SESSION_ID** (`GEMINI_SESSION`) for subsequent phase reuse. + +Output solutions (at least 2), wait for user selection. + +### Phase 3: Planning + +`[Mode: Plan]` - Gemini-led planning + +**MUST call Gemini** (use `resume ` to reuse session): +- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/architect.md` +- Requirement: User's selected solution +- Context: Analysis results from Phase 2 +- OUTPUT: Component structure, UI flow, styling approach + +Claude synthesizes 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 design system and code standards +- Ensure responsiveness, accessibility + +### Phase 5: Optimization + +`[Mode: Optimize]` - Gemini-led review + +**MUST call Gemini** (follow call specification above): +- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/reviewer.md` +- Requirement: Review the following frontend code changes +- Context: git diff or code content +- OUTPUT: Accessibility, responsiveness, performance, design consistency issues list + +Integrate review feedback, execute optimization after user confirmation. + +### Phase 6: Quality Review + +`[Mode: Review]` - Final evaluation + +- Check completion against plan +- Verify responsiveness and accessibility +- Report issues and recommendations + +--- + +## Key Rules + +1. **Gemini frontend opinions are trustworthy** +2. **Codex frontend opinions for reference only** +3. External models have **zero filesystem write access** +4. Claude handles all code writes and file operations diff --git a/commands/multi-plan.md b/commands/multi-plan.md new file mode 100644 index 0000000..cbc37e0 --- /dev/null +++ b/commands/multi-plan.md @@ -0,0 +1,261 @@ +# Plan - Multi-Model Collaborative Planning + +Multi-model collaborative planning - Context retrieval + Dual-model analysis → Generate step-by-step implementation plan. + +$ARGUMENTS + +--- + +## Core Protocols + +- **Language Protocol**: Use **English** when interacting with tools/models, communicate with user in their language +- **Mandatory Parallel**: Codex/Gemini calls MUST use `run_in_background: true` (including single model calls, to avoid blocking main thread) +- **Code Sovereignty**: External models have **zero filesystem write access**, all modifications by Claude +- **Stop-Loss Mechanism**: Do not proceed to next phase until current phase output is validated +- **Planning Only**: This command allows reading context and writing to `.claude/plan/*` plan files, but **NEVER modify production code** + +--- + +## Multi-Model Call Specification + +**Call Syntax** (parallel: use `run_in_background: true`): + +``` +Bash({ + command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF' +ROLE_FILE: + +Requirement: +Context: + +OUTPUT: Step-by-step implementation plan with pseudo-code. DO NOT modify any files. +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` | + +**Session Reuse**: Each call returns `SESSION_ID: xxx` (typically output by wrapper), **MUST save** for subsequent `/ccg:execute` use. + +**Wait for Background Tasks** (max timeout 600000ms = 10 minutes): + +``` +TaskOutput({ 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** + +--- + +## Execution Workflow + +**Planning Task**: $ARGUMENTS + +### Phase 1: Full Context Retrieval + +`[Mode: Research]` + +#### 1.1 Prompt Enhancement (MUST execute first) + +**MUST call `mcp__ace-tool__enhance_prompt` tool**: + +``` +mcp__ace-tool__enhance_prompt({ + prompt: "$ARGUMENTS", + conversation_history: "", + project_root_path: "$PWD" +}) +``` + +Wait for enhanced prompt, **replace original $ARGUMENTS with enhanced result** for all subsequent phases. + +#### 1.2 Context Retrieval + +**Call `mcp__ace-tool__search_context` tool**: + +``` +mcp__ace-tool__search_context({ + query: "", + project_root_path: "$PWD" +}) +``` + +- Build semantic query using natural language (Where/What/How) +- **NEVER answer based on assumptions** +- If MCP unavailable: fallback to Glob + Grep for file discovery and key symbol location + +#### 1.3 Completeness Check + +- Must obtain **complete definitions and signatures** for relevant classes, functions, variables +- If context insufficient, trigger **recursive retrieval** +- Prioritize output: entry file + line number + key symbol name; add minimal code snippets only when necessary to resolve ambiguity + +#### 1.4 Requirement Alignment + +- If requirements still have ambiguity, **MUST** output guiding questions for user +- Until requirement boundaries are clear (no omissions, no redundancy) + +### Phase 2: Multi-Model Collaborative Analysis + +`[Mode: Analysis]` + +#### 2.1 Distribute Inputs + +**Parallel call** Codex and Gemini (`run_in_background: true`): + +Distribute **original requirement** (without preset opinions) to both models: + +1. **Codex Backend Analysis**: + - ROLE_FILE: `~/.claude/.ccg/prompts/codex/analyzer.md` + - Focus: Technical feasibility, architecture impact, performance considerations, potential risks + - OUTPUT: Multi-perspective solutions + pros/cons analysis + +2. **Gemini Frontend Analysis**: + - ROLE_FILE: `~/.claude/.ccg/prompts/gemini/analyzer.md` + - Focus: UI/UX impact, user experience, visual design + - OUTPUT: Multi-perspective solutions + pros/cons analysis + +Wait for both models' complete results with `TaskOutput`. **Save SESSION_ID** (`CODEX_SESSION` and `GEMINI_SESSION`). + +#### 2.2 Cross-Validation + +Integrate perspectives and iterate for optimization: + +1. **Identify consensus** (strong signal) +2. **Identify divergence** (needs weighing) +3. **Complementary strengths**: Backend logic follows Codex, Frontend design follows Gemini +4. **Logical reasoning**: Eliminate logical gaps in solutions + +#### 2.3 (Optional but Recommended) Dual-Model Plan Draft + +To reduce risk of omissions in Claude's synthesized plan, can parallel have both models output "plan drafts" (still **NOT allowed** to modify files): + +1. **Codex Plan Draft** (Backend authority): + - ROLE_FILE: `~/.claude/.ccg/prompts/codex/architect.md` + - OUTPUT: Step-by-step plan + pseudo-code (focus: data flow/edge cases/error handling/test strategy) + +2. **Gemini Plan Draft** (Frontend authority): + - ROLE_FILE: `~/.claude/.ccg/prompts/gemini/architect.md` + - OUTPUT: Step-by-step plan + pseudo-code (focus: information architecture/interaction/accessibility/visual consistency) + +Wait for both models' complete results with `TaskOutput`, record key differences in their suggestions. + +#### 2.4 Generate Implementation Plan (Claude Final Version) + +Synthesize both analyses, generate **Step-by-step Implementation Plan**: + +```markdown +## Implementation Plan: + +### Task Type +- [ ] Frontend (→ Gemini) +- [ ] Backend (→ Codex) +- [ ] Fullstack (→ Parallel) + +### Technical Solution + + +### Implementation Steps +1. - Expected deliverable +2. - Expected deliverable +... + +### Key Files +| File | Operation | Description | +|------|-----------|-------------| +| path/to/file.ts:L10-L50 | Modify | Description | + +### Risks and Mitigation +| Risk | Mitigation | +|------|------------| + +### SESSION_ID (for /ccg:execute use) +- CODEX_SESSION: +- GEMINI_SESSION: +``` + +### Phase 2 End: Plan Delivery (Not Execution) + +**`/ccg:plan` responsibilities end here, MUST execute the following actions**: + +1. Present complete implementation plan to user (including pseudo-code) +2. Save plan to `.claude/plan/.md` (extract feature name from requirement, e.g., `user-auth`, `payment-module`) +3. Output prompt in **bold text** (MUST use actual saved file path): + + --- + **Plan generated and saved to `.claude/plan/actual-feature-name.md`** + + **Please review the plan above. You can:** + - **Modify plan**: Tell me what needs adjustment, I'll update the plan + - **Execute plan**: Copy the following command to a new session + + ``` + /ccg:execute .claude/plan/actual-feature-name.md + ``` + --- + + **NOTE**: The `actual-feature-name.md` above MUST be replaced with the actual saved filename! + +4. **Immediately terminate current response** (Stop here. No more tool calls.) + +**ABSOLUTELY FORBIDDEN**: +- Ask user "Y/N" then auto-execute (execution is `/ccg:execute`'s responsibility) +- Any write operations to production code +- Automatically call `/ccg:execute` or any implementation actions +- Continue triggering model calls when user hasn't explicitly requested modifications + +--- + +## Plan Saving + +After planning completes, save plan to: + +- **First planning**: `.claude/plan/.md` +- **Iteration versions**: `.claude/plan/-v2.md`, `.claude/plan/-v3.md`... + +Plan file write should complete before presenting plan to user. + +--- + +## Plan Modification Flow + +If user requests plan modifications: + +1. Adjust plan content based on user feedback +2. Update `.claude/plan/.md` file +3. Re-present modified plan +4. Prompt user to review or execute again + +--- + +## Next Steps + +After user approves, **manually** execute: + +```bash +/ccg:execute .claude/plan/.md +``` + +--- + +## Key Rules + +1. **Plan only, no implementation** – This command does not execute any code changes +2. **No Y/N prompts** – Only present plan, let user decide next steps +3. **Trust Rules** – Backend follows Codex, Frontend follows Gemini +4. External models have **zero filesystem write access** +5. **SESSION_ID Handoff** – Plan must include `CODEX_SESSION` / `GEMINI_SESSION` at end (for `/ccg:execute resume ` use) diff --git a/commands/multi-workflow.md b/commands/multi-workflow.md new file mode 100644 index 0000000..bdcdab9 --- /dev/null +++ b/commands/multi-workflow.md @@ -0,0 +1,183 @@ +# 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 +``` + +## 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) 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** – 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 {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF' +ROLE_FILE: + +Requirement: +Context: + +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 {{GEMINI_MODEL_FLAG}}resume - \"$PWD\" <<'EOF' +ROLE_FILE: + +Requirement: +Context: + +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: "", 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). + +--- + +## Execution Workflow + +**Task Description**: $ARGUMENTS + +### Phase 1: Research & Analysis + +`[Mode: Research]` - Understand requirements and gather context: + +1. **Prompt Enhancement**: Call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for all subsequent Codex/Gemini calls** +2. **Context Retrieval**: Call `mcp__ace-tool__search_context` +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 `): +- 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 diff --git a/commands/pm2.md b/commands/pm2.md new file mode 100644 index 0000000..75d6349 --- /dev/null +++ b/commands/pm2.md @@ -0,0 +1,271 @@ +# PM2 Init + +Auto-analyze project and generate PM2 service commands. + +**Command**: `$ARGUMENTS` + +--- + +## Workflow + +1. Check PM2 (install via `npm install -g pm2` if missing) +2. Scan project to identify services (frontend/backend/database) +3. Generate config files and individual command files + +--- + +## Service Detection + +| Type | Detection | Default Port | +|------|-----------|--------------| +| Vite | vite.config.* | 5173 | +| Next.js | next.config.* | 3000 | +| Nuxt | nuxt.config.* | 3000 | +| CRA | react-scripts in package.json | 3000 | +| Express/Node | server/backend/api directory + package.json | 3000 | +| FastAPI/Flask | requirements.txt / pyproject.toml | 8000 | +| Go | go.mod / main.go | 8080 | + +**Port Detection Priority**: User specified > .env > config file > scripts args > default port + +--- + +## Generated Files + +``` +project/ +├── ecosystem.config.cjs # PM2 config +├── {backend}/start.cjs # Python wrapper (if applicable) +└── .claude/ + ├── commands/ + │ ├── pm2-all.md # Start all + monit + │ ├── pm2-all-stop.md # Stop all + │ ├── pm2-all-restart.md # Restart all + │ ├── pm2-{port}.md # Start single + logs + │ ├── pm2-{port}-stop.md # Stop single + │ ├── pm2-{port}-restart.md # Restart single + │ ├── pm2-logs.md # View all logs + │ └── pm2-status.md # View status + └── scripts/ + ├── pm2-logs-{port}.ps1 # Single service logs + └── pm2-monit.ps1 # PM2 monitor +``` + +--- + +## Windows Configuration (IMPORTANT) + +### ecosystem.config.cjs + +**Must use `.cjs` extension** + +```javascript +module.exports = { + apps: [ + // Node.js (Vite/Next/Nuxt) + { + name: 'project-3000', + cwd: './packages/web', + script: 'node_modules/vite/bin/vite.js', + args: '--port 3000', + interpreter: 'C:/Program Files/nodejs/node.exe', + env: { NODE_ENV: 'development' } + }, + // Python + { + name: 'project-8000', + cwd: './backend', + script: 'start.cjs', + interpreter: 'C:/Program Files/nodejs/node.exe', + env: { PYTHONUNBUFFERED: '1' } + } + ] +} +``` + +**Framework script paths:** + +| Framework | script | args | +|-----------|--------|------| +| Vite | `node_modules/vite/bin/vite.js` | `--port {port}` | +| Next.js | `node_modules/next/dist/bin/next` | `dev -p {port}` | +| Nuxt | `node_modules/nuxt/bin/nuxt.mjs` | `dev --port {port}` | +| Express | `src/index.js` or `server.js` | - | + +### Python Wrapper Script (start.cjs) + +```javascript +const { spawn } = require('child_process'); +const proc = spawn('python', ['-m', 'uvicorn', 'app.main:app', '--host', '0.0.0.0', '--port', '8000', '--reload'], { + cwd: __dirname, stdio: 'inherit', windowsHide: true +}); +proc.on('close', (code) => process.exit(code)); +``` + +--- + +## Command File Templates (Minimal Content) + +### pm2-all.md (Start all + monit) +```markdown +Start all services and open PM2 monitor. +\`\`\`bash +cd "{PROJECT_ROOT}" && pm2 start ecosystem.config.cjs && start wt.exe -d "{PROJECT_ROOT}" pwsh -NoExit -c "pm2 monit" +\`\`\` +``` + +### pm2-all-stop.md +```markdown +Stop all services. +\`\`\`bash +cd "{PROJECT_ROOT}" && pm2 stop all +\`\`\` +``` + +### pm2-all-restart.md +```markdown +Restart all services. +\`\`\`bash +cd "{PROJECT_ROOT}" && pm2 restart all +\`\`\` +``` + +### pm2-{port}.md (Start single + logs) +```markdown +Start {name} ({port}) and open logs. +\`\`\`bash +cd "{PROJECT_ROOT}" && pm2 start ecosystem.config.cjs --only {name} && start wt.exe -d "{PROJECT_ROOT}" pwsh -NoExit -c "pm2 logs {name}" +\`\`\` +``` + +### pm2-{port}-stop.md +```markdown +Stop {name} ({port}). +\`\`\`bash +cd "{PROJECT_ROOT}" && pm2 stop {name} +\`\`\` +``` + +### pm2-{port}-restart.md +```markdown +Restart {name} ({port}). +\`\`\`bash +cd "{PROJECT_ROOT}" && pm2 restart {name} +\`\`\` +``` + +### pm2-logs.md +```markdown +View all PM2 logs. +\`\`\`bash +cd "{PROJECT_ROOT}" && pm2 logs +\`\`\` +``` + +### pm2-status.md +```markdown +View PM2 status. +\`\`\`bash +cd "{PROJECT_ROOT}" && pm2 status +\`\`\` +``` + +### PowerShell Scripts (pm2-logs-{port}.ps1) +```powershell +Set-Location "{PROJECT_ROOT}" +pm2 logs {name} +``` + +### PowerShell Scripts (pm2-monit.ps1) +```powershell +Set-Location "{PROJECT_ROOT}" +pm2 monit +``` + +--- + +## Key Rules + +1. **Config file**: `ecosystem.config.cjs` (not .js) +2. **Node.js**: Specify bin path directly + interpreter +3. **Python**: Node.js wrapper script + `windowsHide: true` +4. **Open new window**: `start wt.exe -d "{path}" pwsh -NoExit -c "command"` +5. **Minimal content**: Each command file has only 1-2 lines description + bash block +6. **Direct execution**: No AI parsing needed, just run the bash command + +--- + +## Execute + +Based on `$ARGUMENTS`, execute init: + +1. Scan project for services +2. Generate `ecosystem.config.cjs` +3. Generate `{backend}/start.cjs` for Python services (if applicable) +4. Generate command files in `.claude/commands/` +5. Generate script files in `.claude/scripts/` +6. **Update project CLAUDE.md** with PM2 info (see below) +7. **Display completion summary** with terminal commands + +--- + +## Post-Init: Update CLAUDE.md + +After generating files, append PM2 section to project's `CLAUDE.md` (create if not exists): + +```markdown +## PM2 Services + +| Port | Name | Type | +|------|------|------| +| {port} | {name} | {type} | + +**Terminal Commands:** +```bash +pm2 start ecosystem.config.cjs # First time +pm2 start all # After first time +pm2 stop all / pm2 restart all +pm2 start {name} / pm2 stop {name} +pm2 logs / pm2 status / pm2 monit +pm2 save # Save process list +pm2 resurrect # Restore saved list +``` +``` + +**Rules for CLAUDE.md update:** +- If PM2 section exists, replace it +- If not exists, append to end +- Keep content minimal and essential + +--- + +## Post-Init: Display Summary + +After all files generated, output: + +``` +## PM2 Init Complete + +**Services:** +| Port | Name | Type | +|------|------|------| +| {port} | {name} | {type} | + +**Claude Commands:** /pm2-all, /pm2-all-stop, /pm2-{port}, /pm2-{port}-stop, /pm2-logs, /pm2-status + +**Terminal Commands:** +# First time (with config file) +pm2 start ecosystem.config.cjs && pm2 save + +# After first time (simplified) +pm2 start all # Start all +pm2 stop all # Stop all +pm2 restart all # Restart all +pm2 start {name} # Start single +pm2 stop {name} # Stop single +pm2 logs # View logs +pm2 monit # Monitor panel +pm2 resurrect # Restore saved processes + +**Tip:** Run `pm2 save` after first start to enable simplified commands. +```