CLI-first · agent-native · OSS-safe

ContribFlow

A local command line workflow for agents and developers that discovers OSS issues, scores contribution risk, plans small patches, validates in Docker, and prepares draft PRs only after explicit approval.

Start with cflow View GitHub

JSON contracts Local gh auth Draft PR gate

agent-run.local safe mode

$ cflow next --json
{
  "state": "ready_for_discovery",
  "nextAction": "discover",
  "recommendedCommand":
    "cflow discover --json"
}

$ cflow score \
  vercel/next.js#73902 --json
{
  "score": 72,
  "riskLevel": "medium",
  "duplicateRisk": "low",
  "recommendation": "Plan small patch"
}

01 discover open issues

02 score risk + fit

03 plan small patch

04 validate docker sandbox

05 draft PR approval gate

primary interface terminal

machine surface stable JSON

public action policy human approval

runner posture sandbox first

Quickstart

Start via your agent or by hand

Journey 1

Via your autonomous agent

Paste this into Codex, Claude Code, Cursor, or another coding agent from a local checkout. The agent can run the safe local workflow and must stop before public GitHub writes.

You are my autonomous OSS contribution agent.

Use ContribFlow as the source of truth.

Verify gh auth, Docker, and Node. If cflow is unavailable, run npm ci and npm run build:cli.

Run cflow init and cflow next --json. Follow only non-public recommended commands. Discover and score issues, prefer score >= 60 with low/medium risk, plan before checkout, implement the smallest useful patch, capture diff, run Docker sandbox validation, and prepare cflow pr --draft --json.

Hard stop: never run cflow pr --draft --yes --json, push branches, open PRs, post comments, or make public GitHub changes until I explicitly approve the exact public action.

Read agent guide

Journey 2

By hand

Run the same workflow yourself from the terminal with explicit JSON outputs.

gh auth status
npm ci && npm run build:cli
cflow init
cflow discover --lang go --topic observability --json
cflow score owner/repo#123 --json
cflow plan owner/repo#123 --json
cflow validate --run --sandbox docker --json
cflow pr --draft --json

Workflow

Built for agent harnesses and maintainer trust

Find viable issues

Use GitHub issue search, repository metadata, duplicate checks, stale flags, and preference filters.

judge

Score before touching code

Explain fit, scope, duplicate risk, security sensitivity, and likely maintainer friendliness.

patch

Keep changes small

Plan first, checkout locally, capture diffs, and keep work bounded by changed-file and line limits.

ship

Validate, then ask

Run sandboxed validation and produce a draft PR preview before any public GitHub write happens.

Agent skills

Install the orchestrator skill

The orchestrator skill drives `cflow next --json`, follows non-public recommendations, summarizes risk, and stops before draft PR creation until the human approves the exact public action.

npm run skills:list
npm run skills:install -- --target codex \
  --skill oss-contrib-orchestrator

Documentation

Read the operating manuals

Agent Start Autonomous workflow prompt Install Source checkout and CLI setup Use End-to-end cflow workflow Protocol JSON contracts for harnesses Skills Harness installation path Security Guardrails and approval gates Repo Public GitHub project