Agent Protocols
A multi-platform repository of production-validated protocols, specialized agents, skills, and automation frameworks for systematic AI-assisted software development.
Overview
This marketplace contains 2 plugins with complementary capabilities:
- Modernize - Complete modernization workflow (assess → plan → execute → improve) with 6 specialized agents
- Autocoder - Autonomous issue resolution — GitHub, Jira, Azure DevOps, or file-backed trackers — with intelligent testing and quality automation
Both plugins feature continuous improvement through retrospective analysis and are universally applicable to any software project. The repo also ships platform-neutral skills, including improve (skills/improve/) — a validation & refinement loop for stabilizing platforms through repeated live end-to-end runs. Originally created for .NET framework migrations, these tools work with any language or platform.
Start Here
Pick your platform:
Not sure? Claude Code is the primary platform — it has the most complete feature set and documentation.
⚠️ Compatibility Notice
These plugins are primarily developed for personal use. While they should work on Linux, macOS, and WSL (Windows Subsystem for Linux), there are no guarantees they will work in all environments. Use at your own risk.
Tested Platforms:
- ✅ Linux
- ✅ macOS
- ✅ WSL (Windows Subsystem for Linux)
- ❌ Windows (native) - Not supported
Directory Guide
This repository supports multiple agentic platforms. Please refer to the corresponding directory and documentation for your platform:
Each platform has its own directory structure and installation method. See the platform-specific documentation for details.
Codex Support
Codex support is additive and does not replace the Claude Code or Antigravity / Gemini implementations.
Add Marketplace
/plugin add marketplace https://github.com/laird/agents
Codex Skills
skills/autocoder/ - Codex-native entrypoint for autonomous GitHub issue workflowsskills/modernize/ - Codex-native entrypoint for modernization workflows
Gemini CLI Skill Packaging
skills/autocoder/ - shared skill content plus gemini-extension.json and GEMINI.mdskills/modernize/ - shared skill content plus gemini-extension.json and GEMINI.md
Codex Runtime Scripts
# Install Codex skills, aliases, and parallel-agent commands
bash scripts/install-codex.sh /path/to/target-repo
# Run one autocoder pass
bash scripts/codex-autocoder.sh fix
# Run the continuous fix loop
bash scripts/codex-fix-loop.sh
# Run the manager monitor loop
bash scripts/codex-monitor-loop.sh 15
# Stop running loops
bash scripts/codex-stop-loop.sh all
# Start a Codex swarm (defaults to tmux; pass `cmux` to override)
bash scripts/start-parallel-codex.sh 3
If you want shell aliases for Codex swarm startup, source codex-shell-aliases.sh from your shell config. That gives you startct, startcc, joinct, and joincc.
See docs/CODEX.md for details.
Droid (Factory) Support
Droid support is additive and does not replace the Claude Code, Antigravity / Gemini, or Codex implementations.
Droid Skills
.factory/skills/autocoder/ - Droid-native entrypoint for autonomous GitHub issue workflows.factory/skills/modernize/ - Droid-native entrypoint for modernization workflows
Droid Custom Droids (Subagents)
Six specialist subagents in .factory/droids/: architect, coder, documentation, migration-coordinator, security, tester.
Droid Runtime Scripts
# Install Droid skills, droids, aliases, and parallel-agent commands
bash scripts/install-droid.sh /path/to/target-repo
# Run one autocoder pass
bash scripts/droid-autocoder.sh fix
# Run the continuous fix loop
bash scripts/droid-fix-loop.sh
# Run the manager monitor loop
bash scripts/droid-monitor-loop.sh 15
# Stop running loops
bash scripts/droid-stop-loop.sh all
# Start a tmux-based Droid swarm
bash scripts/droid-start-parallel.sh tmux 3
If you want shell aliases for Droid swarm startup, source droid-shell-aliases.sh from your shell config. That gives you startdt, startdc, joindt, and joindc.
See docs/DROID.md for details.
Swarm Quickstart Guides
Platform-specific install and run guides for each supported agent:
Shell Aliases — All Combinations
Source the alias files for the platforms you use. Each provides start and join aliases for both tmux and cmux.
Install all aliases in one step (auto-detects which agent CLIs are installed):
bash /path/to/agents/scripts/install-shell-aliases.sh # auto-detect
bash /path/to/agents/scripts/install-shell-aliases.sh --all # all agents
source ~/.zshrc # or ~/.bashrc
Or install via /autocoder:install in Claude Code.
All aliases call start-parallel with the appropriate --agent and --mux flags. Example — start 3 Claude workers in tmux:
# Add to ~/.zshrc or ~/.bashrc:
source /path/to/agents/scripts/claude-shell-aliases.sh
# Then:
startclt 3 # 1 manager + 3 Claude workers in tmux
startclc 3 # 1 manager + 3 Claude workers in cmux
startct 3 # 1 manager + 3 Codex workers in tmux
startgt 3 # 1 manager + 3 Gemini workers in tmux
startdt 3 # 1 manager + 3 Droid workers in tmux
Installation
Claude Code
Add Marketplace
/plugin add marketplace https://github.com/laird/agents
Install Plugins
Install modernize plugin (software modernization workflows):
/plugin install modernize
Install autocoder plugin (autonomous GitHub issue resolution):
/plugin install autocoder
Install both plugins:
/plugin install modernize autocoder
After installation, commands will be available as slash commands in Claude Code:
- modernize:
/assess, /plan, /modernize, /retro, /retro-apply, /modernize-help
- autocoder:
/fix, /fix-loop, /stop-loop, /monitor-workers, /list-proposals, /approve-proposal, /list-needs-design, /list-needs-feedback, /brainstorm-issue, /full-regression-test, /improve-test-coverage, /review-blocked, /install, /autocoder-help
Get help anytime:
/modernize-help # Overview of modernization workflow
/autocoder-help # Overview of autonomous coding workflow
Optional Companion Plugins
Autocoder and modernize work fine without these. Install them when you hit the scenarios below.
| Plugin | Install when… |
|---|
| superpowers | You encounter complex multi-file issues and want systematic debugging, planning, and verification skills |
| quint | You need structured human-in-the-loop decisions for ultra-complex or irreversible changes |
/plugin install superpowers # optional: structured problem-solving
/plugin install quint # optional: human-guided decisions
When installed, /fix invokes them automatically for the right issue types. When absent, the workflow uses direct problem-solving instead — no configuration needed either way.
Droid (Factory)
Add Marketplace
droid plugin marketplace add https://github.com/laird/agents
Install Plugins
droid plugin install modernize@plugin-marketplace
droid plugin install autocoder@plugin-marketplace
Standalone Installer
bash scripts/install-droid.sh /path/to/target-repo
After installation, the same slash commands are available in Droid. See docs/DROID.md and docs/DROID-INSTALL.md for details.
Antigravity Support
This repository is Antigravity-native. It includes the .agent/ directory containing all agent rules and workflows, making it compatible with the Antigravity engine out of the box.
Quick Install (One-Liner)
Run this command from your project's root directory:
curl -sSL https://raw.githubusercontent.com/laird/agents/main/scripts/install.sh | bash
This fetches only the .agent/ directory and installs it into your project.
[!NOTE]
Cross-Platform Compatibility
- Linux/macOS: Works natively
- Windows: Requires Git Bash or WSL
Manual Installation
Alternatively, copy or symlink the .agent/ directory:
# Option 1: Copy
cp -r /path/to/agents/.agent /your/project/
# Option 2: Symlink (for development)
ln -s /path/to/agents/.agent /your/project/.agent
Available Workflows
After installation, these workflows are available:
Modernize Workflows:
| Workflow | Description |
|---|
/assess | Evaluate modernization viability |
/plan | Create execution strategy |
/modernize | Execute multi-phase modernization |
/retro | Analyze project for improvements |
/retro-apply | Apply retrospective findings |
/modernize-help | Show modernize workflow help |
Autocoder Workflows:
| Workflow | Description |
|---|
/fix | Autonomous issue resolution |
/fix-loop | Continuous autonomous resolution |
/stop-loop | Stop the continuous loop |
/list-proposals | View pending AI-generated proposals |
/approve-proposal | Approve a proposal for implementation |
/list-needs-design | List issues needing design work |
/list-needs-feedback | List issues needing feedback |
/brainstorm-issue | Brainstorm design for an issue |
/full-regression-test | Run comprehensive test suite |
/improve-test-coverage | Analyze and improve test coverage |
/review-blocked | Review and unblock issues labeled by fix-loop |
/monitor-workers | Monitor workers, dispatch idle agents, deploy when done |
/install | Install all autocoder plugin components |
/autocoder-help | Show autocoder workflow help |
[!WARNING]
The watchdog scripts in .agent/scripts/ are experimental. See docs/ANTIGRAVITY.md for details.
Plugins
Plugin 1: Modernize
Complete modernization workflow with multi-agent orchestration. See the Modernize README for full documentation.
Get help: /modernize-help
Commands: /assess, /plan, /modernize, /retro, /retro-apply
Quick Start: /assess → /plan → /modernize → /retro → /retro-apply
Plugin 2: Autocoder
Autonomous issue resolution (GitHub, Jira, Azure DevOps, or file-backed trackers) with intelligent testing, quality automation, multi-agent swarm support, and human-in-the-loop proposal system. See the Autocoder README for full documentation.
Get help: /autocoder-help
Commands: /fix, /fix-loop, /stop-loop, /monitor-workers, /monitor-loop, /review-blocked, /list-proposals, /approve-proposal, /list-needs-design, /list-needs-feedback, /brainstorm-issue, /full-regression-test, /improve-test-coverage, /install, /manager-handoff, /manager-resume
Quick Start:
/fix # Fix highest priority issue
/install # One-time setup for continuous mode
/fix-loop # Run continuously (single agent)
Swarm (parallel workers):
# 1 manager (opus) + 3 workers (sonnet), each in its own tmux pane
startclt 3
# Override models
WORKER_MODEL=claude-sonnet-5 MANAGER_MODEL=claude-opus-5 startclt 3
# Manager-routing mode (zero worker-vs-worker claim races)
start-parallel-agents.sh 3 --mux tmux --agent claude --route manager
Environments (gated releases): the swarm lands on main fast and main-sentinel.sh repairs it when it goes red. Releases do not share that risk. Declare environments in .autocoder.json (staging → uat → prod, each a branch on origin that your deploy reads) and promote.sh moves each one only to a commit with proof of a full-regression pass: the sentinel's main-green tip, the previous environment's tip, or a tree the gate cache recorded as passing. Being on main is never enough. See docs/environments.md.
SRE Monitor (idle fallback):
When a worker has no issues in the queue, it can fall back to monitoring production systems — scanning logs for errors, checking service health, and filing or updating GitHub issues for any problems found. This keeps workers productive during queue droughts and surfaces production incidents automatically.
Copy agents/autocoder/workflows/sre-monitor.md into your project and adapt the log-collection commands for your environment. The log-collection step is necessarily project-specific: it depends on your logging provider, service names, and the error patterns that matter to you. Everything else (severity triage, issue filing, sleep/wake cycle) stays the same.
Extending the log-collection step — examples by provider:
GCP Cloud Run / Cloud Logging:
export SRE_PROJECT_ID="my-gcp-project"
export SRE_SERVICE_NAME="my-api"
gcloud logging read \
"resource.type=cloud_run_revision AND resource.labels.service_name=$SRE_SERVICE_NAME" \
--project="$SRE_PROJECT_ID" --limit=100 --freshness=30m 2>&1 \
| grep -iE "(error|fatal|timeout|Max restart|lock expired)" | head -40
AWS CloudWatch Logs:
aws logs filter-log-events \
--log-group-name "/aws/ecs/my-service" \
--start-time $(date -d '30 minutes ago' +%s000) \
--filter-pattern "?ERROR ?FATAL ?timeout" \
--query 'events[*].message' --output text | head -40
Datadog:
datadog-cli logs search \
"service:my-service status:(error OR warn) @env:production" \
--from "30 minutes ago" --limit 100 \
| jq -r '.[].message' | head -40
Kubernetes (kubectl):
kubectl logs -n production \
-l app=my-service \
--since=30m --prefix \
| grep -iE "(error|fatal|panic|OOMKilled)" | tail -40
Local / file-based logs:
grep -iE "(error|fatal|panic)" /var/log/my-service/app.log \
| awk -v cutoff="$(date -d '30 minutes ago' '+%Y-%m-%d %H:%M')" '$0 >= cutoff' \
| tail -40
Extend the grep -iE pattern with the error signatures that matter for your service — worker crashes, lock timeouts, queue stalls, auth failures, etc. Add a severity table mapping those patterns to P0–P3 so the agent knows when to file immediately vs. comment on an existing issue.
For each finding the monitor either files a new GitHub issue with a priority label, or comments on an existing open issue with the latest timestamp, frequency, and context.
Skill: Improve
A validation and refinement loop for stabilizing a platform — not security hardening. Run the real end-to-end cycle, grade it against an explicit contract, root-cause fix, log findings, repeat until N consecutive clean runs.
When to use: After an initial modernize or migration, when you want to drive defect count to zero through repeated live runs rather than code review alone. Also useful for any system with a runnable end-to-end exercise.
How to invoke:
- Claude Code: load the
improve skill via the Skill tool (or use skills/improve/SKILL.md directly)
- Codex / Gemini: load the
improve skill from skills/improve/
Model tiers: Coordinator on $MANAGER_MODEL (opus / pro) for grading and root-cause analysis; subagent workers on $WORKER_MODEL (sonnet / flash) for bounded fixes. Credentials are inherited from the running session.
See skills/improve/SKILL.md for the full loop protocol including swarm-mode cadence and cost discipline.
Repository Structure
Two plugins (modernize, autocoder) each with their own commands/, agents/, and scripts/ — fully independent and separately installable. Both share the same 6 specialist agents (architect, coder, documentation, migration-coordinator, security, tester). Per-platform directories (.agent/, .factory/, codex-plugins/, .agents/) mirror the Claude Code plugins/ content for their respective agent CLIs; skills/improve/ is platform-neutral and ships once.
See docs/STRUCTURE.md for the full annotated directory tree.
Key Features
Production-Validated Protocols
- ✅ Proven results - Successfully guided 32/32 project migrations
- ✅ Universal applicability - Works with any software project, not just .NET
- ✅ Complete audit trail - HISTORY.md logging for all agent activities
- ✅ Quality gates - Automated validation at each stage
- ✅ Evidence-based evolution - Protocols continuously improved through retrospective analysis
Multi-Agent Coordination
- 🤖 6 specialized agents - Each with defined capabilities and responsibilities
- 🔄 Parallel execution - Multiple agents work independently on separate tasks
- 📊 Enforced quality - 100% test pass rate, security score ≥45/100
- 📝 Systematic workflows - 7-phase migration, 6-phase testing, 8-stage ADR lifecycle
- 🧠 Model-tiered swarms - Manager on
claude-opus-5 (coordination), workers on claude-sonnet-5 (implementation); overridable via WORKER_MODEL/MANAGER_MODEL
- 🆕 Fresh context per issue -
claude-worker-loop.sh restarts Claude for each issue; each worker is a visible tmux pane the user can inspect and interact with
- 🔒 Robust issue claiming - Atomic file-backend rename + GitHub race-detection via
[autocoder-claim] markers; task scope gate checks CONTEXT FIT and WORKTREE INDEPENDENCE before branching
- 📐 Worktree-safe decomposition - Over-large issues are split into sub-tasks with "Files Affected" fields so parallel workers never collide
- 🛡️ Swarm resilience - Manager monitors worker health, restarts unhealthy workers, and can scale the fleet mid-run with
add-worker.sh
Continuous Improvement
- 🔍 Retrospective analysis - Analyzes git history, user corrections, agent mistakes
- 📈 Evidence-based recommendations - 3-5 specific improvements with quantified impact
- 🔧 Automated application - Updates commands, protocols, and automation
- 🎯 Learning from mistakes - Identifies wrong tool usage, wasted effort, requirement misunderstandings
- ♻️ Self-improving system - Each project makes the next one better
- ⏱️ Measurable impact - Recent improvements saved 27 hours per project
Real-World Results
- 32/32 projects migrated successfully (100% success rate)
- 100% test pass rate (meets requirement)
- Security improvement from 0/100 → 45/100 (CRITICAL CVEs eliminated)
- Zero P0/P1 blocking issues in production
- 1,500+ lines of documentation auto-generated
Recent Protocol Improvements (Nov 2025)
Based on retrospective analysis of RawRabbit modernization, 5 evidence-based improvements were implemented:
-
Front-Load Test Environment Setup ⚡
- Phase 0 test setup now mandatory before any work begins
- Verified baseline metrics (build, tests, vulnerability scan) replace estimates
- Prevents "works on my machine" issues discovered too late
-
Spike-Driven ADR Process 🧪
- New Stage 2.5 for high-risk architectural decisions
- Requires empirical validation via spike branches before commitment
- 24-48hr stakeholder review period enforced
- Better decisions through evidence vs. desk research
-
Shift Security Validation Left 🔒
- New automated security scanning protocol
- Phase 0 baseline scan, continuous monitoring throughout project
- Security scores calculated from actual scans, never estimated
- Critical/High CVEs blocked earlier in workflow
-
Continuous Testing Strategy ✅
- Testing after EVERY stage, not delayed until Stage 4
- Tiered testing: Unit → Component → Integration → Performance
- Estimated 7 hours saved per project from early issue detection
- Issues found in Stage 1 vs Stage 4 dramatically cheaper to fix
-
Incremental Documentation 📝
- Status marker system: ⚠️ In Progress → ✅ Fixed (validated) → 📝 Documented
- "Fixed" claims only after test validation passes
- Prevents aspirational documentation requiring corrective commits
- Accurate HISTORY.md audit trail
Combined Impact: 27 hours saved per project, earlier issue detection, verified (not estimated) security posture, empirical architectural decisions, and accurate documentation.
Best Practices
Modernization Workflow:
/assess → /plan → /modernize → /retro → /retro-apply- Monitor HISTORY.md for complete audit trail
- Review
IMPROVEMENTS.md and apply approved changes
- Next project benefits from lessons learned
Quality Gates:
- Security score ≥45 before migration starts
- Build success 100% before next stage
- Test pass rate 100% before proceeding
- All P0/P1 issues resolved before release
Autocoder Workflow:
- Run
/autocoder-help to see all available commands
- Run
/fix to start autonomous issue resolution
- Use
/list-needs-design and /brainstorm-issue for complex issues
- Review proposals with
/list-proposals and approve with /approve-proposal
- For continuous operation:
/install then /fix-loop
Use Cases
- Framework Upgrades - .NET, Node.js, Python, Java, etc.
- Cloud Migrations - AWS, Azure, GCP platform changes
- Language Migrations - Java to Kotlin, JavaScript to TypeScript
- Database Migrations - SQL to NoSQL, version upgrades
- Legacy Modernization - Monolith to microservices, API updates
- Security Remediation - CVE scanning and vulnerability fixes
- Quality Assurance - Comprehensive testing and validation
- Documentation - Technical docs, migration guides, ADRs
Version History
| Version | Date | Changes |
|---|
| 3.42.0 | 2026-08-31 | Autocoder v4.21.0: the manager no longer dies on the bypass-permissions dialog, and the status line names the repo. The manager is the only claude path that launches a REPL and then types its prompt into it, and that typed prompt went in after a fixed sleep 5 with no readiness check — so under --dangerously-skip-permissions, whose consent dialog defaults to "No, exit", the trailing Enter answered the dialog instead of submitting the prompt, and the review window was left at a bare shell that reads as an unrelated login session rather than a failed manager. MANAGER_COMMAND_MODE (argv |
| 3.41.0 | 2026-08-26 | Autocoder v4.20.0: per-issue cost and time attribution. Workers already wrote a full stream-json transcript per session, but its result event — tokens, turns, wall-clock, total_cost_usd — was only ever read by a human doing a post-mortem, and AUTOCODER_LOG_DIR defaults to /tmp, so a reboot deleted the only record of what an issue cost. issue-metrics.py aggregates those transcripts per issue and renders a markdown comment; post-issue-metrics.sh posts it through the issue-fns.sh backend (so it works on GitHub/Jira/ADO/file alike), deduping on an HTML marker so re-runs update rather than pile up. claude-worker-loop.sh calls it after each fix session, fail-soft. Gate transcripts are deliberately excluded — gate work has no single owner and would inflate whichever issue happened to follow it — and an in-flight session (no result event yet) is reported separately rather than published as "$0.00, 0 turns". |
| 3.38.0 | 2026-08-16 | Autocoder v4.17.0: fixed manager idle detection — monitor-workers listed "bare prompt ❯ with no active tool calls" as an idle indicator, but the agent TUI renders an empty input box mid-turn too, so the rule was always true and managers dispatched over live work. New worker-idle.sh decides by double-sampling the pane (any change = busy) and excludes the manager's own pane, which was previously classified as a fourth worker. Same bug removed from modernize's executable auto-dispatch (it grepped for `❯ |
| 3.32.1 | 2026-08-07 | Autocoder v4.10.1: Jira backend migrated to /rest/api/3/search/jql (Atlassian removed the v2 search API — HTTP 410); nextPageToken pagination, explicit fields, ADF descriptions flattened to plain text. Validated LIVE against a real Jira Cloud site (full lifecycle + search); test fakes now 410 the removed endpoint so the migration can't regress. |
Issue Backends
The issue system is pluggable. Four backends ship built-in — file, GitHub, Jira, and Azure DevOps — and any executable implementing the same contract can be added as a custom backend. Select one with /set-issue-source.
See docs/issue-backends.md for the full overview, and docs/jira-setup.md / docs/ado-setup.md for the Jira and Azure DevOps setup guides.
Backend Contract
Every backend accepts the same 9 verbs:
| Subcommand | Args | Output |
|---|
list | [--label L] [--state open|working|blocked|closed|all] [--limit N] | JSON array — gh issue list schema |
get | <number> | JSON object — gh issue view schema |
update | <number> [--add-label L] [--remove-label L] [--status S] [--assignee A] | exit code |
comment | <number> --body "..." | exit code |
close | <number> [--comment "..."] | exit code |
create | --title "..." --body "..." [--label L] | {"number": N} |
claim | <number> | exit code |
release | <number> | exit code |
any-claimable | — | exit 0 if claimable work exists, 1 if none |
list and get must output JSON matching gh issue list --json number,title,body,labels,state and gh issue view --json number,title,body,labels,state,comments respectively. Exit codes: 0 success/work exists, 1 clean negative, 2 usage error, 3 backend error.
Note: --priority is translated to --label by issue-fns.sh before reaching backends. Backends only receive --label.
Restricting the Swarm to Approved Issues
Set requiredLabel in .autocoder.json and workers may only claim issues
carrying that label:
{
"issueSource": "github",
"requiredLabel": "swarm"
}
Approval becomes a positive act — tag an issue swarm and the swarm may take
it — instead of the absence of a blocking label. The gate applies to the
claimable queue and to claim itself, so it holds for issues dispatched by
number as well (/fix N, a manager dispatch, a resumed loop). working and
blocked listings stay ungated so in-flight work remains visible.
AUTOCODER_REQUIRED_LABEL overrides it for one command; empty disables it.
Unset, nothing changes. See docs/issue-backends.md.
Registering a Custom Backend
The built-in sources (file, github, jira, ado) need only issueSource. A custom backend additionally points issueBackend at an executable:
{
"issueSource": "linear",
"issueBackend": "./scripts/backends/linear-backend.sh"
}
Minimal Template
#!/bin/bash
SUBCOMMAND="$1"; shift
case "$SUBCOMMAND" in
list) echo "[]" ;;
get) echo "{}" ;;
update) exit 0 ;;
comment) exit 0 ;;
close) exit 0 ;;
create) echo '{"number": 1}' ;;
*) echo "Unknown: $SUBCOMMAND" >&2; exit 1 ;;
esac
Distributed Lock Pattern
For backends that need distributed locking (multiple parallel agents claiming issues), implement status: open|working|closed semantics in your update subcommand.
The built-in issue_claim N wrapper in issue-fns.sh is the canonical way to claim an issue:
- File backend: performs an atomic
os.rename(open/N.md, working/N.md) — only one worker wins
- GitHub backend: calls
update N --add-label working, then posts an [autocoder-claim] marker comment, waits 3 seconds for concurrent workers to surface, and checks marker count — backs off if more than one marker found
Agents call issue_release N to unclaim (not update N --remove-label working); release moves the file back from working/ to open/ and removes the label. The list --state open call must exclude claimed issues.
References
License
MIT License - See repository for details
Status: Production-validated
Applicability: Universal (all software projects)
Original Context: .NET Framework Migration
Maintained By: AI-assisted development community
