Development Lifecycle

This page walks through common team development workflows end-to-end, showing every command and its expected output. Use these as recipes for your own team development.

For the consumer perspective (installing, using, and updating teams), see Installing & Using.

Author lifecycle

The full create-to-publish loop: build a team locally, iterate on it, version it, and publish to CliqHub.

1. Create the team

cliq team new @myorg/deploy-pipeline

✓ Created @myorg/deploy-pipeline
  → ./deploy-pipeline/@myorg/deploy-pipeline/team.yml

This creates the team directory in the current working directory with a team.yml skeleton and an empty roles/ directory.

2. Build it out

Add roles and generate a workflow:

cliq team add-role @myorg/deploy-pipeline architect --from ./templates/architect.md
cliq team add-role @myorg/deploy-pipeline deployer
cliq team gen-workflow @myorg/deploy-pipeline

Edit the workflow and roles until you’re satisfied:

cliq team edit-workflow @myorg/deploy-pipeline
cliq team validate @myorg/deploy-pipeline

3. Test locally

Install to the global registry and assemble in a test project:

cliq team install ./@myorg/deploy-pipeline

Installing @myorg/deploy-pipeline v1.0.0...
✓ Installed to ~/.cliqrc/teams/@myorg/deploy-pipeline/

cd ~/test-project
cliq init
cliq assemble @myorg/deploy-pipeline
cliq req -m "Deploy the staging environment"
cliq run

4. Iterate

Make changes to the source directory, bump the version, and reinstall:

vim ./@myorg/deploy-pipeline/roles/deployer.md
cliq team version patch @myorg/deploy-pipeline

v1.0.0 → v1.0.1

cliq team install ./@myorg/deploy-pipeline

Upgrading @myorg/deploy-pipeline 1.0.0 → 1.0.1
✓ Installed to ~/.cliqrc/teams/@myorg/deploy-pipeline/

Or use cliq team update if the team is already installed with provenance:

cliq team update @myorg/deploy-pipeline

5. Publish

Authenticate and publish to CliqHub:

cliq hub login
cliq team publish ./@myorg/deploy-pipeline -m "Initial release"

Validating team...
✓ Team valid
Publishing @myorg/deploy-pipeline v1.0.1 to https://cliqhub.io...
✓ Published @myorg/deploy-pipeline v1.0.1

  Changelog: Initial release
  View: https://cliqhub.io/@myorg/deploy-pipeline

6. Ship updates

vim ./@myorg/deploy-pipeline/roles/architect.md
cliq team version minor @myorg/deploy-pipeline

v1.0.1 → v1.1.0

cliq team publish ./@myorg/deploy-pipeline -m "Added rollback phase"

✓ Published @myorg/deploy-pipeline v1.1.0

@local lifecycle

Quick local development without scopes or publishing. Good for experimentation and project-specific teams.

1. Create

cliq team new my-experiment

✓ Created my-experiment
  → ./my-experiment/team.yml

The team has an unscoped name. When installed, it goes to @local/.

2. Develop and test

cliq team add-role my-experiment researcher
cliq team add-role my-experiment writer
cliq team gen-workflow my-experiment

Test directly with --dir:

cd ~/test-project
cliq init
cliq assemble my-experiment --dir ~/my-experiment

3. Install for reuse

cliq team install ~/my-experiment

Installing @local/my-experiment v1.0.0...
✓ Installed to ~/.cliqrc/teams/@local/my-experiment/

Now use it anywhere without --dir:

cliq assemble my-experiment

4. Update from source

Edit the source, bump the version:

vim ~/my-experiment/roles/researcher.md
cliq team version patch my-experiment
cliq team update @local/my-experiment

Updating @local/my-experiment 1.0.0 → 1.0.1 from /Users/you/my-experiment...
✓ Updated

Fork & customize lifecycle

Start from an existing team, customize it, and publish under your own scope. This is the most common path for teams that extend or specialize an official @cliq team.

1. Install the base team

cliq team install hub://@cliq/feature-dev-js

✓ Installed @cliq/feature-dev-js v1.2.0

2. Copy to a local directory

cliq team copy @cliq/feature-dev-js ./my-tdd

This copies all files into ./my-tdd/. The team.yml still says name: @cliq/feature-dev-js — you haven’t claimed a new identity yet.

3. Edit and iterate

Modify roles, adjust the workflow, test from the local directory:

vim ./my-tdd/roles/developer.md
cliq assemble @cliq/feature-dev-js --dir .
cliq req -m "Add input validation to the signup form"
cliq run

You can repeat this cycle as many times as needed. The team identity stays as @cliq/feature-dev-js during development — the --dir . flag tells cliq to resolve from your local directory instead of the registry.

When you’re happy with the changes, re-copy with your scope:

cliq team copy @cliq/feature-dev-js ./my-tdd-final @acme/my-tdd

This creates ./my-tdd-final/ with team.yml rewritten to name: @acme/my-tdd. You can also pass just a scope to keep the original bare name:

cliq team copy @cliq/feature-dev-js ./my-feature-dev @acme

This produces name: @acme/feature-dev-js in team.yml.

5. Install to your registry

cliq team install ./my-tdd-final

  Installing @acme/my-tdd v1.0.0
  Type the full team name to confirm: @acme/my-tdd
  ✓ Installed @acme/my-tdd v1.0.0

Since this is a fresh install (no existing @acme/my-tdd), there’s no overwrite prompt. If you later reinstall, cliq will ask you to type the full team name to confirm the overwrite. Use --force to skip.

6. Publish

cliq team version patch @acme/my-tdd
cliq team publish ./my-tdd-final -m "Custom TDD pipeline based on @cliq/feature-dev-js"

  Publishing @acme/my-tdd v1.0.1 to https://cliqhub.io
  Type the full team name to confirm: @acme/my-tdd
  ✓ Published @acme/my-tdd v1.0.1

Builder lifecycle

Use the AI builder to generate a team, then refine and publish.

1. Generate

cliq builder generate -m "SOC2 compliance audit pipeline" --name @myorg/soc2-audit

Generating team...
  ✓ Created architect role
  ✓ Created auditor role
  ✓ Created evidence-collector role
  ✓ Created report-writer role
  ✓ Generated workflow (4 phases)
  ✓ Generated A2A metadata
✓ Team created at ./@myorg/soc2-audit/

2. Review and refine

cliq team validate @myorg/soc2-audit
cliq builder gaps @myorg/soc2-audit

Suggestions:
  1. [phase] Add a gap analysis phase before evidence collection
  2. [role]  Auditor role should reference specific SOC2 control families
  3. [workflow] Consider adding a human gate after the report phase

cliq builder improve @myorg/soc2-audit --role auditor \
    --instruction "Reference SOC2 Type II control families CC1-CC9"

3. Test, version, and publish

cliq team install ./@myorg/soc2-audit
cd ~/test-project && cliq assemble @myorg/soc2-audit

cliq team version patch @myorg/soc2-audit
cliq hub login
cliq team publish ./@myorg/soc2-audit -m "Initial SOC2 audit pipeline"

Summary

Workflow	Key commands
Author	`team new` → `add-role` → `gen-workflow` → `team install` → `team version` → `team publish`
@local	`team new` → develop → `team install ./path` → `assemble`
Fork & customize	`team install hub://` → `team copy` → edit → `team copy ... @scope` → `team install` → `team publish`
Builder	`builder generate` → `builder improve` → `team install` → `team publish`