@freakpirate/contribflow

v0.1.1

Published

9 days ago

CLI-first OSS contribution toolkit for agents and developers.

0High
0Medium
0Low

freakpirate

contribflow oss open-source contributions cli agents github codex claude-code

ContribFlow

ContribFlow is a CLI-first, agent-native toolkit for making small, high-quality open-source contributions.

Website · Autonomous agent quickstart · Usage guide · Roadmap

It helps developers and AI agents discover suitable issues, score contribution fit, plan a small change, validate the local workspace, and prepare a maintainer-friendly draft PR. Public GitHub actions always require explicit human approval.

Why ContribFlow

CLI-first workflow for terminals, Codex, Claude Code, Cursor-like harnesses, GitHub Actions, and future agents.
Stable JSON output contracts for agent orchestration.
Local gh CLI auth instead of dashboard OAuth for the CLI path.
Safety gates for stale issues, duplicate PRs, sensitive topics, validation failures, and public GitHub writes.
Optional dashboard/API surfaces that observe state but do not own the core workflow.

Install From npm

Install the CLI:

npm install -g @freakpirate/contribflow
cflow --help

Install the agent skills installer:

npm install -g @freakpirate/contribflow-skills
contribflow-skills --target codex --skill oss-contrib-orchestrator

Or install the orchestrator skill without a global package:

npx -y @freakpirate/contribflow-skills --target codex --skill oss-contrib-orchestrator

@freakpirate/contribflow-skills is an installer package. A plain project install such as npm i @freakpirate/contribflow-skills only adds the installer to that project; run its bin with npx, npm exec, or a global install to copy skills into Codex, Claude Code, or another harness directory.

Do not install the unscoped contribflow package from npm for this project; that public package name is not owned by this repository.

Install From Source

The source checkout remains useful for development and local release builds.

git clone https://github.com/FreakPirate/oss-contribution-agent.git
cd oss-contribution-agent
npm install
npm run build:cli
./node_modules/.bin/cflow --help

Local Release Tarball

For an install test outside the monorepo checkout:

npm run release:cli:smoke

To build the tarball only:

npm run release:cli
npm install -g ./dist/release/freakpirate-contribflow-0.1.1.tgz
cflow --help

The release package is named @freakpirate/contribflow and bundles the internal runtime packages.

To build CLI and skills release artifacts with checksums:

npm run release:artifacts

This builds npm tarballs for @freakpirate/contribflow and @freakpirate/contribflow-skills, plus a GitHub-release skills bundle and checksums. The release workflow uploads artifacts only. It does not publish to npm or create a public GitHub Release.

Prerequisites:

Node.js 22+
Git
GitHub CLI authenticated with gh auth status
Docker, only when running sandboxed validation

Quickstart

gh auth status
./node_modules/.bin/cflow init
./node_modules/.bin/cflow discover --lang go --topic observability --json
./node_modules/.bin/cflow score owner/repo#123 --json
./node_modules/.bin/cflow plan owner/repo#123 --json
./node_modules/.bin/cflow checkout owner/repo#123 --json
./node_modules/.bin/cflow validate --run --sandbox docker --json
./node_modules/.bin/cflow pr --draft --json

cflow pr --draft --json is a dry run. It must reach reviewGate.state: "ready_for_human_review" before approval. The public write path is cflow pr --draft --yes --json, and agents must not run it without explicit approval in the current session.

Autonomous Agent Setup

Paste this into Codex, Claude Code, or another local agent harness after cloning the repository:

Use this repository as a CLI-first OSS contribution toolkit.

1. Verify prerequisites with node --version, npm --version, git --version, gh auth status, and docker --version if sandboxed validation is needed.
2. Run npm install and npm run build:cli.
3. Use ./node_modules/.bin/cflow for all CLI commands.
4. Run ./node_modules/.bin/cflow init, then ask me for contribution preferences if config is missing or empty.
5. Discover candidates with ./node_modules/.bin/cflow discover --json, score the best candidates, and choose one small maintainer-friendly issue.
6. If discovery returns status: "blocked", do not retry blocked.failingQuery; report the blocked kind/scope, wait, or narrow --lang, --topic, or --type.
7. Generate a plan, checkout the workspace, inspect repository guidance, and validate locally.
8. Prepare only a draft PR dry run with cflow pr --draft --json.
9. Stop when next reports ready_for_human_review.
10. Hard stop before cflow pr --draft --yes --json or any other public GitHub write. Ask for explicit approval first.

See the full autonomous agent quickstart for the longer setup prompt and expected checkpoints.

Agent Skills

Skills are distributed through @freakpirate/contribflow-skills, source checkout files under skills/, and scripts/install-skills.sh.

npx -y @freakpirate/contribflow-skills --target codex --skill oss-contrib-orchestrator
npm run skills:list
npm run skills:install -- --target codex --skill all --dry-run
npm run skills:install -- --target codex --skill oss-contrib-orchestrator

The orchestrator skill is the recommended default for a fully automated local workflow. See docs/SKILL_DISTRIBUTION.md and docs/SKILLS.md.

Commands

cflow --help
cflow init
cflow status --json
cflow discover --json
cflow score owner/repo#123 --json
cflow plan owner/repo#123 --json
cflow checkout owner/repo#123 --json
cflow validate --json
cflow validate --run --sandbox docker --json
cflow pr --draft --json
cflow next --json

The canonical executable is contribflow; the short alias is cflow.

Documentation

Website documentation pages under site/docs/ are generated from markdown:

npm run build:site-docs

Safety Model

ContribFlow is not an AI spam bot. Its default posture is small changes, local validation, transparent AI assistance, and respect for maintainer guidelines.

Never:

open public PRs, post comments, or push branches without explicit approval
expose tokens in logs
bypass validation failures
mass-create contributions

Always:

keep PRs small
disclose AI assistance
inspect repository contribution guidance
prefer draft PRs
use sandboxed validation before public actions

Development

Run the full local validation path:

make validate
npm run build:web

Run TypeScript tests:

npm test

Start the optional local stack:

make dev

Services:

Web: http://localhost:3000
API healthcheck: http://localhost:8000/healthz
PostgreSQL: localhost:5432
Redis: localhost:6379

Repository Layout

.
├── apps/
│   ├── web/
│   └── api/
├── packages/
│   ├── core/
│   ├── cli/
│   ├── github-provider/
│   ├── agent-protocol/
│   ├── shared/
│   └── config/
├── workers/
│   └── agent-runner/
├── skills/
├── docs/
├── scripts/
├── site/
└── docker-compose.yml

Current Status

ContribFlow is in active MVP development on the CLI/core product path. The dashboard and API are secondary scaffolding until the optional dashboard observer milestone.

Implemented:

CLI/core architecture
issue discovery and scoring
contribution planning
local workspace checkout
patch artifact capture
validation detection and Docker sandbox execution
draft PR dry run and explicit approval path
static website and generated docs pages
source-distributed agent skills, including oss-contrib-orchestrator

See docs/ROADMAP.md for milestone order.

Optional Dashboard And API

The Next.js dashboard and FastAPI service remain in the repository as secondary surfaces. CLI v0 uses local GitHub CLI auth, while GitHub OAuth is only for the dashboard/API path. See docs/AUTH.md for local OAuth setup.

License

ContribFlow is released under the MIT License.