Skip to content

Draft — not approved. A working draft by UASK. It may change without notice.

Status: review · Version 0.1.1

Get started with the Hub in your project

This page shows how a project adopts the Hub: it pins one release, keeps a copy of that release in its own repository, tells its agents where the copy is, and upgrades on purpose. Nothing in your project changes until you move the pin. Allow about fifteen minutes.

What you get

A Hub release is one versioned bundle, uask-hub-vX.Y.Z.tar.gz, published as a GitHub Release together with its manifest.json. It contains:

Part What Lands in your project at
core, playbooks, learn, glossary knowledge items: rules, practices, playbooks, terms .uask/hub/content/
hif, scf the Human Interface Framework and Software Component Framework standards .uask/hub/standards/
templates artefact templates: vision, requirements, blueprint, ADR and others .uask/hub/templates/
skills Agent Skills: step-by-step procedures that apply the items .uask/hub/skills/
schemas JSON Schemas for item front matter and reports .uask/hub/schemas/
base AGENTS.hub.md (instructions for your agents), README.md, licences, manifest.json .uask/hub/

Every item in manifest.json carries its id, version and sha256, so a reviewer can see exactly what changed between two releases. The whole Hub has one version number (ADR-0004); item versions follow semantic versioning.

Before you start

  • Python 3.9 or newer. hub-sync is one file and uses only the standard library.
  • Access. The Hub repository, uaskpro/uask-engineering-hub, is private for now; ask the owner for access. Until it opens, hub-sync downloads releases with a GitHub token that can read the repository’s contents (UASK_HUB_TOKEN, GH_TOKEN or GITHUB_TOKEN in the environment) or through a logged-in GitHub CLI (gh auth login). An SSH deploy key is enough for the Claude Code plugin, which is fetched with git, but not for release files, which GitHub serves only over HTTPS. Once the repository is public, no credentials are needed.

1. Add hub-sync to the project

Copy tools/hub-sync from the release you are going to pin, so the tool and the content come from the same tag:

Terminal window
mkdir -p tools
gh api "repos/uaskpro/uask-engineering-hub/contents/tools/hub-sync?ref=v0.1.0" \
-H "Accept: application/vnd.github.raw" > tools/hub-sync
chmod +x tools/hub-sync

If you already have a checkout of the Hub, you can run its copy instead: python3 ../uask-engineering-hub/tools/hub-sync --repo ..

2. Pin a release

Terminal window
python3 tools/hub-sync init v0.1.0 --claude

This downloads the bundle, checks its sha256 against the release manifest, writes .uask/hub.lock and unpacks the release into .uask/hub/. The lock is a short TOML file:

hub = "0.1.0"
source = "github:uaskpro/uask-engineering-hub"
sha256 = "…" # of the release bundle
include = ["*"] # or only some parts, e.g. ["core", "playbooks", "templates", "skills"]

Until the first full release, pin a pre-release such as v0.1.0-rc.1 in these commands: it ships draft and review items marked “Draft — not approved”, and hub-sync prints a warning with their counts per status.

Commit .uask/ with the tool. The copy is committed on purpose: every person and every agent reads the same text, also offline, and a pull request shows the exact rule changes when the pin moves. Use --include to take only some parts; base always comes along.

3. Point your agents to the Hub

Add a short section to the project’s AGENTS.md, the one file all coding agents read:

## Engineering base
This project follows the UASK Engineering Hub pinned in `.uask/hub.lock`. Read
`.uask/hub/AGENTS.hub.md` before any task; the project rules below come first.

For Claude Code, the project’s CLAUDE.md imports both files, so they load into every session:

@AGENTS.md
@.uask/hub/AGENTS.hub.md

AGENTS.hub.md explains where items, templates and skills are and how to use them. Keep project-specific rules in your own AGENTS.md; a project rule may be stricter than a Hub rule, and relaxing one needs a recorded decision.

4. Add the Claude Code plugin

The --claude option in step 2 wrote .claude/settings.json with the Hub’s plugin marketplace pinned to the same tag and the plugin enabled for the project. Each person then installs it once:

Terminal window
claude plugin install uask-hub@uask-hub --scope project

To use the skills in your own sessions outside a project, add the marketplace pinned to a release and install:

/plugin marketplace add uaskpro/uask-engineering-hub@v0.1.0
/plugin install uask-hub@uask-hub

While the repository is private, Claude Code fetches it with your own git credentials: run gh auth login and gh auth setup-git once, or use an SSH key. With a deploy key under an SSH host alias, add the marketplace by its git address, for example /plugin marketplace add git@github-hub:uaskpro/uask-engineering-hub.git#v0.1.0; hub-sync keeps such an address and moves only the tag.

The plugin carries the skills; .uask/hub/ stays the source of truth for the rules. Both point to the same tag, and hub-sync check fails when they drift apart.

5. Check the pin in CI

Terminal window
python3 tools/hub-sync check

The check runs offline. It fails when a vendored file was edited, deleted or added, when .uask/hub/ holds another version than the lock, or when the plugin is pinned to another tag. hub-sync sync restores the pinned files, for example after a fresh clone without .uask/hub/.

Upgrading

Terminal window
python3 tools/hub-sync upgrade v0.2.0

upgrade moves the pin, replaces .uask/hub/ and lists every changed item:

UASK Engineering Hub v0.1.0 -> v0.2.0
MAJOR arch.adr 1.0.0 -> 2.0.0
MINOR arch.c4-model 1.0.0 -> 1.1.0
ADDED test.unit-tests 0.1.0
summary: 1 MAJOR, 1 MINOR, 0 PATCH, 1 added, 0 removed, 0 other changed

The upgrade policy follows from the Hub’s versioning:

  • Exact pins only. There are no version ranges; a new Hub release reaches a project only through an upgrade.
  • One pull request per upgrade. It contains the new lock, the new .uask/hub/, the plugin pin and any project changes the upgrade needs. Nothing else goes into it.
  • Read by class. PATCH changes wording and sources. MINOR adds items or recommendations. MAJOR adds or tightens a requirement, changes a meaning or removes an item: read each MAJOR item and adapt the project in the same pull request.
  • Upgrade on purpose. Move the pin when the project needs something from a newer release or starts a new stage of work, not automatically. Going back to an older release uses the same command.

Command reference

Command Does
hub-sync init vX.Y.Z [--source …] [--include …] [--claude] pin a release for the first time
hub-sync sync vendor exactly the pinned release; refuses a bundle with another sha256
hub-sync upgrade vX.Y.Z move the pin and list the changes by class
hub-sync check offline check of lock, vendored files and plugin pin

Options: --repo DIR for the project folder, --bundle FILE to use a downloaded bundle, --force to discard local edits of vendored files. The source in the lock is github:OWNER/REPO or path:DIR, a folder with release bundles.

Sources