How pretomsid/gstack works
1. What this repo is
- gstack is a workflow/platform repo for AI-assisted software delivery, not a single app.
- It packages many Markdown “skills” plus the code that makes those skills executable across different agent hosts (Claude Code, Codex, Cursor, OpenClaw, etc.).
2. Two major layers: content and runtime
- The content layer is the large set of SKILL.md files, section templates, and generated docs under directories like review/, ship/, qa/, design/, browse/, document-release/, setup-gbrain/, etc.
- The runtime layer is TypeScript/Bun code under bin/, scripts/, lib/, browse/src/, design/src/, make-pdf/src/, ios-qa/daemon/src/, and shared helpers in lib/.
3. Skill orchestration is the core product
- Most user-facing behavior is delivered as slash-command workflows: plan, review, QA, ship, investigate, browse, design, security audit, document generation, memory sync, and more.
- The scripts/resolvers/ tree acts like a composition engine that assembles prompts, sections, and model-specific overlays into final skill outputs.
4. Browser subsystem is a full service boundary
- browse/ is the heaviest runtime subsystem and effectively the “eyes and hands” for agents.
- It wraps Chromium/CDP, browser session management, proxying, screenshots, cookie import, tab/session tracking, and browser-side commands.
- It also contains a security boundary: URL validation, path permissions, content sanitization, stealth behaviors, and tunnel/session lease logic.
5. Browser security is a first-class architecture concern
- Prompt-injection defense is layered: local classifier logic, transcript checks, canary token detection, allowlists, and a verdict combiner.
- Important boundaries live in browse/src/security-*, sanitize.ts, url-validation.ts, cdp-allowlist.ts, proxy-redact.ts, and related tests.
- This subsystem is designed to trust only curated browser actions, not arbitrary page instructions.
6. Memory and knowledge services are separate from the browser
- The repo integrates with GBrain as an external/persistent knowledge store for agent memory.
- bin/gstack-brain-*, lib/gbrain-*, and scripts/resolvers/gbrain.ts handle detection, sync, guardrails, local/remote status, and source wiring.
- The data flow is from repo content and learned artifacts into a local or remote brain, then back into agent prompts via guidance blocks and search/lookup tools.
7. Design and documentation pipeline is a second major workflow family
- design/ provides a design-to-code and iterate/compare loop with a daemon/client split.
- document-release/, document-generate/, diagram/, and make-pdf/ form the documentation/publishing pipeline: generate docs, render diagrams, and output PDFs/HTML/Word.
- This side of the repo is about turning product intent into artifacts, then keeping repo docs synchronized with shipped changes.
8. Release, review, QA, and security are independent stages
- review/, qa/, cso/, ship/, canary/, benchmark/, and related skills map to the sprint lifecycle: review, test, ship, monitor, measure, and audit.
- These workflows are intentionally separated so architecture, design, security, and QA can be invoked independently depending on the type of change.
- The README emphasizes that each stage consumes outputs from prior stages, rather than all work happening in one prompt.
9. iOS QA is its own daemonized subsystem
- ios-qa/daemon/ is a Mac-side broker for driving a real iPhone over USB/CoreDevice.
- It includes single-instance control, session tokens, proxying, allowlists, and optional Tailscale exposure for remote agents.
- This is a distinct infrastructure boundary from the browser system: hardware access, not web automation.
10. Telemetry and cloud services are minimal but real
- Telemetry is opt-in and flows to Supabase via edge functions in supabase/functions/, with schema and RLS policies in supabase/migrations/.
- The repo also supports update checks, analytics, and public/private state synchronization through cloud-backed services, but these are clearly bounded and optional.
11. Host integration is adapter-based
- hosts/ and scripts/host-adapters/ define how gstack installs and routes skills for different AI tools.
- setup-style behavior is host-aware: skills are copied/symlinked into the right directories, and prompt overlays vary per model/host.
- This means the repo is not tied to one agent runtime; it is a portability layer.
12. Execution model is mostly CLI + Markdown + generated files
- The repo’s primary runtime is command-line driven, with Bun/TypeScript and shell scripts orchestrating local files, generated prompts, browser sessions, and daemon processes.
- Markdown is not just documentation here; it is the contract format for skills, section manifests, and generated outputs.
- Tests are extensive and map closely to subsystems, which is important for the architecture diagram: most boundaries are validated as independent units.
13. A good architecture diagram should show these main flows
- User/agent input enters through a host adapter or slash command.
- Skill composition logic selects templates, sections, model overlays, and guidance.
- That output fans out to one of several execution domains: browser automation, design generation, memory sync, iOS device control, review/QA/ship, or document publishing.
- Results return as transcripts, artifacts, docs, PRs, telemetry, or persisted memory.
14. Key boundary summary
- Content boundary: Markdown skill definitions and templates.
- Orchestration boundary: TypeScript/Bun command and resolver layer.
- Automation boundary: Browser, iOS, and PDF/diagram subprocesses.
- Persistence boundary: GBrain, local state, telemetry, and Supabase.
- Security boundary: browser sanitization, allowlists, redaction, and capability gating.
Main entry points: index.ts Resolvers · server.ts Browser service · redact-engine.ts Shared libs · gstack-config CLI commands
Components 20
Skill content
Markdown skill definitions, templates, and generated workflow docs.
- Skills · Repository-wide skill definitions and templates that define the agent-facing workflow surface.
SKILL.md - Review flow · Architecture, design, devex, QA, and security review workflows plus section bundles.
review/SKILL.md - Ship flow · Release-stage prompts and section templates for testing, changelogs, PR bodies, and completion checks.
ship/SKILL.md - Browse flow · Browser-oriented skill contracts and examples for agent automation.
browse/SKILL.md - Brain setup · Skills for setting up, syncing, and using persistent GBrain knowledge storage.
setup-gbrain/SKILL.md
Runtime orchestration
Command-line entrypoints, resolvers, host adapters, and maintenance scripts.
- Host adapters · Adapters for Claude, Codex, Cursor, OpenClaw, and other host runtimes.
hosts/index.ts - Resolvers · Assembles prompts, overlays, sections, preambles, and routing into executable skills.
scripts/resolvers/index.ts - Skill tooling · Discovery, generation, evaluation, and repo-wide skill maintenance scripts.
scripts/gen-skill-docs.ts - CLI commands · Top-level binaries for config, analytics, redaction, decisions, and session management.
bin/gstack-config
Automation services
Browser, design, iOS, and document-rendering execution boundaries.
- Browser service · Chromium/CDP service for sessions, commands, screenshots, cookies, proxying, and terminal control.
browse/src/server.ts - Browser security · Prompt-injection defense, sanitization, URL and path validation, allowlists, redaction, stealth, and verdict logic.
browse/src/security.ts - Browser sessions · Browser manager, tab/session tracking, PTY leasing, cookies, and command routing.
browse/src/browser-manager.ts - Design runtime · Design-to-code, compare, iterate, evolve, and daemon/client orchestration.
design/src/cli.ts - Doc pipeline · Document generation, release packaging, diagram rendering, and PDF output orchestration.
make-pdf/src/cli.ts - iOS QA daemon · Mac-side broker for controlling real iPhone sessions over USB/CoreDevice with auth, proxying, and tunnel support.
ios-qa/daemon/src/index.ts - Browser extension · Extension-side UI and bridge scripts used by browser automation and sidepanel workflows.
extension/manifest.json - Browser skills pkg · Standalone browser task package and local script harnesses for specific browser workflows.
browser-skills/hackernews-frontpage/SKILL.md
Persistence
Memory, telemetry, and cloud-backed state services.
- GBrain services · Detection, sync, guardrails, sources, and local-status helpers for persistent knowledge storage.
lib/gbrain-exec.ts - Telemetry cloud · Opt-in telemetry, update checks, and installation state synchronized through Supabase functions and migrations.
supabase/functions/telemetry-ingest/index.ts
Shared core
Reusable libraries and cross-cutting helpers.
- Shared libs · Repo-wide helpers for redaction, decisions, worktrees, JSONL storage, and environment shims.
lib/redact-engine.ts
Connections 25
- Host adapters → Resolvers: routes · Host-specific adapters route requests into the shared resolver and composition layer.
- Resolvers → Skills: renders · Resolvers assemble Markdown skills, templates, overlays, and sections into final prompts.
- Resolvers → Review flow: composes · Review-stage workflows are built from shared resolver primitives and section manifests.
- Resolvers → Ship flow: composes · Release workflows are assembled with lifecycle-specific sections and checks.
- Resolvers → Browse flow: injects · Browser-specific commands and prompts are composed into executable browser skills.
- Resolvers → Brain setup: injects · Brain setup and sync guidance is added through resolver-generated prompt blocks.
- Skill tooling → Resolvers: supports · Script tooling discovers skills, generates docs, and validates the resolver output surface.
- CLI commands → Shared libs: uses · Top-level commands rely on shared helpers for state, logging, redaction, and environment handling.
- CLI commands → GBrain services: syncs · Brain-related binaries drive detection, sync, restore, and guardrail flows.
- CLI commands → Telemetry cloud: reports · Analytics and telemetry commands forward opt-in events to cloud-backed services.
- Browser service → Browser security: enforces · All browser actions pass through layered security checks and sanitization boundaries.
- Browser service → Browser sessions: manages · The browser service coordinates session state, tabs, cookies, and terminal interaction.
- Browser service → Browser extension: bridges · Browser automation integrates with extension-side UI and message plumbing.
- Browser service → Browser skills pkg: executes · Browser service runs packaged browser task skills and their local harnesses.
- Browser service → Shared libs: depends on · Browser runtime uses shared redaction, worktree, and support utilities.
- Design runtime → Doc pipeline: publishes · Design artifacts can flow into generated docs, diagrams, and exported deliverables.
- Design runtime → Shared libs: depends on · Design orchestration reuses common repo helpers and state management.
- Doc pipeline → Browser service: renders via · PDF and document generation can drive browser-based rendering and capture.
- iOS QA daemon → Shared libs: depends on · iOS broker logic shares common helpers and repo state utilities.
- GBrain services → Shared libs: uses · GBrain exec and guardrail logic share core library code.
- Telemetry cloud → Shared libs: validates · Cloud sync and telemetry logic use shared redaction and schema helpers.
- Review flow → Ship flow: feeds · Review outputs are consumed by ship-stage templates and release checks.
- GBrain services → Resolvers: feeds context · Brain sync and lookup results are injected back into prompt composition.
- Browser service → Resolvers: returns artifacts · Browser sessions produce transcripts, snapshots, and command outputs that resolvers can reuse.
- iOS QA daemon → Resolvers: returns artifacts · iOS QA sessions return device transcripts and test artifacts into workflows.