RFC: CLI-First Architecture — Migrate Squad Automation from GitHub Actions to CLI Commands

[bradygaster]

RFC: CLI-First Architecture — Migrate Squad Automation from GitHub Actions to CLI Commands

Status: Open for community feedback
Authors: Squad team (Keaton, Fenster, Kobayashi, McManus) — unanimous consensus
Related: #248 (squad triage wiring), #236 (persistent Ralph/watch)

---

Problem Statement

When you run squad init today, Squad installs GitHub Actions workflows into your repository. Some of these workflows run automatically on issue events, label changes, and cron schedules — consuming Actions minutes and producing workflow runs that the repo owner didn't explicitly ask for.

This creates three problems:

1. Trust deficit. Seeing 10-20 unexpected workflow runs in your Actions tab erodes confidence. Users wonder "what is this tool doing in my repo?" — even when the answer is benign (label sync, triage). Zero surprise automation should be the default.
2. Portability lock-in. Squad's core value is the CLI-first multi-agent runtime. But if triage, label management, and heartbeat monitoring only work via GitHub Actions, Squad can't run in containers, Codespaces, devcontainers, or any environment without Actions infrastructure.
3. Unnecessary coupling. Five of our 14 workflows encode Squad-specific logic (triage routing, label sync, assignment) that belongs in the CLI — not in YAML files committed to user repos. The remaining 9 are standard CI/CD infrastructure that should stay as Actions.

Current State

Squad ships 14 GitHub Actions workflows. After analysis, they cleanly separate into two categories:

Squad-Specific Workflows (migrate to CLI)

Workflow	Lines	Actions Min/Month	What It Does
sync-squad-labels.yml	~170	~2	Syncs team labels from config to repo
squad-triage.yml	~260	~5	Routes new issues to squad members
squad-issue-assign.yml	~160	~2	Assigns issues based on squad labels
squad-label-enforce.yml	~180	~2	Validates label conventions on issues/PRs
squad-heartbeat.yml	~170	~1	Periodic health check + stale issue ping
Total	~940	~12

CI/Release Workflows (stay as Actions) ✅

Workflow	Purpose	Why It Stays
squad-ci.yml	Continuous integration	Event-driven gate — must run on every push/PR
squad-release.yml	npm publish pipeline	Release orchestration with secrets
squad-promote.yml	Version promotion	Cross-branch coordination
squad-preview.yml	PR preview builds	Tight GitHub PR integration
squad-docs.yml	Documentation deployment	Triggered by doc changes
squad-publish.yml	Package publishing	npm registry integration
squad-insider-release.yml	Insider channel release	Separate release track
squad-insider-publish.yml	Insider package publish	Separate publish track

These 8 workflows consume ~215 Actions minutes/month and are load-bearing infrastructure. They depend on GitHub-native event triggers (push, PR, release) and secrets management that cannot be replicated CLI-side. They stay exactly where they are.

Proposed Architecture: CLI-First with Opt-In Automation

Core Principle

Squad is a CLI tool that users invoke when they want it. No background automation without explicit opt-in.

CLI Command Mapping

Each squad-specific workflow maps to a CLI command:

Workflow	CLI Command	Notes
sync-squad-labels.yml	squad labels sync	New command. Reads team config, syncs labels to repo.
squad-label-enforce.yml	squad labels enforce	New command. Validates label conventions, reports violations.
squad-triage.yml	squad triage	Enhancement of existing command. Full issue routing with comment posting.
squad-issue-assign.yml	squad assign	New command (or integrate into squad triage).
squad-heartbeat.yml	squad watch	Enhancement of existing command (#236). Already does 80% of heartbeat — needs comment posting.

The Tiered Model

Tier 1 — Manual CLI (Default)

squad init my-repo
# Installs: team config, charters, routing rules
# Installs: ZERO GitHub Actions workflows
# Result: Pure CLI experience. User runs commands when they want.

Tier 2 — Semi-Automated (Opt-In)

squad init my-repo --with-automation
# Everything from Tier 1, PLUS:
# Installs key workflows that call CLI commands on events
# User explicitly chose this — no surprises

Tier 3 — Full Automation (Enterprise)

squad init my-repo --with-full-automation
# Everything from Tier 2, PLUS:
# Cron-based heartbeat, scheduled label sync
# Full event-driven pipeline — for teams that want hands-off operation

Why This Matters

• Portability: CLI commands work everywhere — local terminal, Codespaces, devcontainers, ACA containers, CI runners. No GitHub Actions dependency for core Squad features.
• Transparency: Users see exactly what Squad does because they invoke it. No mystery workflow runs.
• Composability: squad labels sync && squad triage in a script, a Makefile, a container entrypoint — whatever fits the team's workflow.
• Existing investment: squad watch already implements ~80% of heartbeat logic. squad triage exists. We're filling gaps, not starting from scratch.

Migration Plan

Phase 1: CLI Commands + Deprecation (v0.8.22)

CLI Command	Effort	Description
squad labels sync	S (4h)	Read team config → sync labels to repo via GitHub API
squad labels enforce	S (4h)	Validate label conventions → report violations
squad triage enhancement	M (1-2d)	Add comment posting, full issue routing
squad watch enhancement	S (4h)	Add comment posting to existing watch loop (#236)
squad init refactor	M (1d)	Default to no-actions. Add --with-automation flag.

Existing workflows get a deprecation notice in their YAML headers. CHANGELOG announces the shift.

Phase 2: New Commands + Cleanup Tools (v0.8.23)

CLI Command	Effort	Description
squad assign	M (1-2d)	Issue assignment based on squad labels and routing
squad upgrade --clean-actions	S (4h)	Remove deprecated workflow files from repo
squad actions install	M (1-2d)	Opt-in: install specific workflows
squad actions uninstall	S (4h)	Remove specific workflows
squad actions status	S (4h)	Show which workflows are installed and their state

Phase 3: Workflow Removal (v0.9.0)

• Remove 5 squad-specific workflow templates from Squad's codebase entirely
• squad init no longer has any concept of squad-specific workflows
• Opt-in automation (Tier 2/3) installs thin wrapper workflows that call CLI commands

Backward Compatibility

• No breaking changes in v0.8.x. Existing workflows continue to function alongside new CLI commands.
• Deprecation warnings are added to workflow files and CLI output in v0.8.22.
• squad upgrade --clean-actions provides a one-command migration path — users don't have to manually delete files.
• Opt-in automation (Tier 2/3) ensures teams that want event-driven behavior can still have it — they just have to ask for it.

What This Does NOT Change

To be crystal clear:

• ✅ CI workflows stay. squad-ci.yml, squad-release.yml, and all publish/promote workflows are untouched.
• ✅ GitHub integration stays. Squad still uses the GitHub API for issues, labels, PRs. Only the trigger mechanism changes (CLI invocation vs. Actions event).
• ✅ Existing repos keep working. Nothing breaks until you choose to migrate.

Timeline

Milestone	Target	What Ships
v0.8.22	Next release	squad labels sync/enforce, squad triage enhancement, squad watch enhancement, squad init no-actions default, deprecation notices
v0.8.23	Following release	squad assign, squad upgrade --clean-actions, squad actions install/uninstall/status
v0.9.0	Major minor	Remove deprecated workflows from codebase. Opt-in automation via thin wrappers.

Feedback Requested

We want community input before we ship this. Specifically:

1. Does the tiered model make sense? Should squad init default to zero workflows (Tier 1), or is there a better default?

2. Which CLI commands matter most? If you could only have two of the five new commands in v0.8.22, which two?

3. How do you run Squad today? Local terminal? Codespaces? CI? This helps us prioritize the portability story.

4. Opt-in automation UX: Is --with-automation the right flag? Should it be --actions? Something else?

5. Migration friction: Is squad upgrade --clean-actions sufficient, or do you want a more guided migration (interactive prompts, dry-run mode)?

6. Cron replacement: For squad-heartbeat.yml users — would running squad watch in a long-lived container (or as a cron job on your own infra) work for your use case?

7. Anything we're missing? Edge cases, workflows you depend on, concerns about the transition?

---

This RFC reflects unanimous consensus from the Squad team. The analysis covers all 14 workflows, separating load-bearing CI/CD infrastructure (stays) from squad-specific automation (migrates to CLI). We believe this makes Squad more portable, more transparent, and more trustworthy.

— Keaton, Lead