From 79392f296562447d886f789d9813e30d0a02f738 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Elberte=20Pl=C3=ADnio?= Date: Thu, 9 Jul 2026 22:27:17 -0300 Subject: [PATCH] docs: bun version policy and CI/skill conventions Documents the conventions the agent-DX batch created but never wrote down: the workspace-wide bun pin (current version + bump procedure in the ci skill), rust-cache as a requirement in every Rust workflow including release, and the app-local skill layout (.agents canonical + .claude symlink). --- README.md | 25 ++++++++++++++++++++++--- skills/ci/SKILL.md | 13 +++++++++++++ 2 files changed, 35 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2518183..07ccbe4 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,28 @@ feed. ## Workspace skills `skills/` holds agent runbooks shared across the workspace (`release`, `ci`). -Run `scripts/link-workspace-skills.sh` once per machine to symlink them into -the workspace root and every sibling repo — skill discovery does not traverse -parent directories, so each repo needs its own link. +Run `scripts/link-workspace-skills.sh` to symlink them into the workspace root +and every sibling repo (rerun after adding a repo or a skill) — skill discovery +does not traverse parent directories, so each repo needs its own link. + +App-local skills (like each app's `run` skill) live canonically in that repo's +`.agents/skills//SKILL.md`, with `.claude/skills/` committed as a +relative symlink (`../../.agents/skills/`) so both Claude and other +agents discover the same file. If the repo ignores `.claude/`, carve the skill +out (see pickforge's `.gitignore`). + +## CI conventions + +Apply to every workspace repo; new repos adopt them on day one. + +- `bun-version` is pinned in all workflows, never `latest` — current pin and + bump procedure live in [`skills/ci/SKILL.md`](skills/ci/SKILL.md). +- `Swatinem/rust-cache@v2` goes in every Rust workflow, **including release** + (uncached release builds ran 12–35 min; cached 5–8). Repos where the Cargo + manifest lives under `src-tauri/` (not a workspace) need + `with: workspaces: src-tauri`. +- Tagged releases follow the shared `@pickforge/tauri-release` pipeline; the + runbook is the `release` skill. ## Commands diff --git a/skills/ci/SKILL.md b/skills/ci/SKILL.md index a46c44a..3b331ed 100644 --- a/skills/ci/SKILL.md +++ b/skills/ci/SKILL.md @@ -42,3 +42,16 @@ Before pushing, run what the repo's `ci.yml` runs — the repo's `CLAUDE.md` and `bun run build`, `bun run test:unit`, `cargo check --workspace --locked`. Skip what you can't run locally (VRT baselines, cross-platform legs) and say so instead of faking it. + +## Bun version policy + +Every workflow in every workspace repo pins `bun-version` — currently **1.3.12**. +Never use `latest` (a bun release can break CI or a tagged release build with no +repo change). The pin tracks local dev (`bun --version`). To bump: + +```bash +grep -rn "bun-version" ~/Projects/Pickforge/*/.github/workflows/*.yml +``` + +Update every hit in the same wave (one PR per repo), confirm it matches the new +local version, and update the number in this section.