compact-agent 1.10.1 → 1.11.1

package/resources/ecc/commands/multi-plan.md

@@ -0,0 +1,272 @@
+---
+description: Create a multi-model implementation plan without modifying production code.
+---
+
+# 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 <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
+ROLE_FILE: <role prompt path>
+<TASK>
+Requirement: <enhanced requirement>
+Context: <retrieved project context>
+</TASK>
+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: "<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)
+
+**If ace-tool MCP is available**, call `mcp__ace-tool__enhance_prompt` tool:
+
+```
+mcp__ace-tool__enhance_prompt({
+  prompt: "$ARGUMENTS",
+  conversation_history: "<last 5-10 conversation turns>",
+  project_root_path: "$PWD"
+})
+```
+
+Wait for enhanced prompt, **replace original $ARGUMENTS with enhanced result** for all subsequent phases.
+
+**If ace-tool MCP is NOT available**: Skip this step and use the original `$ARGUMENTS` as-is for all subsequent phases.
+
+#### 1.2 Context Retrieval
+
+**If ace-tool MCP is available**, call `mcp__ace-tool__search_context` tool:
+
+```
+mcp__ace-tool__search_context({
+  query: "<semantic query based on enhanced requirement>",
+  project_root_path: "$PWD"
+})
+```
+
+- Build semantic query using natural language (Where/What/How)
+- **NEVER answer based on assumptions**
+
+**If ace-tool MCP is NOT available**, use Claude Code built-in tools as fallback:
+1. **Glob**: Find relevant files by pattern (e.g., `Glob("**/*.ts")`, `Glob("src/**/*.py")`)
+2. **Grep**: Search for key symbols, function names, class definitions (e.g., `Grep("className|functionName")`)
+3. **Read**: Read the discovered files to gather complete context
+4. **Task (Explore agent)**: For deeper exploration, use `Task` with `subagent_type: "Explore"` to search across the codebase
+
+#### 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 Name>
+
+### Task Type
+- [ ] Frontend (→ Gemini)
+- [ ] Backend (→ Codex)
+- [ ] Fullstack (→ Parallel)
+
+### Technical Solution
+<Optimal solution synthesized from Codex + Gemini analysis>
+
+### Implementation Steps
+1. <Step 1> - Expected deliverable
+2. <Step 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: <session_id>
+- GEMINI_SESSION: <session_id>
+```
+
+### 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/<feature-name>.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/<feature-name>.md`
+- **Iteration versions**: `.claude/plan/<feature-name>-v2.md`, `.claude/plan/<feature-name>-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/<feature-name>.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/<feature-name>.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 <SESSION_ID>` use)

package/resources/ecc/commands/multi-workflow.md

@@ -0,0 +1,195 @@
+---
+description: Run a full multi-model development workflow with research, planning, execution, optimization, and review.
+---
+
+# 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

package/resources/ecc/commands/plan-prd.md

@@ -0,0 +1,160 @@
+---
+description: "Generate a lean, problem-first PRD and hand off to /plan for implementation planning."
+argument-hint: "[product/feature idea] (blank = start with questions)"
+---
+
+# PRD Command
+
+Produces a **Product Requirements Document** — the requirements-phase artifact of the SDLC. Captures *what* must be true for success and *why*, and stops before *how*. Implementation decomposition is delegated to `/plan`.
+
+**Input**: `$ARGUMENTS`
+
+## Scope of this command
+
+| This command does | This command does NOT do |
+|---|---|
+| Frame the problem and users | Design the architecture |
+| Capture success criteria and scope | Pick files or write patterns |
+| List open questions and risks | Enumerate implementation tasks |
+| Write `.claude/prds/{name}.prd.md` | Produce an implementation plan — that's `/plan` |
+
+If you find yourself writing implementation detail, stop and cut it. It belongs in `/plan`.
+
+**Anti-fluff rule**: When information is missing, write `TBD — needs validation via {method}`. Never invent plausible-sounding requirements.
+
+## Workflow
+
+Four phases. Each phase is a single gate — ask the questions, wait for the user, then move on. No nested loops, no parallel research ceremony.
+
+### Phase 1 — FRAME
+
+If `$ARGUMENTS` is empty, ask:
+
+> What do you want to build? One or two sentences.
+
+If provided, restate in one sentence and ask:
+
+> I understand: *{restated}*. Correct, or should I adjust?
+
+Then ask the framing questions in a single set:
+
+> 1. **Who** has this problem? (specific role or segment)
+> 2. **What** is the observable pain? (describe behavior, not assumed needs)
+> 3. **Why** can't they solve it with what exists today?
+> 4. **Why now?** — what changed that makes this worth doing?
+
+Wait for the user. Do not proceed without answers (or explicit "skip").
+
+### Phase 2 — GROUND
+
+Ask for evidence. This is the shortest phase and the most load-bearing:
+
+> What evidence do you have that this problem is real and worth solving? (user quotes, support tickets, metrics, observed behavior, failed workarounds — anything concrete)
+
+If the user has none, record the PRD's Evidence section as `Assumption — needs validation via {user research | analytics | prototype}`. This keeps the PRD honest.
+
+### Phase 3 — DECIDE
+
+Scope and hypothesis in a single set:
+
+> 1. **Hypothesis** — Complete: *We believe **{capability}** will **{solve problem}** for **{users}**. We'll know we're right when **{measurable outcome}**.*
+> 2. **MVP** — The minimum needed to test the hypothesis?
+> 3. **Out of scope** — What are you explicitly **not** building (even if users ask)?
+> 4. **Open questions** — Uncertainties that could change the approach?
+
+Wait for responses.
+
+### Phase 4 — GENERATE & HAND OFF
+
+Create the directory if needed, write the PRD, and report.
+
+```bash
+mkdir -p .claude/prds
+```
+
+**Output path**: `.claude/prds/{kebab-case-name}.prd.md`
+
+#### PRD Template
+
+```markdown
+# {Product / Feature Name}
+
+## Problem
+{2–3 sentences: who has what problem, and what's the cost of leaving it unsolved?}
+
+## Evidence
+- {User quote, data point, or observation}
+- {OR: "Assumption — needs validation via {method}"}
+
+## Users
+- **Primary**: {role, context, what triggers the need}
+- **Not for**: {who this explicitly excludes}
+
+## Hypothesis
+We believe **{capability}** will **{solve problem}** for **{users}**.
+We'll know we're right when **{measurable outcome}**.
+
+## Success Metrics
+| Metric | Target | How measured |
+|---|---|---|
+| {primary} | {number} | {method} |
+
+## Scope
+**MVP** — {the minimum to test the hypothesis}
+
+**Out of scope**
+- {item} — {why deferred}
+
+## Delivery Milestones
+<!-- Business outcomes, not engineering tasks. /plan turns each into a plan. -->
+<!-- Status: pending | in-progress | complete -->
+
+| # | Milestone | Outcome | Status | Plan |
+|---|---|---|---|---|
+| 1 | {name} | {user-visible change} | pending | — |
+| 2 | {name} | {user-visible change} | pending | — |
+
+## Open Questions
+- [ ] {question that could change scope or approach}
+
+## Risks
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+
+---
+*Status: DRAFT — requirements only. Implementation planning pending via /plan.*
+```
+
+#### Report to user
+
+```
+PRD created: .claude/prds/{name}.prd.md
+
+Problem:    {one line}
+Hypothesis: {one line}
+MVP:        {one line}
+
+Validation status:
+  Problem  {validated | assumption}
+  Users    {concrete | generic — refine}
+  Metrics  {defined | TBD}
+
+Open questions: {count}
+
+Next step: /plan .claude/prds/{name}.prd.md
+  → /plan will pick the next pending milestone and produce an implementation plan.
+```
+
+## Integration
+
+- `/plan <prd-path>` — consume the PRD and produce an implementation plan for the next pending milestone.
+- `tdd-workflow` skill — implement the plan test-first.
+- `/pr` — open a PR that references the PRD and plan.
+
+## Success criteria
+
+- **PROBLEM_CLEAR**: problem is specific and evidenced (or flagged as assumption).
+- **USER_CONCRETE**: primary user is a specific role, not "users".
+- **HYPOTHESIS_TESTABLE**: measurable outcome included.
+- **SCOPE_BOUNDED**: explicit MVP and explicit out-of-scope.
+- **NO_IMPLEMENTATION_DETAIL**: file paths, libraries, or task breakdowns are absent — if they appeared, move them to the `/plan` step.