Skip to content

jupes/agent-forge-harness / .agents/skills/syncing-repos

syncing-repos

Verified

Clone, inspect, refresh, reset, or manage branches across registered Forge sub-repos. Use for single-repo or multi-repo synchronization.

FileKindSize
SKILL.mdskill md3.8 KB
scripts/repo-select.tsscript1.2 KB
scripts/repo.tsscript8.1 KB
---
name: syncing-repos
description: Clone, inspect, refresh, reset, or manage branches across registered Forge sub-repos. Use for single-repo or multi-repo synchronization.
---

# syncing-repos

Manages multiple sub-repos registered in **local** `repos/repos.json` (gitignored; bootstrap from `repos/repos.json.example`). All operations emit JSON so agents can parse results.

## CLI Usage

```bash
bun run repo <command> [options]
```

All commands accept `--repo <name>` to target a single repo, or operate on all repos by default.

### Archived repos

An entry with `"archived": true` stays registered (and cloned, if it is) but every all-repos run
skips it: `init`, `status`, `refresh`, `reset` and the `branch` commands, and `/sync-knowledge --all`.
The JSON output lists the ones left out under `"skipped"`. To act on one anyway:

```bash
bun run repo refresh --repo old-docs          # naming an archived repo still works
bun run repo status --include-archived        # every repo, archived ones included
```

Archive a dormant or reference-only repo instead of removing its entry, so it keeps its clone,
its knowledge file and its name in the Repo column (`docs/HARNESS-GUIDE.md`).

## Commands

### init
Clone or pull all repos in repos.json.
```bash
bun run repo init              # Non-interactive, JSON output
bun run repo init --human      # Human-readable output with progress
```

### status
Show sync status of all repos.
```bash
bun run repo status
# → { "repos": [{ "name": "my-api", "branch": "main", "ahead": 0, "behind": 2, "dirty": false }] }
```

### refresh
Pull and rebase all repos on their default branch.
```bash
bun run repo refresh
bun run repo refresh --repo my-api
```

### reset
Hard reset a repo to its remote HEAD. Discards all local changes.
```bash
bun run repo reset --repo my-api    # DESTRUCTIVE — confirm before use
```

### branch create
Create a feature branch in one or all repos.
```bash
bun run repo branch create feat/T-42-my-feature
bun run repo branch create feat/T-42-my-feature --repo my-api
```

### branch cleanup
Delete merged branches from one or all repos.
```bash
bun run repo branch cleanup
bun run repo branch cleanup --repo my-api --dry-run
```

### stacked-rebase
Rebase a stack of branches sequentially.
```bash
bun run repo stacked-rebase feat/base feat/feature-a feat/feature-b
```

## Output Format

All commands return:
```json
{
  "ok": true,
  "command": "init",
  "repos": [
    {
      "name": "my-api",
      "ok": true,
      "action": "cloned",
      "path": "repos/my-api",
      "branch": "main"
    }
  ],
  "skipped": ["old-docs"],
  "errors": []
}
```

`"skipped"` names the archived entries the run left out (empty when there are none).

On failure:
```json
{
  "ok": false,
  "command": "refresh",
  "repos": [...],
  "errors": [{ "repo": "my-api", "message": "merge conflict in src/index.ts" }]
}
```

## repos.json Schema

```json
{
  "repos": [
    {
      "name": "my-api",
      "url": "https://github.com/org/my-api.git",
      "defaultBranch": "main",
      "checks": [
        { "name": "typecheck", "argv": ["bun", "run", "typecheck"] },
        { "name": "tests", "argv": ["bun", "test"] }
      ]
    },
    {
      "name": "old-docs",
      "url": "https://github.com/org/old-docs.git",
      "defaultBranch": "main",
      "archived": true
    }
  ]
}
```

`"archived"` is optional; only `true` archives (see *Archived repos* above).

`"checks"` is optional here. It is what the quality gate runs for a Forge run that builds in the
repository, each `"argv"` without a shell; without it the gate refuses such a run. The add-repo skill
says how to write it, including the Windows limit on `.cmd` shims.

## Completion

Inspect the top-level ok flag and each repository result. Report failures and skips separately, and verify the requested branch or sync state for each target.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall