# Swarm Skill

Autonomous multi-agent workflow system for complex coding tasks.

## Installation

1. Add the marketplace:
   ```
   /plugin marketplace add nbashaw/swarm
   ```

2. Install the skill:
   ```
   /plugin install swarm@nbashaw-swarm
   ```

That's it! Claude will automatically load the skill when you request non-trivial coding tasks.

## What It Does

When invoked for non-trivial coding tasks, this skill:
1. Interviews the user to gather requirements
2. Creates a structured markdown plan with review gates
3. Spawns autonomous agents to execute the plan
4. Reports completion when agents finish

## Development Workflow

This repo uses a **symlinked development setup** for rapid iteration.

### Setup (Already Done)

```bash
~/.claude/skills/swarm -> ~/dev/swarm-skill/swarm
```

The installed skill is symlinked to your dev directory. Changes are live immediately!

### Daily Workflow

**1. Edit files directly:**
```bash
# Edit the skill
vim swarm/SKILL.md

# Edit the plan template
vim swarm/assets/PLAN_TEMPLATE.md
```

**2. Test immediately:**
Your changes are live! Just start a new Claude Code session and test:
```bash
claude
# Then: "Refactor the auth module" (or any non-trivial task)
```

**3. Commit when happy:**
```bash
git add .
git commit -m "Improve interview questions"
git push
```

### File Structure

```
swarm-skill/
├── README.md                      # This file
├── release.sh                     # Package for distribution
├── .gitignore                     # Git ignore rules
└── swarm/                         # The actual skill (symlinked)
    ├── SKILL.md                   # Skill instructions
    └── assets/
        ├── PLAN_TEMPLATE.md       # Plan template
        ├── swarm.sh               # Swarm runner script
        └── test_swarm.sh          # Test script for swarm.sh
```

### Releasing

When ready to share the skill with others:

```bash
./release.sh
```

This creates `swarm.skill` in the repo root that others can install.

## Running the Swarm

The `swarm.sh` script executes autonomous agents in a loop until the plan is complete.

**Basic usage:**
```bash
./swarm/assets/swarm.sh .context/YOUR_PLAN.md
```

**Available flags:**
- `-n, --dry-run` - Show what would happen without executing claude
- `-v, --verbose` - Print logs, timing, and plan summary after each iteration
- `-h, --help` - Show help message

**Examples:**
```bash
# Run with verbose output
./swarm/assets/swarm.sh --verbose .context/refactor_plan.md

# Test without running (dry run)
./swarm/assets/swarm.sh --dry-run .context/feature_plan.md

# Combine flags
./swarm/assets/swarm.sh -v -n .context/test_plan.md
```

**Environment variables:**
- `MAX_ITERATIONS` - Maximum iterations before stopping (default: 20)
```bash
MAX_ITERATIONS=50 ./swarm/assets/swarm.sh .context/big_task.md
```

## Testing Tips

**Quick test:** Ask Claude to set up a simple refactoring task
```
"Refactor the test utils to use async/await"
```

**Full test:** Use a real multi-file feature
```
"Add JWT authentication to the API with tests"
```

**Check the plan:** After Claude creates the plan, review it before execution
- Are phases clearly defined?
- Are review gates in place?
- Is the Gatekeeper checklist specific?

**Verify swarm.sh:** Test the runner script with the test suite
```bash
./swarm/assets/test_swarm.sh
```

## Troubleshooting

**Skill not triggering?**
- Check the description in SKILL.md frontmatter (that's the trigger)
- Ensure your task is "non-trivial" (multi-step, multiple files)

**Changes not appearing?**
- Verify symlink: `ls -la ~/.claude/skills/swarm`
- Should show: `swarm -> /Users/nbaschez/dev/swarm-skill/swarm`

**Want to test fresh?**
- Start new Claude session: `claude`
- Old sessions cache the skill content

## Git Workflow

```bash
# Feature development
git checkout -b improve-interview-flow
# ... make changes ...
git commit -m "Add more clarifying questions"
git push origin improve-interview-flow

# After review/testing
git checkout main
git merge improve-interview-flow
./release.sh  # Create distributable
```

## Ideas for Iteration

- Add more examples to SKILL.md
- Refine the interview questions
- Improve the plan template structure
- Add specialized plan templates for common tasks (refactoring, testing, migration)
- Adjust review gate frequencies
- Enhance Gatekeeper checklist items