Dosu LogoDosu Logo
Ask
Join our Discord
Organization avatar
bluefinPublic
Bluefin
Documentsbluefin
AGENTS
AGENTS
Type
External
Status
Published
Created
Jun 13, 2026
Updated
Nov 9, 2026
Updated by
Dosu Bot
Source
AGENTS.md

AGENTS.md#

This file tells AI coding agents (GitHub Copilot, Claude, Gemini, etc.) how to
contribute safely and work in this repository. Human contributors follow the same steps.
See the org-wide agentic model for cross-repo rules.

dakota-iso builds a single bootable UEFI live ISO from Dakota
images (GNOME OS / bootc / composefs). The live environment runs the NVIDIA variant; the offline
embedded OCI store lets the installer deploy to non-NVIDIA hardware without a network pull.

Home repo: projectbluefin/dakota-iso

Scope: dakota and utah. Bluefin and Bluefin LTS HWE are retired (#228).
build-iso-utah.yml builds and publishes Utah live ISOs from utah:stable monthly (04:00 UTC on the 8th) and via manual dispatch.
The bluefin and bluefin-lts-hwe code, docs and size invariants are retained for revival,
not for current CI. Do not re-add bluefin or bluefin-lts-hwe to any workflow matrix. Revival steps: docs/variants.md.

The System You Are Part Of#

ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”
│ KubeStellar Hive https://kubestellar.io/live/hive/ │
│ AI-native Continuous Maturity Model (ACMM) orchestration│
ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”¬ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜
                   │
      ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”“ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”
      ā–¼ ā–¼
common ──────────────────────────┐
(shared OCI layer) │
                                 ā–¼
bluefin / bluefin-lts / dakota ──┤──→ testsuite ──→ dakota-iso
                                 │ (this repo)
                          bootc-installer

You are an agent in this loop. Your work compounds.

The Prime Directive: The Codebase is the Standard#

Use what is in production already.
Whenever you need to make a technical decision — choosing a GitHub Action, picking a CLI tool, writing a configuration file — your first step is to grep the organization's existing codebase to see what is already used in production.

  • If a specific tool (e.g., ublue-os/remove-unwanted-software) is already used across the org's repos, that is the standard.
  • Use the existing production standard to guarantee cross-repo consistency and prevent redundant third-party dependencies.
  • You do not need to ask for permission or look for a separate rules document if the codebase already shows a clear consensus.

Agent fast path#

Before using any tool or library: look up its docs via Context7 first. Always.
bootc, xorriso, composefs, systemd-boot, skopeo, GitHub Actions — every tool has live, authoritative docs.
Pattern: resolve-library-id → get-library-docs → implement → cite the section.
Guessing, flag-hunting, and trial-and-error are banned. The docs exist. Read them.

1. docs/SKILL.md # find the skill for your task
2. Context7: resolve the tool's library ID, read its docs, then act
3. docs/factory/agentic-model.md # cross-repo rules (in projectbluefin/common)
4. justfile # all build tasks go through here

Find something to work on#

Time availableLink
All sizesEverything agent-ready
# P0 blockers — start here every session
gh search issues --label "hive/p0" --owner projectbluefin --state open \
  --json number,title,repository

# Agent-ready issues in this repo
gh issue list --repo projectbluefin/dakota-iso --label "queue/agent-ready" --assignee ""

Mandatory Behavioral Gates#

0. Test Gate — nothing ships without a test that would have caught it#

This gate fires before writing any code.

For every change to the installer pipeline, ask:

"If this change is wrong, which test breaks?"

If the answer is "none", write the test first.

Change typeRequired test
Copying a binary into the live containerUnit test asserts binary AND all shared lib deps are present in Containerfile
Any change to filesystem formattingCI smoke test runs mkfs.<fs> inside the container; E2E uses that filesystem
Any change to the installer recipeE2E recipe matches what the interactive installer sends by default
Any change to boot parametersRegression test asserts the parameter is present in generated boot entries

pytest tests/ passing does NOT mean the application works.
The Python unit tests (test.yml) are fast static checks — they verify source-file
text invariants and Python routing logic with mocked subprocesses. They cannot catch
runtime failures: a broken ISO build, a LUKS unlock that fails in QEMU, or an installer
that cannot find the embedded VFS store. The real functional gates are:

GateWorkflowWhat it proves
Fast unit teststest.yml — runs on every PRSource-file invariants and Python logic. Necessary but not sufficient.
LUKS install E2Etest-luks-install.ymlEncrypted install completes and installed system boots.
Plain install E2Etest-plain-install.ymlUnencrypted btrfs composefs install completes and installed system boots.

Never say "tests pass" to mean "the application works". Say "unit tests pass" and specify
which E2E gate (if any) covers the change.

The E2E must test the same code path users hit. If the interactive installer defaults to XFS, the E2E must use XFS. A test that passes on btrfs while users install on XFS is not a test — it is a false signal.

Never claim a fix is verified by CI if you have not confirmed what the CI test actually exercises. Check the recipe, the flags, the filesystem — not just the green checkmark.

Read the relevant skill file in docs/ before making any changes.
Do not assume you know the build system, disk space requirements, or CI constraints.

Specific triggers — stop and read before acting:

SituationRead first
Any QEMU boot issue (installed disk won't boot, UEFI shell loop)docs/luks-testing.md
ISO is unexpectedly large (>6 GB)docs/ci.md — check for double-embedded store
Install fails: does not resolve to an image IDdocs/ci.md — VFS store not embedded
CI pipeline changesdocs/ci.md
R2 promotion / named releasesdocs/r2-promotion.md
Variant image refs look wrong or reference ublue-osdocs/variants.md — verify via execute-release.yml in source repo
systemd-boot title is wrong<variant>/live_title — edit the live_title file in the variant dir

2. Verification Gate#

Read docs/skills/qa-policy.md before running any test or making any verification claim.

Key rules (full policy in that file):

  • Always test fresh artifacts. Kill stale QEMU processes and delete stale install disks before every run.
  • debug=1 is required for E2E. SSH is disabled in production ISOs. Use just debug=1 plain-e2e dakota.
  • "ISO booted" is not proof. Only a completed install + installed-system boot proves the pipeline works.

Before submitting a PR:

  • Run just debug=1 iso-sd-boot <target> locally (or just container <target> for container-only changes)
  • Run just plain-test-qemu <target> — must exit with āœ… Installed system boot verified
  • Only trigger CI after local tests pass
  • PR description must state what you built and that it booted

3. Justfile Integrity Gate#

The justfile is the canonical interface. All build tasks go through it.
If you identify a missing recipe, add it to the justfile in the same PR.

4. Operator Accountability Gate#

The human operator is responsible for every AI-generated PR.
PRs must include: [ ] I am using an agent and I take responsibility for this PR

5. Upstream-First Gate#

The origin remote is projectbluefin/dakota-iso (upstream). Pushes go directly upstream.
If working from a personal fork, add it as a separate remote — never push to origin from a fork context.


In-repo skills — read these before working#

All accumulated knowledge lives in docs/. These files are the source of truth
for this repo. When you fix a bug or discover a pattern, add a lesson here.

AreaFileLoad when...
Skill routerdocs/SKILL.mdStart here — find the right skill for your task
Build systemdocs/build.mdBuilding ISOs locally, disk space, BTRFS/XFS, variants
Architecturedocs/architecture.mdUnderstanding the two-container pipeline, boot flow, squashfs
CI/CDdocs/ci.mdbuild-iso.yml, test-luks-install.yml, R2 uploads
QA policydocs/skills/qa-policy.mdBefore running any test, E2E, or making a verification claim
LUKS testingdocs/luks-testing.mdLUKS E2E test (local QEMU, libvirt, CI-equivalent)
R2 promotiondocs/r2-promotion.mdPromoting ISOs to production, rclone, named releases
Variantsdocs/variants.mdAdding new variants, payload_ref pattern
Label workflowdocs/skills/label-workflow.mdIssue lifecycle, labels, PR queue
Human gatesdocs/skills/human-gates.mdWhen to stop and ask a human
Skill improvementdocs/skills/skill-improvement.mdWriting skill updates in the same PR
Skill drift CIdocs/skills/skill-drift.mdSkill-drift check failing on a PR

Development Standards#

Commit format#

Conventional Commits: <type>(<scope>): <description>

Common types: feat fix docs ci refactor chore build perf test revert

AI attribution#

Every AI-authored commit must include both trailers:

feat(iso): add loopback.cfg for Ventoy support

Adds boot/grub/loopback.cfg to the ISO layout so the image is
bootable via Ventoy without re-extraction.

Assisted-by: Claude Sonnet 4.6 via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Mandatory pre-commit checks#

# Before every commit — both must pass:
just --list # verify justfile is parseable
pre-commit run --all-files # lint, yaml/json hygiene, no floating action tags

The skill-drift.yml CI check warns when a PR changes implementation files without updating a matching skill doc. Treat warnings as hard requirements.

Agent environment constraints#

  • sudo is not available in automated agent bash sessions (no TTY). Never call
    sudo dd, sudo modprobe, sudo nbd-client, etc. If an operation requires root,
    provide the exact command for the user to run in their terminal instead.
  • just build-bg fails in agent sessions — it calls setsid sudo just ... which
    requires a TTY for sudo. Use direct backgrounding instead:
    LOG=output/build.log; mkdir -p output
    setsid bash -c "just output_dir=output iso-sd-boot <target> > '${LOG}' 2>&1" &
    disown $!
    
  • Block device writes (USB burning, disk inspection via nbd) always require root.
    Use udisksctl for unmounting; provide dd / qemu-nbd commands for the user to run.

ISO payload and size invariant#

  • Each active variant embeds exactly one offline source, never two:
    composefs (Dakota) embeds an unpacked containers-storage graphroot via
    payload_export_store + payload_bind_store; non-composefs (Utah) embeds
    one OCI layout via payload_embed_oci_archive, all in
    scripts/payload-oci.sh. Its schema-v1 /etc/bootc-installer/media-input.json
    binds the actual manifest/config to the read-only squashfs
    (/run/bootcmedia/var/lib/containers/storage for the store form,
    /run/bootcmedia/usr/share/bootc-installer/oci for the layout form).
  • Keep live-iso-mode and fisherman's strict digest/read-only/no-symlink gate
    for both forms. Missing receipt or corrupt media is an installation refusal,
    not a network fallback.
  • Composefs (Dakota) retains podman build --squash-all; non-composefs (Utah and
    retired variants) must retain all layers to preserve ostree commit objects.
  • Do not pass --store to build-iso.sh; do not restore an OCI archive blob
    alongside the store. The store files must share squashfs blocks with the live
    root (single-copy media) — an opaque second copy of the payload fails the size gate.
  • Record actual ISO bytes with stat -c%s. Dakota single-copy target: ≤6.5 GB.
    A size change needs measured contents and installation evidence, not a second
    embedded payload or deletion of required layers.

Sensitive paths (require maintainer review)#

  • .github/workflows/ — CI pipeline changes
  • justfile — canonical build interface
  • live/src/build-iso.sh — ISO assembly logic (single source of truth for CI, scripts/*.sh, and local justfile recipes)
  • live/src/configure-live.sh — live environment setup
  • live/src/install-flatpaks.sh — Flatpak baking into squashfs

🚫 ABSOLUTE PROHIBITION — ublue-os org#

NEVER create issues, pull requests, comments, forks, webhook calls, API writes, automated reports, or any other programmatic action targeting any ublue-os/* repository.

Read-only gh api calls to inspect ublue-os repos are permitted. No writes of any kind.

ublue-os image names are legacy. All active images have migrated to ghcr.io/projectbluefin/.
Never write ublue-os into a payload_ref, base_imgref, nvidia_imgref, or images.json.
If you see a ublue-os ref in source, it is a stale artifact — replace it with the correct projectbluefin image.
Verify the correct name before replacing: read execute-release.yml in the source repo or run skopeo list-tags. Do not guess.


Self-Improvement Loop#

Every agent session produces two outputs:

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

Output 1 without Output 2 leaves the factory no smarter. The loop only compounds if agents write back.

Agent works on task
  └─ discovers pattern / workaround / convention
       └─ writes it to the relevant skill file in docs/ or docs/skills/
            └─ commits in the same PR (never a follow-up)
                 └─ next agent starts smarter → loop

How to add a lesson#

  1. Open the relevant file in docs/ (or docs/skills/ for process/procedure learnings)
  2. Add a section: ### <what you learned> (YYYY-MM-DD)
  3. What failed → why → the fix → code example if applicable
  4. Commit it in the same PR as your change — never a follow-up

Before marking work complete — checklist#

  • Did I discover any workaround, non-obvious pattern, or convention?
  • Is there a skill file for the area I worked in?
  • If yes — did I update it?
  • If no — did I create one in docs/skills/?
  • Is the skill file committed in this same PR?

Human Decision Gates#

Stop and request human input at these four gates. Never guess past them.

GateStop when
DesignArchitecture change, new subsystem, user-visible behavior change
SecuritySigning, supply chain, secrets, COPR/third-party sources
BreakageCross-repo breaking change — removing/renaming inputs, changing defaults
R2 promotionPromoting any ISO to a named release (e.g. alpha3) — requires explicit user "go ahead" after local boot verification
CI trigger on release branchTriggering a CI build that will upload to R2 — confirm with user first
MergePR ready for final review — always requires human lgtm

ā›” Never use rclone copyto to manually overwrite dakota-live-latest.iso on R2. The latest pointer is the production artifact users download. Only CI may write to it — after the E2E gate passes. Manual uploads bypass the gate and ship broken ISOs. See #85.

See docs/skills/human-gates.md for full evidence requirements.

Factory workflow, labels, and ownership#

Use the shared lifecycle and labels in
docs/skills/label-workflow.md and org
Prow config in projectbluefin/.project. Humans triage and approve via
/triage accepted, /lgtm, and /approve; agents claim work when
needs-human is cleared. Never write to ublue-os/*.

Verification Requirements#

Do not request PR review without evidence:

  • CI is passing (link the run in the PR description)
  • Full install completed and installed system boots — "ISO booted" alone is NOT sufficient. Run just plain-e2e <target> or equivalent and paste the result. A live session boot proves the initramfs works; only a completed install proves fisherman, partitioning, and post-install steps work.
  • If the change touches default filesystem, encryption, or bootloader: plain-e2e output is mandatory, not optional.
  • ISO size is ~5.3 GB (release compression, no double-embedded store)
  • Skill file update committed in this same PR (not a follow-up)
  • PR title follows Conventional Commits format
  • Both AI attribution trailers present on every AI-authored commit
Documents
Changelogs
Bluefin LTS Errata
Pin Log
2024-12-30-ublue-2024-wrapup
2025-01-01-announcements-archive
2025-02-23-february-update
2025-05-14-bluefin-f42
2025-06-23-bazaar-default
2025-07-06-fresh-bluefin-isos-and-bazaar
2025-07-11-four-years-of-ublue
2025-07-15-bold-brew
2025-07-17-ask-projectbluefin
2025-08-01-august-wallpapers
2025-08-08-bluefin-on-lfx
2025-08-29-github-oss-fund
2025-09-17-color-with-bluefin
2025-09-18-bluefin-lts-and-gdx
2025-09-23-LTS-at-indiafoss
2025-10-28-bluefin-autumn
2025-10-31-fastfetch-metrics
2025-11-15-cloud-native-milestone-15-million
2025-11-16-coreos-desktop
2025-11-24-new-just-and-bbrew
2025-11-27-bluefin-and-paleoartists
2025-12-04-flatpak-support-in-brewfiles
2025-12-06-interview-with-michael-tunnell
2025-12-07-documentation-updates
2025-12-14-huntress-holiday-wallpapers
2025-12-15-easier-homebrew-installation-for-custom-images
2025-12-27-upcoming-homebrew-cli-changes
2025-12-30-bluefin-2025-wrapup
2026-01-03-modernizing-custom-images
2026-02-01-automated-reports-changelogs
2026-03-13-bluefin-cli-mac-wsl
2026-03-27-bluefin-lts-gnome-49-50
2026-03-29-composefs-fisherman
2026-03-29-composefs-fisherman-design
2026-03-30-boot-verification
2026-03-30-boot-verification-design
2026-03-30-proportional-progress-tracking
2026-03-30-proportional-progress-tracking-design
2026-04-02-state-of-ecosystem
2026-04-19-dakota-alpha-1
2026-05-12-bluefin-spring-2026
2026-05-13-bluefin-spring-2026-2
2026-05-14-making-our-own-fate
2026-05-15-hummingbird
2026-05-23-gradia-capture-bluefin
2026-05-28-knuckle
2026-06-11-promotion-pr-body
AGENTS
AGENTS
AGENTS
AGENTS
AGENTS
Building a Custom Bluefin Image
CI_CD_GUIDE
CLAUDE
CLAUDE
CONTRIBUTING
CONTRIBUTING
CONTRIBUTING
CONTRIBUTING
How can I install Double Commander on Bluefin (an immutable Linux OS), coming from Arch Linux?
How can you fix random GPU artifacts and hard freezes on an AMD Framework 16 laptop running Linux (Bluefin/Fedora)?
How do I install the Cloudflare WARP (One) client on Bluefin?
How to Reset a User's Home Directory to Defaults on Bluefin
INDEX
MAINTAINERS
MULTI_VARIANT_BUILD
PITFALLS
PULL_REQUEST_TEMPLATE
Plex Media Server
README
README
README
README
README
README
README
README
SECURITY
SECURITY
SKILL
SKILL
SKILL
SKILL
TRANSLATING
Update Process
Which Bluefin ISO is recommended for a Lenovo Yoga Pro 9i with an NVIDIA RTX 4050 for Python data science and Machine Learning with CUDA?
action-reference
actionadon
add-package
administration
agentic-contributing
ai
analytics
architect
architecture
artwork
blog-poster.agent
bluefin-dx
bonedigger-overview
bonedigger-templates
bonedigger-ujust
bst-overrides
build
build
buildstream
ci
ci
ci
code-of-conduct
command-line
composite-actions
consumer-guide
consumer-validation
contributing
conventional-commit.prompt
copilot-instructions
copilot-instructions
copilot-instructions
copilot-instructions
dakota-tpm2-validation
debugging
demo-mode-e2e
determinism
dinosaurs
downloads
downloads-testing
driver-versions
e2e-ci
e2e-feature-verification
encryption-matrix
factory-operations
failure-paths
feedback-loop
gstreamer-codec-validation
human-gates
images
index
index
installation
installer
label-workflow
libpastry-integration
live-iso
local-ota
luks-testing
merge-queue
mission
multi-arch
music
not-bluefin
oci-assembly
oci-layers
onboarding
overview
packaging-binaries
packaging-gnome-extensions
packaging-go
packaging-rust
packaging-zig
patch-junctions
patches
pr-checklist
pr-review
press-kit
projects
pull_request_template
pull_request_template
pull_request_template
qr-phone-companion
quickstart
r2-promotion
release-qualification
remove-package
reports
reusable-workflow
skill-improvement
supply-chain
t2-mac
testing
troubleshooting
ujust-recipes
update-refs
upgrade-and-migration
ux-ubuntu-provision
values
variants
vm-stack
workflow