Skip to content

docs: bun version policy and CI/skill conventions #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ElbertePlinio merged 1 commit into from
Jul 10, 2026
Merged

docs: bun version policy and CI/skill conventions #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 22 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<name>/SKILL.md`, with `.claude/skills/<name>` committed as a
relative symlink (`../../.agents/skills/<name>`) 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

Expand Down
13 changes: 13 additions & 0 deletions skills/ci/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.