Skip to content

Tayhlow8/Caixa-D-gua-website-2026 / .agents/skills/gstack

gstack

Flagged

Fast headless browser for QA testing and site dogfooding. Navigate pages, interact with elements, verify state, diff before/after, take annotated screenshots, test responsive layouts, forms, uploads, dialogs, and capture bug evidence. Use when asked to open or test a site, verify a deployment, dogfood a user flow, or file a bug with screenshots. (gstack)

FileKindSize
AGENTS.mdmarkdown2.5 KB
ARCHITECTURE.mdmarkdown29.3 KB
BROWSER.mdmarkdown29.2 KB
CHANGELOG.mdmarkdown389.3 KB
CLAUDE.mdmarkdown40.4 KB
CONTRIBUTING.mdmarkdown21.4 KB
DESIGN.mdmarkdown4.4 KB
ETHOS.mdmarkdown7.3 KB
LICENSEother1.0 KB
README.mdmarkdown37.3 KB
SKILL.mdskill md40.7 KB
SKILL.md.tmplother10.9 KB
TODOS.mdmarkdown79.0 KB
USING_GBRAIN_WITH_GSTACK.mdmarkdown19.0 KB
VERSIONother9 B
actionlint.yamlconfig56 B
agents/openai.yamlconfig351 B
bin/chrome-cdpother2.2 KB
bin/dev-setupother2.4 KB
bin/dev-teardownother1.6 KB
bin/gstack-analyticsother6.3 KB
bin/gstack-brain-consumerother5.5 KB
bin/gstack-brain-enqueueother1.9 KB
bin/gstack-brain-initother13.8 KB
bin/gstack-brain-readerother21 B
bin/gstack-brain-restoreother7.5 KB
bin/gstack-brain-syncother14.6 KB
bin/gstack-brain-uninstallother5.2 KB
bin/gstack-builder-profileother616 B
bin/gstack-codex-probeother4.5 KB
bin/gstack-community-dashboardother4.5 KB
bin/gstack-configother10.4 KB
bin/gstack-developer-profileother15.9 KB
bin/gstack-diff-scopeother3.1 KB
bin/gstack-extensionother2.0 KB
bin/gstack-gbrain-detectother3.6 KB
bin/gstack-gbrain-installother6.6 KB
bin/gstack-gbrain-lib.shscript3.4 KB
bin/gstack-gbrain-repo-policyother7.0 KB
bin/gstack-gbrain-supabase-provisionother15.2 KB
bin/gstack-gbrain-supabase-verifyother4.0 KB
bin/gstack-global-discover.tsscript18.8 KB
bin/gstack-jsonl-mergeother2.7 KB
bin/gstack-learnings-logother3.3 KB
bin/gstack-learnings-searchother4.8 KB
bin/gstack-model-benchmarkother5.8 KB
bin/gstack-next-versionother16.3 KB
bin/gstack-open-urlother338 B
bin/gstack-patch-namesother1.2 KB
bin/gstack-platform-detectother1.0 KB
bin/gstack-question-logother6.4 KB
bin/gstack-question-preferenceother9.4 KB
bin/gstack-relinkother3.0 KB
bin/gstack-repo-modeother3.5 KB
bin/gstack-review-logother866 B
bin/gstack-review-readother528 B
bin/gstack-security-dashboardother4.9 KB
bin/gstack-session-updateother3.5 KB
bin/gstack-settings-hookother2.8 KB
bin/gstack-slugother1.9 KB
bin/gstack-specialist-statsother2.2 KB
bin/gstack-taste-updateother10.5 KB
bin/gstack-team-initother6.7 KB
bin/gstack-telemetry-logother10.0 KB
bin/gstack-telemetry-syncother5.3 KB
bin/gstack-timeline-logother1.6 KB
bin/gstack-timeline-readother2.6 KB
bin/gstack-uninstallother10.3 KB
bin/gstack-update-checkother7.7 KB
bun.lockother57.4 KB
claude/SKILL.md.tmplother8.7 KB
conductor.jsonconfig87 B
connect-chromeother19 B
contrib/add-host/SKILL.md.tmplother1.7 KB
design/prototype.tsscript5.4 KB
design/src/auth.tsscript1.7 KB
design/src/brief.tsscript1.9 KB
design/src/check.tsscript3.3 KB
design/src/cli.tsscript8.9 KB
design/src/commands.tsscript3.0 KB
design/src/compare.tsscript19.1 KB
design/src/design-to-code.tsscript3.0 KB
design/src/diff.tsscript3.3 KB
design/src/evolve.tsscript5.3 KB
design/src/gallery.tsscript7.0 KB
design/src/generate.tsscript4.4 KB
design/src/iterate.tsscript6.5 KB
design/src/memory.tsscript6.0 KB
design/src/serve.tsscript8.3 KB
design/src/session.tsscript1.8 KB
design/src/variants.tsscript8.7 KB
design/test/feedback-roundtrip.test.tsscript12.6 KB
design/test/gallery.test.tsscript5.0 KB
design/test/serve.test.tsscript16.0 KB
docs/ADDING_A_HOST.mdmarkdown6.1 KB
docs/ON_THE_LOC_CONTROVERSY.mdmarkdown13.2 KB
docs/OPENCLAW.mdmarkdown6.5 KB
docs/REMOTE_BROWSER_ACCESS.mdmarkdown9.6 KB
docs/designs/BUN_NATIVE_INFERENCE.mdmarkdown6.7 KB
docs/designs/CHROME_VS_CHROMIUM_EXPLORATION.mdmarkdown4.0 KB
docs/designs/CONDUCTOR_CHROME_SIDEBAR_INTEGRATION.mdmarkdown3.5 KB
docs/designs/CONDUCTOR_SESSION_API.mdmarkdown3.9 KB
docs/designs/DESIGN_SHOTGUN.mdmarkdown22.5 KB
docs/designs/DESIGN_TOOLS_V1.mdmarkdown36.0 KB
docs/designs/GCOMPACTION.mdmarkdown57.6 KB
docs/designs/GSTACK_BROWSER_V0.mdmarkdown17.3 KB
docs/designs/ML_PROMPT_INJECTION_KILLER.mdmarkdown20.7 KB
docs/designs/PACING_UPDATES_V0.mdmarkdown9.7 KB
docs/designs/PLAN_TUNING_V0.mdmarkdown31.2 KB
docs/designs/PLAN_TUNING_V1.mdmarkdown19.0 KB
docs/designs/SELF_LEARNING_V0.mdmarkdown15.4 KB
docs/designs/SESSION_INTELLIGENCE.mdmarkdown6.8 KB
docs/designs/SIDEBAR_MESSAGE_FLOW.mdmarkdown10.1 KB
docs/designs/SLATE_HOST.mdmarkdown12.6 KB
docs/designs/SLOP_SCAN_FOR_REVIEW_SHIP.mdmarkdown3.0 KB
docs/evals/security-bench-ensemble-v2.jsonconfig1.6 KB
docs/gbrain-sync-errors.mdmarkdown6.2 KB
docs/gbrain-sync.mdmarkdown6.5 KB
docs/images/github-2013.pngbinary61.9 KB
docs/images/github-2026.pngbinary59.1 KB
docs/skills.mdmarkdown59.5 KB
extension/background.jsscript20.6 KB
extension/content.cssother2.5 KB
extension/content.jsscript11.9 KB
extension/icons/icon-128.pngbinary2.8 KB
extension/icons/icon-16.pngbinary400 B
extension/icons/icon-48.pngbinary1.1 KB
extension/inspector.cssother798 B
extension/inspector.jsscript15.7 KB
extension/lib/xterm-addon-fit.jsscript1.5 KB
extension/lib/xterm.cssother5.3 KB
extension/lib/xterm.jsscript276.8 KB
extension/manifest.jsonconfig783 B
extension/popup.htmlother2.3 KB
extension/popup.jsscript1.7 KB
extension/sidepanel-terminal.jsscript15.2 KB
extension/sidepanel.cssother39.6 KB
extension/sidepanel.htmlother9.1 KB
extension/sidepanel.jsscript40.2 KB
hosts/claude.tsscript1.1 KB
hosts/codex.tsscript2.2 KB
hosts/cursor.tsscript1.1 KB
hosts/factory.tsscript1.8 KB
hosts/gbrain.tsscript2.2 KB
hosts/hermes.tsscript2.1 KB
hosts/index.tsscript2.2 KB
hosts/kiro.tsscript1.2 KB
hosts/openclaw.tsscript2.0 KB
hosts/opencode.tsscript1.3 KB
hosts/slate.tsscript1.1 KB
lib/worktree.tsscript9.6 KB
model-overlays/claude.mdmarkdown613 B
model-overlays/gemini.mdmarkdown551 B
model-overlays/gpt-5.4.mdmarkdown683 B
model-overlays/gpt.mdmarkdown1.9 KB
model-overlays/o-series.mdmarkdown660 B
model-overlays/opus-4-7.mdmarkdown1.5 KB
openclaw/agents-gstack-section.mdmarkdown2.5 KB
openclaw/gstack-full-CLAUDE.mdmarkdown538 B
openclaw/gstack-lite-CLAUDE.mdmarkdown688 B
openclaw/gstack-plan-CLAUDE.mdmarkdown1.0 KB
package.jsonmanifest4.7 KB
scripts/analytics.tsscript5.3 KB
scripts/app/gstack-browserother2.4 KB
scripts/app/icon.icnsother1.0 MB
scripts/archetypes.tsscript5.4 KB
scripts/build-app.shscript7.5 KB
scripts/compare-pr-version.tsscript3.0 KB
scripts/detect-bump.tsscript1.2 KB
scripts/dev-skill.tsscript2.4 KB
scripts/discover-skills.tsscript1.2 KB
scripts/eval-compare.tsscript3.0 KB
scripts/eval-list.tsscript3.5 KB
scripts/eval-select.tsscript3.1 KB
scripts/eval-summary.tsscript6.5 KB
scripts/eval-watch.tsscript5.4 KB
scripts/garry-output-comparison.tsscript17.0 KB
scripts/gen-skill-docs.tsscript28.3 KB
scripts/host-adapters/openclaw-adapter.tsscript1.7 KB
scripts/host-config-export.tsscript3.4 KB
scripts/host-config.tsscript7.3 KB
scripts/jargon-list.jsonconfig1.8 KB
scripts/models.tsscript2.5 KB
scripts/one-way-doors.tsscript5.6 KB
scripts/preflight-agent-sdk.tsscript4.4 KB
scripts/psychographic-signals.tsscript10.3 KB
scripts/question-registry.tsscript23.5 KB
scripts/resolvers/browse.tsscript6.2 KB
scripts/resolvers/codex-helpers.tsscript5.0 KB
scripts/resolvers/composition.tsscript1.8 KB
scripts/resolvers/confidence.tsscript1.6 KB
scripts/resolvers/constants.tsscript3.1 KB
scripts/resolvers/design.tsscript56.9 KB
scripts/resolvers/dx.tsscript5.4 KB
scripts/resolvers/gbrain.tsscript5.3 KB
scripts/resolvers/index.tsscript4.3 KB
scripts/resolvers/learnings.tsscript3.9 KB
scripts/resolvers/make-pdf.tsscript2.2 KB
scripts/resolvers/model-overlay.tsscript2.2 KB
scripts/resolvers/preamble.tsscript5.7 KB

lib/worktree.ts

View on GitHub
/**
 * Git worktree manager for isolated test execution with change harvesting.
 *
 * Creates git worktrees for test suites that need real repo context,
 * harvests any changes the test agent makes as patches, and provides
 * deduplication across runs.
 *
 * Reusable platform module — future /batch or /codex challenge skills
 * can import this directly.
 */

import { spawnSync } from 'child_process';
import * as crypto from 'crypto';
import * as fs from 'fs';
import * as path from 'path';
import * as os from 'os';

// --- Interfaces ---

export interface WorktreeInfo {
  path: string;
  testName: string;
  originalSha: string;
  createdAt: number;
}

export interface HarvestResult {
  testName: string;
  worktreePath: string;
  diffStat: string;
  patchPath: string;
  changedFiles: string[];
  isDuplicate: boolean;
}

// --- Utility ---

/** Recursive directory copy (pure TypeScript, no external deps). */
function copyDirSync(src: string, dest: string): void {
  fs.mkdirSync(dest, { recursive: true });
  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
    // Skip symlinks to avoid infinite recursion (e.g., .claude/skills/gstack → repo root)
    if (entry.isSymbolicLink()) continue;
    const srcPath = path.join(src, entry.name);
    const destPath = path.join(dest, entry.name);
    if (entry.isDirectory()) {
      copyDirSync(srcPath, destPath);
    } else {
      fs.copyFileSync(srcPath, destPath);
    }
  }
}

/** Run a git command and return stdout. Throws on failure unless tolerateFailure is set. */
function git(args: string[], cwd: string, tolerateFailure = false): string {
  const result = spawnSync('git', args, { cwd, stdio: 'pipe', timeout: 30_000 });
  const stdout = result.stdout?.toString().trim() ?? '';
  const stderr = result.stderr?.toString().trim() ?? '';
  if (result.status !== 0 && !tolerateFailure) {
    throw new Error(`git ${args.join(' ')} failed (exit ${result.status}): ${stderr || stdout}`);
  }
  return stdout;
}

// --- Dedup index ---

interface DedupIndex {
  hashes: Record<string, string>; // hash → first-seen runId
}

function getDedupPath(): string {
  return path.join(os.homedir(), '.gstack-dev', 'harvests', 'dedup.json');
}

function loadDedupIndex(): DedupIndex {
  try {
    const raw = fs.readFileSync(getDedupPath(), 'utf-8');
    return JSON.parse(raw);
  } catch {
    return { hashes: {} };
  }
}

function saveDedupIndex(index: DedupIndex): void {
  const dir = path.dirname(getDedupPath());
  fs.mkdirSync(dir, { recursive: true });
  const tmp = getDedupPath() + '.tmp';
  fs.writeFileSync(tmp, JSON.stringify(index, null, 2));
  fs.renameSync(tmp, getDedupPath());
}

// --- WorktreeManager ---

export class WorktreeManager {
  private repoRoot: string;
  private runId: string;
  private active: Map<string, WorktreeInfo> = new Map();
  private harvestResults: HarvestResult[] = [];

  constructor(repoRoot?: string) {
    if (repoRoot) {
      this.repoRoot = repoRoot;
    } else {
      this.repoRoot = git(['rev-parse', '--show-toplevel'], process.cwd());
    }
    this.runId = crypto.randomUUID();

    // Register cleanup on process exit
    process.on('exit', () => {
      this.cleanupAll();
    });
  }

  /** Create an isolated worktree. Returns the worktree path. Throws on failure. */
  create(testName: string): string {
    const originalSha = git(['rev-parse', 'HEAD'], this.repoRoot);

    const worktreeBase = path.join(this.repoRoot, '.gstack-worktrees', this.runId);
    fs.mkdirSync(worktreeBase, { recursive: true });

    const worktreePath = path.join(worktreeBase, testName);

    // Create detached worktree at current HEAD
    git(['worktree', 'add', '--detach', worktreePath, 'HEAD'], this.repoRoot);

    // Copy gitignored build artifacts that tests need (config-driven)
    const { getExternalHosts } = require('../hosts/index');
    for (const hostConfig of getExternalHosts()) {
      const hostSrc = path.join(this.repoRoot, hostConfig.hostSubdir);
      if (fs.existsSync(hostSrc)) {
        copyDirSync(hostSrc, path.join(worktreePath, hostConfig.hostSubdir));
      }
    }

    const browseDist = path.join(this.repoRoot, 'browse', 'dist');
    if (fs.existsSync(browseDist)) {
      copyDirSync(browseDist, path.join(worktreePath, 'browse', 'dist'));
    }

    const info: WorktreeInfo = {
      path: worktreePath,
      testName,
      originalSha,
      createdAt: Date.now(),
    };
    this.active.set(testName, info);

    return worktreePath;
  }

  /** Harvest changes from a worktree. Returns null if clean or on error. */
  harvest(testName: string): HarvestResult | null {
    const info = this.active.get(testName);
    if (!info) return null;

    try {
      // Check if worktree directory still exists (agent may have deleted it)
      if (!fs.existsSync(info.path)) {
        process.stderr.write(`  HARVEST [${testName}]: worktree dir deleted, skipping\n`);
        return null;
      }

      // Stage everything including untracked files
      git(['-C', info.path, 'add', '-A'], info.path, true);

      // Get diff against original SHA (captures both committed and uncommitted changes)
      const patch = git(['-C', info.path, 'diff', info.originalSha, '--cached'], info.path, true);

      if (!patch) return null;

      // Get diff stat for human-readable output
      const diffStat = git(['-C', info.path, 'diff', info.originalSha, '--cached', '--stat'], info.path, true);

      // Get changed file names
      const nameOnly = git(['-C', info.path, 'diff', info.originalSha, '--cached', '--name-only'], info.path, true);
      const changedFiles = nameOnly.split('\n').filter(Boolean);

      // Dedup check
      const hash = crypto.createHash('sha256').update(patch).digest('hex');
      const dedupIndex = loadDedupIndex();
      const isDuplicate = hash in dedupIndex.hashes;

      let patchPath = '';

      if (!isDuplicate) {
        // Save patch
        const harvestDir = path.join(os.homedir(), '.gstack-dev', 'harvests', this.runId);
        fs.mkdirSync(harvestDir, { recursive: true });
        patchPath = path.join(harvestDir, `${testName}.patch`);
        fs.writeFileSync(patchPath, patch);

        // Update dedup index
        dedupIndex.hashes[hash] = this.runId;
        saveDedupIndex(dedupIndex);
      }

      const result: HarvestResult = {
        testName,
        worktreePath: info.path,
        diffStat,
        patchPath,
        changedFiles,
        isDuplicate,
      };

      this.harvestResults.push(result);
      return result;
    } catch (err) {
      process.stderr.write(`  HARVEST [${testName}]: error — ${err}\n`);
      return null;
    }
  }

  /** Remove a worktree. Non-fatal on error. */
  cleanup(testName: string): void {
    const info = this.active.get(testName);
    if (!info) return;

    try {
      git(['worktree', 'remove', '--force', info.path], this.repoRoot, true);
    } catch {
      // Force remove the directory if git worktree remove fails
      try {
        fs.rmSync(info.path, { recursive: true, force: true });
        git(['worktree', 'prune'], this.repoRoot, true);
      } catch { /* non-fatal */ }
    }

    this.active.delete(testName);
  }

  /** Force-remove all active worktrees (for process exit handler). */
  cleanupAll(): void {
    for (const testName of [...this.active.keys()]) {
      this.cleanup(testName);
    }

    // Clean up the run directory if empty
    const runDir = path.join(this.repoRoot, '.gstack-worktrees', this.runId);
    try {
      const entries = fs.readdirSync(runDir);
      if (entries.length === 0) {
        fs.rmdirSync(runDir);
      }
    } catch { /* non-fatal */ }
  }

  /** Remove worktrees from previous runs that weren't cleaned up. */
  pruneStale(): void {
    try {
      git(['worktree', 'prune'], this.repoRoot, true);

      const worktreeBase = path.join(this.repoRoot, '.gstack-worktrees');
      if (!fs.existsSync(worktreeBase)) return;

      for (const entry of fs.readdirSync(worktreeBase)) {
        // Don't prune our own run
        if (entry === this.runId) continue;

        const entryPath = path.join(worktreeBase, entry);
        try {
          // Skip recent worktrees (< 1 hour old) to avoid killing
          // worktrees from concurrent test runs still in progress
          const stat = fs.statSync(entryPath);
          const ageMs = Date.now() - stat.mtimeMs;
          if (ageMs < 3600_000) continue;
          fs.rmSync(entryPath, { recursive: true, force: true });
        } catch { /* non-fatal */ }
      }
    } catch {
      process.stderr.write('  WORKTREE: prune failed (non-fatal)\n');
    }
  }

  /** Print harvest report summary. */
  printReport(): void {
    if (this.harvestResults.length === 0) return;

    const nonDuplicates = this.harvestResults.filter(r => !r.isDuplicate);
    process.stderr.write('\n=== HARVEST REPORT ===\n');
    process.stderr.write(`${nonDuplicates.length} of ${this.harvestResults.length} test suites produced new changes:\n\n`);

    for (const result of this.harvestResults) {
      if (result.isDuplicate) {
        process.stderr.write(`  ${result.testName}: duplicate patch (skipped)\n`);
      } else {
        process.stderr.write(`  ${result.testName}: ${result.changedFiles.length} files changed\n`);
        process.stderr.write(`    Patch: ${result.patchPath}\n`);
        process.stderr.write(`    Apply: git apply ${result.patchPath}\n`);
        if (result.diffStat) {
          process.stderr.write(`    ${result.diffStat}\n`);
        }
      }
      process.stderr.write('\n');
    }
  }

  /** Get the run ID (for testing). */
  getRunId(): string {
    return this.runId;
  }

  /** Get active worktree info (for testing). */
  getInfo(testName: string): WorktreeInfo | undefined {
    return this.active.get(testName);
  }
}
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall