Patchwork OS — Summary

One-line description

Patchwork is a Python CLI and framework for automated code patching via composable AI-powered pipelines called "patchflows," targeting CI/CD integration for security fixes, dependency upgrades, and documentation generation.

Classification

• Archetype: automated-pipeline-runner (closest to: none of the five seed archetypes — independent Python CLI, not Claude Code or IDE-centric)
• Primary use case: CI/CD automation for code quality tasks (security patching, PR review, docstring generation, dependency updates)
• Methodology fit: not a coding methodology; patchflows are standalone automation pipelines, not agent guidance frameworks

Key facts

Core abstractions

• Step: reusable atomic Python class; 46+ built-in (CallLLM, CreatePR, ScanSemgrep, ModifyCode, ExtractDiff, etc.)
• Patchflow: Python class that chains Steps + YAML prompt templates into a named automation pipeline
• Prompt template: JSON/YAML files with {{variable}} substitution; one per patchflow, stored under patchwork/patchflows/<Name>/

Built-in patchflows (11)

AutoFix, DependencyUpgrade, GenerateCodeUsageExample, GenerateDiagram, GenerateDocstring, GenerateREADME, GenerateUnitTests, LogAnalysis, PRReview, ResolveIssue, SonarFix

Relationship to spec-driven development

Patchwork is not a spec-driven development framework. It does not generate code from specifications, manage agent context, or orchestrate developer workflows. It is a code automation tool that uses LLMs to patch, review, and document existing codebases, typically invoked from CI pipelines (GitHub Actions, etc.).

Included in this research batch because it was listed as a "Reddit-confirmed alt-SDD" reference — the Reddit context appears to be users describing automated code quality pipelines as a form of spec-driven maintenance.

Quality tier

Tier A — comprehensive: 1558-star active project with full Python source, pypi package, detailed docs.

Patchwork OS — Origin and Philosophy

Origin

Patchwork is maintained by patched-codes (patched.codes). The project began as tooling to automate security vulnerability fixes — specifically, to take scanner output and produce a PR with the fix applied. It evolved into a general-purpose code patching framework.

The dual license (AGPL-3.0 for the framework + Apache-2.0 for individual steps and patchflows) is explicitly designed to allow reuse of the building blocks in commercial products while keeping the full framework open.

Core thesis

From the README:

"Patchwork automates development tasks using LLMs. You can run a patchflow locally, or via GitHub Actions."

The philosophy is pipeline composition: complex code automation tasks decompose into sequences of atomic Steps. Each Step is a reusable Python class; a Patchflow wires them together. This makes automation tasks composable, testable, and version-controlled.

Primary target workflows

1. Security patching (AutoFix): ingest vulnerability scanner output → LLM generates fix → commit + PR
2. Dependency upgrades (DependencyUpgrade): identify outdated deps → LLM generates upgrade PR
3. Documentation (GenerateDocstring, GenerateREADME, GenerateDiagram): generate missing docs for existing code
4. PR review (PRReview): LLM-assisted code review with structured comments
5. Unit test generation (GenerateUnitTests): generate tests for uncovered code
6. Log analysis (LogAnalysis): parse and summarize application logs
7. Issue resolution (ResolveIssue): attempt to resolve a GitHub issue automatically

Usage context

Patchwork runs:

• Locally: developer invokes patchwork <PatchflowName> from terminal
• CI/CD: GitHub Actions workflow calls patchwork step; outputs a PR
• Programmatically: Python code imports patchflow classes directly

Relationship to coding agents / AI IDEs

Patchwork is not an AI coding assistant. It does not run inside an IDE and does not assist with interactive development. It operates on code repositories as a batch process, typically triggered by external events (vulnerability scan, PR open, scheduled CI run).

Patchwork OS — Architecture

Distribution

• Type: Python package (patchwork-cli on PyPI)
• Binary: patchwork
• Version analyzed: 0.0.124
• Source: https://github.com/patched-codes/patchwork
• License: AGPL-3.0 (framework) / Apache-2.0 (steps + patchflows)

Install

pip install patchwork-cli
patchwork --help

Runtime requirements

• Python 3.x
• An LLM API key (OpenAI, Anthropic, Groq, Google, HuggingFace, or local via Ollama/llama.cpp)
• Git repository (most patchflows operate on a local checkout)

Directory structure

patchwork/
├── patchflows/               # 11 built-in patchflows
│   ├── AutoFix/
│   │   ├── AutoFix.py        # Patchflow Python class
│   │   └── AutoFix.json      # Prompt template
│   ├── PRReview/
│   │   ├── PRReview.py
│   │   └── PRReview.json
│   ├── GenerateDocstring/
│   ├── GenerateREADME/
│   ├── GenerateUnitTests/
│   ├── DependencyUpgrade/
│   ├── GenerateCodeUsageExample/
│   ├── GenerateDiagram/
│   ├── LogAnalysis/
│   ├── ResolveIssue/
│   └── SonarFix/
├── steps/                    # 46+ reusable Step classes
│   ├── CallLLM/
│   ├── CreatePR/
│   ├── CommitChanges/
│   ├── ExtractCode/
│   ├── ExtractDiff/
│   ├── ModifyCode/
│   ├── PreparePrompt/
│   ├── ScanSemgrep/
│   ├── ScanDepscan/
│   └── ...
├── common/                   # Shared utilities, LLM client abstraction
└── app.py                    # CLI entry point

Execution model

CLI invocation
  → resolve patchflow class
  → instantiate with config dict
  → run() → sequential Step execution
  → each Step: run() → modifies shared context dict → pass to next Step
  → final Step: CreatePR / CommitChanges / output report

Context is a mutable Python dict passed through the Step chain. Steps read and write keys in this dict. There is no async execution or parallel step branching.

LLM abstraction

patchwork/common/ provides a unified LLM client that routes to:

• OpenAI / Azure OpenAI (default: gpt-4o)
• Anthropic
• Google Gemini
• Groq
• HuggingFace Inference API
• Ollama (local)
• llama.cpp (local)
• Any OpenAI-compatible endpoint

Provider is selected via config key model (format: provider/model-name or bare model name for OpenAI).

GitHub Actions integration

- uses: patched-codes/patchwork@v0.0.124
  with:
    patchflow: AutoFix
    openai_api_key: ${{ secrets.OPENAI_API_KEY }}

Patchwork ships a GitHub Action wrapper; this is the primary CI/CD integration path.

Patchwork OS — Components

Steps (46+)

Steps are the atomic building blocks. Each is a Python class with a run() method that reads from and writes to a shared context dict.

LLM interaction steps

Code modification steps

SCM / PR steps

Security scanning steps

Analysis / utility steps

(46+ total; above is a representative subset)

Built-in patchflows (11)

Prompt templates

Each patchflow ships a JSON prompt template alongside its Python class:

patchwork/patchflows/AutoFix/AutoFix.json
patchwork/patchflows/PRReview/PRReview.json
...

Template format:

[
  {
    "role": "system",
    "content": "You are a senior software engineer..."
  },
  {
    "role": "user",
    "content": "Fix the following vulnerability:\n{{vulnerability_details}}\n\nCode:\n{{source_code}}"
  }
]

Variables use {{variable_name}} syntax. PreparePrompt renders templates against the context dict.

Configuration

All patchflows accept configuration via:

1. CLI flags: patchwork AutoFix --openai_api_key=... --github_api_key=...
2. YAML config file: patchwork AutoFix --config=my-config.yaml
3. Environment variables: OPENAI_API_KEY, GITHUB_API_KEY, etc.
4. .patchwork.yaml in the repository root: project-level defaults

Patchwork OS — Uniqueness & Differentiation

Primary differentiator: composable step library as the unit of reuse

Most code automation tools are monolithic — they do one thing (e.g., "review PRs"). Patchwork's architecture separates the reusable primitives (Steps) from the composed automation (Patchflows). A new automation task is built by wiring existing Steps; adding a new scanner is a new Step that slots into any patchflow.

The 46+ built-in Steps cover the full lifecycle: scan → analyze → generate → apply → commit → create PR → comment. Users rarely need to write custom Steps; they write custom Patchflows that wire existing ones.

CI/CD-first design

Patchwork is designed to run headlessly in CI pipelines, not interactively. The primary trigger is a scheduled GitHub Action, not a developer command. This positions it as infrastructure maintenance tooling, not developer tooling — it runs when no one is watching and creates a PR for human review.

This is a distinct design point from AI coding assistants (which help in-session) and from code generation frameworks (which run at development time).

Security patching as a primary use case

AutoFix + SonarFix + ScanSemgrep + ScanDepscan form an end-to-end security remediation pipeline. The system ingests structured vulnerability scanner output (not freeform instructions) and generates targeted fixes with explicit compatibility risk assessment. This is a narrower, more reliable task than general code generation.

Dual license strategy

AGPL-3.0 for the framework + Apache-2.0 for individual Steps and Patchflows. Users can extract any Step or Patchflow and use it in a commercial product under Apache-2.0. Only the orchestration harness (the framework itself) is AGPL. This maximizes reuse of building blocks while keeping the platform open.

Comparison to seed frameworks

Patchwork does not fit any of the five seed archetypes. It is not behavioral guidance for an IDE agent; it is an automated code transformation pipeline that uses LLMs as one step in a larger process.

Scope within this research batch

Patchwork was listed as a "Reddit-confirmed alt-SDD" reference. The Reddit context appears to involve users discussing automated code maintenance pipelines as an alternative to manual spec-driven development. Patchwork automates repetitive code quality tasks (security, docs, deps) but does not implement or enforce a development specification workflow.

Limitations

• No cross-run memory; each run is stateless
• No interactive mode; not usable for exploratory development
• No rollback if a mid-pipeline Step fails (e.g., commit created but PR not opened)
• No parallel step execution within a patchflow
• AGPL-3.0 framework license may be a barrier for some commercial embedding scenarios