Skip to content

RFD 0008: Drop gstack and gbrain from the v2 framework

Summary

The v2 framework drops both gstack (composed external Git-stack tool from github.com/garrytan/gstack) and gbrain (MCP server registration for Claude Code). Neither survives the rebuild as a built-in component. Both may be reintroduced as optional plugins under the [[0001|RFD 0001]] three-tier model, but no such plugins ship at v2.0.

samuel init becomes substantially smaller as a result: framework binary + built-in skills + lockfile setup. That's it. Git-stack workflow and MCP-server-registration are now opt-in via plugins if anyone wants them later.

Problem statement

v1 ships three components through its orchestrator ([[../../wiki/sources/2026-05-12-v1-orchestrator]]):

  1. gstack — clones github.com/garrytan/gstack at a pinned SHA, runs its setup --team --quiet --host claude script.
  2. gbrain — registers gbrain (a user-installed binary) as a Claude Code MCP server via claude mcp add -s user gbrain <bin> serve.
  3. samuel-skills — syncs Samuel's own embedded skill content to ~/.claude/skills/samuel/.

v1's samuel init runs all three by default. Users get all three whether they want them or not (modulo --skip-gstack / --skip-gbrain escape hatches).

v2 is "framework + skills hub" — a thin core with everything tool-specific in plugins ([[../../wiki/synthesis/positioning-rails-for-coding-assistants]]). gstack and gbrain are product opinions that don't belong in the thin core:

  • gstack is one valid choice of git-workflow tool. There are others (graphite, stacked-PRs, sapling, gitless, jj). Hardcoding gstack into every Samuel install privileges one choice over the rest. The framework shouldn't pick.
  • gbrain is one valid choice of memory MCP server. There are others (basic-memory, Mem0 MCP, custom-built variants). Same critique applies.

Both also assume Claude Code specifically. gbrain's registration uses claude mcp add. gstack's setup uses --host claude. v2's agnostic-by-design invariant ([[../../wiki/concepts/agnostic-by-design]]) rules out built-in Claude-coupled components — that's translator-plugin territory.

Requirements

  • The v2 framework binary must not contain hardcoded dependencies on gstack or gbrain.
  • samuel init must work with zero external repos cloned and zero external CLIs invoked beyond the framework's own setup.
  • Users who depended on gstack/gbrain under v1 must have a clear migration path (or be able to opt back in if community plugins emerge).
  • The pinned-SHA pattern from GstackComponent (which is good engineering) survives as a manifest schema feature, not as Samuel-managed source code.

Constraints

  • v2 is a clean break ([[../../wiki/entities/samuel-v2]]). No migration tools for users moving from v1 to v2.
  • The orchestrator pattern itself ([[0005|RFD 0005]]) carries forward — only the two specific concrete components drop.

Background

v1's component design (recap)

The orchestrator wires three components in order: gstack → gbrain → samuel-skills. Install runs forward; uninstall runs reverse. Each implements the Component interface (Detect / Install / Check / Uninstall).

  • GstackComponent's install flow: git clone --quiet <url> <path> → git checkout --quiet <pinned-SHA> → run <path>/setup --team --quiet --host claude. About 250 lines of Go.
  • GbrainComponent's install flow: detect gbrain on PATH → detect claude on PATH → claude mcp add -s user gbrain <bin> serve. About 280 lines.
  • Both have pre-mutation gates (refuse to proceed if prereqs missing) and idempotent re-install paths.

The engineering is solid. The product positioning is the problem.

Why these specific components were chosen for v1

History suggests:

  • gstack was the author's preferred git-workflow tool. Including it made Samuel "the AI coding tool with git-stack baked in" rather than just "an AI coding tool."
  • gbrain provided persistent memory for Claude Code, which the v1 era's Claude Code lacked. By 2026, Claude Code's built-in memory system has matured (per v1's own changelog noting "Uses Claude Code's built-in memory system instead" of .agent/memory/).

Both made sense at the time of v1.0. Neither is obviously load-bearing now.

What changes if they survive vs drop

If they survive as built-ins: - samuel init continues installing them by default. - The agnostic-by-design invariant is broken (gbrain assumes Claude). - Users who prefer different tools have to use --skip-* flags every install. - The framework binary carries logic for one specific git-workflow tool and one specific MCP server.

If they drop: - samuel init becomes thin. - Anyone wanting git-stack workflow installs a plugin: samuel install samuel-gstack-plugin. - Anyone wanting MCP memory installs a plugin: samuel install samuel-gbrain-plugin (which depends on the claude-translator plugin since it's Claude-specific). - v2's agnostic story is coherent.

The drop path is consistent with every other v2 design decision.

Options considered

Option A: Drop both (chosen)

Neither gstack nor gbrain ships in the v2 framework. Both can be reintroduced as plugins later if anyone (the user or the community) wants to write them.

Pros: - Smallest possible framework. Each component dropped is one fewer dependency, one fewer escape-hatch flag, one fewer failure mode in samuel init. - Agnostic-by-design invariant preserved (gbrain dropped removes Claude-coupling from core). - Users pick what they want via the plugin system, just like every other capability in v2. - The migration story is uniform: "v1's components are plugins now; v2 itself is the framework."

Cons: - v1 users who depended on the default gstack install lose it. No automatic migration to a plugin equivalent. - No plugin equivalents ship at v2.0 launch — gstack and gbrain users have to wait (or write their own plugins).

Effort: Zero net — the components don't get ported. The orchestrator pattern they ride on carries forward to host actual v2 plugins.

Option B: Keep gstack, drop gbrain

Reasoning: gstack is tool-agnostic (works with any Claude host, despite the --host claude flag), while gbrain is Claude-specific.

Pros: - Preserves the most-defensible of the two v1 components.

Cons: - gstack is still a product opinion. Picking one git-workflow tool over alternatives is opinion not architecture. - samuel init still has hardcoded gstack logic for a feature most users won't use. - Inconsistent — if gstack stays because "it's tool-agnostic" but gbrain drops because "it's Claude-specific," the rule is unclear for future components.

Effort: Lower (gstack port + drop gbrain). Saves about a week. Not worth the inconsistency.

Option C: Keep gbrain, drop gstack

Reasoning: gbrain provides a memory feature that's genuinely useful for the autonomous loop. gstack is workflow-preference.

Pros: - Persistent memory is more universally useful than a specific git-workflow tool.

Cons: - gbrain is more Claude-coupled than gstack. Keeping it as a built-in violates the agnostic invariant. - Same inconsistency issue as Option B.

Effort: Lower. Not worth the inconsistency.

Option D: Keep both as built-in components

Maintain v1's behavior. samuel init installs both unless flagged off.

Pros: - Zero migration friction for v1 users. - The components are well-engineered; not throwing away working code.

Cons: - Violates "thin framework" thesis. - Violates agnostic-by-design (gbrain). - Hardcodes one git-workflow tool choice. - Hardcodes one memory MCP choice. - Every v2 release maintains compatibility with the gstack pinned-SHA bumping process — overhead that pays no plugin-architecture dividend.

Effort: Same as v1 (port verbatim). But the value proposition regresses.

Decision

Adopt Option A: drop both gstack and gbrain from the v2 framework.

The decision rests on three judgments:

  1. Product opinions don't belong in the framework binary. Samuel v2's thesis is that capability ships as plugins. Picking one git-workflow tool over five alternatives, or one MCP memory server over three, is exactly the kind of opinion the plugin system exists to defer.

  2. Agnostic-by-design demands gbrain drop at minimum. The invariant ([[../../wiki/concepts/agnostic-by-design]]) requires framework code to not write .claude/settings.json or invoke claude directly. gbrain's claude mcp add invocation violates both.

  3. Consistency between gstack and gbrain matters. Dropping one and keeping the other establishes an unprincipled distinction. Either both belong (Option D) or neither does (Option A). Option D loses the thin-framework win.

Implementation plan

Phase 1 — code removal (PRD 0002, week 4)

The v2 port of v1's orchestrator does not include GstackComponent or GbrainComponent. The orchestrator instantiates with only SamuelComponent (built-in skill bundler) at v2.0 launch.

// internal/orchestrator/setup.go
func New(opts Options) *Orchestrator {
    return orchestrator.New(
        // gstack: dropped
        // gbrain: dropped
        samuel.New(skills.MustFS(), opts.HomeDir, opts.ProjectDir, version.Get()),
    )
}

That's the entire diff from v1's setup at the orchestrator level.

Phase 2 — CLI flag removal (PRD 0002, week 4)

samuel init loses four flags from v1:

  • --skip-gstack
  • --skip-gbrain
  • --gbrain-binary <path>
  • --no-orchestrator

The first three are unreachable (no components to skip). The fourth conflated "skip v4 orchestrator" with "use legacy v3 path"; v2 has only one path. All four removed without deprecation (v2 is a clean break).

Phase 3 — preserve the pinned-SHA pattern as a manifest feature (PRD 0003)

The engineering pattern that drove GstackComponent — pin an external Git repo at a specific SHA, document the bump procedure — survives as a manifest schema field. Plugins that wrap external repos use:

# Hypothetical samuel-gstack-plugin manifest
name = "samuel-gstack"
version = "1.0.0"
kind = "oci"

[oci]
image = "ghcr.io/<author>/samuel-gstack:1.0.0"

[external]
upstream = "https://github.com/garrytan/gstack"
pinned_sha = "e8893a18b18e32ebd63a21f6915337868249ebe1"
bump_procedure = "docs/BUMP.md"

The framework doesn't enforce or validate [external] — it's a documentation convention. But it preserves v1's discipline of "bumping the SHA is a deliberate release event with a documented procedure."

Phase 4 — migration notice (Milestone 6)

docs/getting-started/migration-v1.md includes a section explaining the gstack/gbrain change:

What happened to gstack and gbrain?

In v1, samuel init automatically composed gstack into your project and registered gbrain as a Claude Code MCP server. v2 doesn't ship either as a built-in.

Why: both were product opinions about specific tools. v2's framework is agnostic — git-workflow tools, MCP memory servers, and other choices ship as installable plugins, not built-ins.

What to do:

  • If you used gstack: install it manually with the upstream instructions, or wait for a samuel-gstack plugin (no committed timeline).
  • If you used gbrain: install gbrain per its upstream docs, then register it with Claude Code manually: claude mcp add -s user gbrain $(which gbrain) serve. Or wait for a samuel-gbrain plugin (no committed timeline).

This is the only mention. v2's own docs don't reference gstack or gbrain.

Acceptance criteria

  • internal/components/ contains only samuel/ — no gstack/ or gbrain/ packages.
  • No source file in internal/ mentions gstack or gbrain as a string literal (CI grep check, similar to the agnostic-by-design check).
  • samuel init --help shows no --skip-gstack, --skip-gbrain, --gbrain-binary, --no-orchestrator flags.
  • samuel init in a clean directory creates samuel.toml + .samuel/ + AGENTS.md only — no external repo clones, no MCP registrations.
  • Migration notice in docs/getting-started/migration-v1.md covers the gstack/gbrain change.
  • No v2 RFD other than this one references gstack or gbrain as v2-relevant.

Compatibility and migration

  • For v1 users: no automatic migration. v1's samuel init produced different artifacts than v2's. The migration notice explains the new shape and suggests manual setup for users who depended on gstack/gbrain behavior.
  • For v1's ~/.claude/skills/gstack/: untouched. v2 doesn't manage that path. Users who want it gone run rm -rf ~/.claude/skills/gstack themselves.
  • For v1's gbrain MCP registration: untouched. Stays in ~/.claude/settings.json. v2 doesn't read or modify that file.

Risks

Risk Likelihood Mitigation
Existing v1 users complain about losing gstack/gbrain High Migration notice explains the why. Pattern matches every other v2 clean-break decision (samuel.toml replaces samuel.yaml, .samuel/ replaces .claude/, etc.).
Community demand for samuel-gstack plugin emerges; no maintainer steps up Medium Document the gap explicitly. v2's plugin authoring guide includes a "wrapping an external Git repo" template.
The [external] manifest convention isn't followed by plugin authors Low It's a documentation convention, not a hard rule. Plugins that don't use it work fine; users can't query the upstream metadata. Acceptable.
v1 users who installed gstack via Samuel find it broken later (unmanaged) Low gstack is at ~/.claude/skills/gstack/. It works regardless of Samuel. v2 doesn't touch it.
Future Samuel release accidentally re-adds gstack/gbrain logic Low The grep-for-literal CI check (acceptance criterion) prevents this.

Resolved decisions (2026-05-12)

  1. Ship samuel-gstack plugin as example: no. Re-privileges one git-workflow tool. The plugin authoring guide documents the pattern using gstack as an illustrative example without shipping an actual plugin.

  2. samuel doctor detects v1 gstack install: yes, informational. "v1 gstack install detected at ~/.claude/skills/gstack/; not managed by v2." Helps v1 users debug.

  3. Other v1 composed externals: covered by [[0007|RFD 0007]] — the Anthropic community skills migrate via registry subpath references. No other "composed externals" in v1's scope.

Outcome

To be filled in post-v2.0 launch. Expected outcomes:

  • Migration notice is read by ~70% of v1 users surveyed; gstack/gbrain absence is the most-flagged change.
  • ~5% of surveyed users care enough to want a plugin equivalent.
  • No samuel-gstack or samuel-gbrain plugin ships in the first year of v2.x. If the demand stays low, the right outcome is no plugins at all.
  • [[0001|RFD 0001]] — three-tier plugin model that would host any future replacement plugins
  • [[0005|RFD 0005]] — orchestrator + Plugin interface (carries forward without these components)
  • [[../../wiki/entities/component-gstack-gbrain]] — wiki source documenting both v1 components
  • [[../../wiki/concepts/agnostic-by-design]] — invariant gbrain drop preserves
  • [[../../wiki/concepts/extensibility-design]] — built-in vs plugin boundary (these were built-ins; nothing replaces them)
  • v1 source files (preserved for reference at v1-final tag): samuel_v1/internal/orchestrator/component_gstack.go, component_gbrain.go