Mutable Software Framework (MSF), powered by OpenPearl

MSF

Your Customers Ask, the Software Changes

A customer describes a change. An agent builds it as a sandboxed extension for their tenant, automated checks gate it, and it ships in minutes.

Get started

MUTABLEPER-TENANTSANDBOXEDAUTO-MERGEOPEN SOURCE

Open source under the Apache License 2.0

MSF is open source on GitHub. Its engine, OpenPearl, is a GitHub workflow that turns tickets into merged PRs, and it also works standalone for your own repo. It reads a ticket, implements it, opens a PR, reviews it in a loop and auto-merges. All as a GitHub workflow. If it isn't confident, it hands the PR to a human. Seamlessly integrates into your existing CI/CD.

The story

A pipeline that maintains itself

Software delivery pipelines can now be implemented and be self-maintained. We built OpenPearl with an initial prompt that generated a workflow intended to be self-modifiable. Once the boilerplate scaffolding was set, we began using the engine itself to modify and expand its capabilities. It took a few tries, with a few false starts where the engine couldn't modify itself successfully. We're only talking about YAML files because this is a GitHub workflow; there are no other files involved except for evals.

Once we got past the initial problems, we added features that let the workflow integrate seamlessly with Jira, Trello, and GitHub issues. We added image support so the models have vision. Then we added a continuous chat session in issues and pull requests. It became obvious that we needed an eval to decide when a human should verify and validate a pull request, and when the ticket can be auto-merged. The goal is for most tickets to merge automatically. For safety, any modification to the workflows typically triggers human review.

The preferred workflow

We also wanted a command-line interface, so you can submit new tickets directly from your terminal or have an AI agent trigger a series of new tickets that the OpenPearl pipeline implements automatically. This has become the preferred method: spin up your Codex or Claude Code instance and use the GitHub CLI (gh) to create new issues. Ask your coding assistant to create issues for complex tasks, and it may split the work across several tickets.

How we started

At PubNub and Blocks.AI, we wanted to innovate our engineering workflows. Early in 2024, we realized it might be possible to build a software delivery pipeline from Jira tickets to merged PRs. We tried and failed. Most models and harnesses were newly emerging, and even simple tickets needed a lot of back and forth between the harness and a human. Now the models and harnesses are good enough that the automation pipeline we tried to build in 2024 is readily available in 2026.

The simple workflow loop

This is what OpenPearl is: a simple YAML file that describes a workflow for GitHub Actions. It fetches tickets from Trello, Jira, and GitHub Issues, then opens a branch, modifies the code, pushes the branch to origin, and opens a PR. It evaluates the code review in a loop until it looks clean, and finally runs an eval to determine whether the PR can be merged automatically or needs a human. That is the simple loop.

Why workflows

Why not a pile of markdown files?

Instead of piling instructions into markdown files (CLAUDE.md, AGENTS.md, rules and memory docs) that get loaded into the agent's context on every run, OpenPearl uses workflow orchestration and evals. The workflow drives each step (implement, review, fix, merge) as a separate, focused agent call, and evals decide whether a PR is ready to merge. Context isn't consumed by standing instructions, so the agent keeps its context for the actual task.

How it works

How the night shift works

When an owner, member, or collaborator opens an issue, .github/workflows/issue-to-pr.yml runs:

  1. The agent implements the issue and opens a PR.
  2. The agent CLI runs two review/fix rounds.
  3. The agent CLI runs the eval in .github/workflows/evals/pr-ready-to-merge.md. On YES the PR is squash-merged; otherwise it stays open for a human.

Usage

Drop tickets in the slot (gh)

Install the GitHub CLI and run gh auth login once.

gh issue create   # interactive: prompts for title and body
gh issue create -t "Add dark mode toggle" -b "Add a toggle to the settings page."
gh issue list
gh issue view 123 -c
gh issue comment 123 -b "Also handle the empty state."
gh issue close 123
gh pr list
gh run watch

To attach an image, commit it with gh api and link it (replace {owner}/{repo} in the body with your repo):

gh api -X PUT repos/{owner}/{repo}/contents/issue-assets/shot.png \
  -f message="Add shot.png" -f content="$(base64 < shot.png | tr -d '\n')"
gh issue create -t "Button is misaligned" \
  -b "![shot](https://github.com/{owner}/{repo}/blob/HEAD/issue-assets/shot.png?raw=true)"

Mutable Software Framework

How MSF ships a customer request

MSF takes feature requests straight from your product's customers. Each request ships as a tenant extension: a sandboxed plugin that only the requesting customer's tenant can see. It is merged and deployed automatically, typically in about five minutes, with no human in the loop. That's safe because the platform makes a cross-tenant leak impossible by construction, and evals check whatever the platform can't rule out.

  1. Intake The customer submits a request in your product. The tenant comes from their login, and the request is signed and filed as an issue by your GitHub App.
  2. Triage An eval rejects requests for other tenants' data, admin rights, auth or plan changes, outbound network calls or attempts to steer the pipeline. Unclear requests get clarifying questions instead.
  3. Implement An agent with no shell, no repo token and no view of other tenants writes one extension directory.
  4. Gate A path allowlist, the manifest checked against the tenant's plan, a canary isolation harness, acceptance tests from a second agent that never sees the code, and three evals (isolation, least capability, intent match).
  5. Merge The exact patch that passed is merged by a job with no agent in it.
  6. Deploy The merged commit is signed and enabled for that tenant only. Extensions that write data wait in a read-only preview until a tenant admin approves. Bad releases roll back automatically.

Why automatic merge is safe

Security lives in the runtime, and the evals are the second line. Every query is scoped by a session the platform issues, and in Postgres, row-level security enforces the same scoping inside the database, so an extension can't name another tenant. Rows marked owner-only stay with their owner, and sensitive fields like emails need their own capability and never reach logs. Extensions can only use the capabilities their manifest declares, and reaching past them takes the extension offline and alerts you. Each request runs in a fresh sandbox inside a memory-capped isolate, and only signed bundles load.

Evals that keep data where it belongs

The isolation harness seeds unique canary values for several users, every sensitive field and a second tenant, then attacks every route with hostile inputs. It fails if anyone sees a value they aren't entitled to, including data quietly copied into a shared collection or written to a log. A second agent writes acceptance tests from the request alone, so a feature that is safe but wrong doesn't ship, and those tests guard every later change. A corpus of attack extensions must be stopped on every pull request, and a labelled set of malicious and benign requests tests the triage eval every night.

Runs where you run

One container image runs the extension host, the intake service and the migrations. Start everything with docker compose up or podman compose up, or as a pod with podman kube play. Tenant data lives in Postgres behind row-level security, and deploys go through a pluggable adapter for your platform.

See the framework guide, the extension contract and the threat model, including its known limitations.

Research

Can it build a self-healing, self-improving, self-optimizing engine?

59/63PRs merged
17/17merge conflicts resolved
<2 minred-main recovery, down from over an hour

We opened 63 issues with gh issue create and let the pipeline build an engine of 43 source files, repair its own gates, and recover from a red main. 59 of 63 PRs merged, merge conflicts were resolved 17 of 17 times, and a watchdog cut red-main recovery from over an hour to under two minutes. Run time did not improve.

Read the full report with charts and data →

Setup

Move the robot in

Paste this prompt into your coding agent (Claude Code, Codex, OpenCode, Pi) from the root of your project. It installs the OpenPearl workflow files.

Install OpenPearl into this project.

1. Download the .github/workflows directory from https://github.com/stephenlb/openpearl (branch main) into this project's .github/workflows directory: issue-to-pr.yml, pr-comment-chat.yml, retry-issue-to-pr.yml and the evals/ folder (evals/pr-ready-to-merge.md). Only also copy jira-to-issue.yml, issue-comment-to-jira.yml and trello-to-issue.yml if I use Jira or Trello. For example: git clone --depth 1 https://github.com/stephenlb/openpearl /tmp/openpearl, then copy the files. Do not overwrite existing files without asking me.
2. Do not modify any other files in my project.
3. Commit the new files on a branch and tell me to finish setup:
   - Enable Settings > Actions > General > "Allow GitHub Actions to create and approve pull requests".
   - Add the secret ANTHROPIC_API_KEY under Settings > Secrets and variables > Actions (or the Amazon Bedrock secrets listed in https://github.com/stephenlb/openpearl#setup).

Or move in by hand: copy the workflow files into your project, commit them, then finish setup in GitHub.

git clone --depth 1 https://github.com/stephenlb/openpearl /tmp/openpearl
mkdir -p .github/workflows
cp -r /tmp/openpearl/.github/workflows/issue-to-pr.yml /tmp/openpearl/.github/workflows/pr-comment-chat.yml /tmp/openpearl/.github/workflows/retry-issue-to-pr.yml /tmp/openpearl/.github/workflows/evals .github/workflows/
git checkout -b add-openpearl
git add .github/workflows
git commit -m "Add OpenPearl"
git push origin add-openpearl
  1. Enable Settings > Actions > General > Allow GitHub Actions to create and approve pull requests.
  2. Add the secret ANTHROPIC_API_KEY under Settings > Secrets and variables > Actions.
  3. Open a pull request from the add-openpearl branch and merge it, then open an issue and watch the robot work.

See the README for full setup instructions. To let customers request features, follow the Mutable Software Framework setup.