feat: enhance FIDO with PR requirements enforcement + workflow guide by tamirdresher · Pull Request #676 · bradygaster/squad

tamirdresher · 2026-03-29T07:01:18Z

What

Enhances FIDO (Quality Owner) with PR requirements enforcement capabilities, updates routing rules, adds a pre-push quality checklist for @copilot, and adds a comprehensive GitHub workflow guide with visual Mermaid diagrams.

Why

FIDO already owns quality gates and PR blocking authority, but had no knowledge of the PR requirements spec (.github/PR_REQUIREMENTS.md) introduced in PR #672. The routing table had no entry for PR requirements enforcement work. Meanwhile, the @copilot coding agent had no pre-push quality checklist. This creates a gap where CI catches issues that could have been prevented earlier.

Additionally, new contributors need a single-page reference explaining how the repo works — branches, PRs, CI gates, labels, triage, and escape hatches.

Refs #100, #103

How

1. FIDO charter upgrade (.squad/agents/fido/charter.md)

Added PR Requirements Enforcement section with 9 specific checks
Pre-push checks: CHANGELOG gate, exports map, build validation, test validation, bleed detection
PR description checks: template completeness, issue reference, breaking changes, waiver documentation
User-facing change detection logic matching CI gate behavior
Escape hatch reference table with all skip labels
Runnable shell commands for local validation

2. Routing rules update (.squad/routing.md)

Added PR requirements enforcement work type routed to FIDO
Added module ownership: FIDO is primary for PR_REQUIREMENTS.md, PULL_REQUEST_TEMPLATE.md, check-exports-map.mjs; secondary for squad-ci.yml
Added routing principle Please Don't Lock squad into using GitHub #8: spawn FIDO for PR compliance checks before opening PRs

3. Copilot instructions update (.github/copilot-instructions.md)

Added PR Requirements — Pre-Push Quality Checklist section with 6 items
Documents CHANGELOG gate, exports map, samples build, PR description completeness, user-facing change detection, and escape hatches

4. Workflow guide (docs/GITHUB_WORKFLOW_GUIDE.md)

14-chapter reference covering all repo concepts for new contributors
7 Mermaid diagrams: PR lifecycle, CI pipeline, branch strategy, issue triage, label enforcement, escape hatches, fork contribution workflow
Complete reference tables for feature flags, labels, all 15 workflows, and PR requirements by category

Testing

No code changes — documentation, agent charter, and routing only
All four files are additive (no existing content removed or modified destructively)
pm run build not applicable (no source code changes)
pm test not applicable (no test changes)

Docs

Workflow guide added to docs/GITHUB_WORKFLOW_GUIDE.md
N/A for CHANGELOG — no user-facing SDK/CLI change (this PR modifies .squad/ state files and .github/ infrastructure, which are explicitly exempt per PR_REQUIREMENTS.md)
N/A for README — no new feature or module added

Exports

N/A — no new modules

Breaking Changes

None

Waivers

None required — this PR is categorically exempt from Documentation (d), Exports (e), and Samples (f) requirements per the Edge Case Exemptions table in PR_REQUIREMENTS.md (CI/GitHub Actions workflow changes + internal .squad/ state files).

- Upgrade FIDO's charter with pre-CI quality gate enforcement covering CHANGELOG, exports map, build validation, bleed detection, PR template completeness, and waiver documentation checks - Add PR requirements pre-push checklist to copilot-instructions.md so the @copilot coding agent validates compliance before pushing - Add comprehensive GitHub workflow guide (docs/GITHUB_WORKFLOW_GUIDE.md) with Mermaid diagrams covering PR lifecycle, CI pipeline, branch strategy, issue triage, label enforcement, and escape hatches Refs #104 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Enhances repo contribution quality guidance by extending the FIDO (Quality Owner) charter to enforce PR requirements pre-CI, updating Copilot repo instructions with a pre-push checklist, and adding a comprehensive GitHub workflow guide intended to orient new contributors.

Changes:

Add PR-requirements enforcement responsibilities and runnable pre-push validation steps to FIDO’s charter.
Add a PR requirements pre-push checklist to .github/copilot-instructions.md.
Add a long-form workflow/reference guide with Mermaid diagrams and tables describing repo processes and CI gates.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 8 comments.

File	Description
docs/GITHUB_WORKFLOW_GUIDE.md	New end-to-end workflow guide (roles, branches, CI, labels, requirements) with Mermaid diagrams and reference tables.
.squad/agents/fido/charter.md	Expands FIDO responsibilities to include PR requirements enforcement and pre-push/PR-review checks.
.github/copilot-instructions.md	Adds a pre-push quality checklist aligned with PR requirements and CI gates.

Copilot · 2026-03-29T07:05:39Z

docs/GITHUB_WORKFLOW_GUIDE.md

+### 🆕 Added by Dina:
+
+| CI Job | What It Checks | PR |
+|--------|---------------|-----|
+| **`changelog-gate`** | If you change SDK/CLI source, you MUST update CHANGELOG.md | #673 |
+| **`exports-map-check`** | New `src/*/index.ts` barrels must have matching `package.json` exports | #673 |
+| **`samples-build`** | Builds all 11 sample projects against your PR's SDK code | #674 |


This table lists a samples-build CI job (and references PR #674), but .github/workflows/squad-ci.yml currently does not define a samples-build job. Update the guide to reflect the actual CI jobs, or mark this as planned (e.g., #103) rather than already present.

Suggested change

### 🆕 Added by Dina:

| CI Job | What It Checks | PR |

|--------|---------------|-----|

| **`changelog-gate`** | If you change SDK/CLI source, you MUST update CHANGELOG.md | #673 |

| **`exports-map-check`** | New `src/*/index.ts` barrels must have matching `package.json` exports | #673 |

| **`samples-build`** | Builds all 11 sample projects against your PR's SDK code | #674 |

### 🆕 Added by Dina (includes planned jobs):

| CI Job | What It Checks | PR |

|--------|---------------|-----|

| **`changelog-gate`** | If you change SDK/CLI source, you MUST update CHANGELOG.md | #673 |

| **`exports-map-check`** | New `src/*/index.ts` barrels must have matching `package.json` exports | #673 |

| **`samples-build`** | Planned: builds all 11 sample projects against your PR's SDK code (job not yet active in `.github/workflows/squad-ci.yml`) | #674 (planned) |

Copilot · 2026-03-29T07:05:39Z

docs/GITHUB_WORKFLOW_GUIDE.md

+|----------|---------|---------|----------------------------|
+| `SQUAD_CHANGELOG_CHECK` | CHANGELOG gate | ✅ On | Skips CHANGELOG requirement globally |
+| `SQUAD_EXPORTS_CHECK` | Exports map check | ✅ On | Skips exports check globally |
+| `SQUAD_SAMPLES_CI` | Samples build | ✅ On | Skips sample validation globally |


SQUAD_SAMPLES_CI is documented here as a repo variable, but there is currently no SQUAD_SAMPLES_CI feature flag referenced anywhere in workflows/scripts. Please remove it or clearly label it as future/planned so readers don’t look for a setting that doesn’t exist.

Suggested change

| `SQUAD_SAMPLES_CI` | Samples build | ✅ On | Skips sample validation globally |

| `SQUAD_SAMPLES_CI` | (Planned) Samples build toggle — not yet wired into CI | N/A (planned) | Future flag; safe to ignore for now |

Copilot · 2026-03-29T07:05:40Z

docs/GITHUB_WORKFLOW_GUIDE.md

+| `skip-changelog` | CHANGELOG gate | CI/infra-only changes that don't need a changelog entry |
+| `skip-exports-check` | Exports map check | Missing export is intentional or tracked separately |
+| `skip-samples-ci` | Samples build | Sample updates coming in a follow-up PR |
+| `large-deletion-approved` | Deletion guard (>50 files) | Intentional mass refactors or migrations |


skip-samples-ci is documented as a PR skip label, but the current CI workflow doesn’t check for it (and there is no samples CI gate to skip). Please remove it from the guide or align it with an implemented gate/label.

Copilot · 2026-03-29T07:05:40Z

.github/copilot-instructions.md

+### 3. Samples build
+If you changed SDK source files, all 11 sample projects will be built against your changes in CI. Run `npm run build` in any affected sample directory to catch issues early. Bypass: `skip-samples-ci` label (requires reviewer approval).


This checklist references a skip-samples-ci label and says CI builds all 11 samples for SDK changes, but there is currently no samples-build job, skip-samples-ci label check, or SQUAD_SAMPLES_CI feature flag in .github/workflows/squad-ci.yml. This will mislead contributors; either remove/mark this as a future (#103) manual-only requirement or implement the corresponding CI gate + label/flag support.

Copilot · 2026-03-29T07:05:40Z

.squad/agents/fido/charter.md

+6. **Template completeness**: Verify the PR description includes non-empty content for: What, Why, How, Testing. If SDK/CLI files changed, Docs section must mention CHANGELOG.
+7. **Issue reference**: PR body must contain `Closes #N` or `Part of #N`.
+8. **Breaking changes**: If any public API signature changed (parameter name, type, return type, removed export), the Breaking Changes section must be filled.
+9. **Waiver documentation**: If any skip label (`skip-changelog`, `skip-exports-check`, `skip-samples-ci`) is present, verify a `## Waivers` section exists with reason and reviewer approval.


This charter adds skip-samples-ci as a recognized skip label / escape hatch, but the repo currently doesn't implement a samples CI gate or reference skip-samples-ci anywhere in workflows (only skip-changelog, skip-exports-check, and large-deletion-approved exist). To keep the charter aligned with actual enforcement, remove skip-samples-ci (or mark samples checks as manual-only until the gate from #103 exists).

Suggested change

9. **Waiver documentation**: If any skip label (`skip-changelog`, `skip-exports-check`, `skip-samples-ci`) is present, verify a `## Waivers` section exists with reason and reviewer approval.

9. **Waiver documentation**: If any skip label (`skip-changelog`, `skip-exports-check`) is present, verify a `## Waivers` section exists with reason and reviewer approval.

Copilot · 2026-03-29T07:05:40Z

docs/GITHUB_WORKFLOW_GUIDE.md

+    LABEL --> L3[skip-samples-ci]
+    LABEL --> L4[large-deletion-approved]
+
+    FLAG --> F1[SQUAD_CHANGELOG_CHECK]
+    FLAG --> F2[SQUAD_EXPORTS_CHECK]
+    FLAG --> F3[SQUAD_SAMPLES_CI]


The escape-hatch diagram lists skip-samples-ci and SQUAD_SAMPLES_CI, but the current CI workflow only supports skip-changelog, skip-exports-check, and large-deletion-approved (no samples gate/flag exists yet). Please remove these items or clearly label them as planned/future so contributors don’t look for non-existent bypass mechanisms.

Suggested change

LABEL --> L3[skip-samples-ci]

LABEL --> L4[large-deletion-approved]

FLAG --> F1[SQUAD_CHANGELOG_CHECK]

FLAG --> F2[SQUAD_EXPORTS_CHECK]

FLAG --> F3[SQUAD_SAMPLES_CI]

LABEL --> L3[skip-samples-ci (planned)]

LABEL --> L4[large-deletion-approved]

FLAG --> F1[SQUAD_CHANGELOG_CHECK]

FLAG --> F2[SQUAD_EXPORTS_CHECK]

FLAG --> F3[SQUAD_SAMPLES_CI (planned)]

Copilot · 2026-03-29T07:05:40Z

docs/GITHUB_WORKFLOW_GUIDE.md

+    P2[🧪 test\nbuild + test\n+ canary + deletion guard]
+    P3[📋 changelog-gate\nSDK/CLI change?\nCHANGELOG updated?]
+    P4[📦 exports-map-check\nnew barrel?\nexport in package.json?]
+    P5[🎨 samples-build\nbuild all 11 samples\nagainst PR code]


The CI pipeline diagram includes a samples-build job, but .github/workflows/squad-ci.yml currently has no samples-build job (and no samples CI gate). This should be updated to match the actual set of CI jobs, or annotated as a future/planned gate (e.g., tracked by #103).

Suggested change

P5[🎨 samples-build\nbuild all 11 samples\nagainst PR code]

P5[🎨 samples-build (planned)\ntracked in #103\nbuild all 11 samples]

Copilot · 2026-03-29T07:05:41Z

docs/GITHUB_WORKFLOW_GUIDE.md

+
+| CI Job | What It Checks |
+|--------|---------------|
+| **`docs-quality`** | Markdown formatting (`markdownlint`) + spell check (`cspell`) on docs |


This section states docs-quality runs markdownlint + cspell "on docs", but the repo’s markdownlint/cspell configs are currently scoped to docs/src/content/**/*.md and README.md only (so this guide file isn’t checked). Consider tightening the wording to match the actual globs, and/or expanding the globs to include docs/*.md if these files are intended to be covered by docs-quality.

Suggested change

| **`docs-quality`** | Markdown formatting (`markdownlint`) + spell check (`cspell`) on docs |

| **`docs-quality`** | Markdown formatting (`markdownlint`) + spell check (`cspell`) on docs content (`docs/src/content/**/*.md`) and `README.md` |

- Add 'PR requirements enforcement' work type routing to FIDO - Add module ownership for PR_REQUIREMENTS.md, PULL_REQUEST_TEMPLATE.md, squad-ci.yml (secondary), and check-exports-map.mjs - Add routing principle #8: spawn FIDO for PR compliance before opening PRs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tamirdresher · 2026-03-29T08:26:26Z

@copilot please review this PR. Focus on whether the FIDO charter enforcement rules align correctly with the existing CI gates in squad-ci.yml and the PR requirements spec in .github/PR_REQUIREMENTS.md.

…uild as planned) Agent-Logs-Url: https://github.com/bradygaster/squad/sessions/8d6d2f19-2b66-4ff5-afb9-fe67d5910daa Co-authored-by: tamirdresher <342800+tamirdresher@users.noreply.github.com>

Copilot · 2026-03-29T08:29:15Z

@copilot please review this PR. Focus on whether the FIDO charter enforcement rules align correctly with the existing CI gates in squad-ci.yml and the PR requirements spec in .github/PR_REQUIREMENTS.m...

Reviewed and aligned all three files with the actual CI gates in squad-ci.yml. Commit 29f3d1d addresses all the mismatches found:

docs/GITHUB_WORKFLOW_GUIDE.md: samples-build, SQUAD_SAMPLES_CI, and skip-samples-ci are now annotated as planned (tracked in Workflow dual-path support for .squad/ migration #103) in both the Mermaid diagrams and the reference tables. The docs-quality row now lists the exact globs it covers (docs/src/content/**/*.md and README.md).
.github/copilot-instructions.md: The "Samples build" checklist item is rewritten as a manual check with a clear note that the CI gate is planned in Workflow dual-path support for .squad/ migration #103 — removed the misleading skip-samples-ci label reference.
.squad/agents/fido/charter.md: Removed skip-samples-ci from the waiver-documentation check (I don't see a tool called task in github copilot #9) and from the escape hatches table, since no samples CI gate exists yet to skip.

…eed heuristic - Fix sample count: 11 → 9 (actual count in samples/ directory) - Mark samples-build and changelog/exports gates as pending merge (#673, #674) - Add concrete heuristic for bleed check (scope by packages/ directory) - Clarify bash snippet as reference commands, not literal agent execution Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tamirdresher · 2026-03-29T08:43:35Z

All 8 Copilot review findings have been addressed across commits:

29f3d1d (@copilot): Marked \samples-build, \SQUAD_SAMPLES_CI, and \skip-samples-ci\ as planned (Workflow dual-path support for .squad/ migration #103/feat(ci): add samples build validation gate #674). Tightened \docs-quality\ glob description. Removed \skip-samples-ci\ from FIDO charter escape hatches.
15f7ebd: Fixed sample count (11 → 9), added concrete bleed-check heuristic, clarified bash snippet as reference commands.

Remaining \skip-samples-ci\ references in the workflow guide and copilot-instructions are explicitly marked as planned/not yet active. Ready for human review.

tamirdresher · 2026-03-29T13:16:48Z

@bradygaster @diberry PR ready for review. Also check issue #678 for git-notes RFC addressing #643 #498 #670.

Copilot AI review requested due to automatic review settings March 29, 2026 07:01

Copilot started reviewing on behalf of tamirdresher March 29, 2026 07:01 View session

Copilot AI reviewed Mar 29, 2026

View reviewed changes

Copilot started work on behalf of tamirdresher March 29, 2026 08:26 View session

tamirdresher requested review from bradygaster and diberry March 29, 2026 08:27

fix: align docs and FIDO charter with actual CI gates (mark samples-b…

29f3d1d

…uild as planned) Agent-Logs-Url: https://github.com/bradygaster/squad/sessions/8d6d2f19-2b66-4ff5-afb9-fe67d5910daa Co-authored-by: tamirdresher <342800+tamirdresher@users.noreply.github.com>

Copilot finished work on behalf of tamirdresher March 29, 2026 08:29

Copilot started work on behalf of tamirdresher March 29, 2026 08:43 View session

Copilot finished work on behalf of tamirdresher March 29, 2026 08:44

	\| `SQUAD_SAMPLES_CI` \| Samples build \| ✅ On \| Skips sample validation globally \|
	\| `SQUAD_SAMPLES_CI` \| (Planned) Samples build toggle — not yet wired into CI \| N/A (planned) \| Future flag; safe to ignore for now \|

		### 3. Samples build
		If you changed SDK source files, all 11 sample projects will be built against your changes in CI. Run `npm run build` in any affected sample directory to catch issues early. Bypass: `skip-samples-ci` label (requires reviewer approval).

	9. Waiver documentation: If any skip label (`skip-changelog`, `skip-exports-check`, `skip-samples-ci`) is present, verify a `## Waivers` section exists with reason and reviewer approval.
	9. Waiver documentation: If any skip label (`skip-changelog`, `skip-exports-check`) is present, verify a `## Waivers` section exists with reason and reviewer approval.

	P5[🎨 samples-build\nbuild all 11 samples\nagainst PR code]
	P5[🎨 samples-build (planned)\ntracked in #103\nbuild all 11 samples]

	\| `docs-quality` \| Markdown formatting (`markdownlint`) + spell check (`cspell`) on docs \|
	\| `docs-quality` \| Markdown formatting (`markdownlint`) + spell check (`cspell`) on docs content (`docs/src/content/*/.md`) and `README.md` \|

Conversation

tamirdresher commented Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

How

Testing

Docs

Exports

Breaking Changes

Waivers

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

tamirdresher commented Mar 29, 2026

Uh oh!

Copilot AI commented Mar 29, 2026

Uh oh!

tamirdresher commented Mar 29, 2026

Uh oh!

tamirdresher commented Mar 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tamirdresher commented Mar 29, 2026 •

edited

Loading