fork-manager

# Fork Manager Skill

Manage forks where you contribute PRs but also use improvements before they're merged upstream. Includes support for local patches — fixes kept in the production branch even when the upstream PR was closed/rejected.

## When to use

- Sync a fork with upstream
- Check status of open PRs
- Rebase PR branches onto latest upstream
- Build a production branch combining all open PRs + local patches
- Review recently closed/rejected PRs and decide whether to keep locally
- Manage local patches (fixes not submitted or rejected upstream)

## When NOT to use

- General GitHub queries (issues, PRs, CI status on any repo) → use `github` skill instead
- Triaging/ranking/prioritizing issues → use `issue-prioritizer` skill instead
- Reviewing code changes before publishing a PR → use `pr-review` skill instead
- Creating new PRs from scratch (not fork sync) → use `gh pr create` directly

## Execution Model — Orchestrator + Worker

**A skill NUNCA deve ser executada inline pelo agente principal.** Sempre usar o padrão orchestrator/worker:

### Fluxo

1. **Orchestrator (agente principal)** — prepara o contexto e spawna um subagente:
   ```
   sessions_spawn(
     task: "<prompt completo com contexto do repo, config, último history>",
     model: "<model adequado>",
     mode: "run"
   )
   ```
2. **Worker (subagente)** — executa o full-sync/status/rebase/etc. Lê a SKILL.md, segue o fluxo, escreve history.
3. **Monitoramento** — o orchestrator checa progresso a cada **4 minutos** via `sessions_list` / `sessions_history`:
   - Se o worker estiver ativo e progredindo → aguarda
   - Se o worker estiver parado/travado (sem output novo por 2 checks consecutivos) → `subagents kill` + spawna novo worker
   - Se o worker completou → lê o resultado e reporta ao usuário
4. **Fallback** — se o worker falhar (crash, timeout, erro):
   - Orchestrator verifica o estado do repo (`git status`, último checkpoint)
   - Spawna novo worker com contexto atualizado incluindo o ponto...

# Fork Manager Skill

Manage forks where you contribute PRs but also use improvements before they're merged upstream. Includes support for local patches — fixes kept in the production branch even when the upstream PR was closed/rejected.

## Structure

```
fork-manager/
├── SKILL.md              # Full agent instructions
├── README.md             # This file
├── ARCHITECTURE.md       # Design decisions and architecture
└── repos/
    └── <project-name>/
        ├── config.json             (local only - not versioned)
        └── config.example.json     (versioned template)
```

## Installation

```bash
# 1. Clone the repository
git clone https://github.com/Glucksberg/fork-manager-skill.git /path/to/fork-manager

# 2. Create local configs from examples
cd /path/to/fork-manager
cp repos/<project>/config.example.json repos/<project>/config.json

# 3. Edit with your info
vim repos/<project>/config.json

# 4. Configure for OpenClaw (global for all agents)
openclaw config set skills.load.extraDirs '["/path/to/parent/directory"]'

# 5. Configure for Claude Code CLI
ln -s /path/to/fork-manager ~/.claude/skills/fork-manager
```

### Via ClawHub

```bash
clawhub install fork-manager
```

## Integration

### OpenClaw

The skill is loaded via `extraDirs` in the global config:

```json
{
  "skills": {
    "load": {
      "extraDirs": ["/path/to/agents"]
    }
  }
}
```

### Claude Code CLI

The skill is loaded via symlink:

```bash
~/.claude/skills/fork-manager → /path/to/fork-manager
```

## Available Commands

- `status` - Check current fork state
- `sync` - Sync main with upstream
- `rebase <branch>` - Rebase a specific branch
- `rebase-all` - Rebase all PR branches
- `update-config` - Update config with current PRs
- `build-production` - Create production branch with all PRs + local patches
- `review-closed` - Review recently closed PRs (keep/drop/resubmit)
- `review-patches` - Re-evaluate existing local patches
- `audit-open` - Audit open PRs for redundancy/obsolescence
- `...