Agentic Bluefin — Contributor Guide#

:::info What this guide is for
This guide explains how to contribute to projectbluefin — the agentic factory that builds Bluefin. AI agents implement work; humans approve design, review PRs, and run the gates that machine enforcement cannot replace.
:::

What Changed and Why#

Bluefin has been rebooted from ublue-os/bluefin — a community-maintained image built by humans — to projectbluefin/bluefin, a factory where AI agents implement work and humans approve design, security-sensitive changes, and merges.

The reboot took 4–5 days in late May 2026. As Jorge describes it:

I did a 4-5 day sprint to rebuild Bluefin with agents. Lots of AI smart people helped me like Andy Anderson, who really explained this. Then it just became obvious. Bluefin 2.0.
— Jorge Castro, THEPATTERN

For a full technical comparison of what changed between ublue-os/bluefin and projectbluefin/bluefin, see THEPATTERN.md.

The Factory Is Running#

The agentic factory is operational and shipping weekly.

What is operational:

• Keyless signing, merge queue, fast PR validation (1–2 min)
• pr-smoke.yml — full image build + smoke test for PRs that touch build-affecting paths
• post-testing-e2e.yml — runs smoke,common suites against every main push
• nightly.yml — nightly smoke,common,vanilla-gnome baseline run against :latest
• weekly-testing-promotion.yml with 2-human Environment gate
• projectbluefin/actions shared CI library consumed by bluefin, bluefin-lts, and dakota
• bonedigger issue lifecycle bot
• AI Moderator (moderator.yml) — spam detection and moderation on issues and PR comments

Still in progress:

• ARM builds — wired in CI, disabled pending akmods ARM support

What this means for you as a contributor:

The system is intentionally moving fast. When something breaks, the correct response is to file an issue and fix it. The design assumption is that the gates (2-human approval + e2e + SHA-lock) protect users even while individual components are still maturing.

The System You Are Joining#

Bluefin's agentic factory is orchestrated by KubeStellar Hive, an AI-native continuous delivery system. The architecture looks like this:

Components#

KubeStellar Hive is the orchestration layer. It manages 8 repositories in the projectbluefin org (bluefin, bluefin-lts, common, dakota, actions, renovate-config, bonedigger, knuckle). You can watch it work in real time at kubestellar.io/live/hive/bluefin/.

bonedigger is the client + lifecycle bot. On Bluefin systems, users run ujust report — the agent collects system diagnostics that are hard for humans to gather manually, scrubs PII on-device, and files an issue to the relevant image repository. The GitHub Actions lifecycle bot then manages the pipeline: filed → approved → queued → claimed → done.

kubestellar-bot is the repo automation layer. It picks up queued issues, dispatches agents to implement fixes and improvements, and ships them back as PRs against the testing branch.

You are a human in this system. Your work is approving design, reviewing agent PRs, deciding what to reject, and running the gates that machine enforcement cannot replace.

About KubeStellar Hive and the AI Codebase Maturity Model#

:::info Sources
The facts in this section come from primary sources. Read them rather than relying on this summary.

• Anderson, A. The AI Codebase Maturity Model: From Assisted Coding to Fully Autonomous Systems. arXiv:2604.09388
• CNCF blog (2026-05-14): When AI agents become contributors: How KubeStellar reached 81% PR acceptance
• The New Stack (2026): Beyond prompting: How KubeStellar reached 81% PR acceptance with AI agents
• projectbluefin-dot-github/AGENTS.md — org operating model
  :::

Andy Anderson and the ACMM#

KubeStellar Hive was designed by Andy Anderson — Senior Platform Engineer and Architect at IBM, chief maintainer of KubeStellar for 4 years, and CNCF Sandbox project steward. Hive is the reference implementation for his AI Codebase Maturity Model (ACMM).

The ACMM describes how codebases evolve from basic AI-assisted coding toward fully autonomous systems. The model is structured around 5 progressive levels (arXiv:2604.09388), with a 6th "Fully Autonomous" level introduced for Hive in the paper's Section 5:

From the abstract:

"Each level is defined by its feedback loop topology — the specific mechanisms that must exist before the next level becomes possible. You cannot skip levels, and at each level, the thing that unlocks the next one is another feedback mechanism."

The central finding of the paper:

"The intelligence of an AI-driven development system resides not in the AI model itself, but in the infrastructure of instructions, tests, metrics, and feedback loops that surround it."

Hive's reported metrics#

The numbers below are from the KubeStellar Console case study in the ACMM paper and the CNCF blog — an 82-day measurement period.

Specific automations Hive performs (from CNCF blog): repository triage every 15 minutes; PR build monitoring every 60 seconds; error-recovery with exponential backoff; hourly analytics queries for error spikes.

Cross-agent memory continuity in Hive is handled by a system called Beads (arXiv abstract).

A finding that is directly load-bearing for Bluefin#

From the case study (CNCF blog):

"A flaky test in autonomous workflow is erosion of trust model."

A single test with 85% reliability cascaded failures across the system. This is why the Bluefin testsuite uses @quarantine tags for scenarios that are written but not deterministic — a flaky gate is worse than no gate.

How the ACMM maps to Bluefin's current implementation#

The human's role at every level is the same: decide what to build, decide what to reject, define what "good" means. Anderson's paper is explicit on this: "Human oversight remains the source of decisions about what to build, what to reject, and defining quality standards."

The Four Gates — Where Humans Decide#

Agents implement autonomously except at these four gates. Stop and request human input when you hit one. If you are a human contributor reviewing an agent PR, these are the moments your judgment is most needed.

When in doubt, open a draft PR with your implementation and ask explicitly. The system prefers over-communication at gates to silent autonomous action.

The Self-Improvement Loop#

Every agent session is expected to produce two outputs:

1. The work — the PR, fix, or improvement.
2. The learning — what the agent discovered that a future agent should know.

Output 1 without Output 2 leaves the system no smarter. The loop only compounds if agents write back. As the org AGENTS.md states:

What qualifies as a learning worth writing back#

Write it:

• A workaround for an upstream bug (include component + issue link)
• A non-obvious pattern required for correctness
• A convention that is not obvious from the code
• Something discovered by trial and error

Do not write it:

• One-off task notes ("use commit message X for this PR")
• Obvious things any developer would know
• Ephemeral state ("currently broken, fix pending")

Where skill files live#

Where to find what needs review#

queue.projectbluefin.io — the Clanker Control Panel — is the live view of everything waiting for a human decision across the org. It shows open PRs bucketed by review state with approval counts, and hive P0/P1 issues in a priority column.

A machine-readable reviewer briefing is available at:

https://queue.projectbluefin.io/review-guide.md

This document covers: merge rules per repo, what to check in a PR, the four human gates (Design / Security / User Impact / Promotion), hive label taxonomy, repos tracked, and quick-reference shell commands. Agents and humans alike can curl this URL to get a structured, parseable briefing without scraping HTML.

The raw data behind the dashboard is also machine-accessible at https://queue.projectbluefin.io/data.json (updated every 10 minutes).

What humans check in review#

When reviewing an agent PR, verify:

• Did the agent commit a .github/skills/ update in this same PR?
• Is the learning described in that update real and non-obvious?
• If a skill file exists for the area worked in, was it updated?

A PR that touches CI, build, or packaging without a skill file update is a yellow flag. Nothing flags it automatically — the skill-drift check was retired — so this is a judgement the reviewer has to make.

Repo Map#

Core image repos#

Infrastructure repos#

Consuming repos (remain in ublue-os)#

Aurora and Bazzite consume projectbluefin/common but are maintained in the ublue-os org. Agent PRs to ublue-os/* follow each repo's own AGENTS.md.

The Build and Promotion Pipeline#

What happens to a change between git push and :stable:

What each stage checks#

What ":stable" means under the new model#

An image tagged :stable has:

1. Passed smoke,common automated scenarios in a virtual machine running the exact image being promoted
2. Passed developer, vanilla-gnome, software, and common suites in the weekly promotion run
3. Been approved by two distinct maintainers via the GitHub production Environment (machine-enforced — the job cannot start without both)
4. Been copied from :testing to :stable by digest, not by tag — the SHA you receive is the SHA that was tested

Filing Work — The Data Donation Model#

Bluefin bugs are data donations. The system is designed so that user reports flow directly into the agent pipeline without manual triage.

The three ujust commands#

# Run on your Bluefin system when you have a bug or question
ujust report

# When you can reproduce a bug someone else reported
ujust confirm <issue-number>

# When a shipped fix works for you — closes the loop
ujust verify <issue-number>

ujust report runs an agent that collects system diagnostics — logs, hardware info, package versions — that a human would struggle to gather manually. It scrubs PII on-device before filing. The result is a GitHub issue in the relevant image repo with a bonedigger label and a diagnostic gist attached.

ujust confirm and ujust verify are how you record additional real-world hits on an issue. The bonedigger bot uses confirm count as a priority signal. ujust verify closes the loop after a fix ships.

Agent rule when reading issues: if an issue has report: attached, read the gist first. Treat confirm count as a priority signal. Do not bypass the verification loop.

Issue lifecycle#

Lifecycle bot commands#

Branch and Stream Model#

The rule#

All PRs target testing. Never main, stable, or latest directly.

gh pr create --repo projectbluefin/bluefin --base testing

Branch roles#

There are two branch roles to keep straight in the CI configuration:

• Contribution branch: testing — all PRs land here via squash merge
• Image build branch: main — image builds trigger on pushes to main; testing merges advance main

This means the build-image-testing.yml trigger is on main, while pr-validation.yml targets testing. PRs merged to testing cause main to advance, which then triggers image builds and the post-merge e2e gate.

Streams#

Promotion cadence#

Every Tuesday at 06:00 UTC, weekly-testing-promotion.yml:

1. Locks the main HEAD SHA
2. Verifies that post-testing-e2e.yml succeeded for that exact SHA
3. Runs the extended developer,vanilla-gnome,software,common suites
4. Waits for 2 distinct human approvals in the GitHub production Environment
5. Copies :testing@<digest> → :latest and :stable via skopeo copy (digest-locked, no rebuild)
6. Pushes to latest and stable branches, triggering downstream builds

If the e2e verification step finds no passing run for the locked SHA, the workflow exits 1. No image ships.

Merge method#

Squash merge only. Keep PR branches tidy. The squash commit message is what lands in git history.

Submitting a Change#

Finding work#

# Open issues labeled for contribution
gh issue list --repo projectbluefin/bluefin --label "good-first-issue"

# All open issues across the org
gh search issues --owner projectbluefin --state open

Also see:

• todo.projectbluefin.io — work that is new or in progress
• done.projectbluefin.io — recently completed work

Before opening a PR#

# From the repo root
just check # Validates all .just file syntax
pre-commit run --all-files # Lint, format, shellcheck, actionlint

Both must pass. CI will run them anyway; running locally saves the round-trip.

Commit format#

Conventional Commits is required and CI-enforced.

<type>(<scope>): <subject>

<body>

<footer>

Common types: feat fix docs ci refactor chore build

feat(packages): add fzf to base brew
fix(ci): correct digest variable name in reusable-build
chore(deps): update ghcr.io/projectbluefin/common digest to abc123
docs(skills): document dnf-cache key format

AI attribution#

If any AI tool wrote or assisted any part of this commit, the footer is required:

Assisted-by: Claude Opus 4.7 via GitHub Copilot

This applies to humans using AI tools, not just agents running autonomously.

SHA pinning for GitHub Actions references#

All uses: references to external actions must be pinned to a full commit SHA with an inline version comment. Floating tags (@v3, @main) are not allowed and will fail actionlint:

# Correct
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

# Wrong — will fail CI
- uses: actions/checkout@v4

Limits#

• Maximum 4 open PRs per agent (enforced by convention, not machine)
• No WIP PRs — open when the work is ready for review
• All PRs squash-merged by maintainers — your branch history does not survive

Reviewing an Agent PR#

This is the human's most important contribution to an agentic project. Agents implement fast; your review is the quality gate before the machine gates run.

What good evidence looks like#

Before requesting review, an agent PR should include:

• A link to a CI run, workflow run, or test output that exercises the change
• If no automated test exists, a description of how the change was manually verified
• A skill file update committed in the same PR (not a follow-up)

The skill file check#

Look at .github/skills/ in the PR diff. Ask:

• Did this change touch CI, build scripts, or non-obvious configuration?
• If yes, is there a skill file covering this area?
• If yes, was it updated in this PR?

Nothing warns you automatically about code changes landing without a skill update; the skill-drift check was retired. When you spot one, decide whether the omission is justified (a one-liner with nothing non-obvious) or a gap that will cost a future agent time.

Red flags#

PR comment policy#

• One comment per PR event, maximum — combine all findings
• Do not duplicate what the GitHub UI already shows (approval status, CI green/red)
• Test reports: what ran, pass/fail count, blockers only — no diff summaries
• @mentions only when asking for a specific action from a specific person
• When in doubt, post nothing

Testing Your Change#

Automatic smoke testing on build-affecting PRs#

PRs that touch Containerfile, Justfile, image-versions.yml, build_files/, or system_files/ automatically trigger pr-smoke.yml, which builds the image and runs the smoke suite. Results appear as a required check on the PR. You do not need to do anything — the check runs automatically.

The /e2e command#

On any open PR, a maintainer can comment:

/e2e

This triggers e2e-dispatch.yml, which:

1. Builds the PR image
2. Runs smoke + developer + vanilla-gnome suites against it
3. Posts results back to the PR

Use this for extended testing on changes where pr-smoke.yml alone is insufficient.

Switching to a PR image#

Every PR that touches image paths generates an OCI artifact. To test it on a running Bluefin system:

# Find the PR number
sudo bootc switch ghcr.io/projectbluefin/bluefin:pr-<NUMBER>
sudo systemctl reboot

# If it works — leave a ujust verify comment on the PR
# If it doesn't work — revert
sudo bootc switch ghcr.io/projectbluefin/bluefin:testing
sudo systemctl reboot

Local build#

# Local build (no sudo required)
just build bluefin latest main

# CI-equivalent build (requires sudo, uses buildah)
sudo just build-ghcr bluefin testing main

What the testsuite covers#

projectbluefin/testsuite — running on standard ubuntu-latest GitHub Actions runners via QEMU + KVM. No self-hosted hardware required.

Scenarios tagged @quarantine are present in the repo but excluded from the promotion gate. Do not remove a @quarantine tag until the scenario has a demonstrated pass rate suitable for blocking promotion.

Working with Renovate#

Renovate runs on a self-hosted configuration from projectbluefin/renovate-config — GitHub App auth, no PATs.

What Renovate automates:

• Base image digest bumps (Containerfile ARG digest pins)
• GitHub Actions SHA pins (updating commit hashes with version comments)
• Container image digest updates in image-versions.yml

Automerge: renovate-automerge.yml automatically merges passing Renovate PRs for low-risk updates (digest bumps where package list is unchanged). High-risk Renovate PRs (labeled renovate/high-risk) wait for pr-smoke.yml to pass before automerge. These automated updates represent a large fraction of all commits.

When Renovate conflicts with your PR:

git checkout your-branch
git fetch origin
git rebase origin/testing

# Resolve conflicts if any
git add resolved-file
git rebase --continue

# Force push (your branch, your PR)
git push origin your-branch --force-with-lease

Becoming a Maintainer and Approver#

The production gate requires two humans#

The weekly-testing-promotion.yml workflow runs inside a GitHub Environment named production. That Environment has required_reviewers: 2. The build job that runs skopeo copy :testing@<digest> → :stable cannot start until two distinct maintainers click Approve in the GitHub UI. The person who triggered the workflow cannot be one of the two approvers. Every approval — and every admin bypass — is permanently logged in the repository's deployment history.

Being an approver means being personally responsible for what ships to :stable users that week. The gate is enforced, but the judgment behind the approval is yours.

Qualities#

There is no formal application process. Maintainer status emerges from demonstrated contribution:

• Consistent quality PRs over time
• Good judgment in review comments — not just "LGTM"
• Helpful to other contributors without being asked
• Understands the project's quality bar and says no when warranted
• Responsive and reliable

See github.com/orgs/projectbluefin/people for the current team.

Community#

Where to participate#

Issue capture discipline#

Discord is for rapid iteration. GitHub is for permanent knowledge. After a Discord debugging session:

1. Copy findings to a text editor as you go
2. File an issue with: symptoms, root cause, solution, related links
3. Cross-reference the issue from Discord so future searchers find it

Discord messages disappear from search. GitHub issues do not.

Code of conduct#

All contributors follow the Universal Blue Code of Conduct.

Glossary#

nightly — nightly.yml — runs at 02:00 UTC daily against :latest. Runs smoke,common,vanilla-gnome suites. The vanilla-gnome baseline separates Bluefin-specific regressions (smoke fails, vanilla-gnome passes) from upstream GNOME regressions (both fail). Advisory; does not block merges.

pr-smoke — pr-smoke.yml — full image build + smoke test triggered automatically on PRs that touch build-affecting paths (Containerfile, Justfile, image-versions.yml, build_files/, system_files/). Required check for high-risk Renovate automerge. Distinct from /e2e dispatch.

ACMM — AI Codebase Maturity Model. A 5-to-6-level framework (Anderson, arXiv:2604.09388) describing how codebases evolve from AI-assisted to fully autonomous. Each level is defined by its feedback loop topology.

Assisted-by — Required commit footer for any AI-assisted contribution: Assisted-by: <Model Name> via <Tool Name>.

Beads — KubeStellar Hive's system for cross-agent memory continuity (arXiv:2604.09388).

bonedigger — The Bluefin client + lifecycle bot. Client side: ujust report/confirm/verify. Bot side: GitHub Actions that manage the filed → approved → queued → claimed → done pipeline.

@quarantine — Test scenario tag meaning the scenario is written and committed but excluded from promotion gates because its pass rate is not yet reliable enough.

kubestellar-bot — The repo automation layer in KubeStellar Hive. Picks up queued issues, dispatches agents, ships PRs.

Hive — KubeStellar Hive, the reference implementation for ACMM Level 6. Orchestrates the Bluefin agentic factory. Live dashboard: kubestellar.io/live/hive/bluefin/.

SHA-lock — The promotion workflow's property that the image digest at the start of promotion must equal the digest at the end. Prevents a rebuild from silently changing what was tested.

skill file — A Markdown file in .github/skills/ documenting non-obvious patterns, workarounds, and conventions. Required to be updated (or created) in the same PR as the work that discovered the learning.

skill-drift — The gap between what a skill file documents and what the code currently does. Formerly detected by the skill-drift-check.yml workflow and the skill-audit.yml cron; both were retired after the check decayed into a no-op that always passed. It is now caught in review and by the self-repair loop.

testing stream — The :testing tag. Built from every push to main (which advances when PRs merge to testing). This is what developers and testers run. All PRs target the testing branch.

two-human gate — The production GitHub Environment configuration requiring 2 distinct maintainer approvals before the weekly-testing-promotion.yml job that copies :testing → :stable/:latest can execute.

ujust report / confirm / verify — The three data-donation commands. report files a new issue with diagnostics. confirm records another real-world reproduction. verify closes the loop after a fix ships.