agentsys 5.3.0 → 5.3.2

package/.cursor/commands/consult.md

@@ -0,0 +1,417 @@
+
+# /consult - Cross-Tool AI Consultation
+
+You are executing the /consult command. Your job is to parse the user's request (natural language or flags), resolve missing parameters interactively, and execute the consultation.
+
+## Constraints
+
+- NEVER expose API keys in commands or output
+- NEVER run with permission-bypassing flags (`--dangerously-skip-permissions`, `bypassPermissions`)
+- MUST use safe-mode defaults (`env -u CLAUDECODE ... --allowedTools "Read,Glob,Grep"` for Claude, `-c model_reasoning_effort` for Codex). For Codex non-interactive exec mode, resolve `SKIP_GIT_FLAG` via trust gate: empty in trusted git repos, `--skip-git-repo-check` only for trusted non-repo execution.
+- MUST enforce 120s timeout on all tool executions
+- MUST validate tool names against allow-list: gemini, codex, claude, opencode, copilot, kiro (reject all others)
+- MUST prefer ACP transport when available (structured protocol, session persistence)
+- MUST fall back to CLI transport when ACP is unavailable
+- MUST validate `--context=file=PATH` is within the project directory (reject absolute paths outside cwd)
+- MUST enforce the Codex trust gate before setting `SKIP_GIT_FLAG` (same project working directory + resolved active tool is Codex, including flag/NLP/picker/`--continue` restore paths)
+- MUST quote all user-provided values in shell commands to prevent injection
+- NEVER execute tools the user has not explicitly requested
+
+## Execution
+
+### Phase 1: Parse Input (Flags + Natural Language)
+
+Parse `$ARGUMENTS` using both explicit flags and natural language extraction. Flags always take priority over NLP when both provide the same parameter.
+
+#### Step 1a: Extract explicit flags
+
+Look for and remove these flags from `$ARGUMENTS`:
+
+1. `--tool=VALUE` or `--tool VALUE` where VALUE is one of: gemini, codex, claude, opencode, copilot, kiro
+2. `--effort=VALUE` or `--effort VALUE` where VALUE is one of: low, medium, high, max
+3. `--model=VALUE` or `--model VALUE` (any string, including quoted)
+4. `--context=VALUE` where VALUE is: diff, file=PATH, or none
+5. `--continue` (optionally `--continue=SESSION_ID`)
+6. `--count=N` where N is 1-5
+
+Remove all matched flags and their values from `$ARGUMENTS`.
+
+#### Step 1b: Natural language extraction (on remaining text)
+
+After removing flags, parse the remaining text for these patterns:
+
+**Tool extraction** (case-insensitive):
+- "with {tool}" (e.g., "with codex") -> tool
+- "ask {tool}" (e.g., "ask gemini") -> tool
+- "consult {tool}" -> tool
+- "{tool} about" (e.g., "codex about") -> tool
+- Tool names: claude, gemini, codex, opencode, copilot, kiro
+
+**Count extraction**:
+- "ask {N} {tool}" (e.g., "ask 3 codex") -> count=N, tool
+- "{N} {tool}" (e.g., "3 codex") -> count=N, tool
+- "{N} instances" -> count=N
+- "few instances" / "multiple" / "several" -> count=ambiguous (ask user in Phase 2)
+
+**Count validation**: After extracting count (from flags or NLP), validate: 1 <= count <= 5. If count < 1 or count > 5, show `[ERROR] Instance count must be 1-5. Got: {count}` and stop.
+
+**Effort extraction**:
+- "quick" / "fast" / "brief" -> effort=low
+- "thorough" / "deep" / "carefully" / "detailed" -> effort=high
+- "maximum" / "max effort" / "exhaustive" -> effort=max
+
+**Question extraction**:
+- Text after "about" is the question (e.g., "with codex about my auth approach" -> question="my auth approach")
+- If no "about" pattern, everything remaining after removing tool/count/effort markers is the question
+
+**Precedence rule**: Flags from Step 1a always override NLP from Step 1b.
+
+If no question text and no `--continue` flag found after both steps:
+```
+[ERROR] Usage: /consult "your question" or /consult with gemini about your question
+```
+
+### Phase 2: Interactive Parameter Resolution
+
+MUST resolve ALL missing parameters interactively. ONLY skip this phase if ALL required params (tool, effort, model) are resolved AND either a question exists or --continue is present. Do NOT silently default any parameter.
+
+#### Step 2a: Handle --continue
+
+**Note:** `--continue` and `--count > 1` are mutually exclusive. Session resume applies to a single tool session. If both are present, show `[ERROR] Cannot use --continue with --count > 1. Use --continue for single session resume.` and stop.
+
+If `--continue` is present:
+1. Read the session file at `{AI_STATE_DIR}/consult/last-session.json`
+
+   Platform state directory:
+   - Claude Code: `.claude/`
+   - OpenCode: `.opencode/`
+   - Codex CLI: `.codex/`
+2. If the file exists, restore the saved tool, session_id, and model from it
+3. If the file does not exist, show `[WARN] No previous session found` and proceed as a fresh consultation
+
+#### Step 2b: Detect installed tools
+
+Run all 5 checks **in parallel** via Bash:
+
+- `where.exe <tool> 2>nul && echo FOUND || echo NOTFOUND` (Windows)
+- `which <tool> 2>/dev/null && echo FOUND || echo NOTFOUND` (Unix)
+
+Check for: claude, gemini, codex, opencode, copilot, kiro-cli.
+
+#### Step 2b-acp: Detect ACP support (parallel with Step 2b)
+
+For each tool found in Step 2b (plus kiro-cli), check ACP support in parallel:
+
+```
+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"
+```
+
+Record which providers have ACP support. This enables:
+- Kiro as a consultation target (ACP-only provider, no CLI mode)
+- Preferred ACP transport for providers that support both CLI and ACP
+
+If the `node` command is not available, skip ACP detection and use CLI transport only.
+
+If zero tools are installed (neither CLI nor ACP): `[ERROR] No AI CLI tools found. Install at least one: npm i -g @anthropic-ai/claude-code, npm i -g @openai/codex, npm i -g opencode-ai`
+
+#### Step 2c: Batch selection for missing params
+
+Use a SINGLE AskUserQuestion call to ask all missing parameters at once. Include ONLY questions for parameters NOT already resolved from Phase 1:
+
+```
+AskUserQuestion:
+  questions:
+    - header: "AI Tool"                          # SKIP if tool resolved
+      question: "Which AI tool should I consult?"
+      multiSelect: false
+      options (only if installed):
+        - 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)"
+
+    - header: "Effort"                           # SKIP if effort resolved
+      question: "What thinking effort level?"
+      multiSelect: false
+      options:
+        - label: "Medium (Recommended)"  description: "Balanced speed and quality"
+        - label: "Low"                   description: "Fast, minimal reasoning"
+        - label: "High"                  description: "Thorough analysis"
+        - label: "Max"                   description: "Maximum reasoning depth"
+
+    - header: "Instances"                        # SKIP if count resolved or not hinted
+      question: "How many parallel consultations?"
+      multiSelect: false
+      options:
+        - label: "1 (Single)"             description: "Standard single consultation"
+        - label: "2 (Compare)"            description: "Two responses to compare"
+        - label: "3 (Panel)"              description: "Three perspectives"
+        - label: "5 (Full spread)"        description: "Five diverse perspectives"
+```
+
+ONLY show the Instances question if:
+- The user explicitly mentioned multiple instances (e.g., "few", "multiple", "several")
+- The count was set but ambiguous
+Do NOT show Instances question for simple single-tool requests. Default count=1 silently when no multi-instance intent detected.
+
+Map tool choice to lowercase: "Claude" -> "claude", "Codex" -> "codex", etc.
+Map effort choice: "Medium (Recommended)" -> "medium", "Low" -> "low", etc.
+Map count choice: "1 (Single)" -> 1, "2 (Compare)" -> 2, "3 (Panel)" -> 3.
+
+#### Step 2d: Model selection (MUST ask if no --model)
+
+After tool is resolved, present a model picker with options specific to the selected tool. The user can always type a custom model name via the "Other" option.
+
+**For Claude:**
+```
+AskUserQuestion:
+  questions:
+    - header: "Model"
+      question: "Which Claude model?"
+      multiSelect: false
+      options:
+        - label: "sonnet (Recommended)"  description: "Sonnet 4.5 - balanced speed and intelligence"
+        - label: "opus"                  description: "Opus 4.6 - most capable, adaptive thinking"
+        - label: "haiku"                 description: "Haiku 4.5 - fastest, lightweight"
+```
+
+**For Gemini:**
+```
+AskUserQuestion:
+  questions:
+    - header: "Model"
+      question: "Which Gemini model?"
+      multiSelect: false
+      options:
+        - label: "gemini-3.1-pro-preview"          description: "Most capable, strong reasoning"
+        - label: "gemini-3-flash-preview"  description: "Fast, efficient coding"
+        - label: "gemini-2.5-pro"        description: "Previous gen pro model"
+        - label: "gemini-2.5-flash"      description: "Previous gen flash model"
+```
+
+**For Codex:**
+```
+AskUserQuestion:
+  questions:
+    - header: "Model"
+      question: "Which Codex model?"
+      multiSelect: false
+      options:
+        - label: "gpt-5.3-codex"        description: "Latest, most capable coding model"
+        - label: "gpt-5.2-codex"        description: "Strong coding model"
+        - label: "gpt-5.2"              description: "General purpose GPT-5.2"
+        - label: "gpt-5.3-codex-spark"   description: "Cost-effective, 4x more usage"
+```
+
+**For OpenCode (model format: `provider/model`, run `opencode models` to list all):**
+```
+AskUserQuestion:
+  questions:
+    - header: "Model"
+      question: "Which model? (format: provider/model, type via Other for any)"
+      multiSelect: false
+      options:
+        - label: "opencode/big-pickle"                     description: "Free - stealth model, 200K context"
+        - label: "github-copilot/gemini-3.1-pro-preview"   description: "Copilot - Google Gemini 3.1 Pro"
+        - label: "opencode/minimax-m2.5-free"              description: "Free - 230B MoE, multilingual coding"
+        - label: "github-copilot/claude-opus-4.6"          description: "Copilot - Claude Opus 4.6"
+```
+
+**For Copilot:**
+```
+AskUserQuestion:
+  questions:
+    - header: "Model"
+      question: "Which Copilot model?"
+      multiSelect: false
+      options:
+        - label: "claude-sonnet-4-5"        description: "Default Copilot model"
+        - label: "claude-opus-4-6"          description: "Most capable Claude model"
+        - label: "gpt-5.3-codex"            description: "OpenAI GPT-5.3 Codex"
+        - label: "gemini-3.1-pro-preview"           description: "Google Gemini 3.1 Pro"
+```
+
+**For Kiro:**
+
+Kiro does not support model selection. Skip the model picker for Kiro. Set model to `"kiro"` and proceed directly to Phase 3.
+
+Map the user's choice to the model string (strip " (Recommended)" suffix if present).
+
+IMPORTANT: Do NOT skip model selection. Do NOT silently use a default model. If --model was not explicitly provided, you MUST present this picker.
+
+### Phase 3: Execute Consultation
+
+With all parameters resolved (tool, effort, model, question, count, and optionally context/continue):
+
+#### Multi-instance (count > 1)
+
+Spawn the `consult-agent` via the Task tool with all resolved parameters:
+
+```
+Task:
+  subagent_type: "consult-agent"
+  prompt: |
+    Execute a multi-instance consultation with these pre-resolved parameters:
+    - tool: [tool]
+    - model: [model]
+    - effort: [effort]
+    - question: [question]
+    - count: [count]
+    - context: [context or none]
+
+    Run [count] parallel consultations with the same tool and parameters.
+    Return all responses formatted with numbered headers and a brief synthesis.
+```
+
+Then skip to Phase 4 (multi-instance).
+
+#### Single instance (count=1, the default)
+
+Execute the consultation directly. Do NOT call `Skill: consult` - that would recursively load this command file.
+
+##### Step 3a: Resolve model from effort (if not explicit)
+
+If `--model` was provided, use it directly. Otherwise map effort to model:
+
+| Effort | Claude | Gemini | Codex | OpenCode | Copilot | Kiro |
+|--------|--------|--------|-------|----------|---------|------|
+| low | claude-haiku-4-5 (1 turn) | gemini-3-flash-preview | gpt-5.3-codex (low) | default (low) | no control | n/a |
+| medium | claude-sonnet-4-6 (3 turns) | gemini-3-flash-preview | gpt-5.3-codex (medium) | default (medium) | no control | n/a |
+| high | claude-opus-4-6 (5 turns) | gemini-3.1-pro-preview | gpt-5.3-codex (high) | default (high) | no control | n/a |
+| max | claude-opus-4-6 (10 turns) | gemini-3.1-pro-preview | gpt-5.3-codex (high) | default + --thinking | no control | n/a |
+
+**Claude model ID resolution**: If the CLI returns "invalid model identifier", retry with Bedrock format: replace `claude-opus-4-6` with `us.anthropic.claude-opus-4-6-v1`, `claude-sonnet-4-6` with `us.anthropic.claude-sonnet-4-6-v1`, `claude-haiku-4-5` with `us.anthropic.claude-haiku-4-5-20251001-v1:0`.
+
+##### Step 3b: Context packaging
+
+If `--context=diff`: run `git diff 2>/dev/null` and prepend output to the question.
+If `--context=file=PATH`: read the file using the Read tool and prepend its content to the question.
+
+##### Step 3c: Write question to temp file
+
+Write the full question text (with any prepended context) to `{AI_STATE_DIR}/consult/question.tmp` using the Write tool. Create the `consult/` directory if needed.
+
+Platform state directory: `.claude/` (Claude Code), `.opencode/` (OpenCode), `.codex/` (Codex).
+
+##### Step 3d: Codex trust gate (Codex only)
+
+If tool is codex, resolve `{SKIP_GIT_FLAG}`:
+1. Run `git rev-parse --is-inside-work-tree`
+2. If true: `SKIP_GIT_FLAG` = empty string
+3. If false: `SKIP_GIT_FLAG` = `--skip-git-repo-check`
+
+##### Step 3e: Build and execute CLI command
+
+**For ACP providers** (preferred when ACP was detected in Step 2b-acp):
+
+```
+node acp/run.js --provider="PROVIDER" --question-file="{AI_STATE_DIR}/consult/question.tmp" --timeout=120000 [--model="MODEL"] [--effort="EFFORT"] [--max-turns=TURNS]
+```
+
+**For CLI providers** (fallback when ACP unavailable):
+
+| Provider | Safe Command Pattern |
+|----------|---------------------|
+| Claude | `env -u CLAUDECODE claude -p - --output-format json --model "MODEL" --max-turns TURNS --allowedTools "Read,Glob,Grep" < "{AI_STATE_DIR}/consult/question.tmp"` |
+| Claude (resume) | `env -u CLAUDECODE claude -p - --output-format json --model "MODEL" --max-turns TURNS --allowedTools "Read,Glob,Grep" --resume "SESSION_ID" < "{AI_STATE_DIR}/consult/question.tmp"` |
+| Gemini | `gemini -p - --output-format json -m "MODEL" < "{AI_STATE_DIR}/consult/question.tmp"` |
+| Gemini (resume) | `gemini -p - --output-format json -m "MODEL" --resume "SESSION_ID" < "{AI_STATE_DIR}/consult/question.tmp"` |
+| Codex | `codex exec "$(cat "{AI_STATE_DIR}/consult/question.tmp")" --json -m "MODEL" {SKIP_GIT_FLAG} -c model_reasoning_effort="LEVEL"` |
+| Codex (resume) | `codex exec resume "SESSION_ID" "$(cat "{AI_STATE_DIR}/consult/question.tmp")" --json -m "MODEL" {SKIP_GIT_FLAG} -c model_reasoning_effort="LEVEL"` |
+| OpenCode | `opencode run - --format json --model "MODEL" --variant "VARIANT" < "{AI_STATE_DIR}/consult/question.tmp"` |
+| OpenCode (resume) | `opencode run - --format json --model "MODEL" --variant "VARIANT" --session "SESSION_ID" < "{AI_STATE_DIR}/consult/question.tmp"` |
+| Copilot | `copilot -p - < "{AI_STATE_DIR}/consult/question.tmp"` |
+| Kiro | ACP only - use ACP command above |
+
+**Timeout enforcement**: Wrap CLI commands with the `timeout` command to enforce the 120s limit:
+
+```
+timeout 120 env -u CLAUDECODE claude -p - --output-format json ... < question.tmp
+timeout 120 gemini -p - --output-format json ... < question.tmp
+```
+
+If `timeout` is not available (some macOS systems), use a background process with kill:
+```
+COMMAND < question.tmp & PID=$!; ( sleep 120 && kill $PID 2>/dev/null ) & TIMER=$!; wait $PID 2>/dev/null; kill $TIMER 2>/dev/null
+```
+
+For ACP, `acp/run.js --timeout=120000` handles timeouts internally via per-request timers.
+
+##### Step 3f: Parse result
+
+| Provider | Parse Expression |
+|----------|-----------------|
+| Claude | `JSON.parse(stdout).result` |
+| Gemini | `JSON.parse(stdout).response` |
+| Codex | `JSON.parse(stdout).message` or raw text |
+| OpenCode | Newline-delimited JSON events. Concatenate `part.text` from events where `type === "text"`. Session ID from `event.sessionID`. |
+| Copilot | Raw stdout text |
+| ACP (any) | `JSON.parse(stdout).response` |
+
+Extract: response text, session_id (if available), duration_ms.
+
+### Phase 4: Present Results
+
+#### Single instance
+
+Display:
+
+```
+Tool: {tool}, Model: {model}, Effort: {effort}, Duration: {duration_ms}ms.
+
+The results of the consultation are:
+{response}
+```
+
+For continuable tools (Claude, Gemini, Codex, OpenCode), display: `Session: {session_id} - use /consult --continue to resume`
+
+Save session state to `{AI_STATE_DIR}/consult/last-session.json`.
+
+#### Multi-instance
+
+Display the agent's formatted output directly. The agent returns numbered responses with a synthesis section.
+
+On failure: `[ERROR] Consultation Failed: {specific error message}`
+
+## Error Handling
+
+| Error | Output |
+|-------|--------|
+| No question provided | `[ERROR] Usage: /consult "your question" or /consult with gemini about your question` |
+| Tool not installed | `[ERROR] {tool} is not installed. Install with: {install command from skill}` |
+| Tool execution fails | `[ERROR] {tool} failed: {error}. Try a different tool with --tool=[other]` |
+| Timeout (>120s) | `[ERROR] {tool} timed out after 120s. Try --effort=low for faster response` |
+| No tools available | `[ERROR] No AI CLI tools found. Install: npm i -g @anthropic-ai/claude-code` |
+| Session not found | `[WARN] No previous session found. Starting fresh consultation.` |
+| API key missing | `[ERROR] {tool} requires API key. Set {env var} (see skill for details)` |
+| Count out of range | `[ERROR] Instance count must be 1-5. Got: {count}` |
+| Multi-instance partial failure | Show successful responses, note failures |
+
+## Example Usage
+
+```bash
+# Natural language (NLP parsing)
+/consult with codex about my auth approach
+/consult ask 3 codex about this design
+/consult gemini should I use redis or postgres
+/consult thoroughly ask claude about error handling
+/consult codex few instances about performance
+
+# Explicit flags (backward compatible)
+/consult "Is this the right approach?" --tool=gemini --effort=high
+/consult "Review this function" --tool=codex --count=3
+/consult "Suggest improvements" --tool=opencode --model=github-copilot/claude-opus-4-6
+/consult --continue
+/consult "Explain this error" --context=diff --tool=gemini
+/consult "Review this file" --context=file=src/index.js --tool=claude
+
+# Mixed (flags + natural language)
+/consult with gemini --effort=max about database schema design
+```