Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "killall-agents",
"description": "Killallgit agent catalog and per-project agents",
"version": "2.6.0",
"version": "2.7.0",
"author": {
"name": "archae0pteryx"
},
Expand Down
2 changes: 1 addition & 1 deletion .codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "killall-agents",
"version": "2.6.0",
"version": "2.7.0",
"description": "Killallgit agent catalog and per-project agents",
"author": {
"name": "archae0pteryx",
Expand Down
2 changes: 1 addition & 1 deletion .cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "killall-agents",
"displayName": "Killall Agents",
"version": "2.6.0",
"version": "2.7.0",
"description": "Killallgit agent catalog and per-project agents",
"author": {
"name": "archae0pteryx"
Expand Down
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,3 +22,5 @@ jobs:
run: python3 scripts/build_agents.py --check
- name: Project install
run: python3 skills/agent-setup/scripts/test_install.py
- name: Catalog and interactive install
run: python3 skills/agent-setup/scripts/test_catalog.py
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,14 @@

Public agent catalog and per-project agents for Claude Code, Codex, and Cursor. Keep credentials, machine-specific settings and runtime state out of this repository.

The project agents' source is `factory/claude/`; `scripts/build_agents.py` writes the Codex and Cursor copies beside it (the janitor agents are Claude-only and have none), and the per-host Codex models live in that script. `skills/agent-setup/scripts/install.py` copies `factory/` into one project. The orchestrator is the `orchestrate` skill, not an agent. Keep the `<!-- killall-agents -->` / `# killall-agents` ownership markers stable.
The project agents' source is `factory/claude/`; `scripts/build_agents.py` writes the Codex and Cursor copies beside it (the janitor agents are Claude-only and have none), and the per-host Codex models live in that script. `skills/agent-setup/scripts/install.py` copies `factory/` into one project, and installs the engineering catalog in `factory/catalog/` (one source file per agent, rendered per host by `catalog.py`) into a project or the user-wide folders. The orchestrator is the `orchestrate` skill, not an agent. Keep the `<!-- killall-agents -->` / `# killall-agents` ownership markers stable.

Run from the repository root:

```sh
python3 scripts/build_agents.py --check
python3 skills/agent-setup/scripts/test_install.py
python3 skills/agent-setup/scripts/test_catalog.py
python3 skills/wrap-up/scripts/test_wrap_up.py
git diff --check
```
Expand Down
62 changes: 45 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# killall-agents

Agent catalog and per-project agents for Claude Code, Codex, and Cursor. Ordinary workflow skills live in [killall-skills](https://github.com/killallgit/killall-skills).
Agent catalog + per-project agents for Claude Code, Codex, Cursor. Ordinary workflow skills live in [killall-skills](https://github.com/killallgit/killall-skills).

## Install

Expand All @@ -26,42 +26,70 @@ Skills CLI (setup and rules only):
npx skills add killallgit/killall-agents
```

Includes `agent-setup`, `orchestrate`, `wrap-up` and `follow-the-rules`.
Includes `agent-setup`, `orchestrate`, `wrap-up`, `follow-the-rules`.

## Project agents
## Install agents

Run `/killall-agents:agent-setup` in Claude Code, or `$agent-setup` in Codex, inside a project. It copies these agents from [`factory/`](factory/) into the project's `.claude/agents/`, `.codex/agents/` and `.cursor/agents/`, keeps them out of Git through `.git/info/exclude`, and lists them in `.worktreeinclude` so Claude Code worktrees get them too. Nothing is installed globally. `remove` takes it all out again.
Run installer in terminal, answer questions:

```sh
python3 skills/agent-setup/scripts/install.py
```

Asks where agents go (user-wide or current project), which tools (Claude Code, Codex, Cursor), which agents from multi-select, then model for each catalog tier. Confirms before writing anything. Type `q` to quit. Rerun starts from what is already installed; prompts make folders match selection: remove copies it wrote that you deselected, keep every other file.

In session, `/killall-agents:agent-setup` in Claude Code or `$agent-setup` in Codex runs same script with flags: `--scope user|project`, `--hosts claude,codex`, `--agents lanes,catalog,<names>`, `--model codex:opus=<id>`, `--remove`, and `--force` to replace same-named agent it did not write. Flags add to what is installed; `--prune` also removes copies you did not select. No `--scope`: flags install into current project, prompts suggest user-wide.

Project install copies agents into project's `.claude/agents/`, `.codex/agents/` and `.cursor/agents/`, keeps them out of Git through `.git/info/exclude`, lists them in `.worktreeinclude` so Claude Code worktrees get them too. User-wide install writes to `~/.claude/agents`, `~/.codex/agents` and `~/.cursor/agents` (or `CLAUDE_CONFIG_DIR` and `CODEX_HOME`). Lane agents below install per project only.

## Lane agents

| Agent | Job | Claude model / effort | Codex model / effort |
| --- | --- | --- | --- |
| `planner` | Turns a spec into lanes, contracts and acceptance checks; read-only | Opus / high | `gpt-6-astra` / high |
| `grunt` | Relays a task that fits 64K tokens to the local [Pi](https://github.com/earendil-works/pi) agent | Haiku / low | `gpt-6-luna` / low |
| `builder` | Implements one lane in its own worktree | Sonnet / medium | `gpt-6.1-sol` / medium |
| `reviewer` | Checks a lane's behavior and runs the gate independently | Sonnet / high | `gpt-6.1-sol` / high |
| `hall-monitor` | Quick check of a lane's changes against `follow-the-rules`; read-only | Sonnet / low | `gpt-6.1-sol` / low |
| `planner` | Turns spec into lanes, contracts, acceptance checks; read-only | Opus / high | `gpt-6-astra` / high |
| `grunt` | Relays task fitting 64K tokens to local [Pi](https://github.com/earendil-works/pi) agent | Haiku / low | `gpt-6-luna` / low |
| `builder` | Implements one lane in own worktree | Sonnet / medium | `gpt-6.1-sol` / medium |
| `reviewer` | Checks lane behavior, runs gate independently | Sonnet / high | `gpt-6.1-sol` / high |
| `hall-monitor` | Quick check of lane changes against `follow-the-rules`; read-only | Sonnet / low | `gpt-6.1-sol` / low |

Claude Code also gets three utility agents. They have no Codex or Cursor copy.
Claude Code also gets three utility agents. No Codex or Cursor copy.

| Agent | Purpose |
| --- | --- |
| `git-janitor` | Haiku background runner for the [`wrap-up`](skills/wrap-up/SKILL.md) skill: runs its script and returns the table, or the one roadblock that needs you |
| `git-janitor-investigator` | Collects read-only branch/worktree evidence for the janitor |
| `git-janitor` | Haiku background runner for [`wrap-up`](skills/wrap-up/SKILL.md) skill: runs its script, returns table, or the one roadblock needing you |
| `git-janitor-investigator` | Collects read-only branch/worktree evidence for janitor |
| `comment-janitor` | Reviews changed comments for useful intent |

Installing the plugin adds no agents. Run the `wrap-up` skill after a PR lands: it confirms the work merged and nothing is stranded, updates the main checkout, grooms beads, prunes merged worktrees and branches, and asks only about what is left.
Installing plugin adds no agents. Run `wrap-up` skill after PR lands: confirms work merged and nothing stranded, updates main checkout, grooms beads, prunes merged worktrees and branches, asks only about what is left.

## Engineering catalog

Twenty-four specialist agents in [`factory/catalog/`](factory/catalog/), one source file each. Installer fills in each tool's format: Claude Code gets `model`, `effort`, `tools`, `maxTurns`; Codex gets `model`, `model_reasoning_effort` and, for agents that only read, `sandbox_mode = "read-only"`; Cursor gets `readonly`.
| Agents | Access | Claude model / effort | Codex model / effort |
| --- | --- | --- | --- |
| `autonomous-optimization-architect`, `backend-architect`, `incident-response-commander`, `multi-agent-systems-architect`, `software-architect` | Reads only | Opus / high | `gpt-6-astra` / high |
| `privacy-engineer` | Edits files | Opus / high | `gpt-6-astra` / high |
| `code-reviewer`, `network-engineer`, `sre` | Reads only | Sonnet / high | `gpt-6.1-sol` / high |
| `knowledge-graph-engineer`, `rust-refactoring-specialist`, `search-relevance-engineer` | Edits files | Sonnet / high | `gpt-6.1-sol` / high |
| `desktop-app-engineer`, `developer-tooling-engineer`, `devops-automator`, `frontend-developer`, `it-service-manager`, `minimal-change-engineer`, `mobile-app-builder`, `platform-engineer`, `senior-developer`, `technical-writer` | Edits files | Sonnet / medium | `gpt-6.1-sol` / medium |
| `codebase-onboarding-engineer` | Reads only | Sonnet / low | `gpt-6.1-sol` / low |
| `git-workflow-master` | Edits files | Sonnet / low | `gpt-6.1-sol` / low |

"Reads only" agents get no `Edit` or `Write` in Claude Code, read-only sandbox in Codex; `incident-response-commander` and `network-engineer` also get no `Bash`. Other reads-only agents keep `Bash` in Claude Code, so only Codex and Cursor enforce read-only for them. Catalog adapted from [agency-agents](https://github.com/msitarzewski/agency-agents) (MIT, copy in [`factory/catalog/LICENSE`](factory/catalog/LICENSE)) with persona, memory, metrics sections and most sample code removed, cutting set from about 315 KB to under 200 KB. Edit source file, next install picks it up.

Cursor agents inherit the session model. Ask the top-level session to use the [`orchestrate`](skills/orchestrate/SKILL.md) skill to run a spec. The skill is the project-manager loop: plan with the planner, run lanes with grunt and builders, check with reviewer and hall-monitor. Agents read the gate, branch and worktree rules from the project's own `AGENTS.md`.
Cursor agents inherit session model. Ask top-level session to use [`orchestrate`](skills/orchestrate/SKILL.md) skill to run a spec. Skill is project-manager loop: plan with planner, run lanes with grunt and builders, check with reviewer and hall-monitor. Agents read gate, branch, worktree rules from project's own `AGENTS.md`.

Grunt needs `pi` on `PATH` with a ready provider. Builders and hall-monitor need the included `follow-the-rules` skill.
Grunt needs `pi` on `PATH` with ready provider. Builders and hall-monitor need included `follow-the-rules` skill.

## Development

`factory/claude/` is the source. After editing it, regenerate the Codex and Cursor copies:
`factory/claude/` is source. After editing, regenerate Codex and Cursor copies:

```sh
python3 scripts/build_agents.py # write factory/codex and factory/cursor
python3 scripts/build_agents.py --check # CI: copies are current and valid
python3 skills/agent-setup/scripts/test_install.py
python3 skills/agent-setup/scripts/test_catalog.py
```

See [pending work](tasks/todo.md) and [factory research](docs/research/agent-factory-patterns.md) for design background.
See [pending work](tasks/todo.md) and [factory research](docs/research/agent-factory-patterns.md) for design background.
21 changes: 21 additions & 0 deletions factory/catalog/LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2025 AgentLand Contributors

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.
106 changes: 106 additions & 0 deletions factory/catalog/autonomous-optimization-architect.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
---
name: Autonomous Optimization Architect
description: Intelligent system governor that continuously shadow-tests APIs for performance while enforcing strict financial and security guardrails against runaway costs. Use to design or review cost and security guardrails for automated API experiments. Reads the code but does not change it.
tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
model: opus
effort: high
maxTurns: 30
color: "#673AB7"
---

# Autonomous Optimization Architect

## Your Core Mission
- **Continuous A/B Optimization**: Run experimental AI models on real user data in the background. Grade them automatically against the current production model.
- **Autonomous Traffic Routing**: Safely auto-promote winning models to production (e.g., if Gemini Flash proves to be 98% as accurate as Claude Opus for a specific extraction task but costs 10x less, you route future traffic to Gemini).
- **Financial & Security Guardrails**: Enforce strict boundaries *before* deploying any auto-routing. You implement circuit breakers that instantly cut off failing or overpriced endpoints (e.g., stopping a malicious bot from draining $1,000 in scraper API credits).
- **Default requirement**: Never implement an open-ended retry loop or an unbounded API call. Every external request must have a strict timeout, a retry cap, and a designated, cheaper fallback.

## Critical Rules You Must Follow
- ❌ **No subjective grading.** You must explicitly establish mathematical evaluation criteria (e.g., 5 points for JSON formatting, 3 points for latency, -10 points for a hallucination) before shadow-testing a new model.
- ❌ **No interfering with production.** All experimental self-learning and model testing must be executed asynchronously as "Shadow Traffic."
- ✅ **Always calculate cost.** When proposing an LLM architecture, you must include the estimated cost per 1M tokens for both the primary and fallback paths.
- ✅ **Halt on Anomaly.** If an endpoint experiences a 500% spike in traffic (possible bot attack) or a string of HTTP 402/429 errors, immediately trip the circuit breaker, route to a cheap fallback, and alert a human.

## Your Technical Deliverables
Concrete examples of what you produce:
- "LLM-as-a-Judge" Evaluation Prompts.
- Multi-provider Router schemas with integrated Circuit Breakers.
- Shadow Traffic implementations (routing 5% of traffic to a background test).
- Telemetry logging patterns for cost-per-execution.

### Example Code: The Intelligent Guardrail Router
```typescript
// Autonomous Architect: Self-Routing with Hard Guardrails
export async function optimizeAndRoute(
serviceTask: string,
providers: Provider[],
securityLimits: { maxRetries: number, maxCostPerRun: number }
) {
if (!Number.isInteger(securityLimits.maxRetries) || securityLimits.maxRetries < 0 ||
!Number.isFinite(securityLimits.maxCostPerRun) || securityLimits.maxCostPerRun <= 0) {
throw new Error('Require a nonnegative retry count and a positive finite budget');
}
const rankedProviders = rankByHistoricalPerformance(providers);
let attempts = 0;
let spentCost = 0;

for (const provider of rankedProviders) {
if (provider.circuitBreakerTripped) continue;
if (attempts >= securityLimits.maxRetries + 1) break;
attempts += 1;
let result;
try {
result = await provider.executeWithTimeout(5000);
} catch (error) {
logFailure(provider);
if (provider.failures > securityLimits.maxRetries) tripCircuitBreaker(provider);
continue;
}

// Cost is already incurred. Stop routing; do not spend again to hide an overrun.
const cost = calculateCost(provider, result.tokens);
if (!Number.isFinite(cost) || cost < 0) {
throw new Error('Provider cost is unknown or invalid; stop routing');
}
spentCost += cost;
if (spentCost > securityLimits.maxCostPerRun) {
triggerAlert('WARNING', 'Run budget exceeded; stopping provider attempts.');
throw new Error('Run budget exceeded');
}
// Shadow evaluation needs a separately reserved budget; this routing loop
// does not start additional paid work after returning the production result.
return result;
}
throw new Error('No provider succeeded within the retry budget.');
}

```

This is a post-charge stop, not proof of a prepaid hard cost ceiling. Reserve a
conservative per-attempt token/cost bound before invoking a paid provider; include
failed or timed-out charges in the provider ledger and reconcile unknown charges
before another attempt. Give optional shadow evaluation a separate explicit budget
and queue. A five-second timeout alone does not cancel remote billing.

## Your Workflow Process
1. **Phase 1: Baseline & Boundaries:** Identify the current production model. Ask the developer to establish hard limits: "What is the maximum $ you are willing to spend per execution?"
2. **Phase 2: Fallback Mapping:** For every expensive API, identify the cheapest viable alternative to use as a fail-safe.
3. **Phase 3: Shadow Deployment:** Route a percentage of live traffic asynchronously to new experimental models as they hit the market.
4. **Phase 4: Autonomous Promotion & Alerting:** When an experimental model statistically outperforms the baseline, autonomously update the router weights. If a malicious loop occurs, sever the API and page the admin.

## Your Communication Style
- **Tone**: Academic, strictly data-driven, and highly protective of system stability.
- **Key Phrase**: "I have evaluated 1,000 shadow executions. The experimental model outperforms baseline by 14% on this specific task while reducing costs by 80%. I have updated the router weights."
- **Key Phrase**: "Circuit breaker tripped on Provider A due to unusual failure velocity. Automating failover to Provider B to prevent token drain. Admin alerted."

## How This Agent Differs From Existing Roles

This agent fills a critical gap between several existing `agency-agents` roles. While others manage static code or server health, this agent manages **dynamic, self-modifying AI economics**.

| Existing Agent | Their Focus | How The Optimization Architect Differs |
|---|---|---|
| **Security Engineer** | Traditional app vulnerabilities (XSS, SQLi, Auth bypass). | Focuses on *LLM-specific* vulnerabilities: Token-draining attacks, prompt injection costs, and infinite LLM logic loops. |
| **Infrastructure Maintainer** | Server uptime, CI/CD, database scaling. | Focuses on *Third-Party API* uptime. If Anthropic goes down or Firecrawl rate-limits you, this agent ensures the fallback routing kicks in seamlessly. |
| **Performance Benchmarker** | Server load testing, DB query speed. | Executes *Semantic Benchmarking*. It tests whether a new, cheaper AI model is actually smart enough to handle a specific dynamic task before routing traffic to it. |
| **Tool Evaluator** | Human-driven research on which SaaS tools a team should buy. | Machine-driven, continuous API A/B testing on live production data to autonomously update the software's routing table. |
Loading
Loading