CF ContribFlow

Installation

Installation

ContribFlow is distributed through npm, source checkout, and release artifacts. The CLI is the primary product surface.

Prerequisites

  • Node.js 22 or newer
  • npm
  • Git
  • GitHub CLI (gh)
  • Docker, for sandboxed validation

Check GitHub auth:

gh auth status

Install From npm

Install the CLI:

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

Install the skills installer globally:

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

Or run the installer without a global install:

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

@freakpirate/contribflow-skills is an installer package. npm i @freakpirate/contribflow-skills inside a project only adds that installer to the project; it does not copy skills into an agent harness until you run contribflow-skills, cflow-skills, npx, or npm exec.

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

Run From Source

git clone https://github.com/FreakPirate/oss-contribution-agent.git
cd oss-contribution-agent
npm ci
npm run build:cli

Use either executable:

cflow --help
contribflow --help

contribflow is canonical. cflow is the short alias.

Install From A Local Release Tarball

Build and smoke-test a self-contained npm tarball:

npm run release:cli:smoke

The smoke test builds dist/release/freakpirate-contribflow-0.1.1.tgz, installs it into a disposable global prefix, and verifies:

  • cflow --help
  • contribflow next --json
  • cflow init --json

To build the tarball without the smoke install:

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

The release tarball package is named @freakpirate/contribflow. It bundles the internal @contribflow/* runtime packages, so those packages do not need to be published separately for the local tarball path.

Local Validation

make validate
npm run build:web

Distribution Status

Current:

  • npm CLI package @freakpirate/contribflow
  • npm skills package @freakpirate/contribflow-skills
  • source checkout
  • npm workspace bin links
  • self-contained local release tarball
  • agent skill folders under skills/
  • skill installer script under scripts/install-skills.sh

Planned:

  • versioned GitHub releases
  • deeper harness-specific install docs for Cursor-like harnesses and GitHub Actions

Source markdown: docs/INSTALLATION.md