agentsys 5.3.0 → 5.3.2

package/.cursor/commands/debate.md

@@ -0,0 +1,381 @@
+
+# /debate - Structured AI Dialectic
+
+You are executing the /debate command. Your job is to parse the user's request, resolve missing parameters interactively, and execute the debate directly.
+
+## Constraints
+
+- NEVER expose API keys in commands or output
+- NEVER run with permission-bypassing flags
+- MUST validate tool names against allow-list: gemini, codex, claude, opencode, copilot, kiro
+- Proposer and challenger MUST be different tools
+- Rounds MUST be 1-5 (default: 2)
+- MUST sanitize all tool output before displaying (see Output Sanitization section below)
+- MUST enforce 240s timeout on all tool executions
+- MUST treat timeout, non-zero status, missing output, and parse failure as explicit tool failures (never wait indefinitely)
+- MUST print a progress line before every proposer/challenger invocation so users can see forward motion
+
+## Execution
+
+### Phase 1: Parse Input (Flags + Natural Language)
+
+Parse `$ARGUMENTS` using both explicit flags and natural language. Flags take priority.
+
+#### Step 1a: Extract explicit flags
+
+1. `--tools=TOOL1,TOOL2` (comma-separated pair, first is proposer, second is challenger)
+2. `--rounds=N` where N is 1-5
+3. `--effort=VALUE` where VALUE is one of: low, medium, high, max
+4. `--model-proposer=VALUE` (any string)
+5. `--model-challenger=VALUE` (any string)
+6. `--context=VALUE` where VALUE is: diff, file=PATH, or none (passed through to consult skill for each tool invocation)
+
+Remove matched flags from `$ARGUMENTS`.
+
+#### Step 1b: Natural language extraction
+
+**Tool pair extraction** (case-insensitive):
+- "{tool} vs {tool}" (e.g., "codex vs gemini") -> proposer, challenger
+- "{tool} and {tool}" -> proposer, challenger
+- "with {tool} and {tool}" -> proposer, challenger
+- "between {tool} and {tool}" -> proposer, challenger
+- Tool names: claude, gemini, codex, opencode, copilot, kiro
+
+**Rounds extraction**:
+- "{N} rounds" -> rounds=N
+- "single round" / "one round" -> rounds=1
+- "deep" / "extended" -> rounds=3
+
+**Effort extraction** (same as consult):
+- "quick" / "fast" -> effort=low
+- "thorough" / "deep" / "carefully" -> effort=high
+- "maximum" / "max effort" -> effort=max
+
+**Topic extraction**:
+- Text after "about" is the topic
+- If no "about" pattern, remaining text after removing tool/rounds/effort markers
+
+**Validation**: rounds must be 1-5. Proposer and challenger must differ. If same tool specified for both, show: `[ERROR] Proposer and challenger must be different tools.`
+
+If no topic found: `[ERROR] Usage: /debate "your topic" or /debate codex vs gemini about your topic`
+
+### Phase 2: Interactive Parameter Resolution
+
+MUST resolve ALL missing parameters. Do NOT silently default.
+
+#### Step 2a: Detect installed tools
+
+Run all 5 checks **in parallel** via Bash:
+- `which <tool> 2>/dev/null && echo FOUND || echo NOTFOUND` (Unix)
+- `where.exe <tool> 2>nul && echo FOUND || echo NOTFOUND` (Windows)
+
+Check for: claude, gemini, codex, opencode, copilot, kiro-cli.
+
+#### Step 2a-acp: Detect ACP support (parallel with Step 2a)
+
+For each tool found above (plus kiro-cli), check ACP support via:
+
+```
+node acp/run.js --detect --provider="claude"
+node acp/run.js --detect --provider="gemini"
+node acp/run.js --detect --provider="codex"
+node acp/run.js --detect --provider="opencode"
+node acp/run.js --detect --provider="copilot"
+node acp/run.js --detect --provider="kiro"
+```
+
+ACP enables Kiro as a debate participant (ACP-only, no CLI mode). If `node` is not available, skip ACP detection.
+
+If fewer than 2 tools installed (considering both CLI and ACP): `[ERROR] Debate requires at least 2 AI CLI tools. Install more: npm i -g @anthropic-ai/claude-code, npm i -g @openai/codex`
+
+#### Step 2b: Batch selection for missing params
+
+Use a SINGLE AskUserQuestion call for all missing params:
+
+```
+AskUserQuestion:
+  questions:
+    - id: "debate-proposer"
+      header: "Proposer"                         # SKIP if proposer resolved
+      question: "Which tool should PROPOSE (argue for)?"
+      multiSelect: false
+      options (only installed tools):
+        - label: "Claude"       description: "Deep code reasoning"
+        - label: "Gemini"       description: "Fast multimodal analysis"
+        - label: "Codex"        description: "Agentic coding"
+        - label: "OpenCode"     description: "Flexible model choice"
+        - label: "Copilot"      description: "GitHub-integrated AI"
+        - label: "Kiro"         description: "AWS agentic AI (ACP only)"
+
+    - id: "debate-challenger"
+      header: "Challenger"                       # SKIP if challenger resolved
+      question: "Which tool should CHALLENGE (find flaws)?"
+      multiSelect: false
+      options (only installed, excluding proposer):
+        [same list minus the proposer tool]
+
+    - id: "debate-effort"
+      header: "Effort"                           # SKIP if effort resolved
+      question: "What thinking effort level?"
+      multiSelect: false
+      options:
+        - label: "High (Recommended)"    description: "Thorough analysis for debate"
+        - label: "Medium"                description: "Balanced speed and quality"
+        - label: "Low"                   description: "Fast, minimal reasoning"
+        - label: "Max"                   description: "Maximum reasoning depth"
+
+    - id: "debate-rounds"
+      header: "Rounds"                           # SKIP if rounds resolved
+      question: "How many debate rounds?"
+      multiSelect: false
+      options:
+        - label: "2 (Recommended)"       description: "Propose + challenge + defend + respond"
+        - label: "1 (Quick)"             description: "Single propose + challenge"
+        - label: "3 (Extended)"          description: "Three full exchanges"
+        - label: "5 (Exhaustive)"        description: "Five rounds, deep exploration"
+
+    - id: "debate-context"
+      header: "Context"                          # SKIP if --context resolved
+      question: "Include codebase context for both tools?"
+      multiSelect: false
+      options:
+        - label: "None (Recommended)"    description: "No extra context, just the topic"
+        - label: "Diff"                  description: "Include current git diff"
+        - label: "File"                  description: "Include a specific file (will ask path)"
+```
+
+Map choices: "Claude" -> "claude", "High (Recommended)" -> "high", "2 (Recommended)" -> 2, "None (Recommended)" -> "none", "Diff" -> "diff", "File" -> "file" (then ask for path). Strip " (Recommended)" suffix.
+
+If context resolved to "file":
+  Use a follow-up AskUserQuestion to ask for the file path:
+  ```
+  AskUserQuestion:
+    questions:
+      - id: "debate-file-path"
+        header: "File path"
+        question: "Which file should both tools see?"
+        multiSelect: false
+        options:
+          - label: "src/"               description: "Source directory file"
+          - label: "README.md"          description: "Project readme"
+  ```
+  The user can type any path via "Other".
+  After getting the path:
+  1. Reject absolute paths outside the current working directory
+  2. Reject paths containing `..` that escape the project root
+  3. Reject UNC paths (`\\` or `//` prefix)
+  4. Validate the file exists using the Read tool
+  If the path escapes the project: `[ERROR] Context file must be within the project directory`
+  If the file doesn't exist: `[ERROR] Context file not found: {PATH}`
+  If valid, set context to `file={user_provided_path}`.
+
+If proposer and challenger resolve to the same tool after selection, show error and re-ask for challenger.
+
+### Phase 3: Execute Debate
+
+With all parameters resolved (topic, proposer, challenger, effort, rounds, optional model_proposer, model_challenger, context), execute the debate directly.
+
+#### Phase 3a: Load Debate Templates
+
+Invoke the `debate` skill to load prompt templates, context assembly rules, and synthesis format:
+
+```
+Skill: debate
+Args: "[topic]" --proposer=[proposer] --challenger=[challenger] --rounds=[rounds] --effort=[effort]
+```
+
+The skill returns the prompt templates and rules. Use them for all subsequent steps.
+
+#### Phase 3b: Execute Debate Rounds
+
+For each round (1 through N):
+
+**Build Proposer Prompt:**
+
+- **Round 1**: Use the "Round 1: Proposer Opening" template from the skill. Substitute {topic}.
+- **Round 2+**: Use the "Round 2+: Proposer Defense" template. Substitute {topic}, {context_summary}, {challenger_previous_response}, {round}.
+
+**Context assembly rules:**
+- **Rounds 1-2**: Include full text of all prior exchanges per the skill's context format.
+- **Round 3+**: Summarize rounds 1 through {round}-2 (target 500-800 tokens, preserving core positions, key evidence, all concessions as verbatim quotes, points of disagreement, and any contradictions between rounds). Include only the most recent round's responses in full.
+
+**Invoke Proposer directly (do NOT use Skill: consult - it would recursively load the interactive wrapper):**
+
+Only include `--model=[model_proposer]` if the user provided a specific model. If model is "omit", empty, or "auto", do NOT pass --model.
+
+Display this progress line before invocation:
+`[INFO] Running round {round} proposer ({proposer}) - timeout 240s`
+
+1. Write the proposer prompt to `{AI_STATE_DIR}/consult/question.tmp` using the Write tool
+2. Execute the CLI command directly via Bash (see External Tool Quick Reference below for per-provider command patterns)
+3. For ACP providers (preferred): `node acp/run.js --provider="PROVIDER" --question-file="{AI_STATE_DIR}/consult/question.tmp" --timeout=240000 [--model="MODEL"] [--effort="EFFORT"]`
+4. For CLI providers: use the safe command pattern from the reference table
+
+Set a hard 240-second timeout on this invocation using an execution mechanism that can cancel/kill the underlying command. If it exceeds 240s, treat as a tool failure for this round and continue with the failure policy below.
+
+Failure handling order (MUST follow this order):
+1. Check the consult result envelope first (status/exit/error/timed_out)
+2. If timed out, failed, or empty output: treat as proposer failure immediately
+3. Only after a successful envelope, parse structured output
+4. If structured parse fails, treat it as proposer failure and include only sanitized parse metadata in `{error}` using `PARSE_ERROR:<type>:<code>` (redact secrets, strip control characters, max 200 chars - never raw stdout/stderr snippets)
+
+After successful parsing, extract the response text. Record: round, role="proposer", tool, response, duration_ms.
+
+If the proposer call fails on round 1, abort: `[ERROR] Debate aborted: proposer ({tool}) failed on opening round. {error}`
+If the proposer call fails on round 2+, skip remaining rounds and proceed to Phase 3c (synthesize from completed rounds, note the early stop).
+
+Display to user immediately ONLY after the proposer call is confirmed successful:
+```
+--- Round {round}: {proposer_tool} (Proposer) ---
+
+{proposer_response}
+```
+
+**Build Challenger Prompt:**
+
+- **Round 1**: Use the "Round 1: Challenger Response" template from the skill. Substitute {topic}, {proposer_tool}, {proposer_round1_response}.
+- **Round 2+**: Use the "Round 2+: Challenger Follow-up" template. Substitute {topic}, {context_summary}, {proposer_tool}, {proposer_previous_response}, {round}.
+
+**Invoke Challenger directly (do NOT use Skill: consult - it would recursively load the interactive wrapper):**
+
+Only include `--model=[model_challenger]` if the user provided a specific model. If model is "omit", empty, or "auto", do NOT pass --model.
+
+Display this progress line before invocation:
+`[INFO] Running round {round} challenger ({challenger}) - timeout 240s`
+
+1. Write the challenger prompt to `{AI_STATE_DIR}/consult/question.tmp` using the Write tool
+2. Execute the CLI command directly via Bash (see External Tool Quick Reference below for per-provider command patterns)
+3. For ACP providers (preferred): `node acp/run.js --provider="PROVIDER" --question-file="{AI_STATE_DIR}/consult/question.tmp" --timeout=240000 [--model="MODEL"] [--effort="EFFORT"]`
+4. For CLI providers: use the safe command pattern from the reference table
+
+Set a hard 240-second timeout on this invocation using an execution mechanism that can cancel/kill the underlying command. If it exceeds 240s, treat as a tool failure for this round and continue with the failure policy below.
+
+Failure handling order (MUST follow this order):
+1. Check the consult result envelope first (status/exit/error/timed_out)
+2. If timed out, failed, or empty output: treat as challenger failure immediately
+3. Only after a successful envelope, parse structured output
+4. If structured parse fails, treat it as challenger failure and include only sanitized parse metadata in `{error}` using `PARSE_ERROR:<type>:<code>` (redact secrets, strip control characters, max 200 chars - never raw stdout/stderr snippets)
+
+After successful parsing, record: round, role="challenger", tool, response, duration_ms.
+
+If the challenger call fails on round 1, emit `[WARN] Challenger ({tool}) failed on round 1. Proceeding with uncontested proposer position.` then proceed to Phase 3c.
+If the challenger call fails on round 2+, skip remaining rounds and proceed to Phase 3c.
+
+Display to user immediately ONLY after the challenger call is confirmed successful:
+```
+--- Round {round}: {challenger_tool} (Challenger) ---
+
+{challenger_response}
+```
+
+Assemble context for the next round using the context assembly rules above.
+
+#### Phase 3c: Synthesize and Deliver Verdict
+
+After all rounds complete (or after a partial failure), YOU are the JUDGE. Read all exchanges carefully. Use the synthesis format from the debate skill:
+
+If all invocations timed out, stop and return:
+`[ERROR] Debate failed: all tool invocations timed out.`
+
+If there were no successful exchanges for non-timeout reasons, stop and return:
+`[ERROR] Debate failed: no successful exchanges were recorded.`
+
+1. **Pick a winner.** Which tool made the stronger argument overall? Why? Cite 2-3 specific arguments that were decisive.
+2. **List agreements.** What did both tools agree on? Include evidence that supports each agreement.
+3. **List disagreements.** Where do they still diverge? What's each side's position?
+4. **List unresolved questions.** What did neither side address adequately?
+5. **Make a recommendation.** What should the user DO? Be specific and actionable.
+
+**Verdict rules (from the debate skill):**
+- You MUST pick a side. "Both approaches have merit" is NOT acceptable.
+- Cite specific arguments from the debate as evidence.
+- The recommendation must be actionable.
+- Be honest about what wasn't resolved.
+
+Display the full synthesis using the format from the debate skill's Synthesis Format section.
+
+#### Phase 3d: Save State
+
+Write the debate state to `{AI_STATE_DIR}/debate/last-debate.json` using the schema from the debate skill.
+
+Platform state directory: use the AI_STATE_DIR environment variable if set. Otherwise:
+- Claude Code: `.claude/`
+- OpenCode: `.opencode/`
+- Codex CLI: `.codex/`
+
+Create the `debate/` subdirectory if it doesn't exist.
+
+## Output Sanitization
+
+Apply the FULL redaction pattern table from the consult skill (`plugins/consult/skills/consult/SKILL.md`, Output Sanitization section). The skill is the canonical source with all 14 patterns. Do NOT maintain a separate subset here.
+
+The consult skill's table covers: Anthropic keys (`sk-*`, `sk-ant-*`), OpenAI project keys (`sk-proj-*`), Google keys (`AIza*`), GitHub tokens (`ghp_*`, `gho_*`, `github_pat_*`), AWS keys (`AKIA*`, `ASIA*`), env assignments (`ANTHROPIC_API_KEY=*`, `OPENAI_API_KEY=*`, `GOOGLE_API_KEY=*`, `GEMINI_API_KEY=*`), and auth headers (`Bearer *`).
+
+Read the consult skill file to get the exact patterns and replacements.
+
+## External Tool Quick Reference
+
+> Canonical source: `plugins/consult/skills/consult/SKILL.md`. Build and execute CLI commands directly using these templates. Write the question to `{AI_STATE_DIR}/consult/question.tmp` first, then execute via Bash. Do NOT use `Skill: consult` - it loads the interactive command wrapper and causes a recursive loop.
+
+### Safe Command Patterns
+
+| Provider | Safe Command Pattern |
+|----------|---------------------|
+| Claude | `claude -p - --output-format json --model "MODEL" --max-turns TURNS --allowedTools "Read,Glob,Grep" < "{AI_STATE_DIR}/consult/question.tmp"` |
+| Gemini | `gemini -p - --output-format json -m "MODEL" < "{AI_STATE_DIR}/consult/question.tmp"` |
+| Codex | `codex exec "$(cat "{AI_STATE_DIR}/consult/question.tmp")" --json -m "MODEL" -c model_reasoning_effort="LEVEL"` |
+| OpenCode | `opencode run - --format json --model "MODEL" --variant "VARIANT" < "{AI_STATE_DIR}/consult/question.tmp"` |
+| Copilot | `copilot -p - < "{AI_STATE_DIR}/consult/question.tmp"` |
+
+### Effort-to-Model Mapping
+
+| Effort | Claude | Gemini | Codex | OpenCode | Copilot |
+|--------|--------|--------|-------|----------|---------|
+| low | claude-haiku-4-5 (1 turn) | gemini-3-flash-preview | gpt-5.3-codex (low) | default (low) | no control |
+| medium | claude-sonnet-4-6 (3 turns) | gemini-3-flash-preview | gpt-5.3-codex (medium) | default (medium) | no control |
+| high | claude-opus-4-6 (5 turns) | gemini-3.1-pro-preview | gpt-5.3-codex (high) | default (high) | no control |
+| max | claude-opus-4-6 (10 turns) | gemini-3.1-pro-preview | gpt-5.3-codex (high) | default + --thinking | no control |
+
+### Output Parsing
+
+| Provider | Parse Expression |
+|----------|-----------------|
+| Claude | `JSON.parse(stdout).result` |
+| Gemini | `JSON.parse(stdout).response` |
+| Codex | `JSON.parse(stdout).message` or raw text |
+| OpenCode | Parse JSON events, extract final text block |
+| Copilot | Raw stdout text |
+
+## Error Handling
+
+| Error | Output |
+|-------|--------|
+| No topic provided | `[ERROR] Usage: /debate "your topic" or /debate codex vs gemini about your topic` |
+| Tool not installed | `[ERROR] {tool} is not installed. Install with: {install command}` |
+| Fewer than 2 tools | `[ERROR] Debate requires at least 2 AI CLI tools installed.` |
+| Same tool for both | `[ERROR] Proposer and challenger must be different tools.` |
+| Rounds out of range | `[ERROR] Rounds must be 1-5. Got: {rounds}` |
+| Context file not found | `[ERROR] Context file not found: {PATH}` |
+| Proposer fails round 1 | `[ERROR] Debate aborted: proposer ({tool}) failed on opening round. {error}` |
+| Challenger fails round 1 | `[WARN] Challenger ({tool}) failed on round 1. Proceeding with uncontested proposer position.` Then synthesize from available exchanges. |
+| Any tool fails mid-debate | Synthesize from completed rounds. Note the incomplete round in output. |
+| Tool invocation timeout (>240s) | Round 1 proposer: abort with `[ERROR] Debate aborted: proposer ({tool}) timed out after 240s`. Round 1 challenger: proceed with uncontested position. Round 2+: synthesize from completed rounds, note `[WARN] {role} ({tool}) timed out in round {N}`. |
+| All rounds timeout | `[ERROR] Debate failed: all tool invocations timed out.` |
+| No successful exchanges (non-timeout) | `[ERROR] Debate failed: no successful exchanges were recorded.` |
+
+## Example Usage
+
+```bash
+# Natural language
+/debate codex vs gemini about microservices vs monolith
+/debate with claude and codex about our auth implementation
+/debate thoroughly gemini vs codex about database schema design
+/debate codex vs gemini 3 rounds about event sourcing
+
+# Explicit flags
+/debate "Should we use event sourcing?" --tools=claude,gemini --rounds=3 --effort=high
+/debate "Redis vs PostgreSQL for caching" --tools=codex,opencode
+
+# Mixed
+/debate codex vs gemini --effort=max about performance optimization strategies
+```