Fork Manager

---

name: fork-manager description: Manage forks with open PRs - sync upstream, rebase branches, track PR status, and maintain production branches with pending contributions. Supports automatic conflict resolution via --auto-resolve flag (spawns AI subagents to resolve rebase conflicts). Use when syncing forks, rebasing PR branches, building production branches that combine all open PRs, reviewing closed/rejected PRs, or managing local patches kept outside upstream. Requires Git and GitHub CLI (gh). metadata: {"openclaw": {"requires": {"bins": ["git", "gh"]}}}

---

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: "",
     model: "",
     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 onde parou - Máximo de 2 retries antes de reportar falha ao usuário

Contexto para o Worker

O orchestrator deve incluir no prompt do worker:

Path da SKILL.md (para o worker ler e seguir)

Config do repo (inline ou path)

Última entrada do history (resumo ou path)

Modo de execução (full-sync, status, rebase-all, etc.)

Se é cron mode ou manual

Quaisquer instruções específicas do usuário

Por que subagente?

Resiliência: se o worker falha, o orchestrator pode recuperar

Context window: a skill é pesada (145+ PRs = muito output). O worker gasta seu context sem poluir o agente principal

Paralelismo futuro: permite spawnar workers para repos diferentes simultaneamente

Cron Mode

When invoked by a cron job (automated recurring sync), follow these guidelines for efficient execution:

1. Skip interactive prompts — auto-resolve decisions that don't require human input: - Rebases: attempt automatically, report failures - Closed PRs: report but defer decision (don't drop or keep without human input) - Audit findings: report but don't act 2. Compact output — use the summary format, not full verbose report:

   🍴 Fork Sync Complete — 
   Main: synced N commits (old_sha → new_sha)
   PRs: X open, Y changed state
   - Rebased: A/B clean (C conflicts)
   Production: rebuilt clean | N conflicts
   Notable upstream: [1-3 bullet highlights]
   

3. Checkpoint on failure — if a rebase fails or production build has conflicts, write state to repos//checkpoint.json so the next run (or manual invocation) can resume 4. Time budget — target <10 minutes total. If rebasing 20+ PRs, batch push at the end instead of per-branch

Configuration

Configs are organized per repository in repos//config.json relative to the skill directory:

fork-manager/
├── SKILL.md
└── repos/
    ├── project-a/
    │   └── config.json
    └── project-b/
        └── config.json

Formato do config.json:

{
  "repo": "owner/repo",
  "fork": "your-user/repo",
  "localPath": "/path/to/local/clone",
  "mainBranch": "main",
  "productionBranch": "main-with-all-prs",
  "upstreamRemote": "upstream",
  "forkRemote": "origin",
  "autoResolveConflicts": false,
  "openPRs": [123, 456],
  "prBranches": {
    "123": "fix/issue-123",
    "456": "feat/feature-456"
  },
  "localPatches": {
    "local/my-custom-fix": {
      "description": "Breve descrição do que o patch faz",
      "originalPR": 789,
      "closedReason": "rejected|superseded|duplicate|wontfix",
      "keepReason": "Motivo pelo qual mantemos localmente",
      "addedAt": "2026-02-07T00:00:00Z",
      "reviewDate": "2026-03-07T00:00:00Z"
    }
  },
  "lastSync": "2026-01-28T12:00:00Z",
  "notes": {
    "mergedUpstream": {},
    "closedWithoutMerge": {},
    "droppedPatches": {}
  }
}

Resolução automática de conflitos (autoResolveConflicts)

A resolução automática pode ser ativada de duas formas (qualquer uma basta):

1. Flag de invocação (ad-hoc, por execução):

   /fork-manager --auto-resolve
   /fork-manager full-sync --auto-resolve
   

2. Config persistente (sempre ativo pra aquele repo):

   { "autoResolveConflicts": true }
   

| Fonte | Comportamento | |-------|---------------| | Nenhuma (default) | Conflitos são reportados mas não resolvidos. Relatório inclui "⚠️ Conflitos requerem aval do desenvolvedor." | | --auto-resolve OU config.autoResolveConflicts: true | Spawna subagentes Opus para resolver conflitos. Resultados classificados como trivial/semântico/irresolvível. |

Precedência: --auto-resolve na invocação ativa a resolução mesmo se o config diz false. Não existe --no-auto-resolve — se o config diz true e o usuário não quer resolver, basta não rodar o passo manualmente.

Para usuários do ClawHub: basta passar --auto-resolve no comando. Nenhuma configuração de repo necessária.

Campos de localPatches

Cada entry em localPatches é uma branch local mantida na production branch mas sem PR aberto no upstream.

| Campo | Descrição | |-------|-----------| | description | O que o patch faz | | originalPR | Número do PR original que foi fechado (opcional se criado direto como patch) | | closedReason | Por que o PR foi fechado: rejected (mantenedor recusou), superseded (outro PR resolve parcialmente mas não totalmente), duplicate (fechamos nós mesmos), wontfix (upstream não vai resolver) | | keepReason | Por que precisamos manter localmente | | addedAt | Data em que foi convertido para local patch | | reviewDate | Data para reavaliar se ainda é necessário (upstream pode ter resolvido) |

Histórico de Execuções

Cada repositório gerenciado tem um arquivo history.md que registra todas as execuções da skill como um livro de registro append-only:

fork-manager/
└── repos/
    ├── project-a/
    │   ├── config.json
    │   └── history.md
    └── project-b/
        ├── config.json
        └── history.md

Regra: Ler último output antes de começar

Antes de qualquer operação, ler o history.md do repositório alvo e extrair a última entrada (último bloco ---). Isso dá contexto sobre:

O que foi feito na última execução

Quais PRs tinham problemas

Quais decisões foram tomadas

Se ficou alguma ação pendente

# Ler última entrada do history (tudo após o último "---")
tail -n +$(grep -n '^---$' "$SKILL_DIR/repos//history.md" | tail -1 | cut -d: -f1) "$SKILL_DIR/repos//history.md"

Se o arquivo não existir, criar com o header e prosseguir normalmente.

Regra: Registrar output ao finalizar

Ao final de toda execução, fazer append ao history.md com o resultado completo. Formato:

---
YYYY-MM-DD HH:MM UTC | 
Operator: 
Summary
Main: 
PRs: 
Local Patches: 
Production: 
Actions Taken

<"Rebased 21/21 branches clean">
<"PR #999 closed → kept as local patch local/my-fix">
<"PR #777 reopened → restored to openPRs (was in droppedPatches)">
Pending

<"3 local patches with expired reviewDate — run review-patches">
Full Report

Importante: O bloco Full Report contém o relatório completo sem abreviação. Isso garante que o próximo agente que ler o history tenha toda a informação, não apenas o resumo.

Fluxo de Análise

1. Carregar config e histórico

Resolve the skill directory (where SKILL.md lives):

# SKILL_DIR is the directory containing this SKILL.md
Resolve it relative to the agent's workspace or skill install path
SKILL_DIR=""
Load config for the target repo
cat "$SKILL_DIR/repos//config.json"
Ler último output do history para contexto
HISTORY="$SKILL_DIR/repos//history.md"
if [ -f "$HISTORY" ]; then
  # Extrair última entrada (após último ---)
  LAST_SEP=$(grep -n '^---$' "$HISTORY" | tail -1 | cut -d: -f1)
  if [ -n "$LAST_SEP" ]; then
    tail -n +"$LAST_SEP" "$HISTORY"
  fi
fi

2. Navegar para o repositório

cd 

3. Fetch de ambos remotes

git fetch 
git fetch 

4. Analisar estado do main

# Commits que upstream tem e origin/main não tem
git log --oneline /../
Contar commits atrás
git rev-list --count /../

5. Verificar PRs abertos via GitHub CLI

# Listar PRs abertos do usuário
gh pr list --state open --author @me --json number,title,headRefName,state
Verificar status de um PR específico
gh pr view  --json state,mergedAt,closedAt,title

6. Classificar cada PR

Para cada PR no config, verificar:

| Estado | Condição | Ação | | ------------ | --------------------------------- | --------------------------------------- | | open | PR aberto no GitHub | Manter, verificar se precisa rebase | | merged | PR foi mergeado | Remover do config, deletar branch local | | closed | PR fechado sem merge | Acionar review-closed (ver abaixo) | | conflict | Branch tem conflitos com upstream | Precisa rebase manual | | outdated | Branch está atrás do upstream | Precisa rebase |

Comando para verificar se branch precisa rebase:

git log --oneline /../ | wc -l  # commits à frente
git log --oneline /../ | wc -l  # commits atrás

7. Revisar PRs recém-fechados (review-closed)

Quando um PR é detectado como fechado sem merge, NÃO remover automaticamente. Iniciar um fluxo de revisão interativo:

#### 7.1. Coletar contexto do fechamento

# Buscar comentários e motivo do fechamento
gh pr view  --repo  --json title,closedAt,state,comments,labels
Verificar se upstream resolveu o problema de outra forma
(procurar PRs mergeados recentes que toquem os mesmos arquivos)
gh pr list --state merged --repo  --json number,title,mergedAt --limit 30

#### 7.2. Classificar o motivo do fechamento

| Categoria | Descrição | Ação padrão | |-----------|-----------|-------------| | resolved_upstream | Upstream corrigiu o problema por outro caminho | drop — não precisamos mais | | superseded_by_ours | Fechamos nós mesmos em favor de outro PR nosso | drop — o substituto já está em openPRs | | rejected_approach | Mantenedor não gostou da abordagem, mas o bug/feature existe | review — considerar resubmeter com abordagem diferente | | rejected_need | Mantenedor não concorda que é um problema | review — avaliar se precisamos localmente | | wontfix | Upstream marcou como wontfix | review — provável candidato a local patch |

#### 7.3. Apresentar ao usuário para decisão

Para cada PR fechado, apresentar:

### PR # —