Autonomous Agent Quickstart

ContribFlow can be driven by an AI agent from setup through draft PR preview.

Autonomous means the agent may run local and non-public workflow steps without waiting between every command. It does not mean the agent may push branches, open pull requests, post comments, or take other public GitHub actions without explicit human approval.

Journey 1: Via Your Agent

Copy this prompt into Codex, Claude Code, Cursor, or another coding agent from a local checkout of this repository.

You are my autonomous OSS contribution agent.

Use ContribFlow as the source of truth for the workflow.

Goal:
- Find one small, maintainer-friendly open-source contribution.
- Score it for fit and risk.
- Generate a plan.
- Check out the workspace.
- Implement the smallest useful patch.
- Capture the diff artifact.
- Run validation safely.
- Prepare a draft PR dry-run.
- Stop before any public GitHub write and ask for my explicit approval.

Setup:
1. Verify prerequisites:
   - gh auth status
   - docker --version
   - node --version
2. If cflow is unavailable, run:
   - npm ci
   - npm run build:cli
   - npm run cflow -- --help
3. Initialize ContribFlow:
   - cflow init
   - cflow status --json

Operating loop:
1. Run cflow next --json.
2. Follow only non-public recommended commands. JSON `recommendedCommand` values use canonical `contribflow`; execute them exactly when present.
3. Parse JSON outputs. Do not scrape human text.
4. Discover candidates with cflow discover --json.
5. If discovery returns status: "blocked", do not retry blocked.failingQuery. Report the blocked kind and scope, run the recommended quota inspection command if useful, then wait or narrow --lang, --topic, or --type.
6. Score promising candidates with cflow score owner/repo#123 --json.
7. Prefer candidates with score >= 60, low or medium risk, no high duplicate risk, no security-sensitive flag, clear scope, and small expected patch.
8. Skip unclear, duplicate-likely, stale, security-sensitive, or broad issues unless I explicitly accept the risk.
9. For the selected issue, run:
   - cflow plan owner/repo#123 --json
   - cflow checkout owner/repo#123 --json
10. Inspect contribution guidelines and implement the smallest useful patch.
11. Run:
    - cflow diff --json
    - cflow validate --json
    - cflow validate --run --sandbox docker --json
    - cflow pr --draft --json
12. Run cflow next --json and stop if state is ready_for_human_review.

Hard stop:
- Never run cflow pr --draft --yes --json unless I explicitly approve that exact public GitHub action.
- Never push branches, open PRs, post comments, or make public repository changes without my explicit approval.

Before asking for approval, report:
- selected issue
- score and risk breakdown
- changed files
- validation result
- review gate state and failed checks, if any
- PR title and body summary
- exact public commands that would run

Journey 2: By Hand

Run the same workflow directly from the terminal:

gh auth status
docker --version
node --version
npm ci
npm run build:cli
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 diff --json
cflow validate --json
cflow validate --run --sandbox docker --json
cflow pr --draft --json
cflow next --json

Install The Orchestrator Skill

For Codex-style skill directories:

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

For a custom harness directory:

npm run skills:install -- --dest /path/to/skills --skill oss-contrib-orchestrator

The skill teaches the agent to run cflow next --json, follow non-public recommendations, and stop at approval gates.

Expected Agent Stop Points

The agent should stop and ask when:

• GitHub CLI auth is missing
• Docker is unavailable for sandbox validation
• discovery returns status: "blocked" for GitHub search throttling
• validation fails
• duplicate PR risk is high
• security-sensitive risk is true
• patch size exceeds configured limits
• cflow next --json returns requiresHumanApproval: true
• the next step would write to public GitHub

Good Autonomous Outcomes

A good agent run ends with:

• one selected issue
• a score result and risk explanation
• a contribution plan
• a local workspace
• a small patch artifact
• sandbox validation output
• a draft PR preview
• a clear approval request before public GitHub writes