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:

cliq team version patch @myorg/my-pipeline

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> [ref]

Argument	Description
patch / minor / major	Bump type
ref	Team reference (optional — defaults to the team in the current directory)

The command reads the current version from team.yml, computes the next version, and writes it back.

cliq team version patch @myorg/my-pipeline   # 1.2.0 → 1.2.1
cliq team version minor @myorg/my-pipeline   # 1.2.0 → 1.3.0
cliq team version major @myorg/my-pipeline   # 1.2.0 → 2.0.0

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

cliq team version patch @myorg/new-team      # (none) → 1.0.0

Git integration

When the team directory is inside a git repository, cliq team version automatically:

1. Stages team.yml
2. Creates a commit with message v1.2.1
3. Creates a git tag v1.2.1

To skip git operations:

cliq team version patch @myorg/my-pipeline --no-git

---

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 @myorg/my-pipeline

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

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

# Bump the version
cliq team version patch @myorg/my-pipeline
# → v1.2.1 (git commit + tag created automatically)

# Publish with a changelog
cliq team publish ./@myorg/my-pipeline -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.