CI Squad
Label a GitHub issue squad-ready and ContextKit automatically creates a branch, runs the full squad pipeline in GitHub Actions, and opens a draft PR — no local setup required.
Overview
CI Squad is the automated version of the Squad Workflow. Instead of running the pipeline interactively in your editor, it runs entirely in GitHub Actions — triggered by a label, completed with a PR.
Auto branch
Creates fix/issue-N-slug or feat/... automatically from the issue title
Full pipeline
Runs PO → Architect → Dev → Test → Review → Doc using Claude Code CLI inside the runner
Draft PR
Opens a draft PR linked to the issue when the pipeline completes — always human-reviewed before merge
How It Works
1Label an issue
Apply the squad-ready label to any GitHub issue. The workflow triggers immediately.
2Branch is created
GitHub Actions creates fix/issue-42-add-dark-mode (or feat/... if the title starts with "feat"). If the branch already exists, it's reused.
3Squad pipeline runs
The issue title and body are written into .contextkit/squad/handoff.md. Claude Code CLI reads squad-ci.md and runs the full pipeline non-interactively: PO → Architect → Dev → Test → Review → Doc.
4Draft PR opened
Changes are committed and pushed. A draft PR is opened with the squad summary, test results, and Closes #N linking back to the issue.
# 1. Write a clear GitHub issue # 2. Apply the label gh issue edit 42 --add-label "squad-ready" # GitHub Actions takes it from here: # → creates fix/issue-42-add-dark-mode # → runs squad pipeline (~10-20 min) # → opens draft PR linked to #42
Setup
1Install with the CI squad prompt
Run ck install and answer yes when asked about the GitHub Actions workflow. This downloads .github/workflows/squad-issue.yml and sets squad_ci_workflow: true in your config.
ck install # ... # Install GitHub Actions workflow for issue-triggered squad automation? # (requires ANTHROPIC_API_KEY secret in repo settings) › Yes
Already installed? Run ck update — it re-downloads the workflow if the flag is set.
2Add the API key secret
The workflow uses Claude Code CLI, which needs your Anthropic API key. Add it as a repository secret:
In your GitHub repo:
Settings → Secrets and variables → Actions → New repository secret
Name: ANTHROPIC_API_KEY
3Create the label
Create a squad-ready label in your repo (Issues → Labels → New label).
Writing Good Issues
The quality of the PR is directly tied to the quality of the issue. The PO agent reads the issue title and body — the more specific, the better.
✓ Good issue
Add dark mode toggle to settings page
Body:
Add a light/dark mode toggle in Settings → Appearance. Should persist across sessions (localStorage). Follow the existing theme provider pattern in components/theme-provider.tsx. Add a test verifying the preference is saved and restored on reload.
✗ Vague issue
dark mode
Body: (empty)
The PO agent will post a clarification comment and exit rather than generating a bad PR.
Tips for better results
— Include acceptance criteria directly in the issue body
— Reference specific files, components, or patterns to follow
— Mention what not to change (scope guard)
— Start the title with feat: to get a feat/... branch instead of fix/...
Clarify Flow
If the issue is too vague to produce a meaningful spec, the pipeline posts a comment on the issue with specific questions — then exits cleanly. The workflow run shows as success, not failure.
🤔 Squad needs clarification The squad pipeline needs more information before it can proceed. Please answer the following and re-apply the `squad-ready` label when ready: 1. Which settings page should the toggle appear on — the user profile page or a dedicated appearance page? 2. Should dark mode apply only to authenticated users or all visitors? 3. Is there an existing theme provider or should one be created? --- Automated by ContextKit Squad CI
After answering the questions in the issue, re-apply the squad-ready label to trigger a fresh run. Duplicate runs on the same issue are deduplicated automatically.
What to Expect
| Situation | What happens |
|---|---|
| Issue is clear | Full pipeline runs, draft PR opened (~10–20 min) |
| Issue is vague | Comment posted with questions, run exits cleanly — no PR |
| Label applied twice | Concurrency group by issue number prevents duplicate runs |
| Branch already exists | Existing branch is reused and pipeline continues from it |
No ANTHROPIC_API_KEY | Workflow fails immediately with a clear message pointing to the secret name |
| Tests fail in CI | Draft PR still opens with test results noted — never silently disappears |
Draft PRs are always human-reviewed
CI Squad never auto-merges. Every PR opens as a draft — you review, request changes if needed, and mark it ready to merge when you're satisfied.
Was this helpful?
Help us improve the documentation by sharing your feedback.