CF ContribFlow

Usage Guide

Usage Guide

ContribFlow helps agents and developers find, evaluate, plan, validate, and prepare small OSS contributions from the terminal.

Agent-facing JSON uses contribflow in recommendedCommand values. Agents should execute the returned command exactly. Humans can use cflow as the short alias for typed examples.

First Run

gh auth status
cflow init
cflow status --json

cflow init creates:

.contribflow/config.json

Discover Candidates

cflow discover --lang go --topic observability --limit 5 --json

Discovery uses public GitHub issue search through the local GitHub CLI auth. Local preferences in .contribflow/config.json are used as a personal contribution profile for ranking candidates.

If GitHub search is throttled, cflow discover --json returns status: "blocked" with blocked.kind, blocked.scope, blocked.failingQuery, retry guidance, and recommendedCommand: "gh api rate_limit --jq '.resources.search'". Do not immediately retry the same failing query. Wait for GitHub search protection to cool down or rerun discovery with narrower --lang, --topic, or --type flags.

Prefer candidates with:

  • clear issue body
  • focused scope
  • maintainer-friendly labels such as help wanted, good first issue, docs, tests, bug, or tooling
  • low duplicate PR risk
  • no security-sensitive terms
  • no dependency automation dashboard signals
  • recent maintainer activity

Score One Issue

cflow score owner/repo#123 --json

The score output includes:

  • score
  • score band
  • recommendation
  • risk flags
  • duplicate evidence
  • score breakdown
  • rule explanations

The score breakdown includes profileFit, which explains how well the issue matches your configured languages, topics, contribution types, and difficulty.

Avoid candidates marked Duplicate likely, Avoid, or high risk unless a human explicitly accepts the risk.

Generate A Contribution Plan

cflow plan owner/repo#123 --json

The plan gives:

  • proposed minimal fix
  • likely files
  • detected repository guidance files
  • likely validation commands
  • test plan
  • PR title/body guidance
  • stop conditions
  • assumptions
  • questions
  • next recommended command

Use the plan before checkout or code changes. A plan should be treated as a pre-checkout hypothesis; re-check repository guidance after checkout before editing.

Checkout A Workspace

cflow checkout owner/repo#123 --json

This creates or reuses:

.contribflow/workspaces/<owner>-<repo>-<issue>

Checkout may run git clone, git checkout, and git status. It must not execute target repository code. When a repository declares submodules, checkout reports their status and a safe git submodule update --init --recursive command. Draft PR dry-runs are blocked until declared submodules are initialized.

Checkout JSON includes controllerWorkspacePath and runFrom. Stateful commands such as diff, validate, pr, and next can run from that controller root or from inside a managed checkout under .contribflow/workspaces/<slug>.

Capture A Patch Artifact

After editing the workspace:

cflow diff owner/repo#123 --json

After checkout, the issue reference is optional:

cflow diff --json

This writes:

.contribflow/artifacts/patch-<owner>-<repo>-<issue>.json

The artifact contains changed files, a unified diff, risk flags for sensitive files or duplicate content, and the next action.

Validate

Detection-only validation:

cflow validate --json

This detects likely dependency setup and validation commands, then blocks PR creation by default.

Sandboxed validation:

cflow validate --run --sandbox docker --json

The Docker sandbox uses a two-phase flow:

  • dependency setup runs first when a supported lockfile is present
  • validation commands run after setup with network disabled
  • both phases mount only the active workspace
  • changed files under nested packages add scoped validation commands with workingDirectory
  • applies CPU, memory, process, capability, and no-new-privileges limits
  • never passes host GitHub credentials or secrets into the container
  • redacts and truncates command output

Supported setup detection currently includes npm ci --ignore-scripts, pnpm install --frozen-lockfile --ignore-scripts, YARN_ENABLE_SCRIPTS=false yarn install --immutable, and go mod download. Package-manager setup is blocked without the expected lockfile.

For Go repositories, ContribFlow reads toolchain goX.Y or go X.Y from go.mod and uses the matching golang:X.Y-bookworm sandbox image for Go setup and Makefile validation commands.

For repositories that need native OS packages, use a trusted prebuilt image:

cflow validate --run --sandbox docker --sandbox-image ghcr.io/acme/project-validation:go1.26 --json

If validation fails on common missing headers, JSON output may include suggestedSystemPackages, for example ["libx11-dev"]. Treat this as a hint for building a custom validation image; ContribFlow does not run arbitrary setup commands from the host.

Prepare A Draft PR

Dry-run only:

cflow pr --draft --json

This performs no GitHub writes. It returns:

  • title
  • body preview
  • changed files
  • validation status
  • planned commands
  • review gate checks
  • human approval requirement

The dry run only reaches reviewGate.state: "ready_for_human_review" when the patch artifact exists, patch size is within config limits, sensitive and duplicate-content risk flags are clean, Docker sandbox validation passed, planned public commands are listed, and the PR body includes AI disclosure.

Approved write path:

cflow pr --draft --yes --json

Run this only after explicit human approval. It may fork, commit, push, and open a draft PR. The command is blocked unless a prior dry run for the same workspace reached ready_for_human_review.

Ask For The Next Step

cflow next --json

next reads local state and recommends one CLI action. It performs no writes.

Common states:

  • needs_init
  • needs_github_auth
  • ready_for_discovery
  • ready_for_diff
  • needs_validation
  • ready_for_pr_dry_run
  • ready_for_human_review
  • pr_review_blocked
  • done
  1. Run cflow next --json.
  2. Execute the recommended non-public command.
  3. Parse JSON, not human text.
  4. Stop on high-risk candidates.
  5. Keep patches small.
  6. Run sandbox validation.
  7. Generate PR dry-run.
  8. Stop on ready_for_human_review.
  9. Ask before cflow pr --draft --yes --json.

Source markdown: docs/USAGE.md