gstack

Lời nói đầu

gstack ra đời từ một nhận thức quan trọng: AI coding assistant không nên stuck (mắc kẹt) trong một mode duy nhất.

Planning (lập kế hoạch) không phải review (đánh giá). Review không phải shipping (phát hành). Founder taste (khẩu vị sáng lập) không phải engineering rigor (kỷ luật kỹ thuật). Nếu bạn trộn lẫn tất cả lại, bạn thường nhận được một sản phẩm trung bình.

Garry Tan - CEO của Y Combinator - xây dựng gstack vì muốn explicit gears (bánh răng rõ ràng): khả năng chuyển đổi cognitive mode (chế độ nhận thức) theo yêu cầu - từ founder, eng manager, paranoid reviewer cho đến release machine.

Cuốn hướng dẫn này biên soạn lại toàn bộ tài liệu gstack thành tiếng Việt, giữ nguyên thuật ngữ gốc tiếng Anh để bạn dễ tra cứu thêm.

1. Giới thiệu gstack

gstack là gì?

gstack biến Claude Code từ một assistant (trợ lý) generic thành đội ngũ specialist (chuyên gia) bạn có thể triệu hồi theo yêu cầu.

8 opinionated workflow skills cho Claude Code: plan review, code review, one-command shipping, browser automation, QA testing, và engineering retrospectives - tất cả dưới dạng slash commands.

Without vs With gstack

Không có gstack

• Agent nhận request quá literal (theo nghĩa đen) - không bao giờ hỏi bạn có đang build đúng thứ không
• Nó implement đúng những gì bạn nói, dù sản phẩm thực sự cần thứ lớn hơn
• "Review my PR" cho kết quả depth (chiều sâu) không nhất quán mỗi lần
• "Ship this" biến thành cuộc trao đổi dài dòng về việc phải làm gì
• Agent viết code được nhưng không nhìn thấy app - nó "mù một nửa"

Với gstack

Ai nên dùng gstack?

Bạn đã dùng Claude Code nhiều và muốn consistent, high-rigor workflows thay vì "one mushy generic mode" (một chế độ chung chung). Bạn muốn nói cho model biết loại brain (bộ não) nào cần dùng ngay - founder taste, engineering rigor, paranoid review, hoặc fast execution.

Đây không phải prompt pack cho beginners (người mới). Đây là operating system cho người ship (phát hành sản phẩm).

2. 8 Skills chi tiết

/plan-ceo-review - Founder Mode

Ví dụ: Bạn nói "Cho sellers upload photo cho item". Assistant yếu sẽ thêm file picker và save image. Nhưng /plan-ceo-review sẽ hỏi liệu "photo upload" có phải feature thực không. Có thể feature thực là giúp người bán tạo listing bán chạy:

• Có thể identify (nhận diện) sản phẩm từ ảnh?
• Có thể search web và draft (soạn thảo) title + description tự động?
• Có thể pull specs, category, pricing comps?
• Có thể detect ảnh xấu, tối, cluttered?

Nó không chỉ hỏi "làm sao thêm feature này?" mà hỏi "10-star product ẩn trong request này là gì?"

/plan-eng-review - Eng Manager Mode

Mode này nail (đóng đinh):

• Architecture (kiến trúc) và system boundaries (ranh giới hệ thống)
• Data flow (luồng dữ liệu) và state transitions (chuyển trạng thái)
• Failure modes (các cách hỏng) và edge cases (trường hợp biên)
• Trust boundaries (ranh giới tin cậy) và test coverage (phạm vi kiểm thử)
• Diagrams (sơ đồ) - sequence, state, component, data-flow diagrams

LLMs trở nên hoàn chỉnh hơn rất nhiều khi bạn buộc chúng vẽ hệ thống. Diagrams bắt hidden assumptions (giả định ẩn) lộ ra.

/review - Paranoid Staff Engineer Mode

Structural audit (kiểm toán cấu trúc), không phải style nitpick (chỉnh sửa phong cách). Model tìm:

• N+1 queries và stale reads (đọc dữ liệu cũ)
• Race conditions (điều kiện tranh chấp)
• Bad trust boundaries (ranh giới tin cậy sai)
• Missing indexes và escaping bugs
• Broken invariants (bất biến bị phá vỡ)
• Tests that pass while missing the real failure mode

/ship - Release Machine Mode

/ship là cho final mile. Cho branch ready, không phải để decide what to build. Model trở thành disciplined release engineer:

• Sync with main, run tests
• Check branch state, update changelog/versioning
• Push và create/update PR
• Triage Greptile review comments

Nhiều branches chết khi phần hấp dẫn xong và chỉ còn boring release work. Humans procrastinate (trì hoãn) phần đó. AI không nên.

/browse - QA Engineer Mode

Compiled binary talks to persistent Chromium daemon - build trên Playwright. First call start browser (~3s). Mỗi call sau: ~100-200ms. Browser stays running giữa các commands.

Ví dụ flow:

You:   /browse staging.myapp.com - log in, test signup flow

Claude: [18 tool calls, ~60 seconds]
        > browse goto https://staging.myapp.com/signup
        > browse snapshot -i
        > browse fill @e2 "[email protected]"
        > browse fill @e3 "password123"
        > browse click @e5  (Submit)
        > browse screenshot /tmp/signup.png

        Signup works. Redirected to onboarding.
        Dashboard loads. No console errors.
        All 4 pages load correctly.

/qa - QA Lead Mode

4 modes:

You:   /qa
Claude: Analyzing branch diff against main...
        12 files changed, 3 routes affected.
        QA Report: 3 routes tested, all working.
        No console errors. No regressions.

/setup-browser-cookies - Session Manager Mode

Auto-detect Chromium browsers, decrypt cookies qua macOS Keychain, load vào session. Interactive picker UI hoặc CLI trực tiếp:

You:   /setup-browser-cookies github.com
Claude: Imported 12 cookies for github.com from Chrome.

/retro - Engineering Manager Mode

/retro phân tích commit history, work patterns, shipping velocity và viết candid retrospective (đánh giá thẳng thắn). Team-aware: identify ai đang chạy command, deep treatment cho bạn, sau đó breakdown mỗi contributor với specific praise và growth opportunities.

Metrics: commits, LOC, test ratio, PR sizes, fix ratio, coding sessions, hotspot files, shipping streaks.

You:   /retro
Claude: Week of Mar 1: 47 commits (3 contributors),
        3.2k LOC, 38% tests, 12 PRs, peak: 10pm

        ## Your Week
        32 commits, +2.4k LOC, 41% tests.
        Biggest ship: cookie import system.

        ## Team Breakdown
        ### Alice - 12 commits, disciplined PRs
        ### Bob - 3 commits, fixed N+1 query

3. Demo thực tế

One Feature, Five Modes

Garry Tan start hầu hết feature trong plan mode. Describe what to build, dùng /plan-ceo-review để pressure-test (kiểm tra áp lực) liệu đang build đúng thứ không. Chỉ sau khi product direction locked mới shift sang engineering, review, ship, test.

You:   [enter plan mode, describe feature]
       I want to add seller photo upload to the listing app.

You:   /plan-ceo-review
Claude: "Photo upload" is not the feature. The real job is
        helping sellers create listings that actually sell.
        Here's what the 10-star version looks like...

You:   /plan-eng-review
Claude: [Architecture diagram, state machine for upload →
        classify → enrich → draft pipeline, test matrix]

You:   [exit plan mode, implement the plan]

You:   /review
Claude: Race condition: two tabs can overwrite cover-photo.
        Trust boundary: web data → prompt injection vector.
        Missing: orphan cleanup for failed uploads.

You:   (fix the issues)

You:   /ship
Claude: [Syncs main, runs tests, pushes, opens PR — done]

You:   /qa
Claude: Analyzing diff... 3 routes affected.
        Upload + enrichment flow passes end to end.

Greptile Integration

Greptile (YC company) review PRs tự động. Bắt real bugs - race conditions, security issues. Vấn đề là triage (phân loại). Không phải mọi comment đều là real issue.

gstack giải quyết: /review và /ship là Greptile-aware. Đọc comments, classify mỗi cái, take action:

Hệ thống cũng learns (học): mỗi false positive bạn confirm được lưu vào ~/.gstack/greptile-history.md. Future runs auto-skip known FP patterns.

10 Sessions song song với Conductor

gstack powerful với 1 Claude Code session. Nó transformative (biến đổi) với 10.

Conductor chạy multiple Claude Code sessions parallel - mỗi cái trong isolated workspace riêng. Nghĩa là bạn có thể:

• 1 session chạy /qa trên staging
• 1 session làm /review trên PR
• 1 session implementing feature
• 7 sessions khác trên branches khác

Mỗi workspace có browser instance riêng - separate Chromium process, cookies, tabs, logs. Không port collisions, không shared state.

One person, ten parallel agents, each with the right cognitive mode for its task. Đó không phải incremental improvement. Đó là cách hoàn toàn khác để build software.

4. Cài đặt

Yêu cầu hệ thống

/browse works trên macOS và Linux (x64 và arm64).

Cài đặt nhanh

Step 1: Install on your machine

Mở Claude Code và paste đoạn này. Claude sẽ làm phần còn lại:

Install gstack: run
git clone https://github.com/garrytan/gstack.git \
  ~/.claude/skills/gstack && \
  cd ~/.claude/skills/gstack && ./setup

Sau đó thêm section "gstack" vào CLAUDE.md liệt kê các skills.

Step 2: Add to repo (Optional)

cp -Rf ~/.claude/skills/gstack .claude/skills/gstack
rm -rf .claude/skills/gstack/.git
cd .claude/skills/gstack && ./setup

Real files committed to repo (không phải submodule), nên git clone just works. Binary và node_modules là gitignored - teammates chỉ cần chạy ./setup một lần.

Cấu trúc sau cài đặt

• Skill files (Markdown prompts) trong ~/.claude/skills/gstack/
• Symlinks tại ~/.claude/skills/browse, ~/.claude/skills/qa,... pointing vào gstack directory
• Browser binary tại browse/dist/browse (~58MB, gitignored)

Mọi thứ nằm trong .claude/. Không đụng PATH hay chạy background processes.

Upgrade & Uninstall

Upgrade

cd ~/.claude/skills/gstack
git fetch origin && git reset --hard origin/main && ./setup

Uninstall

for s in browse plan-ceo-review plan-eng-review review \
  ship retro qa setup-browser-cookies; do
  rm -f ~/.claude/skills/$s
done
rm -rf ~/.claude/skills/gstack

5. Kiến trúc hệ thống

Browse Daemon Model

Insight (nhận thức) cốt lõi: AI agent tương tác với browser cần sub-second latency (độ trễ dưới giây) và persistent state (trạng thái bền vững). Nếu mỗi command cold-start browser, bạn đợi 3-5 giây/tool call. 20 commands = 40+ giây overhead (chi phí phụ).

Claude Code                     gstack
─────────                      ──────
                               ┌──────────────────────┐
  Tool call: $B snapshot -i    │  CLI (compiled binary)│
  ─────────────────────────→   │  • reads state file   │
                               │  • POST /command      │
                               └──────────┬───────────┘
                                          │ HTTP
                               ┌──────────▼───────────┐
                               │  Server (Bun.serve)   │
                               │  • dispatches command  │
                               │  • talks to Chromium   │
                               └──────────┬───────────┘
                                          │ CDP
                               ┌──────────▼───────────┐
                               │  Chromium (headless)   │
                               │  • persistent tabs     │
                               │  • cookies carry over  │
                               │  • 30min idle timeout  │
                               └───────────────────────┘

First call starts everything (~3s). Every call after: ~100-200ms.

State file (.gstack/browse.json): chứa PID, port, token, version. CLI đọc file này để tìm server. Nếu file missing/stale/PID chết, CLI spawn server mới.

Port selection: Random 10000-60000 (retry 5 lần nếu collision). 10 Conductor workspaces chạy song song không config.

Why Bun?

Bottleneck (nút thắt) luôn là Chromium, không phải CLI hay server.

Security Model

Localhost only

HTTP server binds localhost, không 0.0.0.0. Không reachable từ network.

Bearer token auth

Mỗi session tạo random UUID token, written vào state file với mode 0o600 (owner-only read). Mỗi request phải có Authorization: Bearer <token>.

Cookie security

• Keychain access yêu cầu user approval (macOS dialog)
• Decryption in-process (PBKDF2 + AES-128-CBC), không write plaintext ra disk
• Database read-only (copy sang temp file trước)
• Key caching per-session, server shutdown = cache gone
• Không cookie values trong logs

Ref System (@e1, @c1)

Refs là cách agent address elements mà không viết CSS selectors hay XPath.

1. Agent: $B snapshot -i
2. Server: page.accessibility.snapshot()
3. Parser walks ARIA tree → @e1, @e2, @e3...
4. Build Playwright Locator: getByRole(role, {name}).nth(i)
5. Store Map<string, Locator>

Sau đó:
6. Agent: $B click @e3
7. Server: @e3 → Locator → locator.click()

Tại sao Locators thay vì DOM mutation? Vì CSP (Content Security Policy) block DOM modification, React/Vue hydration strip injected attributes, Shadow DOM không reach được. Playwright Locators dùng accessibility tree - external to DOM.

6. Testing & QA Infrastructure

3-Tier Eval Suite

Tier 1 chạy mỗi bun test. Tier 2+3 gated sau EVALS=1. Ý tưởng: catch 95% issues miễn phí, dùng LLMs chỉ cho judgment calls.

E2E Test Infrastructure

E2E tests spawn claude -p (Agent SDK không nest được trong Claude Code sessions). Runner:

1. Write prompt vào temp file (tránh shell escaping issues)
2. Spawn sh -c 'cat prompt | claude -p --output-format stream-json --verbose'
3. Stream NDJSON từ stdout cho real-time progress
4. Race against configurable timeout
5. Parse transcript thành structured results

Observability: heartbeat file, per-run log directory, progress.log, failure transcripts. Machine-readable diagnostics: exit_reason, timeout_at_turn, last_tool_call. Non-fatal everything - write failure không bao giờ cause test fail.

bun test                     # Tier 1: static tests (<5s)
EVALS=1 bun run test:evals   # Full E2E + LLM (~$4, ~20min)
bun run eval:watch            # Live dashboard

7. Changelog Highlights

Tốc độ phát triển: từ v0.0.1 đến v0.3.7 trong 4 ngày - điển hình cho phong cách build nhanh chóng của Garry Tan và YC.