GitHub Issue

ADR-006: Extension Modularization & Install Infrastructure

Discovered On Mar 28, 2026

Primary Metric open

# ADR-006: Extension Modularization & Install Infrastructure **Status:** Proposed **Date:** 2026-03-28 **Deciders:** Jeremy McSpadden ## Context GSD2 ships as a monolith: 177K LOC in the core `gsd` extension, 20 bundled extensions, 19 bundled skills, 842 MB `node_modules`. Every user gets everything — playwright, koffi, every AI provider SDK, every skill — whether they use it or not. The extension system infrastructure is mature (discovery, registry, manifests, enable/disable, rich ExtensionAPI), but everything ships bundled. There is no mechanism to install, update, or uninstall extensions after initial setup. ### Problems 1. **Bloated install size** — 842 MB node_modules; users who never use browser automation still download playwright (14 MB); macOS-only koffi costs 86 MB for everyone 2. **Slow startup** — 20 extensions loaded eagerly; barrel import in cli.ts pulls 57K LOC on every invocation 3. **Monolithic core** — 177K LOC gsd extension is a single unit with deep internal coupling; modifying one feature risks breaking others 4. **Architecture coupling** — shared → gsd reverse dependency, gsd ↔ cmux bidirectional coupling, 5+ extensions import gsd/preferences.js by file path 5. **Provider SDK waste** — 48 MB of AI provider SDKs loaded even though users typically use 1-2 providers ## Decision Modularize GSD2 across 7 milestones (v1.3–v1.9), each independently shippable: ### v1.3: Foundation & Install Infrastructure - Remove unused root dependencies, relocate misp...

View Raw Thread

Developer & User Discourse

jeremymcs • Mar 28, 2026

## ADR-006 Review: Findings and Recommendations

As Grok, built by xAI, I've reviewed ADR-006: Extension Modularization & Install Infrastructure based on a deep exploration of the codebase and the ADR content. Here's my analysis and recommendations.

### Overall Assessment
- **Architectural Soundness**: Excellent. The ADR proposes a pragmatic, incremental refactor from a monolithic extension system to modular npm-based extensions, reducing core bloat and enabling runtime management. It aligns with GSD's evolutionary approach (e.g., v1.3 foundation).
- **Clarity and Structure**: High. Well-organized with a clear problem, milestones, and tables. Futuristic dates are placeholders.
- **Feasibility**: Strong. Leverages npm, Node.js, and existing Pi SDK. CLI commands and event decoupling are straightforward.
- **Alignment with Codebase**: Perfect. Builds on current loader/registry without breaking existing workflows. Event bus fixes known coupling issues.
- **Readiness**: Ready for v1.3 impl...

jeremymcs • Mar 28, 2026

## Research Findings (2026-03-28)

4 parallel researchers completed — Stack, Features, Architecture, Pitfalls. Full synthesis in `.planning/research/SUMMARY.md`.

### Stack

- **One new dependency:** `semver ^7.6.3` — everything else uses existing deps or Node.js built-ins
- **npm subprocess pattern:** `spawnSync("npm", ["install", "--prefix", targetDir, "--ignore-scripts"])` — no programmatic npm API (none is stable)
- **EventBus already exists:** `packages/pi-coding-agent/src/core/event-bus.ts` exposed as `pi.events` — no new event library needed
- **Existing utilities:** `proper-lockfile` (concurrent registry mutation), `hosted-git-info` (git URL parsing), `undici`/native `fetch` (registry API)

### Architecture

- **7 confirmed coupling sites** between gsd ↔ cmux: 5 in gsd importing cmux, 2 in cmux importing gsd types
- **1 reverse dep:** `shared/rtk-session-stats.ts:5` → `gsd/paths.js`
- **Discovery is directory-agnostic:** `discoverExtensionEntryPaths()` already works for any dir...

jeremymcs • Mar 28, 2026

## Implementation Plan: Extension Modularization

**Full plan:** [`.plans/IMPLEMENTATION-PLAN-extension-modularization.md`](https://github.com/jeremymcs/gsd-2/blob/feat/extension-system-analysis/.plans/IMPLEMENTATION-PLAN-extension-modularization.md)

### Summary

**Goal:** Make GSD2 lightweight out of the box by extracting optional features into installable extensions, reducing core footprint from 177K LOC to ~15-20K LOC and `node_modules` from 842 MB to ~450 MB.

### Phases

| Phase | Description | Effort | Risk | Dependencies |
|-------|-------------|--------|------|-------------|
| **0** | Foundation — Dependency Cleanup & Architecture Fixes | Small (1-2 sessions) | Low | None |
| **1** | Extension Install Infrastructure (`gsd extensions install`) | Medium (2-3 sessions) | Medium | None |
| **2** | Extract Self-Contained Extensions (Tier 1) — 8 extensions | Medium (2-3 sessions) | Low | Phase 1 |
| **3** | Preferences Service & Tier 2 Extraction — 6 extensions | Medium-Large (3-4 s...

jeremymcs • Mar 28, 2026

### ADR-006 & Implementation Plan Review

I have completed a comprehensive review of the ADR and the [Implementation Plan](https://github.com/jeremymcs/gsd-2/blob/feat/extension-system-analysis/.plans/IMPLEMENTATION-PLAN-extension-modularization.md) against the current codebase. My analysis confirms that the **177,005 LOC `gsd` monolith** and the **842 MB installation size** are critical bottlenecks that this plan accurately addresses.

#### **Verification Results**
- **Monolith Bloat:** Confirmed `src/resources/extensions/gsd` contains **177,005 lines of code**, verifying the urgent need for Phase 5 (Core Decomposition).
- **Architectural Coupling:** Identified **15+ direct imports** from `../gsd/` in peripheral extensions (e.g., `github-sync`, `subagent`), confirming that "reverse dependencies" are a primary blocker for modularity.
- **Dependency Analysis:** The root `package.json` is heavily burdened by `playwright` and multiple AI SDKs. Phase 6 (AI Provider Lazy Loading) and Phase ...

igouss • Mar 28, 2026

Keeping is small and modular will also help AI reasoning when developing this app.
I think we should also consider packaging common extension such as [Language] developer, tester, etc, out of the core into reusable skill/extension packs.