Squad product: Default workflows burn too many Actions minutes for multi-repo customers

[diberry]

Scope: This is a Squad product issue affecting all customers who install Squad. It covers default workflow minute budgets, upgrade safety, config-driven separation, and workflow consolidation. For the specific bradygaster/squad branch protection problem, see #97.

PRD: Default Workflow Minutes Optimization & Upgrade Safety

Status: Implementation-ready
Priority: P0
Owner: Flight (Lead)
Related: #97 (CI feature flags), #84 (Config version auto-update)

---

1. Problem Statement

Squad ships 15 workflows that install into every repo. For customers running Squad on multiple repos, the default configuration burns 9,000-17,000+ GitHub Actions minutes/month -- far exceeding GitHub Free (2,000 min) and even Pro (3,000 min) limits.

Key cost drivers:

• Heartbeat cron (*/30 * * * *) is the dominant offender (~80% of total minutes): ~1,440 runs/month per repo = 1,440-2,880 min/month per repo
• squad upgrade force-overwrites all workflow customizations (double-write bug), meaning customers who tune their workflows to save minutes lose those changes on every upgrade
• No mechanism exists for customers to preserve workflow customizations across upgrades
• Private repos multiply costs: macOS runners cost 2x, Windows runners cost 10x -- a private Windows repo's heartbeat alone burns 14,400 min/month
• No config-driven separation between workflow logic (squad-owned) and runtime settings (user-owned)

This blocks Squad adoption for budget-conscious startups, SaaS platforms (multi-repo), and agencies (5-10 repos).

---

2. Goals

Goal	Target
Default install monthly minutes	~100-300 min/month per repo (Tier 0)
10 repos at Tier 0 on GitHub Free	Fits within 2,000 min/month
Upgrade preserves customer customizations	Config-driven separation + backup mechanism
Config-driven architecture	Workflow logic (squad-owned) vs runtime settings (user-owned)
Workflow consolidation	15 workflows -> 11
Zero surprise bills	squad init defaults to Tier 0 (heartbeat disabled)
Enterprise support	Tier 2 (full) recommended for Enterprise Cloud (unlimited minutes)

---

3. Current State Audit

3.1 Full Workflow Inventory (15 workflows)

Cron-triggered (always running, even if no work exists)

Workflow	Cron	Runs/month	Est. min/month
squad-heartbeat.yml	*/30 * * * * (every 30min)	1,440	1,440-2,880
squad-docs-links.yml	0 9 * * 1 (weekly Mon 9am)	4	~8

PR-triggered (per PR activity)

Workflow	Trigger	Est. min/month
squad-ci.yml	pull_request + push	240-500
squad-heartbeat.yml	Also triggers on pull_request	(included above)

Push-triggered (per merge/push)

Workflow	Est. min/month
squad-ci.yml, squad-docs.yml, squad-preview.yml	~50-100
squad-release.yml, squad-insider-*.yml, sync-squad-labels.yml	~20-50

Event-triggered only (low cost, fires on issue/PR events)

Workflow	Trigger
squad-issue-assign.yml	issues events
squad-label-enforce.yml	issues events
squad-triage.yml	issues events

Additional workflows (kept as-is)

Workflow	Purpose
squad-promote.yml	Complex orchestration
sync-squad-labels.yml	Triggered on team.md changes
squad-npm-publish.yml	Multi-job publishing
squad-docs.yml	Pages deploy
ci-rerun.yml	Manual dispatch

3.2 Per-Repo Monthly Estimate

Category	Minutes
Heartbeat cron	1,440-2,880
CI (PRs + pushes)	300-600
Event-based (issues)	~50
Docs/release/labels	~50
Total per repo	~1,800-3,600

3.3 Multi-Repo Scaling (Linux public repos, 1x multiplier)

Repos	Monthly min (est.)	GitHub Free (2,000)	GitHub Pro (3,000)
1	1,800-3,600	(!) Borderline	(!) Borderline
3	5,400-10,800	No -- 2.7-5.4x over	No -- 1.8-3.6x over
5	9,000-18,000	No -- 4.5-9x over	No -- 3-6x over
10	18,000-36,000	No -- 9-18x over	No -- 6-12x over

3.4 Private Repo Multiplier Impact

GitHub Actions charges different rates by runner OS:

Runner	Multiplier
Linux	1x
macOS	2x
Windows	10x

Impact on per-repo estimates (Tier 2 -- current defaults):

Repos	Linux (1x)	macOS Private (2x)	Windows Private (10x)
1	1,800-3,600	3,600-7,200	18,000-36,000
5	9,000-18,000	18,000-36,000	90,000-180,000
10	18,000-36,000	36,000-72,000	180,000-360,000

Key insight: Most Squad workflows use ubuntu-latest (1x), but if a customer's CI runs on Windows or macOS runners, the multiplier applies to ALL minutes including Squad's workflows.

Enterprise Cloud note: GitHub Enterprise Cloud provides unlimited minutes on GitHub-hosted runners. Enterprise customers should use Tier 2 (full monitoring) freely. Tier 0/1 are optimized for Free/Pro limits.

3.5 Double-Write Bug in Upgrade Logic

Location: packages/squad-cli/src/cli/core/upgrade.ts:519-553

The upgrade logic writes each workflow file twice:

1. Line 521-533: Manifest loop writes all overwriteOnUpgrade: true files from TEMPLATE_MANIFEST (lines 184-248), which includes ALL 11 workflows
2. Line 539-553: Separate readdirSync loop writes all .yml files from templates/workflows/ again

Consequences:

• If the first write preserves a customer's commented-out cron, the second write may restore it
• writeWorkflowFile() may strip comments or apply different formatting
• Any transformation applied twice risks data loss or corruption

Customer action	What upgrade does
Changed heartbeat cron to every 6h	Reset to */30 * * * *
Added concurrency groups to CI	Removed
Added path filters to reduce runs	Removed
Disabled cron via commenting	Re-enabled
Added feature flag checks (vars.SQUAD_*)	Removed

---

4. Tiered Defaults

Squad ships with minimal minutes by default and lets users opt into higher tiers.

Tier 0 -- Zero-cost (default for squad init)

• Heartbeat: cron disabled, event-triggers only (issues, PRs, workflow_dispatch)
• CI: runs on pull_request only (not push)
• Docs link check: disabled (manual via workflow_dispatch)
• Labels/triage/assign: event-triggered only (already cheap)
• Est: ~100-300 min/month per repo

Tier 1 -- Light monitoring

• Heartbeat: cron every 6 hours (0 */6 * * *)
• CI: PR + push to default branch
• Docs link check: weekly
• Est: ~400-800 min/month per repo

Tier 2 -- Full monitoring (current default, legacy)

• Heartbeat: every 30 min
• CI: PR + push
• Everything enabled
• Est: ~1,800-3,600 min/month per repo

Scaling Table by Tier x Repos x Plan

Repos	Tier 0 (min/mo)	Tier 1 (min/mo)	Tier 2 (min/mo)	Free (2,000)	Pro (3,000)
1	100-300	400-800	1,800-3,600	Yes -- T0/T1	Yes -- T0/T1
3	300-900	1,200-2,400	5,400-10,800	Yes -- T0	Yes -- T0/T1
5	500-1,500	2,000-4,000	9,000-18,000	Yes -- T0	(!) T0 only
10	1,000-3,000	4,000-8,000	18,000-36,000	(!) T0 only	(!) T0 only

Private repo multiplier: Multiply above by 2x (macOS) or 10x (Windows). For a Windows private 5-repo shop at Tier 0: ~500-1,500 min/month x 10 = 5,000-15,000 min/month for Windows CI jobs. Squad's own workflows run on Linux (1x), so the multiplier primarily affects customer CI jobs.

Enterprise Cloud: Unlimited minutes on GitHub-hosted runners. Use Tier 2 freely.

Init UX

During squad init, surface the tier selection:

Choose a monitoring tier:
  [0] Tier 0 -- Zero-cost (default): ~100-300 min/mo, heartbeat disabled
  [1] Tier 1 -- Light: ~400-800 min/mo, heartbeat every 6h
  [2] Tier 2 -- Full: ~1,800-3,600 min/mo, heartbeat every 30m (legacy default)

---

5. Architecture: Config-Driven Separation

Principle

Separate workflow logic (squad-owned, safe to overwrite on upgrade) from runtime settings (user-owned, preserved on upgrade).

• Workflow .yml files contain only logic -> overwriteOnUpgrade: true
• .squad/config.json contains preferences -> overwriteOnUpgrade: false
• Workflows read their schedules and feature flags from config at runtime

Config Schema

.squad/config.json gains a ci section:

{
  "version": 1,
  "ci": {
    "tier": "zero",
    "heartbeatCron": "",
    "features": {
      "eslint": true,
      "audit": false,
      "coverage": 0,
      "deletionGuard": true,
      "spellcheck": false
    }
  }
}

Field	Type	Default	Description
ci.tier	"zero" | "light" | "full"	"zero"	Monitoring tier preset
ci.heartbeatCron	string	"" (disabled)	Custom cron expression, overrides tier default
ci.features.eslint	boolean	true	Run ESLint in CI
ci.features.audit	boolean	false	Run npm audit in CI
ci.features.coverage	number	0	Coverage threshold (0 = disabled)
ci.features.deletionGuard	boolean	true	Prevent accidental large deletions
ci.features.spellcheck	boolean	false	Run spellcheck in CI

Precedence Order

repo variable (SQUAD_HEARTBEAT_CRON, etc.)
  > .squad/config.json (ci.tier, ci.heartbeatCron, ci.features.*)
  > workflow default (disabled for Tier 0)

Repo variables are overrides (not checked into source). Config.json is the primary source of truth (versioned, portable). Workflow defaults are the fallback (safe for missing config).

Workflow Runtime Integration

Workflows read config at runtime:

# squad-heartbeat.yml
jobs:
  heartbeat:
    steps:
      - name: Read CI config
        id: config
        run: |
          CRON=$(jq -r '.ci.heartbeatCron // ""' .squad/config.json 2>/dev/null || echo "")
          echo "cron=$CRON" >> $GITHUB_OUTPUT

This way: upgrade overwrites the workflow logic (safe), but the workflow reads its schedule from config.json (user-owned, preserved).

---

6. Upgrade Safety

6.1 Fix Double-Write Bug

Remove workflows from TEMPLATE_MANIFEST entirely. The readdirSync loop at line 539 already handles all workflow files. The manifest entries are redundant and cause double-write.

// templates.ts -- remove workflow entries from TEMPLATE_MANIFEST
- { source: 'workflows/squad-ci.yml', destination: '../.github/workflows/squad-ci.yml', overwriteOnUpgrade: true },
- { source: 'workflows/squad-heartbeat.yml', destination: '../.github/workflows/squad-heartbeat.yml', overwriteOnUpgrade: true },
- // ... (remove all workflow entries)

The readdir loop stays as the single source of truth for workflow upgrades.

6.2 # squad-custom: true Header

If a workflow file contains the header # squad-custom: true, upgrade skips overwriting that file entirely. This is an opt-in escape hatch for customers who heavily customize workflows.

6.3 Backup Before Overwrite

Modified files are backed up before overwriting:

.squad/upgrade-backups/{version}/squad-heartbeat.yml
.squad/upgrade-backups/{version}/squad-ci.yml

Logic:

1. For each workflow file to be written, check if destination exists
2. If file has # squad-custom: true header -> skip entirely, log warning
3. If file differs from template -> backup to .squad/upgrade-backups/{version}/, then overwrite
4. If file matches template -> overwrite silently (no noise)

6.4 Config.json in Manifest

Add .squad/config.json to TEMPLATE_MANIFEST as user-owned:

{
  source: 'config.json',
  destination: 'config.json',
  overwriteOnUpgrade: false,  // USER-OWNED -- never overwrite
  description: 'Squad configuration (CI tier, feature flags, model prefs)',
}

• Initialized by squad init with Tier 0 defaults
• Never touched on upgrade (user-owned)
• Workflows gracefully handle missing/malformed config (fall back to defaults)

---

7. Workflow Consolidation (15 -> 11)

Overlaps Found

1. Issue event workflows (3 -> 1)

squad-triage.yml + squad-label-enforce.yml + squad-issue-assign.yml all trigger on issues:labeled. They form a sequential chain: squad label -> triage assigns squad:{member} label -> issue-assign posts comment. Merge into single squad-issue-workflow.yml with conditional jobs.

2. Insider release (2 -> 1)

squad-insider-release.yml + squad-insider-publish.yml both trigger on push:insider. Different purposes (git tag vs npm publish) but can be sequential jobs via needs:.

3. Branch release pipelines (3 -> 1)

squad-release.yml (main), squad-preview.yml (preview), squad-insider-release.yml (insider) all validate/release on push to a branch. Use matrix or conditionals in a single squad-branch-release.yml.

4. @Copilot assignment is tripled

Three workflows independently implement @copilot assignment: squad-triage.yml, squad-issue-assign.yml, squad-heartbeat.yml. Extract to a single reusable workflow (_assign-copilot.yml) called via workflow_call.

5. Heartbeat duplicates triage

squad-heartbeat.yml re-triages issues every 30 minutes that squad-triage.yml already handled on the label event. Creates duplicate comments. Heartbeat should only repair orphaned labels, not redo triage.

Consolidation Map

New workflow	Replaces	Risk
squad-issue-workflow.yml	triage + label-enforce + issue-assign	Low -- conditional if: per job
squad-branch-release.yml	release + preview + insider-release	Medium -- needs per-branch conditionals
squad-insider-full.yml	insider-release + insider-publish	Low -- sequential needs: chain
squad-heartbeat.yml (modified)	Remove duplicate triage logic	Low -- just delete a job
_assign-copilot.yml (reusable)	Extract @copilot logic from 3 files	Low -- called via workflow_call

Keep as-is (well-isolated)

• squad-ci.yml -- core CI
• squad-promote.yml -- complex orchestration
• sync-squad-labels.yml -- distinct trigger (team.md changes)
• squad-npm-publish.yml -- complex multi-job publishing
• squad-docs.yml -- Pages deploy
• squad-docs-links.yml -- weekly link check
• ci-rerun.yml -- manual dispatch

Minutes Impact

Consolidation doesn't directly reduce minutes (same work runs either way), but it:

• Eliminates duplicate runs -- heartbeat won't re-triage already-triaged issues
• Reduces workflow startup overhead -- 1 workflow with 3 jobs starts faster than 3 separate workflows
• Simplifies feature flags -- fewer files to add vars.SQUAD_* checks to
• Reduces upgrade surface -- fewer workflow files in template manifest = fewer things to overwrite

---

8. Implementation Phases

Phase 1 -- P0: Upgrade Safety & Config Foundation

Dependencies: None (start here)

1. Fix double-write bug -- Remove workflow entries from TEMPLATE_MANIFEST in templates.ts. Keep readdir loop as single source of truth.
2. Add config.json template -- Create template with CI tier defaults (tier: "zero", heartbeatCron: ""). Add to TEMPLATE_MANIFEST with overwriteOnUpgrade: false.
3. Add upgrade safety mechanism -- Implement # squad-custom: true header check + backup to .squad/upgrade-backups/{version}/ in upgrade.ts.

Phase 2 -- P0: Ship Tier 0 Defaults

Dependencies: Phase 1 (config.json must exist)

4. Update heartbeat template -- Ship with cron disabled by default. Workflow reads cron from .squad/config.json at runtime.
5. Update CI template -- Default to pull_request only (no push trigger). Configurable via config.json.
6. Init UX -- squad init surfaces tier selection, writes choice to .squad/config.json. Prints: "CI tier: zero (heartbeat disabled, ~100-300 min/month). Change in .squad/config.json"

Phase 3 -- P1: Workflow Consolidation (15 -> 11)

Dependencies: Phase 2 (Tier 0 defaults stabilized)

7. Merge issue event workflows (3 -> 1): squad-issue-workflow.yml
8. Merge release workflows (3 -> 1): squad-branch-release.yml
9. Merge insider workflows (2 -> 1): squad-insider-full.yml
10. Extract @copilot assignment to reusable _assign-copilot.yml
11. Remove duplicate triage from heartbeat

Phase 4 -- P1: Tests for Upgrade Preservation

Dependencies: Phases 1-2 (mechanism must be implemented first)

12. Test: config.json preserved on upgrade -- Init -> write custom config -> upgrade -> assert config unchanged
13. Test: squad-custom header skips overwrite -- Init -> add header -> modify workflow -> upgrade -> assert preserved
14. Test: modified workflows backed up -- Init -> modify workflow -> upgrade -> assert backup exists in .squad/upgrade-backups/
15. Test: user-owned files not overwritten -- Init -> modify ceremonies.md -> upgrade -> assert unchanged

Phase 5 -- P2: Docs & Polish

Dependencies: Phases 1-4 complete

16. Update cost analysis docs with private repo multiplier tables
17. Add enterprise guidance -- "Enterprise Cloud = unlimited minutes. Use Tier 2 freely."
18. Upgrade transition playbook -- Document how v0.8.x customers transition: check .squad/upgrade-backups/ for preserved files
19. Config schema documentation -- Add config.schema.json for validation

---

9. Approach Comparison

Approach	Description	Best for	Brady can toggle?
Config tiers	.squad/config.json with ci.tier	Teams wanting preset packages	Yes -- Edit one field
Feature flags (repo vars)	SQUAD_HEARTBEAT_CRON, SQUAD_CI_ON_PUSH	Per-repo overrides, not in source	Yes -- Set in repo settings
Heartbeat ships disabled	Template ships with cron commented out	Immediate relief, no config needed	(!) Must edit YAML
Config + flags (recommended)	Config.json as primary, repo vars as override	Full flexibility, versioned + override	Yes -- Either path works

Recommendation: Config.json as primary (versioned, portable) + repo variables as override (per-environment). This gives teams a checked-in source of truth with per-repo escape hatches.

---

10. Acceptance Criteria

• squad init creates repos with Tier 0 defaults (~100-300 min/month per repo)
• squad init surfaces tier selection to user during setup
• squad upgrade preserves customer workflow customizations via config-driven separation
• squad upgrade backs up modified workflows to .squad/upgrade-backups/{version}/ before overwriting
• squad upgrade skips files with # squad-custom: true header
• Double-write bug is fixed (workflows written once, not twice)
• .squad/config.json initialized by squad init with CI tier defaults
• .squad/config.json marked overwriteOnUpgrade: false in manifest
• Workflows read runtime settings from config.json (not hardcoded)
• Precedence order works: repo variable > config.json > default
• 10 repos at Tier 0 fits within GitHub Free (2,000 min/month)
• Workflow count reduced from 15 to 11
• No duplicate @copilot assignment logic across workflows
• Tests verify upgrade preservation behavior (config preserved, header skip, backup created)
• Private repo multiplier documented in cost analysis
• Enterprise Cloud guidance documented (use Tier 2 freely)

---

11. Related Issues

• bradygaster/squad: Branch protection blocking merges + CI gap analysis #97 -- CI feature flags (repo variables approach, pairs with config-driven tiers)
• bug: squad config version not auto-updated during upgrade #84 -- Config version auto-update (config.json schema migration on upgrade)

---

Consolidated from original issue analysis + Flight review + FIDO quality review + consolidation analysis + blocker fix proposals. All findings, tables, and numbers sourced from issue #98 comments.

[diberry]

VERDICT: APPROVE WITH CONDITIONS

Flight review of issue #98 -- Default workflows burn too many Actions minutes.

Analysis Summary

1. Problem Framing -- (ok) Accurate
The minutes audit is solid. Heartbeat at every-30-min = ~1,440 runs/month/repo is the correct scale. The multi-repo scaling math (5 repos = 9k-18k min/month, exceeding Free/Pro limits 4.5-9x) is the real friction point. This blocks Squad adoption for budget-conscious teams and SaaS customers on shared GitHub orgs. Problem is real and urgent.

2. Tiered Defaults -- (ok) Right Structure
Tier 0/1/2 is the right mental model:

• Tier 0 (100-300 min/mo): Safe default, fits Free tier
• Tier 1 (400-800 min/mo): Light monitoring, safe for 3-5 repos
• Tier 2 (1,800-3,600 min/mo): Kept for power users

However, missing a critical gap: GitHub Enterprise customers have different minute economics (unlimited for large enterprises, tiered for smaller ones). Proposal should note that Tier selection should account for org plan. Add callout to docs during implementation.

3. Implementation: Option B + C -- (ok) Correct Call
Option B (heartbeat ships disabled by default) + Option C (repo variables) is the right two-track approach:

• B handles the 80% case: Cron disabled = zero surprise bills on day 1
• C enables the 20% case: Opt-in via variables for customers who need cloud heartbeat
• Local squad watch as free alternative is excellent -- emphasize this in release notes

Architectural reason this works: heartbeat is the dominant cost driver (40-80% of total). Disabling it by default solves the problem immediately. Everything else (CI, docs, labels) scales reasonably and can stay enabled.

4. Upgrade Reset Problem -- (ok) Properly Identified
This is the critical blocker that I flagged in my own architecture notes. Every squad upgrade force-overwrites workflows, erasing customer customizations. The issue correctly identifies this would sabotage the fix: even if we change defaults to Tier 0, any existing customer upgrading gets reset back to Tier 2.

5. Config-Driven Separation (Option C for Upgrade) -- (ok) Architecturally Sound
Moving schedules + feature flags into .squad/config.json (user-owned, overwriteOnUpgrade: false) is the right approach. This separates concerns:

• Workflow files (.yml): Logic only, safe to overwrite (templates version them)
• Config (.squad/config.json): Preferences only, never touched on upgrade

This composes well with the existing template manifest system because:

• Template manifest marks workflows with overwriteOnUpgrade: true
• Config reads via ${{ vars.SQUAD_HEARTBEAT_CRON }} etc. at workflow runtime
• Upgrade logic skips .squad/config.json (already does for user files)

One refinement needed (see CONDITIONS below): Decide whether to use repo variables OR a config file as the single source of truth. Currently the proposal mixes both. For maintainability, recommend one path: repo variables with CI-time rendering of .squad/config.json.

6. Multi-Repo Scaling -- (ok) Adequately Addressed
10 repos at Tier 0 = ~1,000-3,000 min/month fits Free tier. This is the key win. Scale math is sound.

7. Missing Considerations

GAP A: Private vs Public Repo Minute Multipliers
GitHub charges 2x minute cost for private repos. Issue doesn't mention this. A customer with 3 public + 2 private repos at Tier 0 pays ~1,500-2,500 min/month, not the 500-1,500 estimated. Add a note to the implementation plan.

GAP B: Enterprise vs Free/Pro Economics
Enterprises have unlimited minutes (large plans) or per-seat tiering. Tier 0/1/2 should be scoped as "GitHub Free/Pro default" with a callout that Enterprise customers may want Tier 2. Document this during init.

GAP C: Initial Setup Messaging
Squad init should warn: "You're starting Tier 0 (minimal cost, ~100-300 min/month per repo). Uncomment heartbeat cron in .github/workflows/squad-heartbeat.yml or set SQUAD_HEARTBEAT_CRON to enable cloud monitoring."

GAP D: Upgrade Guidance
When customers upgrade, we should surface: "Your workflows are preserved. To opt into higher monitoring tiers, edit .squad/config.json and set tier flags." Otherwise they'll stay on Tier 0 indefinitely (which is fine, but worth clarifying).

---

CONDITIONS FOR APPROVAL

Before implementation, issue must be updated with:

1. Config vs Variables Clarity -- Decide the single source of truth for feature flags. Recommendation:

   • Repo variables are the primary mechanism (simpler, no file to manage)
   • .squad/config.json is optional override (for teams that want versioned config)
   • Upgrade flow: squad upgrade regenerates config from template, user edits with their preferences, workflow reads variables
   • Update issue to specify this clearly.

2. Private/Public Repo Multiplier -- Add footnote: "Minute estimates assume public repos. Private repos cost 2x. 5 repos (3 public + 2 private) at Tier 0 => 1,500-2,500 min/month."

3. Enterprise Tier Guidance -- Add section: "GitHub Enterprise customers with unlimited actions should prefer Tier 2 (full monitoring). Tier 0/1 are optimized for Free/Pro limits."

4. Init UX Callout -- Specify: During squad init, surface the tier selection to the user. Recommendation:
   Choose a monitoring tier: [1] Tier 0 -- Zero-cost (default): ~100-300 min/mo, heartbeat disabled [2] Tier 1 -- Light: ~400-800 min/mo, heartbeat every 6h [3] Tier 2 -- Full: ~1,800-3,600 min/mo, heartbeat every 30m (legacy default)
   This makes the choice explicit and documents the cost upfront.

5. Upgrade Transition Playbook -- Add section describing how existing v0.8.x customers transition:

   • squad upgrade reads their existing cron from workflows
   • Script detects which tier they're currently on (heuristic: cron frequency)
   • Suggests tier change or confirms preference
   • Applies config and preserves customizations
   • This prevents silent downgrades or surprise resets.

---

What I Love About This Issue

(ok) Identifies root cause clearly: Heartbeat cron is the problem, not "too many workflows."

(ok) Real customer pain: Multi-repo scaling is a hard blocker for SaaS and agencies. Fixing this unblocks a whole segment.

(ok) Solves upgrade sabotage: Option C (config-driven) elegantly fixes the "upgrade erases customizations" problem, which is a separate but equally critical issue.

(ok) Two-track solution: Option B (disable by default) + Option C (feature flags) gives immediate relief + flexibility.

(ok) Local alternative: squad watch as free heartbeat replacement is smart product thinking.

---

Implementation Priority

This is P0. Block it at the top of the next wave. Unblock adoption for:

• Budget-conscious startups (GitHub Free tier)
• SaaS platforms (multi-repo, cost-aware)
• Agencies (5-10 repos, sensitive to per-repo costs)

Pair with #97 (feature flag framework) as a linked dependency.

---

Related Issue: Upgrade Reset Pattern

This issue surfaces a systemic upgrade problem beyond workflows. Consider filing a parallel issue for the broader "preserve user customizations on upgrade" pattern -- it affects not just workflows, but any template-driven file. Option C (config separation) is the architectural fix, but it should be documented as a reusable pattern.

---

Recommendation: Merge this issue with #97 (feature flags). They're solving the same system (per-repo configuration), just different layers (feature flags in #97, workflow scheduling in #98). Combined they form a complete "cost control + feature management" system.

[diberry]

QUALITY REVIEW: Issue #98 -- Default Workflows Actions Minutes

Reviewer: FIDO (Quality Owner)
Date: 2026-03-26
Issue: #98
Verdict: (!) NEEDS WORK

---

Executive Summary

Issue #98 proposes a critical system change to reduce GitHub Actions minutes for multi-repo customers by disabling heartbeat cron by default. The proposed solution is sound in intent but has 5 blocking quality issues that must be resolved before merge:

1. Double-write on upgrade -- workflows written twice (manifest loop + separate loop)
2. No test for customization preservation -- upgrade safety not validated
3. Config file not in manifest -- config.json exists but isn't upgrade-safe
4. Private repo minute multiplier unaccounted for -- cost analysis incomplete
5. No rollback/safety mechanism -- customers who upgrade get silently reset

---

Detailed Findings

1. (!) CRITICAL: Double-Write Vulnerability in Upgrade Logic

Location: packages/squad-cli/src/cli/core/upgrade.ts:519-553

The Issue:
The upgrade logic writes each workflow file TWICE:

Line 521: Manifest loop writes all overwriteOnUpgrade: true files

• TEMPLATE_MANIFEST (lines 184-248) includes ALL 11 workflows with overwriteOnUpgrade: true
• Upgrade logic (line 521) filters these and copies each

Line 543-549: Separate workflows loop writes all .yml files again

• readdir workflows/ directory
• For each .yml, calls writeWorkflowFile()
• This writes squad-heartbeat.yml a SECOND time

The Problem:

• If the first write includes a customer's commented-out cron, the second write may restore it
• writeWorkflowFile() may strip comments or apply different formatting, overwriting the first write
• Any transformation applied twice risks data loss or corruption
• This violates the principle of single responsibility in file operations

Recommendation: Consolidate. Either:
A) Remove workflows from TEMPLATE_MANIFEST (they're already handled by readdir loop)
B) Skip the separate workflows loop if manifest already handled them

---

2. (!) CRITICAL: No Test for Upgrade Preserves User Customizations

Location: test/cli/upgrade.test.ts

Current Test Coverage:

• (ok) "should overwrite squad-owned template files" (line 79-95)
• (ok) "should preserve user state files (team.md, decisions/)"
• Γ¥î MISSING: Customer modifies heartbeat cron ΓåÆ upgrade preserves it
• Γ¥î MISSING: Customer adds concurrency groups to CI ΓåÆ upgrade preserves them
• Γ¥î MISSING: Customer disables workflow via comment ΓåÆ upgrade re-enables it

The Problem:
Issue #98 explicitly states:

"Every squad upgrade force-overwrites all workflows, wiping any customer customizations."

This is the CORE PROBLEM we're trying to solve. But we have NO test that validates the fix works.

What should be tested:

1. Create a squad
2. Modify squad-heartbeat.yml: change cron from */30 to */6h
3. Run upgrade
4. Assert the cron is PRESERVED (not reset to */30)
5. Repeat for other customizations (concurrency, path filters, etc.)

Recommendation: Add to upgrade.test.ts:

it('should preserve workflow customizations on upgrade', async () => {
  const workflowPath = join(TEST_ROOT, '.github/workflows/squad-heartbeat.yml');
  let content = await readFile(workflowPath, 'utf-8');
  
  // Customer changes cron
  content = content.replace(/cron: '\*\/30/, "cron: '0 */6");
  await writeFile(workflowPath, content);
  
  // Upgrade
  await runUpgrade(TEST_ROOT);
  
  // Customer's cron MUST be preserved
  const upgraded = await readFile(workflowPath, 'utf-8');
  expect(upgraded).toContain("cron: '0 */6");
});

---

3. (!) CRITICAL: Config File Not in Upgrade Manifest

Location:

• .squad/config.json is used by multiple commands but NOT in TEMPLATE_MANIFEST
• Used in: init-remote.ts, link.ts, economy.ts, doctor.ts, extract.ts
• Never initialized by default init
• Never upgraded/migrated

The Problem:
Issue proposes config-driven approach:

{ "ci": { "tier": "zero" } }

But:

1. No TEMPLATE_MANIFEST entry = no upgrade handling
2. Not initialized by default = customers never get it unless they run init-remote/link
3. Schema changes in future versions won't be migrated on upgrade
4. If workflow reads from config and config is missing = silent failure

Edge Cases Not Handled:

• What if config.json is missing when workflow runs?
• What if config is malformed (invalid JSON)?
• What if config has cron: "*/6h" but workflow expects YAML schedule array?
• What if user deletes config but keeps workflows?
• What if upgrade changes config schema?

Recommendation:

• Add .squad/config.json to TEMPLATE_MANIFEST as user-owned (overwriteOnUpgrade: false)
• Initialize default config.json during squad init (not just in init-remote)
• Document config schema (add config.schema.json)
• Workflows should gracefully handle missing/invalid config (use safe defaults)

---

4. 🟡 HIGH: Private Repo Minute Multiplier Not Accounted For

Location: Issue #98 cost analysis

The Problem:
GitHub Actions charges different rates by runner type:

• Public repos, Linux: 1x
• Private repos, Linux: 1x
• Private repos, macOS: 2x
• Private repos, Windows: 10x

Issue analysis lists: "Heartbeat cron: 1,440-2,880 min/month"

But for a private repo on Windows (common for .NET projects):

• Actual cost = 1,440 min ├ù 10x = 14,400 minutes/month per repo
• 5 repos = 72,000 minutes/month (vs. Free tier of 2,000)
• 10x higher than the analysis suggests

Impact:

• Cost analysis incomplete for real-world private repo + expensive runner scenarios
• Tier 0 estimate (~100-300 min/month) only correct for Linux public repos
• Recommendation still valid, but analysis should be complete

Recommendation:

• Update issue cost table to show runner type multipliers
• Note: "Linux public = 1x, macOS private = 2x, Windows private = 10x"
• For Windows private 5-repo shop: Tier 0 still ~500-1500 min/month (within Free 2,000)
• Conclusion unchanged, but analysis is complete

---

5. (!) CRITICAL: No Upgrade Safety Mechanism or Warning

Location: Upgrade logic, lines 519-553

The Problem:
Current upgrade: silently overwrites all workflows with no warning.

Scenario:

1. Customer A: "I modified heartbeat to every 6 hours"
2. Runs squad upgrade
3. Gets reset to default silently
4. No notification, no backup, no way to recover

This violates quality principle: "No silent data loss"

Recommendation - Pick one:
A) Pre-upgrade check: Scan workflows for modifications, warn user before overwriting
B) Backup before write: Create .github/workflows/.backup/ with pre-upgrade copies
C) Config-driven approach: Workflows read cron from .squad/config.json (not hardcoded), so upgrade doesn't touch the config
D) Mark customized files: If workflow has # squad-custom: true header, skip overwrite

Option C (config-driven) is cleanest and pairs with #97 (feature flags).

---

6. 🟡 MEDIUM: Config-Driven Cron Approach Not Fully Designed

Location: Issue suggests option C: config.json + feature flags

Questions Not Answered:

1. What if config.json is missing? Workflow default (cron disabled, or every 30 min)?
2. What if config.json is malformed? Silent fallback or error?
3. If both repo variables (from bradygaster/squad: Branch protection blocking merges + CI gap analysis #97) and config.json exist: which takes precedence?
4. Workflow parsing: vars.SQUAD_HEARTBEAT_CRON from GitHub or .squad/config.json from disk?

Precedence should be documented:

repo variable (SQUAD_HEARTBEAT_CRON) 
  > config.json (ci.tier or ci.schedules.heartbeat)
  > workflow default (disabled for Tier 0)

Recommendation:

• Add to .squad/decisions/ when merging: "Feature flag precedence"
• Document in workflow comments: "Config precedence: vars > config.json > defaults"
• Add validation in .squad/config.schema.json

---

Feature Flag Interaction (Issue #97)

Finding: #97 proposes repo variables for feature flags.

If they use the same mechanism (repo variables):

• Both want to control heartbeat scheduling
• Both want to control CI on push
• Potential overlap/conflict

Recommendation:
When merging both, clarify in decisions:

• Does Squad product: Default workflows burn too many Actions minutes for multi-repo customers #98 create config.json approach?
• Does bradygaster/squad: Branch protection blocking merges + CI gap analysis #97 create repo variables approach?
• Or does Squad product: Default workflows burn too many Actions minutes for multi-repo customers #98 use repo variables from bradygaster/squad: Branch protection blocking merges + CI gap analysis #97?

---

Blocking vs. Non-Blocking Issues

Issue	Severity	Must Fix	Effort
Double-write in upgrade.ts	CRITICAL	YES	30 min
No customization preservation test	CRITICAL	YES	45 min
config.json not in manifest	CRITICAL	YES	1 hour
Private repo cost multiplier	HIGH	NO	15 min
No upgrade safety mechanism	CRITICAL	YES	1-2 hours
Config precedence undocumented	MEDIUM	NO	15 min

---

VERDICT: (!) NEEDS WORK

The intent is correct. Disabling heartbeat by default is the right decision for multi-repo customers.

But the implementation has critical gaps:

1. Double-write vulnerability -- upgrade writes workflows twice
2. No test for the core promise -- "customizations are preserved" is untested
3. Config file orphaned -- not part of upgrade system
4. Silent data loss -- customers lose modifications with no warning
5. Incomplete analysis -- private repo costs not accounted for

Do NOT merge until:

• (ok) Fix double-write (remove workflows from manifest OR skip readdir loop)
• (ok) Add test for upgrade-preserves-customizations
• (ok) Add config.json to manifest, initialize in init
• (ok) Add upgrade safety warnings or backup mechanism
• (ok) Update cost analysis with private repo multipliers (or mark as incomplete)

Re-review estimate: ~3-4 hours to fix + 30 min validation.

---

FIDO's Recommendation: This is solid foundational work. Land it carefully with proper safety gates. The multi-repo cost problem is real, and Tier 0 by default is the right call. But ship the upgrade safety mechanism alongside the feature flag changes, not after.

[diberry]

---

Workflow Consolidation Analysis

Current: 15 workflows. Proposed: 11 (with extracted shared logic)

Overlaps Found

1. Issue event workflows (3 files → 1)
squad-triage.yml + squad-label-enforce.yml + squad-issue-assign.yml all trigger on issues:labeled. They form a sequential chain: squad label ΓåÆ triage assigns squad:{member} label ΓåÆ issue-assign posts comment. Safe to merge into single squad-issue-workflow.yml with conditional jobs.

2. Insider release (2 files → 1)
squad-insider-release.yml + squad-insider-publish.yml both trigger on push:insider. Different purposes (git tag vs npm publish) but can be sequential jobs via needs:.

3. Branch release pipelines (3 files → 1)
squad-release.yml (main), squad-preview.yml (preview), squad-insider-release.yml (insider) all validate/release on push to a branch. Could use matrix or conditionals in a single squad-branch-release.yml.

4. @Copilot assignment is tripled
Three workflows independently implement @copilot assignment: squad-triage.yml, squad-issue-assign.yml, squad-heartbeat.yml. Should be extracted to a single reusable workflow.

5. Heartbeat duplicates triage
squad-heartbeat.yml re-triages issues every 30 minutes that squad-triage.yml already handled on the label event. Creates duplicate comments. Heartbeat should only repair orphaned labels, not redo triage.

Consolidation Map

New workflow	Replaces	Risk
squad-issue-workflow.yml	triage + label-enforce + issue-assign	Low -- conditional if: per job
squad-branch-release.yml	release + preview + insider-release	Medium -- needs per-branch conditionals
squad-insider-full.yml	insider-release + insider-publish	Low -- sequential needs: chain
squad-heartbeat.yml (modified)	Remove duplicate triage logic	Low -- just delete a job
_assign-copilot.yml (reusable)	Extract @copilot logic from 3 files	Low -- called via workflow_call

Keep as-is (well-isolated)

• squad-ci.yml (core CI)
• squad-promote.yml (complex orchestration)
• sync-squad-labels.yml (distinct trigger: team.md changes)
• squad-npm-publish.yml (complex multi-job publishing)
• squad-docs.yml (Pages deploy)
• squad-docs-links.yml (weekly link check)
• ci-rerun.yml (manual dispatch)

Minutes impact of consolidation

Consolidation doesn't directly reduce minutes (same work runs either way), but it:

• Eliminates duplicate runs -- heartbeat won't re-triage already-triaged issues
• Reduces workflow startup overhead -- 1 workflow with 3 jobs starts faster than 3 separate workflows
• Simplifies feature flags -- fewer files to add vars.SQUAD_* checks to
• Reduces upgrade surface -- fewer workflow files in template manifest = fewer things to overwrite

[diberry]

Proposed Fixes for Review Blockers

Blocker 1: Double-Write Vulnerability (FIDO Critical)

Problem: upgrade.ts writes workflows twice -- once via TEMPLATE_MANIFEST loop (line 521-533), once via separate readdirSync loop (line 539-553).

Fix: Remove workflows from TEMPLATE_MANIFEST entirely. The readdir loop at line 539 already handles all workflow files. The manifest entries are redundant and cause double-write.

// templates.ts -- remove workflow entries from TEMPLATE_MANIFEST
- { source: 'workflows/squad-ci.yml', destination: '../.github/workflows/squad-ci.yml', overwriteOnUpgrade: true, ... },
- { source: 'workflows/squad-heartbeat.yml', destination: '../.github/workflows/squad-heartbeat.yml', overwriteOnUpgrade: true, ... },
- // ... (remove all workflow entries)

The readdir loop stays as the single source of truth for workflow upgrades. This also reduces manifest size.

---

Blocker 2: No Test for Customization Preservation (FIDO Critical)

Fix: Add test cases to upgrade.test.ts:

// Test 1: Config-driven values survive upgrade
test('upgrade preserves .squad/config.json ci settings', async () => {
  // Setup: init, write custom config with ci.tier = 'zero'
  // Act: run upgrade
  // Assert: config.json still has ci.tier = 'zero'
});

// Test 2: User-owned files not overwritten
test('upgrade does not overwrite user-owned files', async () => {
  // Setup: init, modify ceremonies.md and routing.md
  // Act: run upgrade
  // Assert: ceremonies.md and routing.md unchanged
});

// Test 3: squad-custom header skips overwrite (if Option B implemented)
test('upgrade skips workflows with squad-custom header', async () => {
  // Setup: init, add "# squad-custom: true" to squad-heartbeat.yml, change cron
  // Act: run upgrade
  // Assert: heartbeat still has custom cron
});

---

Blocker 3: config.json Not in Upgrade Manifest (FIDO Critical)

Problem: .squad/config.json exists at runtime but isn't initialized by squad init with a schema, and isn't in the template manifest.

Fix: Two parts:

A. Add config.json template with CI defaults:

{
  "version": 1,
  "ci": {
    "tier": "zero",
    "heartbeatCron": "",
    "features": {
      "eslint": true,
      "audit": false,
      "coverage": 0,
      "deletionGuard": true,
      "spellcheck": false
    }
  }
}

B. Add to TEMPLATE_MANIFEST as user-owned:

{
  source: 'config.json',
  destination: 'config.json',
  overwriteOnUpgrade: false,  // USER-OWNED -- never overwrite
  description: 'Squad configuration (CI tier, feature flags, model prefs)',
}

C. Workflows read config at runtime:

# squad-heartbeat.yml
jobs:
  heartbeat:
    steps:
      - name: Read CI config
        id: config
        run: |
          CRON=$(jq -r '.ci.heartbeatCron // ""' .squad/config.json 2>/dev/null || echo "")
          echo "cron=$CRON" >> $GITHUB_OUTPUT

This way: upgrade overwrites the workflow logic (safe), but the workflow reads its schedule from config.json (user-owned, preserved).

---

Blocker 4: No Upgrade Safety Mechanism (FIDO Critical)

Fix: Add a pre-upgrade diff check to upgrade.ts:

// Before overwriting any workflow:
for (const file of wfFiles) {
  const destPath = path.join(workflowsDest, file);
  const srcPath = path.join(workflowsSrc, file);

  if (fs.existsSync(destPath)) {
    const existing = fs.readFileSync(destPath, 'utf8');
    const template = fs.readFileSync(srcPath, 'utf8');

    // Check for squad-custom header
    if (existing.includes('# squad-custom: true')) {
      warn(`skipping ${file} (marked squad-custom)`);
      continue;
    }

    // Check if modified from previous template
    if (existing !== template) {
      info(`updating ${file} (local modifications will be overwritten)`);
      // Backup to .squad/upgrade-backups/{version}/{file}
      const backupDir = path.join(squadDir, 'upgrade-backups', oldVersion);
      fs.mkdirSync(backupDir, { recursive: true });
      fs.copyFileSync(destPath, path.join(backupDir, file));
    }
  }

  writeWorkflowFile(file, srcPath, destPath, projectType);
}

This gives customers:

• # squad-custom: true header ΓåÆ skip overwrite entirely
• Modified files ΓåÆ backup to .squad/upgrade-backups/{version}/ before overwriting
• Unmodified files ΓåÆ overwrite silently (no noise)

---

Blocker 5: Private Repo Cost Multiplier (FIDO High)

Fix: Add multiplier footnote to the issue body's scaling table:

Repos	Monthly min (Linux public)	Private Linux (1x)	Private Windows (10x)	Private macOS (2x)
1	1,800-3,600	Same	18,000-36,000	3,600-7,200
5	9,000-18,000	Same	90,000-180,000	18,000-36,000

Key insight: Most Squad workflows use ubuntu-latest (1x), but if a customer's CI runs on Windows or macOS runners, the multiplier applies to ALL minutes including Squad's workflows.

Also add: GitHub Enterprise Cloud has no minute limits on GitHub-hosted runners, so Tier 2 is fine for Enterprise customers.

---

Flight's Conditions (non-blocking but should address)

Condition	Fix
Config vs variables single source of truth	Config.json is primary (checked into repo). Repo variables are overrides (not checked in). Document precedence: repo variable > config.json > default
Enterprise tier guidance	Add note: "Enterprise Cloud = unlimited minutes. Use Tier 2 freely."
Init UX callout	squad init should print: "CI tier: zero (heartbeat disabled, ~100-300 min/month). Change in .squad/config.json"
Upgrade transition playbook	Add to docs: "After upgrading, check .squad/upgrade-backups/ for any workflow changes"

---

Implementation Order

1. P0: Fix double-write (templates.ts) -- remove workflow entries from manifest
2. P0: Add config.json template with CI tier defaults
3. P0: Add # squad-custom: true skip + backup mechanism to upgrade.ts
4. P1: Ship heartbeat template with cron disabled (Tier 0 default)
5. P1: Add upgrade preservation tests
6. P2: Update cost analysis with private repo multipliers
7. P2: Workflow consolidation (15 → 11)