external-tools

Name: external-tools
Author: dsifry

361stars51forks

How to install external-tools?

dsifry/metaswarm/external-tools

$npx -y skills add dsifry/metaswarm --skill external-tools

Installs into the current project.

Summary

Delegate implementation and review tasks to external AI CLI tools (Codex, Gemini) with cross-model adversarial review

Files · 1

View on GitHub

SKILL.md

1	# External Tools Skill
2
3	## Purpose
4
5	This skill delegates implementation and review tasks to external AI CLI tools (OpenAI Codex CLI, Google Gemini CLI), enabling cost savings through cheaper models and cross-model adversarial review that eliminates single-model blind spots. Three core principles govern every interaction: one job per invocation (an external tool implements OR reviews, never self-validates), minimal permissions (sandboxed execution scoped to the task's working directory with only the tool's own API key), and the orchestrator verifies independently (external tools report facts only, the orchestrator judges pass/fail).
6
7	---
8
9	## Prerequisites
10
11	### Required Tools
12
13	\| Tool \| Install \| Auth \|
14	\|------\|---------\|------\|
15	\| OpenAI Codex CLI \| `npm i -g @openai/codex` \| API key or ChatGPT subscription \|
16	\| Google Gemini CLI \| `npm i -g @google/gemini-cli` \| Google login (free 1K req/day) or API key \|
17
18	Neither tool is strictly required. The skill adapts based on what is available (see Escalation Model below).
19
20	### Configuration
21
22	Per-project config at `.metaswarm/external-tools.yaml` (optional -- if absent, external tools are not used):
23
24	```yaml
25	adapters:
26	codex:
27	enabled: true
28	model: "gpt-5.3-codex"
29	timeout_seconds: 300
30	sandbox: docker # docker \| platform \| none
31	gemini:
32	enabled: true
33	model: "pro"
34	timeout_seconds: 300
35	sandbox: docker
36
37	routing:
38	default_implementer: "cheapest-available"
39	escalation_order: ["codex", "gemini", "claude"]
40
41	budget:
42	per_task_usd: 2.00 # circuit breaker per task
43	per_session_usd: 20.00 # circuit breaker per session
44	```
45
46	### Fallback Behavior
47
48	- Both tools available: Full cross-model delegation and review
49	- One tool available: Reduced chain with mutual review between the tool and Claude
50	- No tools available: Existing metaswarm behavior unchanged; skill is a no-op
51
52	---
53
54	## Quick Reference
55
56	### Health Check
57
58	```bash
59	# Check if Codex is installed, authenticated, and reachable
60	adapters/codex.sh health
61
62	# Check Gemini
63	adapters/gemini.sh health
64	```
65
66	Returns JSON with `status: "ready\|degraded\|unavailable"`.
67
68	### Implement
69
70	```bash
71	adapters/codex.sh implement \
72	--worktree "/tmp/ext-codex-task-42" \
73	--prompt-file "/private/tmp/xt-abc123/prompt.md" \
74	--attempt 1 \
75	--timeout 300
76	```
77
78	### Review
79
80	```bash
81	adapters/gemini.sh review \
82	--worktree "/tmp/ext-codex-task-42" \
83	--rubric-file "./rubrics/external-tool-review-rubric.md" \
84	--spec-file "/private/tmp/xt-abc123/spec.md" \
85	--timeout 300
86	```
87
88	All commands return a uniform JSON envelope with facts only (exit code, files changed, cost, duration). The orchestrator interprets results -- adapters never self-judge.
89
90	---
91
92	## Workflow: Routing & Dispatch
93
94	### Phase 0: Tool Discovery (Health Checks)
95
96	Before dispatching any task, the orchestrator runs health checks to determine which tools are available:
97
98	```bash
99	# Run health checks for all configured adapters
100	for adapter in adapters/*.sh; do
101	result=$("$adapter" health)
102	# Parse status: ready \| degraded \| unavailable
103	done
104	```
105
106	Health is checked per task dispatch, not just at session start. Auth tokens can expire mid-session, network conditions change, and rate limits reset. A tool that was `ready` five minutes ago may now be `unavailable`.
107
108	Build the available tools list:
109
110	```python
111	available_tools = [t for t in adapters if t.health() == "ready"]
112	```
113
114	### Phase 1: IMPLEMENT (External Tool or Claude)
115
116	If an external tool is selected as implementer:
117
118	1. Create worktree -- `git worktree add "$WORKTREE_PATH" -b "external/$TOOL/$TASK_ID"` for isolation
119	2. Package context -- Gather relevant files, spec, acceptance criteria into a prompt file in a secure temp dir (mode 700, trap cleanup). Token-budget the context to fit the model's window.
120	3. Invoke -- `safe_invoke()` with timeout wrapper; capture JSON output
121	4. Scope check -- Verify all file changes are within the declared file scope; revert any out-of-scope changes
122	5. Capture output -- Facts only: exit code, files changed, diff stats, cost, duration
123
124	If Claude is selected (escalation or no external tools), use the existing `Task()` mechanism unchanged.
125
126	### Phase 2: VALIDATE (Always Orchestrator -- Unchanged)
127
128	The orchestrator independently runs all quality gates:
129
130	- `npm test` / `npx vitest run`
131	- `npx tsc --noEmit`
132	- `npx eslint <changed-files>`
133	- Coverage enforcement via `.coverage-thresholds.json`
134	- File scope verification via `git diff --name-only`
135
136	This phase is identical whether the implementer was an external tool or Claude. Never trust the implementer's self-report.
137
138	### Phase 3: ADVERSARIAL REVIEW (Cross-Model)
139
140	The key advantage of exter

People who liked this also viewed

6 picks

Type

paperclip-create-agentCreate new agents in Paperclip with governance-aware hiring. Use when you need to inspect adapter configuration options, compare existing agent configs, draft a new agent prompt/config, and submit a hSkillsJul 2026157k5
subagent-driven-developmentUse when executing implementation plans with independent tasks in the current sessionSkillsJul 2026154k259k
dispatching-parallel-agentsUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesSkillsJul 2026143k259k
browser-act-skill-forgeForges reusable Skill packages (SKILL.md + scripts) from website exploration via browser-act — no re-exploration later. Use when: user wants a reusable Skill for any website, needs to understand a sitSkillsJul 202685k4.6k
wizardGenerate an interactive bash wizard that walks a human through a manual procedure — third-party setup, a one-off migration, an A→B state transition — opening URLs, capturing values, confirming each stSkillsJul 202675k182k
wonda-cliUsing the Wonda CLI to generate images, videos, music, and audio from the terminal — plus LinkedIn, Reddit, and X/Twitter research and automationSkillsJul 202666k137

external-tools

361stars51forks

View on GitHub

How to install external-tools?

dsifry/metaswarm/external-tools

$npx -y skills add dsifry/metaswarm --skill external-tools

Installs into the current project.

Summary

Delegate implementation and review tasks to external AI CLI tools (Codex, Gemini) with cross-model adversarial review

Files · 1

View on GitHub

SKILL.md

1	# External Tools Skill
2
3	## Purpose
4
5	This skill delegates implementation and review tasks to external AI CLI tools (OpenAI Codex CLI, Google Gemini CLI), enabling cost savings through cheaper models and cross-model adversarial review that eliminates single-model blind spots. Three core principles govern every interaction: one job per invocation (an external tool implements OR reviews, never self-validates), minimal permissions (sandboxed execution scoped to the task's working directory with only the tool's own API key), and the orchestrator verifies independently (external tools report facts only, the orchestrator judges pass/fail).
6
7	---
8
9	## Prerequisites
10
11	### Required Tools
12
13	\| Tool \| Install \| Auth \|
14	\|------\|---------\|------\|
15	\| OpenAI Codex CLI \| `npm i -g @openai/codex` \| API key or ChatGPT subscription \|
16	\| Google Gemini CLI \| `npm i -g @google/gemini-cli` \| Google login (free 1K req/day) or API key \|
17
18	Neither tool is strictly required. The skill adapts based on what is available (see Escalation Model below).
19
20	### Configuration
21
22	Per-project config at `.metaswarm/external-tools.yaml` (optional -- if absent, external tools are not used):
23
24	```yaml
25	adapters:
26	codex:
27	enabled: true
28	model: "gpt-5.3-codex"
29	timeout_seconds: 300
30	sandbox: docker # docker \| platform \| none
31	gemini:
32	enabled: true
33	model: "pro"
34	timeout_seconds: 300
35	sandbox: docker
36
37	routing:
38	default_implementer: "cheapest-available"
39	escalation_order: ["codex", "gemini", "claude"]
40
41	budget:
42	per_task_usd: 2.00 # circuit breaker per task
43	per_session_usd: 20.00 # circuit breaker per session
44	```
45
46	### Fallback Behavior
47
48	- Both tools available: Full cross-model delegation and review
49	- One tool available: Reduced chain with mutual review between the tool and Claude
50	- No tools available: Existing metaswarm behavior unchanged; skill is a no-op
51
52	---
53
54	## Quick Reference
55
56	### Health Check
57
58	```bash
59	# Check if Codex is installed, authenticated, and reachable
60	adapters/codex.sh health
61
62	# Check Gemini
63	adapters/gemini.sh health
64	```
65
66	Returns JSON with `status: "ready\|degraded\|unavailable"`.
67
68	### Implement
69
70	```bash
71	adapters/codex.sh implement \
72	--worktree "/tmp/ext-codex-task-42" \
73	--prompt-file "/private/tmp/xt-abc123/prompt.md" \
74	--attempt 1 \
75	--timeout 300
76	```
77
78	### Review
79
80	```bash
81	adapters/gemini.sh review \
82	--worktree "/tmp/ext-codex-task-42" \
83	--rubric-file "./rubrics/external-tool-review-rubric.md" \
84	--spec-file "/private/tmp/xt-abc123/spec.md" \
85	--timeout 300
86	```
87
88	All commands return a uniform JSON envelope with facts only (exit code, files changed, cost, duration). The orchestrator interprets results -- adapters never self-judge.
89
90	---
91
92	## Workflow: Routing & Dispatch
93
94	### Phase 0: Tool Discovery (Health Checks)
95
96	Before dispatching any task, the orchestrator runs health checks to determine which tools are available:
97
98	```bash
99	# Run health checks for all configured adapters
100	for adapter in adapters/*.sh; do
101	result=$("$adapter" health)
102	# Parse status: ready \| degraded \| unavailable
103	done
104	```
105
106	Health is checked per task dispatch, not just at session start. Auth tokens can expire mid-session, network conditions change, and rate limits reset. A tool that was `ready` five minutes ago may now be `unavailable`.
107
108	Build the available tools list:
109
110	```python
111	available_tools = [t for t in adapters if t.health() == "ready"]
112	```
113
114	### Phase 1: IMPLEMENT (External Tool or Claude)
115
116	If an external tool is selected as implementer:
117
118	1. Create worktree -- `git worktree add "$WORKTREE_PATH" -b "external/$TOOL/$TASK_ID"` for isolation
119	2. Package context -- Gather relevant files, spec, acceptance criteria into a prompt file in a secure temp dir (mode 700, trap cleanup). Token-budget the context to fit the model's window.
120	3. Invoke -- `safe_invoke()` with timeout wrapper; capture JSON output
121	4. Scope check -- Verify all file changes are within the declared file scope; revert any out-of-scope changes
122	5. Capture output -- Facts only: exit code, files changed, diff stats, cost, duration
123
124	If Claude is selected (escalation or no external tools), use the existing `Task()` mechanism unchanged.
125
126	### Phase 2: VALIDATE (Always Orchestrator -- Unchanged)
127
128	The orchestrator independently runs all quality gates:
129
130	- `npm test` / `npx vitest run`
131	- `npx tsc --noEmit`
132	- `npx eslint <changed-files>`
133	- Coverage enforcement via `.coverage-thresholds.json`
134	- File scope verification via `git diff --name-only`
135
136	This phase is identical whether the implementer was an external tool or Claude. Never trust the implementer's self-report.
137
138	### Phase 3: ADVERSARIAL REVIEW (Cross-Model)
139
140	The key advantage of exter

People who liked this also viewed

6 picks

Type