CF ContribFlow

Publishing

Publishing Plan

ContribFlow is installable from npm and source. Publishing should preserve the CLI-first product contract and agent-safe defaults.

The npm publishing decision record is ADR 0002.

Current Delivery

  • Public GitHub repository
  • Source checkout
  • npm workspace bin:
  • contribflow
  • cflow
  • The public unscoped npm package name contribflow is occupied by another project (contribflow@0.3.7, verified on 2026-06-05), so public CLI publishing should use a scoped package name or another verified package name
  • npm CLI package name @freakpirate/contribflow
  • Published npm CLI version @freakpirate/contribflow@0.1.1
  • Self-contained release tarball at dist/release/freakpirate-contribflow-0.1.1.tgz
  • Internal runtime packages are bundled in the release tarball and are not published separately
  • Local npm publishing auth is configured as freakpirate as of 2026-06-05
  • Static website in site/
  • GitHub Pages workflow deployment
  • Published website at https://freakpirate.github.io/oss-contribution-agent/
  • Published GitHub Release v0.1.0 at https://github.com/FreakPirate/oss-contribution-agent/releases/tag/v0.1.0
  • Harness skills under skills/
  • Skill installer script
  • Skills npm package name @freakpirate/contribflow-skills
  • Published npm skills version @freakpirate/contribflow-skills@0.1.1
  • Skills npm tarball at dist/release/freakpirate-contribflow-skills-0.1.1.tgz
  • GitHub-release skills bundle at dist/release/contribflow-skills-0.1.1.tar.gz

Install from npm:

npm install -g @freakpirate/contribflow
npm install -g @freakpirate/contribflow-skills

Website Publishing

The repository is public and GitHub Pages is enabled with workflow publishing.

To rebuild the site:

  1. Update files in site/.
  2. Update markdown files in docs/ if documentation changed.
  3. Run npm run build:site-docs.
  4. Push to main, or run the Pages workflow manually.
  5. Confirm the published URL from the workflow environment output.

CLI Release Tarball

Build a self-contained tarball:

npm run release:cli

Build and smoke-test the tarball from a disposable global install:

npm run release:cli:smoke

The smoke test verifies:

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

Install the built tarball manually:

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

This is a local/release-artifact path. The public npm package uses the same package contents.

Release Artifacts Workflow

Build all release artifacts locally:

npm run release:artifacts

This produces:

  • dist/release/freakpirate-contribflow-0.1.1.tgz
  • dist/release/freakpirate-contribflow-skills-0.1.1.tgz
  • dist/release/contribflow-skills-0.1.1.tar.gz
  • dist/release/SHA256SUMS
  • dist/release/release-artifacts.json

The release artifact workflow is .github/workflows/release-artifacts.yml. It runs on:

  • manual workflow_dispatch
  • version tags matching v*

The workflow:

  1. installs dependencies
  2. builds and smoke-tests the CLI tarball
  3. validates skill installer behavior
  4. packages and smoke-tests the skills npm tarball
  5. verifies SHA-256 checksums
  6. uploads artifacts with actions/upload-artifact

It does not publish to npm and does not create a GitHub Release. Creating a public release or npm package requires explicit manual approval.

Near-Term Delivery

  1. Revoke the one-time release npm token after publication.
  2. Decide whether to create signed GitHub release artifacts in addition to SHA-256 checksums.
  3. Add deeper harness-specific install docs for Cursor-like harnesses and GitHub Actions.
  4. Evaluate trusted publishing for future releases.

Skill Publishing

The orchestrator skill is source-distributed today:

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

Release artifacts include an npm tarball for the skills package:

npm install -g ./dist/release/freakpirate-contribflow-skills-0.1.1.tgz
contribflow-skills --target codex --skill oss-contrib-orchestrator

The public one-shot install path is:

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

The persistent global install path is:

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

The package also exposes cflow-skills as a short alias. A plain project install such as npm i @freakpirate/contribflow-skills only installs the package locally; run the bin with npm exec contribflow-skills -- --target codex --skill oss-contrib-orchestrator to copy skills. skills/manifest.json remains the machine-readable catalog for harness installers.

npm Publishing Guardrail

No workflow may publish to npm by default.

Before publishing is added or run:

  1. confirm explicit human approval in the current session
  2. confirm npm whoami
  3. confirm the exact package name and scope
  4. confirm public package visibility is intended
  5. run make validate
  6. run npm run release:artifacts
  7. inspect release artifacts and checksums
  8. run an npm dry-run publish first
  9. document the published version and checksums

Release Checklist

Before publishing:

  • make validate
  • npm run build:web
  • npm run release:artifacts
  • CLI smoke test for cflow --help
  • live local dry-run through cflow pr --draft --json
  • no secrets in artifacts
  • changelog entry
  • version bump
  • GitHub release notes

Safety Requirements

Published versions must keep:

  • JSON contracts stable
  • PR creation draft-only by default
  • --yes required for public GitHub writes
  • Docker sandbox validation separate from detection-only validation
  • AI disclosure in PR body previews

Source markdown: docs/PUBLISHING.md