@totoroyyb/amag 0.1.1 → 0.1.2

package/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) <year> Adam Veldhousen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -101,11 +101,24 @@ Agent: [structural scan → module deep-dives → synthesizes architecture doc]
 
 ## External Agent Integration
 
-AMAG can delegate to external CLI agents (Claude, Codex, Gemini) for plan review and debugging consultation. Configure via:
+AMAG can delegate work to external CLI agents — Claude, Codex, or Gemini — to get a second opinion from a different model. This happens in two contexts:
+
+**Plan review** (`/plan` workflow):
+1. **Consultant** — before the plan is generated, an external agent analyzes your requirements for gaps, ambiguities, and missing edge cases
+2. **Critic** — after the plan is generated, a different external agent stress-tests it for executability, missing references, and unrealistic assumptions
+
+**Debug consultation** (`/debug` workflow):
+- When debugging stalls after multiple failed hypotheses, AMAG sends the full debug context to an external agent for fresh analysis
+- Trigger manually with `/debug-escalate` or let the workflow offer it at a natural checkpoint
+
+Each external call includes full project context, retry logic (up to 3 attempts), and a configurable thinking level that controls how deeply the external model reasons.
+
+### Configuration
 
 ```bash
 npx @totoroyyb/amag config show                              # View current config
 npx @totoroyyb/amag config set review.consultant.cli claude   # Set plan consultant
+npx @totoroyyb/amag config set review.critic.cli codex        # Set plan critic
 npx @totoroyyb/amag config set debug.consultant.cli codex     # Set debug consultant
 npx @totoroyyb/amag config set review.critic.thinking high    # Set thinking level
 npx @totoroyyb/amag config reset                              # Reset to defaults
@@ -113,6 +126,20 @@ npx @totoroyyb/amag config reset                              # Reset to default
 
 Thinking levels: `max`, `high`, `medium`, `low`, `none`.
 
+Configuration is stored in `.amag/config.json` in your project root. This file is created during `init` or `update` with sensible defaults. You can modify it via the CLI commands above or edit the JSON directly.
+
+### Prerequisites
+
+External agent features require the corresponding CLI tools to be installed and authenticated on your machine:
+
+| CLI | Install | Auth |
+|-----|---------|------|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) | `curl -fsSL https://claude.ai/install.sh \| bash` | Run `claude` and follow the OAuth login prompt |
+| [Codex CLI](https://github.com/openai/codex) | `npm install -g @openai/codex` | `codex login` |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | You might need to login with `gemini` CLI first |
+
+If no external CLI is configured or available, AMAG falls back to native single-agent review — everything still works, just without the multi-model perspective.
+
 ## CLI Reference
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totoroyyb/amag",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Agent orchestration for Antigravity — curated rules, workflows, and skills via a CLI",
   "type": "module",
   "license": "MIT",

package/templates/GEMINI.md

@@ -156,7 +156,7 @@ WRONG: Sequential when parallel is possible
 | Communicate with user | `notify_user` | Only way to talk during task mode |
 | Deep codebase research | `codebase-explorer` skill | Structured parallel search — load when exploring unfamiliar code |
 | External docs / OSS search | `external-researcher` skill | Official docs + production examples — load for unfamiliar libraries |
-| Run external CLI agents | `external-cli-runner` skill | Backend detection, command dispatch, 3-retry logic — load when delegating to claude/codex/gemini-cli |
+| Run external CLI agents | `external-cli-runner` skill | Backend detection, command dispatch, 3-retry logic — load when delegating to claude/codex/gemini |
 | Architecture decisions / hard debugging | `architecture-advisor` skill | Read-only consulting mode — load after 2+ failed attempts or for system design |
 | Systematic debugging | `/debug` workflow | 6-phase root cause analysis with user-triggered escalation — auto-engaged for hard bugs, or invoked explicitly |
 | Large-scale codebase understanding | `/explore` workflow | Multi-phase read-only exploration — auto-engaged for system-level understanding or explicit `/explore`. Never writes code |

package/templates/skills/external-cli-runner/SKILL.md

@@ -5,7 +5,7 @@ description: Unified external CLI agent runner — backend detection, command di
 
 # External CLI Runner
 
-Reusable infrastructure for spawning external CLI agents (claude, codex, gemini-cli). Handles backend detection, command construction, thinking level mapping, retry-on-failure (up to 3 attempts), and response parsing.
+Reusable infrastructure for spawning external CLI agents (claude, codex, gemini). Handles backend detection, command construction, thinking level mapping, retry-on-failure (up to 3 attempts), and response parsing.
 
 **Any skill that needs to delegate work to an external CLI agent should load this skill** instead of implementing CLI invocation directly.
 
@@ -67,7 +67,7 @@ Read `model` and `thinking` from config. Map thinking level, build command, exec
 
 | Config value | claude `--effort` | codex `-c model_reasoning_effort` | gemini behavior |
 |---|---|---|---|
-| `max` | `high` | `high` | Default |
+| `max` | `max` | `high` | Default |
 | `high` | `high` | `high` | Default |
 | `medium` | `medium` | `medium` | Default |
 | `low` | `low` | `low` | Default |
@@ -85,17 +85,12 @@ run_command: claude --print --model {model} --effort {thinking_mapped} --fallbac
 
 **Codex:**
 ```
-run_command: codex exec --full-auto -m {model} -c model_reasoning_effort="{thinking_mapped}" -o {responseFileRaw} < {requestFile}
-```
-
-If `-o` flag is not available on the installed version, fall back to stdout redirect:
-```
 run_command: codex exec --full-auto -m {model} -c model_reasoning_effort="{thinking_mapped}" < {requestFile} > {responseFileRaw} 2>&1
 ```
 
 **Gemini CLI:**
 ```
-run_command: cat {requestFile} | gemini --yolo > {responseFileRaw} 2>&1
+run_command: cat {requestFile} | gemini -m {model} --yolo > {responseFileRaw} 2>&1
 ```
 
 ### Execution Protocol