CF ContribFlow

Roadmap

Roadmap

ContribFlow is now CLI-first. The dashboard/API work from Milestones 0-4 is preserved as secondary scaffolding, but pending product development is sequenced around the CLI/core engine.

Milestone 0: Documentation and Repo Setup

Status: Complete

Deliverables:

  • README
  • PRD
  • Architecture doc
  • Roadmap
  • Security doc
  • Progress log
  • AGENTS.md
  • CI skeleton

Acceptance:

  • Repository exists on GitHub.
  • Initial commit is pushed.
  • Documentation validation runs locally and in CI.

Milestone 1: App Skeleton

Status: Complete

Deliverables:

  • Next.js web app shell
  • FastAPI service shell
  • Healthcheck endpoint
  • Shared types package
  • Docker Compose services
  • Makefile or task runner

Acceptance:

  • One command starts local app.
  • Frontend loads.
  • Backend healthcheck works.

Milestone 2: GitHub Auth

Status: Complete

Deliverables:

  • GitHub OAuth login
  • Session handling
  • User persistence
  • Logout
  • Dashboard user card

Acceptance:

  • User can log in.
  • User profile is visible.
  • Auth flow is documented.

Milestone 3: Preferences

Status: Complete

Deliverables:

  • Preference form
  • Language, topic, and contribution type selection
  • Persistence
  • Validation

Acceptance:

  • User can save preferences.
  • Preferences influence issue discovery query.

Milestone 4: Issue Discovery

Status: Complete

Deliverables:

  • GitHub issue search client
  • Repo metadata fetch
  • Candidate storage
  • Duplicate PR check
  • Recommended issues page

Acceptance:

  • User sees recommended OSS issues.
  • Stale and duplicate candidates are flagged.

Milestone 5: Issue Scoring

Status: Replaced by Milestone 5A and 5B

Milestone 5A: CLI-First Pivot Foundation

Status: Complete

Deliverables:

  • Pivot plan
  • CLI spec
  • Agent protocol spec
  • Core package
  • CLI package
  • GitHub provider package
  • Agent protocol package
  • Initial commands:
  • contribflow --help
  • contribflow init
  • contribflow status --json
  • contribflow discover --json
  • contribflow score owner/repo#123 --json
  • Agent skill docs

Acceptance:

  • README states CLI-first direction.
  • PRD and architecture define CLI/core as primary.
  • Initial CLI commands run locally.
  • CLI uses local gh auth status.
  • CI passes.

Milestone 5B: Issue Scoring Engine

Status: Complete

Deliverables:

  • Scoring engine
  • Score breakdown
  • Unit tests
  • Recommendation labels

Acceptance:

  • Every issue has score and explanation.
  • Poor candidates are filtered.
  • CLI/core scoring is the product source of truth.
  • Dashboard/API scoring remains secondary scaffolding until the optional dashboard observer milestone.

Milestone 6: Contribution Task Flow

CLI-first name: Contribution Planning

Status: Complete

Deliverables:

  • contribflow plan owner/repo#123 --json
  • plan JSON contract
  • risk assessment
  • test plan
  • user approval guidance

Acceptance:

  • User or agent can generate a contribution plan from the CLI.
  • Plan is machine-readable and maintainer-friendly.

Milestone 7: Agent Runner Prototype

CLI-first name: Local Workspace Runner

Status: Complete

Deliverables:

  • contribflow checkout owner/repo#123
  • local workspace creation
  • clone public repo
  • branch creation
  • command log capture

Acceptance:

  • CLI can create a local isolated workspace.
  • Command logs are captured in .contribflow.

Milestone 8: Patch Artifact

Status: Complete

Deliverables:

  • CLI diff capture
  • Diff capture
  • Changed files summary
  • patch artifact JSON

Acceptance:

  • CLI can produce a diff artifact.
  • Agents can inspect changed files from JSON.

Milestone 9: Validation

Status: Complete

Deliverables:

  • contribflow validate --json
  • Test command detection
  • Lint/typecheck command detection
  • Sandboxed command execution
  • Validation result summary

Acceptance:

  • Validation results block unsafe PR by default.
  • Default validation detects commands and blocks PR creation unless sandboxed execution is explicitly requested.
  • Docker sandbox validation executes detected commands with network disabled, resource limits, and redacted output.

Milestone 10: Draft PR Creation

Status: Complete

Deliverables:

  • contribflow pr --draft
  • dry-run PR preview
  • explicit --yes approval gate
  • Fork repo
  • Create branch
  • Commit patch
  • Push branch
  • Open draft PR
  • Link PR to task

Acceptance:

  • Dry-run PR preview performs no GitHub writes.
  • User approval opens draft PR.
  • PR body uses platform template.
  • Task stores PR URL.

Milestone 10A: Next Action Command

Status: Complete

Deliverables:

  • contribflow next --json
  • Workflow state summarizer
  • Next recommended CLI command
  • Human approval flag

Acceptance:

  • next reads local CLI/core state.
  • next performs no writes.
  • next returns stable JSON for agents.

Milestone 10B: Documentation, Site, And Skill Delivery

Status: Complete

Deliverables:

  • usage guide
  • installation guide
  • publishing plan
  • skill distribution guide
  • static GitHub Pages site
  • skill install script
  • orchestrator skill

Acceptance:

  • New users can run the CLI from source.
  • Harnesses have a documented skill installation path.
  • The orchestrator skill can drive the CLI workflow through PR dry-run.
  • Static website deploys from site/ through GitHub Pages.

Later Milestones

  • Optional dashboard observer
  • PR monitoring
  • Review response loop
  • Contributor portfolio
  • Maintainer beta
  • Team controls

Source markdown: docs/ROADMAP.md