gStack: Specialized AI Workflows for Claude Code

---

Detailed Description of gstack: A Revolutionary Workflow System for Claude Code

Introduction to gstack

gstack is an innovative extension designed for Claude Code, a specialized coding assistant developed by Anthropic, transforming it from a generic AI tool into a team-based workflow engine. It introduces nine distinct cognitive modes—each tailored to different stages of software development—to enhance productivity, precision, and collaboration. By allowing users to switch between roles like founder, engineering manager, paranoid reviewer, or release engineer, gstack eliminates the ambiguity inherent in generic AI prompts.

At its core, gstack is a modular operating system for software teams, enabling parallel execution of multiple workflows simultaneously. It leverages Conductor (a tool by Y Combinator) to run multiple Claude Code sessions concurrently, each with isolated browser instances and state management. This setup ensures no interference between tasks, allowing developers to focus on distinct phases—such as planning, coding, reviewing, or testing—without context-switching.

---

Core Concepts and Workflow Modes

1. The Problem with Generic AI Prompts

Before gstack, Claude Code operated in a single, monolithic mode, leading to inefficiencies:

• Lack of Directionality: Users were forced to implement requests literally, often missing the bigger picture.
• Inconsistent Depth: "Review my PR" yielded varying levels of scrutiny each time.
• Blind Coding: The AI could write code but lacked visibility into the application’s UI or backend logic.
• Manual QA Testing: Developers had to manually open browsers, click through pages, and verify fixes—a tedious process.

gstack addresses these issues by providing nine specialized modes, each designed for a specific cognitive role:

| Skill | Role | Purpose | |-------------------------|------------------------------|----------------------------------------------------------------------------| | /plan-ceo-review | Founder/CEO | Reframes the problem to uncover the 10-star product behind the request. | | /plan-eng-review | Engineering Manager | Locks in architecture, data flow, and failure modes with detailed diagrams. | | /review | Paranoid Staff Engineer | Identifies production-breaking bugs that pass CI checks. | | /ship | Release Engineer | Executes the final release process: syncing branches, running tests, and pushing code. | | /browse | QA Engineer | Provides visual inspection of web applications via a headless browser. | | /qa | QA Lead | Automates testing based on git diffs or URLs, with quick/smoke/regression modes. | | /qa-only | Bug Reporter | Reports bugs without modifying code. | | /setup-browser-cookies| Session Manager | Imports real browser cookies for authenticated testing. | | /retro | Engineering Manager | Conducts data-driven retrospectives, analyzing team performance and growth opportunities. |

---

2. How gstack Operates: A Step-by-Step Breakdown

Step 1: Installation

To integrate gstack with Claude Code, users must follow these steps:

1. Install Dependencies:

• Ensure Claude Code, Git, and Bun (v1.0+) are installed.
• Clone the gstack repository: bash git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup

1. Configure CLAUDE.md:

• Add a gstack section to specify the use of /browse for web browsing and list all available skills.

1. Project Installation (Optional):

• For team collaboration, copy gstack into the project directory and update CLAUDE.md.

Step 2: Key Features

• Isolated Workspaces: Each session runs in a separate Chromium process with its own cookies and tabs, preventing conflicts.
• Browser Automation: The /browse skill compiles a native binary that interacts with Playwright (Microsoft’s headless browser automation tool), enabling rapid UI testing.
• Greptile Integration: gstack works seamlessly with Greptile, an AI-powered PR reviewer. It triages comments automatically:
• Valid issues are fixed immediately.
• Already-fixed issues receive auto-replies.
• False positives are flagged for manual review.

Step 3: Workflow Execution

A typical gstack workflow follows a structured sequence:

1. Planning Phase (/plan-ceo-review):

• The user describes the feature (e.g., "Add seller photo upload to the listing app").
• The AI reframes the request into a higher-value goal: "Help sellers create listings that sell by auto-identifying products, drafting titles, and suggesting hero images."
• This ensures alignment with user needs rather than just implementing a literal requirement.

1. Engineering Review (/plan-eng-review):

• Once the product direction is clear, the AI generates an architecture diagram, state machine, and test matrix.
• Example: For photo upload, it defines boundaries between upload, classification, enrichment, and draft generation workflows.

1. Bug Detection (/review):

• After implementation, /review performs a structural audit for issues like race conditions, trust boundaries, or missing indexes.
• Example: It flags "Race condition: two tabs can overwrite cover-photo selection" and suggests fixes.

1. Release Execution (/ship):

• The final step syncs with main, runs tests, resolves Greptile reviews, and pushes the code.
• This ensures the branch is ready for deployment without manual intervention.

1. Quality Assurance (/qa and /browse):

• /qa analyzes git diffs to identify affected pages and tests them automatically.
  • Example: For a listing app, it checks /listings/new, /listings/:id, and /api/listings.
• /browse performs manual UI testing via screenshots and console logs.
  • Example: It signs up a test user, navigates through pages, and verifies functionality.

1. Session Management (/setup-browser-cookies):

• Before authenticated testing, users import cookies from their real browser (e.g., Chrome or Edge) to avoid manual logins.

1. Retrospective Analysis (/retro):

• At the end of a sprint, /retro generates a data-driven report on team performance.
  • Example: It highlights productivity metrics like commits, LOC, and PR sizes, along with individual contributions and growth opportunities.

---

Visualizing gstack in Action

Example Workflow: Adding Seller Photo Upload

1. Planning Phase: (Illustration of the AI reframing "photo upload" into a product vision.)

• The AI suggests enhancing the feature with auto-product identification, title drafting, and image optimization.

1. Engineering Review: (Architecture diagram showing async job boundaries for upload → classification → enrichment.)

• A state machine diagram illustrates how failed uploads are handled and retries work.

1. Bug Detection:

• /review identifies race conditions in the cover-photo selection process. (Example of a critical bug report with suggested fixes.)

1. Testing Phase:

• /qa performs a quick smoke test on staging: Health Score: 91/100 Medium Issue: Mobile nav overlaps below 1024px width.
• Screenshots of the UI are saved for reference.

1. Release Execution:

• /ship syncs with main, runs tests, and pushes the branch: Syncing main... Tests passed. PR created: https://github.com/your-repo/pull/123

---

Technical Internals

Browser Automation (/browse)

• Uses Playwright to interact with Chromium, enabling:
• Cookie persistence across sessions.
• Screenshot capture and console log analysis.
• Form filling and navigation automation.

Greptile Integration

• gstack reads Greptile’s PR comments and classifies them as:
• Valid: Immediate fixes required.
• Already Fixed: Auto-replies to acknowledge.
• False Positive: Manual review needed.

Retrospective Analysis (/retro)

• Tracks metrics like:
• Commit frequency and LOC.
• Test coverage and PR sizes.
• Team productivity trends over time.
• Uses JSON snapshots for trend comparison (e.g., comparing this week vs. last).

---

Advantages Over Traditional Workflows

| Aspect | Traditional AI Prompts | gstack | |--------------------------|----------------------------------------------------|------------------------------------------------| | Cognitive Flexibility | Single, monolithic mode | Nine specialized modes for distinct roles. | | Parallel Execution | Sequential tasks | Concurrent workflows via Conductor. | | Bug Detection | Manual QA testing | Automated /review and /qa with Greptile. | | Testing Efficiency | Time-consuming manual checks | Fast, automated UI tests via /browse. | | Retrospectives | Vague team feedback | Data-driven insights with /retro. |

---

Use Cases for gstack

1. Founders and Product Managers:

• Use /plan-ceo-review to validate product direction before coding.
• Example: "Should we add a photo upload feature, or should we focus on auto-product identification?"

1. Engineering Teams:

• Use /plan-eng-review to design robust architectures (e.g., async job boundaries).
• Example: "How do we handle failed uploads without orphaned files?"

1. QA Engineers:

• Use /qa to automate regression testing after code changes.
• Example: "Test all affected routes in the listing app."

1. Release Teams:

• Use /ship to streamline final deployments.
• Example: "Sync with main, run tests, and push the branch."

1. Engineering Managers:

• Use /retro to analyze team performance and growth opportunities.
• Example: "What were our biggest productivity gains this week?"

---

Troubleshooting and Best Practices

Common Issues

• Skills Not Showing Up? Run:

  cd ~/.claude/skills/gstack && ./setup

• /browse Fails? Ensure Bun is installed (v1.0+) and compile the binary:

  bun install && bun run build

Best Practices

• Use /plan-ceo-review Early: Refine product vision before diving into implementation.
• Leverage /review for Critical Bugs: Catch production issues before they escalate.
• Automate Testing with /qa: Reduce manual QA effort by 90%+.
• Import Cookies for Authenticated Tests: Avoid manual logins with /setup-browser-cookies.
• Conduct Weekly Retrospectives: Use /retro to track team trends and improve workflows.

---

Conclusion: Why gstack is a Game-Changer

gstack transforms Claude Code from a generic coding assistant into a powerful, modular workflow engine. By providing explicit cognitive modes for planning, reviewing, shipping, and testing, it eliminates ambiguity and accelerates software development. Its ability to run parallel sessions with isolated state management enables teams to work on multiple tasks simultaneously without interference.

For developers who prioritize precision, collaboration, and efficiency, gstack is not just an upgrade—it’s a revolution in how AI-assisted workflows are designed and executed. Whether you’re a founder refining product vision or a QA engineer automating regression tests, gstack offers the tools to build better software faster.

---

Final Note: For further details on technical internals (e.g., browser architecture, Greptile integration), refer to the included documentation files (CONTRIBUTING.md, ARCHITECTURE.md, BROWSER.md).