agents-setup 0.2.0

Bootstrap and manage agent skills in brownfield repos

Skills — Agent Skills Monorepo

A monorepo of 34 composable skills for AI coding agents (Cursor, Claude Code, OpenCode) with an agents-setup CLI to bootstrap them into any brownfield repository. Supports multi-vendor installation, graph-first code exploration, and autonomous Ralph iterations.

What this is

• A working monorepo of 34 agent skills — TDD, brainstorming, architecture analysis, PRDs, triage, and more.
• A bootstrapper — agents-setup init ports skills, Cursor/OpenCode config, MCP wiring, and Ralph loop tooling into any repo with a single command.
• An autonomous coding rig — Ralph loop + Docker sandbox + parallel job coordinator for hands-off iteration.

Agents in this repo follow AGENTS.md rules: graph-first exploration, Ralph-style iterative slices, and skill routing by task type.

Quick start

Bootstrap skills into a repo

pip install agents_setup

agents-setup init                              # defaults to this repo as source
agents-setup init --source JuanSebastianGB/agents-setup --target /path/to/your/repo

Available commands

agents-setup init       # Bootstrap skills, Ralph scripts, optional MCP + PRD templates
agents-setup update     # Pull latest from source
agents-setup remove     # Clean up installed files

Init options

Flag	Effect
--diff	Preview changes without writing files
--force	Overwrite conflicts without prompting
--symlink	Create symlinks instead of copying (for development)
--with-mcp	Include .cursor/mcp.json MCP server template
--with-prd-templates	Include docs/prd/ starter (PRD.md, prd.json, progress.txt)
--all-scripts	Include all scripts from scripts/ directory
--json	Machine-parseable output

Run an autonomous iteration

./ralph-once.sh              # Single pass
./afk-ralph.sh 10            # Batch mode (stops on <promise>COMPLETE</promise>)
./ralph-once.sh --cursor     # Use Cursor as agent backend
./ralph-once.sh --sync-issues  # Sync issues from GitHub before running

Skills

By phase

Phase	Skills
Design	brainstorming, process-interviewer, grill-me, ubiquitous-language
Build	tdd, mcp-builder, write-a-skill, sudolang_workflow_planner, prd-copilot
Review	skill-quality-audit, skill-metrics, improve-codebase-architecture, principled-architecture
Validate	backend-qa-playbook, fact-checker, humanizer, debugger
Plan	to-prd, to-issues, request-refactor-plan, ddd-architecture, domain-model
Execute	ralph-loop, repo-inspirer, agent-architecture, caveman, conventional-commits, create-readme

Full listing

agent-architecture, auto-improve-skill, backend-qa-playbook, brainstorming, caveman, conventional-commits, create-readme, create-readme-workspace, debugger, ddd-architecture, domain-model, fact-checker, frontend-slides, grill-me, humanizer, improve-codebase-architecture, mcp-builder, postgresql-table-design, prd-copilot, principled-architecture, process-interviewer, ralph-loop, repo-inspirer, request-refactor-plan, skill-metrics, skill-quality-audit, sudolang-skillreducer, sudolang_workflow_planner, tdd, to-issues, to-prd, triage-issue, ubiquitous-language, write-a-skill

Project structure

.
├── agents_setup/              # Python CLI package
│   ├── cli.py                # Entry point
│   ├── commands/             # Deep module (init, update, remove, conflicts, output, install)
│   ├── ports.py              # Abstractions (IGitHubClient, IFileSystem, IConsole)
│   ├── vendors/              # Transform, preview, verify, mcp_merge, registry
│   ├── test_doubles.py       # FakeGitHubClient, InMemoryFileSystem, FakeConsole
│   └── api.py                # GitHub API client
├── ralph_lib/                # Ralph iteration helpers (progress, prd, state)
├── src/                      # Sandbox engine
│   ├── sandbox/              # Docker/host test execution
│   ├── worktree.py           # Git worktree management
│   ├── session.py            # Session state and path rewriting
│   └── parallel.py           # Parallel job coordinator
├── scripts/                  # Ralph bash helpers
│   ├── ralph-once.sh         # Single iteration driver
│   ├── afk-ralph.sh          # Batch iteration driver
│   ├── ralph-common.sh       # Shared prompt and utilities
│   └── ralph_status.sh       # Ralph status CLI
├── docs/
│   ├── prd/                  # PRD artifacts (PRD.md, prd.json, progress.txt)
│   └── research/             # Dated research notes
├── vendors/                  # Vendor-specific install logic
├── tests/                    # Boundary tests + conftest fixtures
├── AGENTS.md                 # Agent behavior rules (graph-first, skill routing)
├── UBIQUITOUS_LANGUAGE.md    # Domain glossary
├── opencode.json             # MCP server config for OpenCode
└── .agents/skills/            # The 34 skills library

Key features

Multi-vendor installation

agents-setup detects and installs into multiple AI IDEs:

• Cursor — rules (.cursor/rules/*.mdc), skills (.cursor/skills/), MCP configs
• OpenCode — commands (.opencode/commands/), context paths, MCP servers
• Claude Code — agents with mode: subagent frontmatter

Code knowledge graph

The repo is indexed with code-review-graph MCP — graph queries are first-class exploration:

• detect_changes — risk-scored review guidance
• get_impact_radius — blast radius of changes
• query_graph — callers, callees, imports, tests
• get_affected_flows — execution paths impacted

Agents use graph tools before grep/read. See AGENTS.md.

Ralph loop

Autonomous iterations with git-backed memory. Each run: fresh agent context, one vertical slice, PR with Closes #N, merge-to-close. Docker sandbox support with parallel job coordination.

• ./ralph-once.sh — single pass
• ./afk-ralph.sh N — batch mode (stops on <promise>COMPLETE</promise>)
• ./ralph-once.sh --sync-issues — sync GitHub issues first

Auto-release on push to main

Every push to main triggers:

1. Semantic version bump (from commit message or auto-increment)
2. GitHub Release with generated notes
3. PyPI publish (requires PYPI_TOKEN secret)

Architecture highlights

• agents_setup/commands/ — Deep module split by single responsibility: _conflicts, _install, _output, _tracking, _result
• agents_setup/ports.py — IGitHubClient, IFileSystem, IConsole interfaces; CommandsContext wires via context variables
• src/sandbox/ — Provider-agnostic sandbox abstraction (DockerSandboxProvider, TestSandboxProvider)
• Test doubles — test_doubles.py provides FakeGitHubClient, InMemoryFileSystem, FakeConsole for boundary testing without mocking internals