jupes/agent-forge-harness / .agents/skills/syncing-repos
syncing-repos
VerifiedClone, inspect, refresh, reset, or manage branches across registered Forge sub-repos. Use for single-repo or multi-repo synchronization.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.8 KB |
| scripts/repo-select.ts | script | 1.2 KB |
| scripts/repo.ts | script | 8.1 KB |
SKILL.md
View on GitHub---
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |