repo-flow

repo-flow is a Linux x64 command-line tool and Pi package for moving code safely between an authoritative downstream repository and a Git upstream. It provides deterministic inbound synchronization, guarded backflow artifacts, local upstream-PR verification, and machine-readable evidence.

The current adapter targets AGS-authoritative downstream repositories through ags-cli --json. Git remains the authority for commits and refs. Upstream review stays Git-only and does not require AGS credentials.

Install

The public npm package requires Bun 1.3.14 or newer and does not bundle or redistribute the Bun standalone runtime. Registry latest remains 0.1.4 until the 0.1.5 candidate in this source is published and read back; do not treat package.json as registry evidence.

bun --version
npm install --global @yoyooyoooyoooo/[email protected]
repo-flow --version --json

To load the bundled Agent Skills in Pi:

pi install npm:@yoyooyoooyoooo/[email protected]

Pi package installation does not promise to add package bins to the Agent shell PATH. Each bundled Skill therefore resolves its own package root from the absolute SKILL.md location supplied by Pi and invokes that root's dist/repo-flow.js with Bun. It does not search PATH or fall back to a global repo-flow.

The npm package contains a Bun-targeted JavaScript entry and three Skills:

upstream-sync
merdi-backflow-submit
upstream-backflow-pr

Internal standalone binaries, release manifests, rollback evidence, and production deployment are maintained separately and are not part of the npm package or npm publish gate.

Repository Profile

Run commands from a repository root containing .repo-flow.yaml. A strict portable profile has this shape:

schema: repo-flow.profile.v1
repository: owner/downstream
refs:
  main: main
  upstream_ruler: upstream-main
  upstream_absorbed: sync/upstream-absorbed
  upstream_active: sync/upstream/active
backflow:
  product_paths:
    - src/
  downstream_only_paths:
    - .agents/

Existing schema-1 deployments remain read-only by default. A repository owner may explicitly promote that legacy profile for the TypeScript writer by adding:

runtime:
  writer: repo-flow

Promotion is fail-closed: the writer value must be exact, the repository refs and Backflow policy must validate, and secrets or credential-shaped keys are rejected. Host credentials, provider URLs, tokens, and machine paths do not belong in the portable profile consumed by the new writer.

Commands

The accepted long-term Agent-facing surface is:

repo-flow --version --json
repo-flow status --json
repo-flow sync run --json
repo-flow backflow create --ags-pr <number> --json
repo-flow backflow consume <artifact> --json
repo-flow backflow continue [--allow-empty-resolution] --json
repo-flow backflow status --json
repo-flow upstream-pr verify --json

The 0.1.5 source candidate routes only the command closure above. It is not an installable registry fact until publish/readback. Compatibility/conformance primitives, backflow reconcile, qualification faults, and evidence tooling are available only from the separate internal/test composition and are not part of the npm public surface. Removed public routes fail with the structured public_route_removed envelope. See the end-to-end operating model and ADR 0002.

Public observation is fail-closed but diagnostic: a stopped workflow returns a stable phase/error, first_wrong_state, retained Unit/Batch/Q/PR/fence identity, and one next_action. Late AGS failures do not erase verified Git facts. Inbound maps only OPEN to review, MERGED to resume closeout, and rejects CLOSED without merge or unknown states. Backflow keeps read failures and protocol damage distinct from a healthy q_remote; durable pending output exposes non-sensitive fence evidence but never the claim token, while a visible PR without a fence is sent through continue_backflow to bind the existing exact PR before it can be called ready.

Inbound

sync run consumes the mirrored upstream ruler, allocates or resumes one frozen unit, derives exact coverage, acquires a unit + candidate Git-CAS fence, publishes at most one downstream PR, and closes only after exact readback. An unresolved create claim is observed indefinitely rather than taken over on a timer; while that fence exists, accepted-main movement cannot rebuild or move the candidate before the original claim is settled, and a PR first observed as merged is bound by number before closeout. Initial cursor advancement requires accepted main == candidate; once the cursor reaches the frozen target, that durable fact permits a Git-only active-release retry without re-reading AGS or revalidating a later ruler/main. It does not accept environment, deployment, unit, SHA, or coverage arguments from the operator.

Backflow

backflow create derives one checksummed Git-bundle artifact from an accepted downstream PR. backflow consume runs in a controlled upstream workspace and creates or resumes the canonical single-parent Q branch. Q PR publication first acquires a per-Batch Batch + current Q Git-CAS fence and binds the exact AGS PR number after readback; a same-Batch Q rebuild can migrate that binding only when the same PR number shows the new head. An unresolved claim is reported as pr_create_pending and never triggers a timed second create. The artifact and its verified handoff bind the source PR, source range, upstream anchor, Batch identity, and checksum.

Upstream Review

upstream-pr verify uses only the current Git repository, base/head refs, tracked diff, and Q commit structure. It does not construct an AGS adapter or read a downstream profile. Repository-specific tests and the decision to create or merge a real upstream PR remain with the upstream owner.

Security Boundary

• System Git performs all object and ref operations.
• Downstream AGS facts come from the installed ags-cli JSON interface.
• RepoFlow does not read AGS secret files or Forgejo credentials.
• Unknown external effects require exact readback; commands do not blind-retry writes.
• The npm package has no install, preinstall, or postinstall lifecycle scripts.
• The npm tarball does not contain a Bun standalone binary; Bun is an explicit runtime prerequisite.
• Pi Skills can instruct an agent to run commands with the user's authority; review them before enabling the package.

Product And Architecture

Start with the end-to-end operating model for background, roles, user stories, both code-flow directions, authority boundaries, delivery stages, and claim limits. Current fact writers live in SSoT; runtime boundaries live in Architecture.

Development

The canonical source uses Bun and TypeScript:

bun install --frozen-lockfile
bun run check
bun run test:temp-lifecycle
bun run package:candidate
bun run test:package-install

Conformance uses isolated repositories and the same compiled binary. Fixture runs and simulated upstream PRs prove only their listed properties; they do not claim a real upstream provider effect.

License

MIT. See LICENSE.