Skip to content

Instantly share code, notes, and snippets.

@castrojo

castrojo/jorgeflow.md

Created March 15, 2026 03:36
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save castrojo/9c1ef29f4a8e96eac065cd9924e8ceef to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save castrojo/9c1ef29f4a8e96eac065cd9924e8ceef to your computer and use it in GitHub Desktop.
Download ZIP
Raw
jorgeflow.md

Workspace Onboarding — @castrojo's Copilot Setup

Last updated: 2026-03-15 Automatically updated by fleet agents when workspace config changes.

GitHub Copilot CLI workspace for @castrojo — maintainer of Project Bluefin and Universal Blue contributor.

Manages 51+ projects across 4 GitHub namespaces from one directory, with a self-improving skills library and swarm-first execution.

What This Is

~/src is simultaneously:

  • A directory holding 50+ project git repos
  • A private git repo (castrojo/copilot-config) tracking only workspace config
  • A Copilot workspace with automatic context, skills, and rules

Key insight: all project repos are gitignored. Only the config layer is tracked.

Prerequisites

gh auth status        # GitHub CLI authenticated with SSH
ssh -T git@github.com # SSH key working
just --version        # just build runner
copilot --version     # GitHub Copilot CLI

New Machine Setup

git clone git@github.com:castrojo/copilot-config.git ~/src
cd ~/src && just setup
source ~/.bashrc

just setup:

  • Symlinks ~/.copilot/copilot-instructions.md → ~/src/dotcopilot/copilot-instructions.md
  • Symlinks ~/.gemini/GEMINI.md → ~/src/dotgemini/GEMINI.md
  • Symlinks ~/.gitconfig → ~/src/dot/gitconfig
  • Sets COPILOT_CUSTOM_INSTRUCTIONS_DIRS="$HOME/src/instructions" in ~/.bashrc
  • Runs just link-projects (per-project instruction symlinks — see below)
  • Updates dotcopilot/config.json trusted_folders for this machine's $HOME

Workspace Structure

~/src/
├── AGENTS.md                    ← source of truth for ALL AI clients
├── GEMINI.md                    ← "read AGENTS.md" (Gemini CLI)
├── CLAUDE.md                    ← "read AGENTS.md" (Claude Code)
├── AGENTS-onboarding.md         ← this file
├── Justfile                     ← setup / sync / pull / status / link-projects
├── projects.json                ← catalog of all 51 projects
│
├── instructions/                ← COPILOT_CUSTOM_INSTRUCTIONS_DIRS target
│   └── _workspace.instructions.md  ← skill loading decision tree (always loads, ~20 lines)
│
├── skills/                      ← personal skills library (skills.sh format)
│   ├── workflow/                ← commit discipline, PR rules, review habits
│   ├── oci-images/              ← cross-cutting OCI/container image patterns
│   ├── github/                  ← gh CLI patterns and preferences
│   ├── linux-desktop/           ← Fedora/atomic/Flatpak/bootc patterns
│   ├── cncf-community/          ← CNCF governance and community norms
│   ├── bluefin-build/           ← build + validation + PR workflow (scripts/)
│   ├── bluefin-packages/        ← brew/flatpak/RPM/COPR management (scripts/)
│   ├── bluefin-iso/             ← ISO pipeline + LTS safety guard (scripts/)
│   ├── bluefin-release/         ← streams, changelogs, release cadence (scripts/)
│   ├── bluefin-renovate/        ← automated dependency update workflow
│   ├── bluefin-docs/            ← documentation and website management
│   ├── bluefin-variants/        ← image × tag × flavor matrix reference
│   ├── bluefin-ci/              ← CI/CD troubleshooting (scripts/)
│   ├── bluefin-security/        ← COPR isolation, cosign, secureboot
│   └── bluefin-lts/             ← LTS variant (critical ISO safety warnings)
│
├── .github/
│   ├── copilot-instructions.md  ← "read AGENTS.md" pointer
│   └── instructions/            ← per-project instruction files (13 projects)
│       ├── bluefin.instructions.md
│       ├── aurora.instructions.md
│       └── ... (one per active project)
│
├── dotgemini/                   ← tracked ~/.gemini/ config
│   └── GEMINI.md                ← global Gemini rules → symlinked from ~/.gemini/
│
├── dotcopilot/                  ← tracked ~/.copilot/ config
│   ├── copilot-instructions.md  ← global Copilot rules → symlinked from ~/.copilot/
│   ├── config.json              ← trusted_folders, allowed URLs, preferences
│   └── mcp-config.json          ← MCP server config (linux-mcp-server)
│
└── dot/
    └── gitconfig                ← ~/.gitconfig → symlinked by just setup

Context Loading — Per-Session Efficiency

Context loaded is scoped to exactly what you need:

Where you are What loads ~Size
~/src/ AGENTS.md + workspace guide ~120 lines
~/src/bluefin/ workspace guide + bluefin instructions ~105 lines
~/src/tab/ workspace guide + tab instructions ~54 lines
Anywhere Skills (on-demand via /skills only) 0 until loaded

How per-project instructions load: just link-projects creates PROJECT/.github/copilot-instructions.md → symlink to the instruction file in ~/src/.github/instructions/. This is excluded via .git/info/exclude in each project repo — never committed, never pushed upstream. Recreated by just link-projects on any new machine.

Without this architecture: 577 lines would load for every session regardless of project.

Supported AI Clients

All clients point to AGENTS.md as the single source of truth:

Client Global config Workspace file
GitHub Copilot CLI ~/.copilot/copilot-instructions.md → symlink AGENTS.md
Gemini CLI ~/.gemini/GEMINI.md → symlink GEMINI.md → AGENTS.md
Claude Code (add ~/.claude/CLAUDE.md symlink manually) CLAUDE.md → AGENTS.md
Any AGENTS.md reader — AGENTS.md

Swarm-First Execution

Default mode: dispatch fleet agents in parallel, keep the main session free.

  • Independent subtasks → multiple /fleet agents simultaneously
  • Skill captures → /fleet (always, never inline)
  • Main session = user interaction + tasks requiring approval only
Can this be parallelized?  → /fleet (multiple agents)
Can it be fully delegated? → /fleet (single agent, background)
Requires user approval?    → do inline, delegate follow-on work

The Self-Improvement Loop

After every session, fleet agents capture what was learned:

  1. /fleet agent dispatched (main session uninterrupted)
  2. Agent writes to skill or instruction file
  3. Runs just sync → commits and pushes to castrojo/copilot-config
  4. Available on all machines next session

Two stores, strictly separated:

  • Project-specific → ~/src/.github/instructions/PROJECT.instructions.md
  • Cross-cutting personal → ~/src/skills/SKILL/SKILL.md

The PR Workflow (Hard Rule — No Exceptions)

origin   = castrojo fork  ← push here
upstream = project org    ← PRs land here
  1. Work on feature branches, commit freely
  2. Push to origin
  3. Open Firefox for the upstream PR comparison: 
    bash ~/src/skills/bluefin-build/scripts/open-pr.sh
  4. You write the description and submit

gh pr create and /delegate are never used. This is in every client's config.

Workspace Commands

just setup         # new machine: symlinks, ~/.bashrc, config.json, link-projects
just link-projects # (re)create per-project .github/copilot-instructions.md symlinks
just sync          # commit + push to castrojo/copilot-config
just pull          # pull latest
just status        # show changed tracked files

⚠️ LTS ISO Safety

Bluefin LTS ISOs are currently broken and disabled.

  • Never run promote-iso.yml with variant: lts or variant: all
  • promote-iso.sh enforces this with a hard abort
  • Load /skills bluefin-lts before any LTS work for full safety context

Adding a New Project

  1. Clone into ~/src/YOUR-PROJECT
  2. Add upstream: git remote add upstream git@github.com:ORG/REPO.git
  3. Add entry to ~/src/projects.json
  4. Create ~/src/.github/instructions/YOUR-PROJECT.instructions.md
  5. Add a link line to the link-projects recipe in Justfile
  6. Run just link-projects && just sync
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment