Title: PRD: Code Quality Linting for Squad Monorepo · Issue #477 · github/squad · GitHub
Open Graph Title: PRD: Code Quality Linting for Squad Monorepo · Issue #477 · github/squad
X Title: PRD: Code Quality Linting for Squad Monorepo · Issue #477 · github/squad
Description: @bradygaster — PRD for your review. Code Quality Linting for Squad Monorepo Author: Book (Docs Agent) Requested By: Dina Berry Date: 2026-03-19 Status: Draft — Awaiting Brady's Review Target Repository: bradygaster/squad 1. Problem State...
Open Graph Description: @bradygaster — PRD for your review. Code Quality Linting for Squad Monorepo Author: Book (Docs Agent) Requested By: Dina Berry Date: 2026-03-19 Status: Draft — Awaiting Brady's Review Target Reposi...
X Description: @bradygaster — PRD for your review. Code Quality Linting for Squad Monorepo Author: Book (Docs Agent) Requested By: Dina Berry Date: 2026-03-19 Status: Draft — Awaiting Brady's Review Target Re...
Opengraph URL: https://github.com/github/squad/issues/477
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"PRD: Code Quality Linting for Squad Monorepo","articleBody":"@bradygaster — PRD for your review.\n\n---\n\n# Code Quality Linting for Squad Monorepo\r\n\r\n**Author:** Book (Docs Agent) \r\n**Requested By:** Dina Berry \r\n**Date:** 2026-03-19 \r\n**Status:** Draft — Awaiting Brady's Review \r\n**Target Repository:** `bradygaster/squad`\r\n\r\n---\r\n\r\n## 1. Problem Statement & Context\r\n\r\nThe Squad monorepo (`bradygaster/squad`) currently has no runtime behavior linter. The existing `lint` script runs `tsc --noEmit`, which provides type checking but cannot detect several classes of runtime anti-patterns:\r\n\r\n**What TypeScript strict mode misses:**\r\n- **Synchronous I/O inside async functions** — Blocking `fs.readFileSync()`/`writeFileSync()` calls in async handlers, defeating the purpose of async declarations and blocking the Node.js event loop\r\n- **Fire-and-forget promises** — Missing `await` on async calls, causing race conditions or silent errors\r\n- **Unused code** — Dead variables, imports, and parameters (`noUnusedLocals`/`noUnusedParameters` are disabled)\r\n- **Promise misuse** — Conditionals testing promises instead of awaiting them\r\n\r\n**Real-world impact:** Investigation of the SDK revealed 581 instances of sync file system calls inside async functions. For example, `tools/index.ts` contains `squad_decide`, `squad_memory`, and `squad_skill` handlers that are declared `async` but use `readFileSync`/`writeFileSync`. Every time an agent calls these tools, the event loop blocks. As the codebase grows and more contributors (including AI agents like Copilot) submit PRs, these patterns will compound without automated detection.\r\n\r\n**What we need:** A lightweight, configurable linter that surfaces these issues during development without blocking the current workflow.\r\n\r\n---\r\n\r\n## 2. Goals & Success Metrics\r\n\r\n**Goals:**\r\n1. **Detect event loop blockers** — Flag synchronous I/O inside async functions in hot paths (SDK tool handlers, platform utilities)\r\n2. **Catch promise misuse** — Identify missing `await`, floating promises, and incorrect promise conditionals\r\n3. **Maintain velocity** — No disruption to existing build/CI workflows; informational-only initially\r\n4. **Enable incremental adoption** — Team can triage findings and gradually increase enforcement\r\n\r\n**Success Metrics:**\r\n- Hot paths (SDK tool handlers) converted from sync to async I/O within 2 weeks of adoption\r\n- Zero new sync-in-async patterns introduced after enforcement enabled\r\n- Developer satisfaction: \"Helpful findings, not noise\" (measured via team feedback)\r\n- CI remains green during Phase 1-2 rollout (no build blocking)\r\n\r\n**Non-goals:**\r\n- Replace TypeScript type checking\r\n- Enforce opinionated code style preferences (e.g., semicolons, indentation)\r\n- Block PRs immediately (phased enforcement only)\r\n\r\n---\r\n\r\n## 3. Key User Scenarios\r\n\r\n**Scenario 1: Developer submits PR with sync I/O in async handler**\r\n- *Before:* Pattern ships undetected, discovered later during performance testing\r\n- *After:* Linter flags it in local development or CI logs; developer converts to `fs.promises` before merge\r\n\r\n**Scenario 2: AI agent (Copilot) generates code with floating promise**\r\n- *Before:* Missing `await` on database save; PR reviewer spots it manually (or doesn't)\r\n- *After:* Linter flags missing `await` in CI output; human reviewer confirms and fixes\r\n\r\n**Scenario 3: Maintainer evaluates linter findings**\r\n- *Before:* No visibility into async anti-patterns across codebase\r\n- *After:* Run linter, review 1,058 findings, prioritize top 20 hot paths for immediate fix\r\n\r\n**Scenario 4: Team decides to enforce linting**\r\n- *Before:* Manual code review is the only gate\r\n- *After:* Incrementally increase severity on critical rules (sync I/O, floating promises), CI enforces them\r\n\r\n---\r\n\r\n## 4. Scope and Non-Goals\r\n\r\n**In Scope:**\r\n- Detect async/promise anti-patterns (sync I/O, missing await, promise misuse)\r\n- Flag type safety bypasses (`any`, non-null assertions `!`)\r\n- Identify unused code (variables, imports)\r\n- Informational warnings initially; phased enforcement later\r\n- Integration with existing tooling (package.json scripts, GitHub Actions)\r\n\r\n**Out of Scope:**\r\n- Code formatting (use Prettier or similar if desired)\r\n- Comprehensive security auditing (use dedicated security scanners)\r\n- Migration of existing findings (team decides per-rule enforcement timeline)\r\n- Linting non-TypeScript files (Markdown, JSON, etc.)\r\n\r\n---\r\n\r\n## 5. High-Level Approach: Solution Options\r\n\r\nThree options exist, each with trade-offs around ecosystem maturity, speed, and detection capabilities:\r\n\r\n### Option 1: ESLint 9 with TypeScript Plugin\r\n**What it is:** Industry-standard JavaScript/TypeScript linter with extensive plugin ecosystem. Uses TypeScript's type system for advanced analysis.\r\n\r\n**Pros:**\r\n- **Type-aware rules** — Can detect sync-in-async, floating promises, promise misuse (all require type information)\r\n- **Mature ecosystem** — 10+ years, thousands of plugins, well-documented\r\n- **Flat config system** — ESLint 9 uses modern `eslint.config.mjs` format (simpler than old `.eslintrc`)\r\n- **Proven at scale** — Used by Microsoft, Google, Airbnb, Meta\r\n\r\n**Cons:**\r\n- **Heaviest option** — 3 npm packages required (`eslint`, `@typescript-eslint/parser`, `@typescript-eslint/eslint-plugin`, plus optional `eslint-plugin-n` for Node.js rules)\r\n- **Slower** — Type-aware analysis requires loading TypeScript compiler, runs slower than non-type-aware linters\r\n- **Steeper learning curve** — Extensive configuration options (though flat config helps)\r\n\r\n**What it catches:**\r\n- ✅ Sync I/O in async functions (via `eslint-plugin-n`)\r\n- ✅ Floating promises (`no-floating-promises`)\r\n- ✅ Promise misuse (`no-misused-promises`)\r\n- ✅ Unused vars, `any`, non-null assertions\r\n\r\n**Proof of concept:** Branch `squad/eslint9-info-only` implements this. Found 1,058 informational findings (581 sync-in-async, 17 floating promises, etc.). Technical spec available at `.squad/skills/typescript-review/eslint9-spec.md`.\r\n\r\n---\r\n\r\n### Option 2: Biome\r\n**What it is:** Newer Rust-based toolchain combining linting and formatting. Fast, opinionated, built-in TypeScript support.\r\n\r\n**Pros:**\r\n- **Fast** — Rust implementation, 10-100x faster than ESLint on large codebases\r\n- **All-in-one** — Linter + formatter in one tool (like Prettier + ESLint combined)\r\n- **Built-in TypeScript** — No separate parser plugin needed\r\n- **Simple config** — Single `biome.json` file\r\n\r\n**Cons:**\r\n- **No type-aware rules** — Cannot detect sync-in-async or floating promises (requires type system integration, not yet available)\r\n- **Smaller rule set** — ~200 rules vs ESLint's 1,000+ (though growing rapidly)\r\n- **Newer ecosystem** — Less mature than ESLint, fewer community plugins\r\n- **Opinionated defaults** — Less customizable than ESLint\r\n\r\n**What it catches:**\r\n- ❌ **Cannot detect sync I/O in async** (no Node.js plugin equivalent)\r\n- ❌ **Cannot detect floating promises** (requires type awareness)\r\n- ✅ Basic unused vars, suspicious patterns\r\n- ✅ Some TypeScript anti-patterns (but not type-aware ones)\r\n\r\n**Verdict:** Biome is excellent for speed and basic linting, but **cannot address the core problem** (sync-in-async detection).\r\n\r\n---\r\n\r\n### Option 3: oxlint (Oxc Project)\r\n**What it is:** Very fast Rust-based linter implementing subset of ESLint rules. Focused on speed over feature parity.\r\n\r\n**Pros:**\r\n- **Fastest option** — 50-100x faster than ESLint (Rust + optimized AST parsing)\r\n- **ESLint-compatible** — Implements many ESLint rules, familiar syntax\r\n- **Single binary** — No npm dependencies, just download and run\r\n- **Good for basics** — Catches common mistakes quickly\r\n\r\n**Cons:**\r\n- **No type-aware analysis** — Cannot detect sync-in-async, floating promises, or promise misuse\r\n- **Subset of rules** — Only ~200 ESLint rules implemented (vs 1,000+ total)\r\n- **No TypeScript-ESLint rules** — Missing `@typescript-eslint/no-floating-promises`, etc.\r\n- **Limited configurability** — Less customizable than ESLint\r\n\r\n**What it catches:**\r\n- ❌ **Cannot detect sync I/O in async** (no `eslint-plugin-n` equivalent)\r\n- ❌ **Cannot detect floating promises** (no type awareness)\r\n- ✅ Basic unused vars, syntax errors\r\n- ✅ Some suspicious patterns (but limited rule set)\r\n\r\n**Verdict:** oxlint is great for ultra-fast basic linting, but **cannot address the core problem**.\r\n\r\n---\r\n\r\n### Recommendation Matrix\r\n\r\n| Requirement | ESLint 9 | Biome | oxlint |\r\n|------------|----------|-------|--------|\r\n| **Detects sync-in-async** | ✅ Yes | ❌ No | ❌ No |\r\n| **Detects floating promises** | ✅ Yes | ❌ No | ❌ No |\r\n| **Speed** | Moderate | Fast | Fastest |\r\n| **Ecosystem maturity** | Highest | Medium | Lowest |\r\n| **Configurability** | Highest | Medium | Low |\r\n| **npm dependencies** | 3 packages | 1 package | 0 (binary) |\r\n\r\n**If the priority is detecting sync-in-async and promise misuse** (the stated problem), **ESLint 9 is the only option that works**. Biome and oxlint are excellent tools but cannot perform type-aware analysis needed to catch these patterns.\r\n\r\n---\r\n\r\n## 6. Risks, Dependencies, and Open Questions\r\n\r\n**Risks:**\r\n- **Noisy output overwhelms developers** — Mitigation: Start with warnings-only, separate script, opt-in usage\r\n- **Build time increase** — Mitigation: ESLint 9 is fast enough for this small monorepo (~5 seconds); can run in parallel with `tsc`\r\n- **Team rejects after trying** — Mitigation: Easy rollback (remove packages + config file)\r\n- **False positives in specific contexts** — Mitigation: Test file exclusions already defined; can disable rules per-file if needed\r\n\r\n**Dependencies:**\r\n- Requires Node.js 18+ (already met)\r\n- For Option 1: 3 npm packages (`eslint`, `@typescript-eslint/*`, `eslint-plugin-n`)\r\n- For Option 2/3: Single package or binary\r\n- No changes to existing CI/build scripts required for Phase 1\r\n\r\n**Open Questions for Brady:**\r\n1. **Which solution option?** ESLint 9 (only option that solves sync-in-async), or evaluate Biome/oxlint for future when type-aware rules land?\r\n2. **Triage strategy:** Fix high-traffic paths (SDK tools) before enabling in CI, or surface all findings immediately?\r\n3. **Test file linting:** Fully exclude, use relaxed rules, or lint with same rules as source?\r\n4. **Enforcement timeline:** How long should warnings-only phase last before increasing severity to block builds?\r\n5. **Rule customization:** Any specific rules to enable/disable based on team preferences?\r\n\r\n**Next Steps:**\r\n1. Brady selects solution option and answers open questions\r\n2. If ESLint 9: Merge proof-of-concept branch `squad/eslint9-info-only` (ready now)\r\n3. Team evaluates findings in local development (Phase 1: opt-in)\r\n4. Add to CI with `continue-on-error: true` (Phase 2: visible but non-blocking)\r\n5. Triage findings, tune rules, enable enforcement (Phase 3+)\r\n\r\n---\r\n\r\n**Technical Specification Reference:** For implementation details of Option 1 (ESLint 9), see `.squad/skills/typescript-review/eslint9-technical-spec.md`.\r\n\n\n---\n\n**Proof of concept:** Branch `squad/eslint9-info-only` off `dev` is ready with Option 1 (ESLint 9) implemented. 1,058 informational findings, exit code 0, nothing blocking.\n\n**Companion technical spec** with full config, install commands, and adoption ladder is available on request.\n\ncc @diberry","author":{"url":"https://github.com/diberry","@type":"Person","name":"diberry"},"datePublished":"2026-03-20T20:47:53Z","url":"https://github.com/github/squad/issues/477"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:d2b9ad19-d7ed-ed05-44d5-ba86c891f34b |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | A880:14F601:27A29CC:324D872:6B017F86 |
| html-safe-nonce | 093c75050eb56b5938c7494983ba6f7a79b0120d2be83ad1f0c0bdd1aa97f50a |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJBODgwOjE0RjYwMToyN0EyOUNDOjMyNEQ4NzI6NkIwMTdGODYiLCJ2aXNpdG9yX2lkIjoiNzk5MDUyNjYwMDAyODQ1NDc5MCIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | 3001daad56f82cd99b28cc27622be2cb45e7a8734bb6a3a6e40e20456fdbe24f |
| hovercard-subject-tag | issue:4110038678 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/github/squad/477/issue_layout |
| twitter:image | https://opengraph.githubassets.com/336b844c38299deeeaeb56880f22ef19a17c7babe713058136a17079d03693dc/github/squad/issues/477 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/336b844c38299deeeaeb56880f22ef19a17c7babe713058136a17079d03693dc/github/squad/issues/477 |
| og:image:alt | @bradygaster — PRD for your review. Code Quality Linting for Squad Monorepo Author: Book (Docs Agent) Requested By: Dina Berry Date: 2026-03-19 Status: Draft — Awaiting Brady's Review Target Reposi... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | diberry |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| turbo-cache-control | no-preview |
| go-import | github.com/github/squad git https://github.com/github/squad.git |
| octolytics-dimension-user_id | 9919 |
| octolytics-dimension-user_login | github |
| octolytics-dimension-repository_id | 1151205052 |
| octolytics-dimension-repository_nwo | github/squad |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 1151205052 |
| octolytics-dimension-repository_network_root_nwo | github/squad |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width