# pretomsid/gstack architecture

> Architecture diagram of the GitHub repository pretomsid/gstack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pretomsid/gstack
- Repository: https://github.com/pretomsid/gstack

## Overview

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: [`scripts/resolvers/index.ts`](https://github.com/pretomsid/gstack/blob/main/scripts/resolvers/index.ts) (Resolvers), [`browse/src/server.ts`](https://github.com/pretomsid/gstack/blob/main/browse/src/server.ts) (Browser service), [`lib/redact-engine.ts`](https://github.com/pretomsid/gstack/blob/main/lib/redact-engine.ts) (Shared libs), [`bin/gstack-config`](https://github.com/pretomsid/gstack/tree/main/bin/gstack-config) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Skill content"]
  node_skills_root["Skills<br/>markdown workflows<br/>[SKILL.md]"]
  node_review_skills["Review flow<br/>skill family<br/>[SKILL.md]"]
  node_ship_skills["Ship flow<br/>skill family<br/>[SKILL.md]"]
  node_browse_skills["Browse flow<br/>skill runtime<br/>[SKILL.md]"]
  node_gbrain_skills["Brain setup<br/>skill family<br/>[SKILL.md]"]
end

subgraph group_runtime["Runtime orchestration"]
  node_host_adapters["Host adapters<br/>adapter layer<br/>[index.ts]"]
  node_skill_resolvers["Resolvers<br/>composition engine<br/>[index.ts]"]
  node_skill_scripts["Skill tooling<br/>cli tooling<br/>[gen-skill-docs.ts]"]
  node_cli_bins["CLI commands<br/>command suite"]
end

subgraph group_automation["Automation services"]
  node_browser_service[("Browser service<br/>automation boundary<br/>[server.ts]")]
  node_browser_security{{"Browser security<br/>security boundary<br/>[security.ts]"}}
  node_browser_session["Browser sessions<br/>session manager<br/>[browser-manager.ts]"]
  node_design_runtime["Design runtime<br/>workflow service<br/>[cli.ts]"]
  node_doc_pipeline["Doc pipeline<br/>publishing pipeline<br/>[cli.ts]"]
  node_ios_daemon[("iOS QA daemon<br/>device broker<br/>[index.ts]")]
  node_browser_extension["Browser extension<br/>browser bridge<br/>[manifest.json]"]
  node_browser_skills_pkg["Browser skills pkg<br/>skill package<br/>[SKILL.md]"]
end

subgraph group_persistence["Persistence"]
  node_gbrain_services[("GBrain services<br/>memory service<br/>[gbrain-exec.ts]")]
  node_telemetry_cloud[("Telemetry cloud<br/>supabase backend<br/>[index.ts]")]
end

subgraph group_shared["Shared core"]
  node_shared_libs["Shared libs<br/>core libraries<br/>[redact-engine.ts]"]
end

node_host_adapters -->|"routes"| node_skill_resolvers
node_skill_resolvers -->|"renders"| node_skills_root
node_skill_resolvers -->|"composes"| node_review_skills
node_skill_resolvers -->|"composes"| node_ship_skills
node_skill_resolvers -->|"injects"| node_browse_skills
node_skill_resolvers -->|"injects"| node_gbrain_skills
node_skill_scripts -->|"supports"| node_skill_resolvers
node_cli_bins -->|"uses"| node_shared_libs
node_cli_bins -->|"syncs"| node_gbrain_services
node_cli_bins -->|"reports"| node_telemetry_cloud
node_browser_service -->|"enforces"| node_browser_security
node_browser_service -->|"manages"| node_browser_session
node_browser_service -->|"bridges"| node_browser_extension
node_browser_service -->|"executes"| node_browser_skills_pkg
node_browser_service -->|"depends on"| node_shared_libs
node_design_runtime -->|"publishes"| node_doc_pipeline
node_design_runtime -->|"depends on"| node_shared_libs
node_doc_pipeline -->|"renders via"| node_browser_service
node_ios_daemon -->|"depends on"| node_shared_libs
node_gbrain_services -->|"uses"| node_shared_libs
node_telemetry_cloud -->|"validates"| node_shared_libs
node_review_skills -.->|"feeds"| node_ship_skills
node_gbrain_services -.->|"feeds context"| node_skill_resolvers
node_browser_service -.->|"returns artifacts"| node_skill_resolvers
node_ios_daemon -.->|"returns artifacts"| node_skill_resolvers

click node_skills_root "https://github.com/pretomsid/gstack/blob/main/SKILL.md"
click node_review_skills "https://github.com/pretomsid/gstack/blob/main/review/SKILL.md"
click node_ship_skills "https://github.com/pretomsid/gstack/blob/main/ship/SKILL.md"
click node_browse_skills "https://github.com/pretomsid/gstack/blob/main/browse/SKILL.md"
click node_gbrain_skills "https://github.com/pretomsid/gstack/blob/main/setup-gbrain/SKILL.md"
click node_host_adapters "https://github.com/pretomsid/gstack/blob/main/hosts/index.ts"
click node_skill_resolvers "https://github.com/pretomsid/gstack/blob/main/scripts/resolvers/index.ts"
click node_skill_scripts "https://github.com/pretomsid/gstack/blob/main/scripts/gen-skill-docs.ts"
click node_cli_bins "https://github.com/pretomsid/gstack/tree/main/bin/gstack-config"
click node_browser_service "https://github.com/pretomsid/gstack/blob/main/browse/src/server.ts"
click node_browser_security "https://github.com/pretomsid/gstack/blob/main/browse/src/security.ts"
click node_browser_session "https://github.com/pretomsid/gstack/blob/main/browse/src/browser-manager.ts"
click node_design_runtime "https://github.com/pretomsid/gstack/blob/main/design/src/cli.ts"
click node_doc_pipeline "https://github.com/pretomsid/gstack/blob/main/make-pdf/src/cli.ts"
click node_ios_daemon "https://github.com/pretomsid/gstack/blob/main/ios-qa/daemon/src/index.ts"
click node_gbrain_services "https://github.com/pretomsid/gstack/blob/main/lib/gbrain-exec.ts"
click node_telemetry_cloud "https://github.com/pretomsid/gstack/blob/main/supabase/functions/telemetry-ingest/index.ts"
click node_shared_libs "https://github.com/pretomsid/gstack/blob/main/lib/redact-engine.ts"
click node_browser_extension "https://github.com/pretomsid/gstack/blob/main/extension/manifest.json"
click node_browser_skills_pkg "https://github.com/pretomsid/gstack/blob/main/browser-skills/hackernews-frontpage/SKILL.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skills_root,node_review_skills,node_ship_skills,node_browse_skills,node_gbrain_skills toneBlue
class node_host_adapters,node_skill_resolvers,node_skill_scripts,node_cli_bins toneAmber
class node_browser_service,node_browser_security,node_browser_session,node_design_runtime,node_doc_pipeline,node_ios_daemon,node_browser_extension,node_browser_skills_pkg toneMint
class node_gbrain_services,node_telemetry_cloud toneRose
class node_shared_libs toneIndigo
```

## Components

### Skill content

Markdown skill definitions, templates, and generated workflow docs.

- [Skills](https://github.com/pretomsid/gstack/blob/main/SKILL.md): markdown workflows · Repository-wide skill definitions and templates that define the agent-facing workflow surface. · `SKILL.md`
- [Review flow](https://github.com/pretomsid/gstack/blob/main/review/SKILL.md): skill family · Architecture, design, devex, QA, and security review workflows plus section bundles. · `review/SKILL.md`
- [Ship flow](https://github.com/pretomsid/gstack/blob/main/ship/SKILL.md): skill family · Release-stage prompts and section templates for testing, changelogs, PR bodies, and completion checks. · `ship/SKILL.md`
- [Browse flow](https://github.com/pretomsid/gstack/blob/main/browse/SKILL.md): skill runtime · Browser-oriented skill contracts and examples for agent automation. · `browse/SKILL.md`
- [Brain setup](https://github.com/pretomsid/gstack/blob/main/setup-gbrain/SKILL.md): skill family · 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](https://github.com/pretomsid/gstack/blob/main/hosts/index.ts): adapter layer · Adapters for Claude, Codex, Cursor, OpenClaw, and other host runtimes. · `hosts/index.ts`
- [Resolvers](https://github.com/pretomsid/gstack/blob/main/scripts/resolvers/index.ts): composition engine · Assembles prompts, overlays, sections, preambles, and routing into executable skills. · `scripts/resolvers/index.ts`
- [Skill tooling](https://github.com/pretomsid/gstack/blob/main/scripts/gen-skill-docs.ts): cli tooling · Discovery, generation, evaluation, and repo-wide skill maintenance scripts. · `scripts/gen-skill-docs.ts`
- [CLI commands](https://github.com/pretomsid/gstack/tree/main/bin/gstack-config): command suite · 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](https://github.com/pretomsid/gstack/blob/main/browse/src/server.ts): automation boundary · Chromium/CDP service for sessions, commands, screenshots, cookies, proxying, and terminal control. · `browse/src/server.ts`
- [Browser security](https://github.com/pretomsid/gstack/blob/main/browse/src/security.ts): security boundary · Prompt-injection defense, sanitization, URL and path validation, allowlists, redaction, stealth, and verdict logic. · `browse/src/security.ts`
- [Browser sessions](https://github.com/pretomsid/gstack/blob/main/browse/src/browser-manager.ts): session manager · Browser manager, tab/session tracking, PTY leasing, cookies, and command routing. · `browse/src/browser-manager.ts`
- [Design runtime](https://github.com/pretomsid/gstack/blob/main/design/src/cli.ts): workflow service · Design-to-code, compare, iterate, evolve, and daemon/client orchestration. · `design/src/cli.ts`
- [Doc pipeline](https://github.com/pretomsid/gstack/blob/main/make-pdf/src/cli.ts): publishing pipeline · Document generation, release packaging, diagram rendering, and PDF output orchestration. · `make-pdf/src/cli.ts`
- [iOS QA daemon](https://github.com/pretomsid/gstack/blob/main/ios-qa/daemon/src/index.ts): device broker · 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](https://github.com/pretomsid/gstack/blob/main/extension/manifest.json): browser bridge · Extension-side UI and bridge scripts used by browser automation and sidepanel workflows. · `extension/manifest.json`
- [Browser skills pkg](https://github.com/pretomsid/gstack/blob/main/browser-skills/hackernews-frontpage/SKILL.md): skill package · 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](https://github.com/pretomsid/gstack/blob/main/lib/gbrain-exec.ts): memory service · Detection, sync, guardrails, sources, and local-status helpers for persistent knowledge storage. · `lib/gbrain-exec.ts`
- [Telemetry cloud](https://github.com/pretomsid/gstack/blob/main/supabase/functions/telemetry-ingest/index.ts): supabase backend · 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](https://github.com/pretomsid/gstack/blob/main/lib/redact-engine.ts): core libraries · Repo-wide helpers for redaction, decisions, worktrees, JSONL storage, and environment shims. · `lib/redact-engine.ts`

## Connections

- 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.