DUBSOpenHubDUBSOpenHub/terminal-stampede/AGENTS.md

terminal-stampede

AGENTS.md4 starsChanged 7 months agoMITView on GitHub

Terminal Stampede ships three components: a Stampede orchestrator skill, a worker agent (stampede-agent), and a merger agent (stampede-merger). Together they form a complete parallel agent runtime — the skill parses your instructions and spawns agents, each worker claims tasks and writes code on isolated branches, and the merger auto-merges all branches with conflict resolution and Shadow Score quality measurement. These scripts are installed to ~/bin/ and drive the tmux runtime: Or add via Copilot CLI:

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,700 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository2 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- stampedeSkill

The file

We split this AGENTS.md into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Model: Default model in your Copilot CLI session (configurable per-agent)
line 17
Distinctive:
Usage: Run automatically after all agents finish, or invoke manually:
line 23
Distinctive:
Model: Default model in your Copilot CLI session
line 27
Distinctive:
Observability: Every agent runs in a visible tmux pane.
line 60

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

Agents

Overview

Terminal Stampede ships three components: a Stampede orchestrator skill, a worker agent (stampede-agent), and a merger agent (stampede-merger). Together they form a complete parallel agent runtime — the skill parses your instructions and spawns agents, each worker claims tasks and writes code on isolated branches, and the merger auto-merges all branches with conflict resolution and Shadow Score quality measurement.

Available Agents

stampede-agent (Worker Agent)

Purpose: Autonomous worker that claims tasks from the filesystem queue, executes them on an isolated git branch, writes results atomically, and loops until the queue is empty. Each instance runs in its own tmux pane with its own Copilot CLI context window. Supports up to 20 simultaneous instances.

Usage: Spawned automatically by stampede.sh. Can also be invoked manually for a single task:

# After installing, the launcher handles this:
stampede.sh --count 6 --task "add unit tests to all modules"

Model: Default model in your Copilot CLI session (configurable per-agent)
Location: agents/stampede-agent.agent.md → installs to ~/.copilot/agents/stampede-agent.agent.md

stampede-merger (Merger Agent)

Purpose: After all worker agents complete, this agent discovers all stampede branches, sorts them by output size (largest first as a quality proxy), merges them sequentially into a combined branch, resolves conflicts using AI with full task context, shadow-scores each agent's work across 3 layers, and produces a scored merge report.
Usage: Run automatically after all agents finish, or invoke manually:
```
~/bin/stampede-merge.sh    # Triggers merger agent via Copilot CLI
```
Model: Default model in your Copilot CLI session
Location: agents/stampede-merger.agent.md → installs to ~/.copilot/agents/stampede-merger.agent.md

stampede (Orchestrator Skill)

Purpose: Primary entry point for Terminal Stampede. Parses your natural language command, generates structured task files, monitors agent progress, detects stuck agents, and synthesizes final results. Drives the full Stampede workflow from a single command.

Usage:

run stampede "add error handling to all API endpoints"
run stampede "write tests for every function in src/"
stampede status        # Check live progress
stampede merge         # Trigger the merger agent

Location: skills/stampede/SKILL.md → installs to ~/.copilot/skills/stampede/SKILL.md

Shell Scripts

These scripts are installed to ~/bin/ and drive the tmux runtime:

Script	Purpose
`stampede.sh`	Creates the tmux session, spawns agent panes, tracks PIDs
`stampede-monitor.sh`	Live progress display, stuck detection, runtime stats
`stampede-merge.sh`	Discovers branches, sorts by size, launches the merger agent

Configuration

Default agents: 3 (configurable with --count, maximum 20)
Sweet spot: 6–8 agents for most tasks
Task queue: Filesystem-based atomic queue (/tmp/stampede-tasks/ by default) — no Redis, no message broker
Task claiming: Atomic file rename — no locks, no coordination server, no race conditions
Branch naming: Each agent works on stampede/<agent-id>/<task-id> — fully isolated
Quality scoring: Uses Shadow Score — quality criteria defined before agents run, measured silently after
Observability: Every agent runs in a visible tmux pane; type into any pane, kill it, or watch in real time
CLI agent compatibility: Built for GitHub Copilot CLI; shell scripts work with Aider, Claude Code, or any CLI tool

Install

git clone https://github.com/DUBSOpenHub/terminal-stampede.git
cd terminal-stampede && ./install.sh

Or add via Copilot CLI:

/skills add DUBSOpenHub/terminal-stampede

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free