Agent Quickstart#

Zero-context entry point for routine dakota maintenance — add package, remove package, update refs.

Historical path note: elements/bluefin/* is Dakota's package tree. The name
is legacy. Do not use it as a cue to reach for dnf, RPM/COPR, or Containerfile
overlay workflows.

5 Always Rules#

1. Always run just --list first — the Justfile is the ground truth for available recipes
2. Always run just validate, just lint, and just boot-test before opening a PR — graph check, image lint, and automated boot smoke test
3. Always add new elements to deps.bst (binary) or gnome-shell-extensions.bst (extensions)
4. Always grep for all references before removing — grep -r <name> elements/ .github/workflows/ files/
5. Always use just bst not bare bst — BST must run inside the pinned container

6 Never Rules#

1. Never edit elements/freedesktop-sdk.bst or elements/gnome-build-meta.bst without human review
2. Never open a PR to projectbluefin/dakota without running just validate first
3. Never add Renovate entries for elements already in the track-tarballs CI job — causes racing PRs
4. Never call bst directly — always just bst ...
5. Never skip just validate even if just bst build "looks right"
6. Never solve package/image-content changes in Containerfile — those belong in .bst elements and elements/bluefin/deps.bst

Task Routing#

Tracking Groups#

Fix an Issue — End-to-End#

# 1. Claim the issue
gh issue comment 635 --repo projectbluefin/dakota --body "/claim"

# 2. Branch from upstream/main
git checkout upstream/main -b fix/short-description

# 3. Make changes, validate
just validate && just lint

# 4. Commit with correct trailer
git commit -m "fix(bluefin): short description

Closes #635

Assisted-by: Copilot <223556219+Copilot@users.noreply.github.com>"

# 5. Push to upstream (never castrojo fork)
git push upstream fix/short-description

# 6. Open PR with checklist checkbox checked
gh pr create --repo projectbluefin/dakota ...

If the issue is still status/triage (not yet status/approved), ask the user before claiming — agents don't self-approve issues.

Commit Conventions#

feat(bluefin): add <name>
chore(deps): update <name>
fix(bluefin): <description>
chore: remove <name>

Trailer: Always Assisted-by: or Signed-off-by: — never Co-authored-by:. This is a hard rule from docs/pr-checklist.md.

Key Paths#

elements/bluefin/ All Bluefin-specific elements
elements/bluefin/deps.bst Central dependency manifest
elements/bluefin/shell-extensions/ GNOME Shell extensions
elements/bluefin/gnome-shell-extensions.bst Extension stack
include/aliases.yml URL aliases
.github/workflows/track-bst-sources.yml Tracking matrix
.github/renovate.json5 Renovate config

Throughput Rule#

If working through a backlog of issues, do not stop after the first fix. Work from the issue backlog in this order:

1. Issues labeled status/queued
2. Issues labeled kind:bug
3. Issues explicitly named by the user

Lessons Learned#

Add entries here when you discover a new pattern or fix a recurring mistake.
Format: ### <pattern name> (YYYY-MM-DD)

Restarting the publish factory after a pause (2026-06-05)#

When publishing has been intentionally paused (e.g., post-repo-refactor), the
factory restart sequence is:

1. Fix any startup_failure in publish.yml — check for invalid permissions: scopes
   (e.g., artifact-metadata: write is not a valid GITHUB_TOKEN scope) and
   job-level permissions: on reusable workflow call jobs.
2. Dispatch build.yml --ref main to populate the remote CAS.
3. Wait ~60–90 minutes for the build to complete.
4. publish.yml auto-triggers via workflow_run. If not, dispatch manually.
5. After :testing lands, dispatch weekly-testing-promotion.yml and get
   2 human approvals at https://github.com/projectbluefin/dakota/deployments
   to promote :testing → :latest + :stable.

Full details: docs/ci.md → "Restarting the factory".