Versioning

Every team published to CliqHub is versioned using semantic versioning (semver). Versions are immutable — once a version is published, it cannot be overwritten. This guarantees that cliq team install hub://@scope/[email protected] always returns the exact same team, no matter when you run it.

---

How semver works in cliq

Versions follow the MAJOR.MINOR.PATCH format:

Bump	When to use	Example
patch	Bug fixes, prompt tweaks, minor role adjustments	1.0.0 → 1.0.1
minor	New phases, new roles, added capabilities (backward-compatible)	1.0.0 → 1.1.0
major	Breaking workflow changes, removed phases, renamed roles	1.0.0 → 2.0.0

The first publish of any team starts at 1.0.0.

---

The version field

The version lives in team.yml as a top-level field:

name: "@myorg/my-pipeline"
description: "Feature development pipeline"
version: "1.2.0"

This field is managed metadata — you don’t edit it by hand. Use cliq team version to bump it:

cd ~/src/cliq-teams/@myorg/my-pipeline
cliq team version patch

The version field is:

• Read by cliq team publish to determine what version to publish
• Validated by cliq doctor — warns if missing, errors if malformed
• Checked by cliq team install to detect duplicate installs

If the field is missing, cliq team publish will reject the publish and tell you to add one with cliq team version patch.

---

Bumping versions

cliq team version <patch|minor|major> [path] [--git-tag]

Argument	Description
patch / minor / major	Bump type
path	Directory containing the team.yml to bump (default: current directory)

The command reads the current version from team.yml at [path], computes the next version, and writes it back. This is a local file operation — it never reads or writes the installed registry under ~/.cliqrc/teams/. Run it from your source repository, before publishing.

cd ~/src/cliq-teams/@myorg/my-pipeline
cliq team version patch                    # 1.2.0 → 1.2.1
cliq team version minor                    # 1.2.0 → 1.3.0
cliq team version major                    # 1.2.0 → 2.0.0
cliq team version patch ../sibling-team    # operate on a sibling dir

If there is no version field yet (first time), any bump type produces 1.0.0:

cliq team version patch                    # (none) → 1.0.0

Git integration (opt-in)

By default, cliq team version only edits team.yml — it does not touch git. Pass --git-tag to also create a commit + tag in the team’s git repository:

cliq team version patch --git-tag

This will:

1. Stage team.yml
2. Create a commit with message vX.Y.Z
3. Create a git tag vX.Y.Z

If [path] is not inside a git work-tree, --git-tag errors out — the version bump is still written to team.yml, but no git actions are performed.

---

Changelogs

Add a changelog message when publishing with the -m flag:

cliq team publish ./@myorg/my-pipeline -m "Fixed architect prompt for monorepo projects"

The message is stored with the version and displayed in:

• cliq team info hub:// output (version history section)
• The team detail page on cliqhub.io
• The CliqHub Builder publish dialog

If you omit -m, the version is published without a changelog entry.

---

Version immutability

Published versions are immutable. If you try to publish a version that already exists on CliqHub, the publish is rejected:

✗ Version 1.2.0 already exists on CliqHub.
  Bump the version first: cliq team version patch

This is by design. Consumers who pin to @myorg/[email protected] can trust that the team definition will never change out from under them. To ship a fix, bump the version and publish again.

---

Typical workflow

cd ~/src/cliq-teams/@myorg/my-pipeline

# Make changes to your team roles/workflow
vim roles/reviewer.md

# Bump the version (and optionally tag in git)
cliq team version patch --git-tag
# → v1.2.1 (git commit + tag created)

# Publish with a changelog
cliq team publish . -m "Improved reviewer checklist for edge cases"
# → Published @myorg/my-pipeline v1.2.1

# Consumers update
cliq team update @myorg/my-pipeline

---

Validation

cliq doctor checks the version field when you run it against a team:

cliq doctor @myorg/my-pipeline

version... ✓ (1.2.1)

Condition	Result
Version present and valid semver	✓ success
Version missing	⚠ warning — suggests cliq team version patch
Version present but not valid semver	✗ error

The workflow parser also validates the version field during cliq team publish and cliq assemble.