Git Integration

The feature-dev-js team adds a complete git lifecycle to the TDD pipeline — branch creation, TDD workflow, merge-conflict resolution, commit, push, and PR creation. It works with both GitHub and Bitbucket Cloud, giving you end-to-end automation from requirements to pull request.

Quick Start

Three commands to go from requirements to PR:

cliq assemble feature-dev-js
cliq req requirements.md
cliq run

Setup

1. Assemble the team

cliq assemble feature-dev-js

This deploys seven agent roles: git-setup, architect, tester, developer, reviewer, git-finalize, git-resolver, plus a git-verify exec phase.

2. Configure your git provider

Set up credentials for GitHub or Bitbucket Cloud — see Integrations — GitHub or Integrations — Bitbucket for step-by-step token creation, settings reference, and the finalize_to options. The provider is auto-detected from your git remote URL.

3. Verify

cliq doctor test github      # or: cliq doctor test bitbucket
cliq doctor                  # check local dependencies (git, tmux, node)

Pipeline Flow

Git Integration Pipeline

Phase Breakdown

git-setup (gate, max_iterations: 1)

Verifies a clean working tree and creates a feature branch. Runs a clean-tree command (git status --porcelain). If the tree is dirty or the branch already exists, it escalates immediately — no retries.

architect → tester → developer (standard)

The normal TDD pipeline. Architect designs, tester writes failing tests, developer makes them pass.

reviewer (gate, max_iterations: 3)

Runs three commands (all scope: repo):

build — npm run build (skipped via if: "test -f package.json" in repos without one)
tests — npm test (same conditional)
merge-clean — verifies no merge conflicts with the base branch

In multi-repo workspaces, each command runs once per repo. If tests fail, routes back to developer. If merge conflicts exist, routes to git-resolver. After 3 failed iterations, escalates to a human.

git-finalize (standard)

Fetches the latest base branch, merges, commits with a structured message ([REQ-KEY] description (instance-id)), pushes, and creates a PR.

git-verify (exec)

Runs shell commands (scope: repo) to verify git-finalize completed successfully:

pushed — confirms the branch exists on the remote
pr-exists — confirms an open PR exists for the branch

In multi-repo workspaces, both commands run per-repo. If PR creation failed silently (e.g., auth error), this exec phase catches it and escalates.

git-resolver (support)

Only activated when the reviewer gate detects merge conflicts. Resolves conflicts and signals done so the reviewer can re-evaluate.

Multi-repo Workspaces

The feature-dev-js pipeline works seamlessly across multiple repositories. Clone the repos into a workspace directory, then initialize Cliq — it auto-detects the child git repos:

mkdir my-workspace && cd my-workspace
git clone https://github.com/org/api.git
git clone https://github.com/org/frontend.git
cliq init
cliq assemble feature-dev-js
cliq req requirements.md
cliq run

In this setup:

git-setup creates a feature branch in each repo independently
architect, tester, developer receive a WORKSPACE section in their prompts listing all repos, enabling cross-repo reasoning
reviewer runs all commands (build, tests, merge-clean) once per repo via scope: repo, with if conditions to skip inapplicable commands
git-finalize commits, pushes, and creates PRs for each repo
git-verify validates each repo has been pushed and has an open PR

Branch Naming

Branch names are deterministic, derived from the req key with the configured prefix:

Source	Req key	Branch
File (`requirements.md`)	`requirements`	`cliq/requirements`
File (`login-page.md`)	`login-page`	`cliq/login-page`
URL	`api-spec`	`cliq/api-spec`
Jira (`-s jira:PROJ-123`)	`PROJ-123`	`cliq/PROJ-123`

If the branch already exists, git-setup escalates — the human must delete the old branch or choose a different req key.

Choosing a Provider

The git hosting provider is auto-detected from the origin remote URL. If the URL contains bitbucket.org, Bitbucket Cloud is used; otherwise GitHub is used. No manual configuration is needed.

All git operations (branch, commit, push) are provider-agnostic — only PR creation and PR verification use the provider API. The git-finalize agent uses cliq tool run create-pr, which routes to the correct provider automatically.

If the repo has no remote (or the host is unrecognized), cliq falls back to whichever integration has credentials configured.

Troubleshooting

Error	Fix
”No GitHub token configured”	Set up GitHub credentials. See Integrations — GitHub.
”No Bitbucket credentials configured”	Set up Bitbucket credentials. See Integrations — Bitbucket Cloud.
”No Bitbucket workspace configured”	Set `workspace` in `integrations.bitbucket`. This is the workspace slug from your Bitbucket repo URLs (e.g., `m1ai` from `bitbucket.org/m1ai/repo`).
git-setup escalates with “dirty tree”	Commit or stash your changes before running `cliq run`. The working tree must be clean for git-setup to create a branch.
git-setup escalates with “branch already exists”	Delete the existing branch (`git branch -d cliq/<key>`) or use a different req key.
git-verify exec phase fails	Check `orchestrator.log` for details. Usually means the PR wasn’t created — verify your token has the right permissions with `cliq doctor test github` or `cliq doctor test bitbucket`.
Reviewer keeps routing to developer	The gate has a `max_iterations` budget (default: 3). If the developer can’t fix the issue within that budget, the reviewer escalates. Check the review findings in `.cliq/reviews/` for details.