Metadata-Version: 2.4
Name: agents_setup
Version: 0.2.0
Summary: Bootstrap and manage agent skills in brownfield repos
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"

# 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

```bash
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

```bash
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

```bash
./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
