# GSD Browser Capture Commands: screenshot, PDF, HAR, records Source: https://docs.opengsd.net/browser/commands/capture Complete reference for GSD Browser capture and extraction commands: screenshot, PDF, page source, eval, HAR export, recordings, and debug bundles. Capture and extraction commands let you read data out of the browser — as images, documents, raw HTML, JavaScript return values, or structured network archives. Use these commands to build evidence bundles, verify page state, extract data for downstream processing, or record flows for replay and audit. *** ## `gsd-browser screenshot` Capture a screenshot of the current page and return it as a base64-encoded image. When you pass `--output`, the raw image bytes are written directly to a file on disk instead. ```bash theme={null} gsd-browser screenshot [flags] ``` File path where the image should be saved (e.g. `./screenshots/page.png`). When set, the command writes raw bytes to disk and prints a confirmation line instead of returning base64 data. CSS selector of a single element to capture. The screenshot crops to that element's bounding box and always produces a PNG, ignoring the `--format` flag. Capture the entire scrollable page height, not just the current viewport. JPEG compression quality from `1` (lowest) to `100` (highest). Defaults to `80`. Has no effect when the format is `png`. Image format: `jpeg` (default) or `png`. Element screenshots (`--selector`) are always PNG regardless of this setting. **Examples** ```bash theme={null} # Capture the viewport as JPEG (default quality 80) gsd-browser screenshot # Save a full-page PNG to disk gsd-browser screenshot --full-page --format png --output ./captures/full-page.png # Crop to a specific element gsd-browser screenshot --selector "#hero-banner" --output ./captures/hero.png # High-quality JPEG for sharing gsd-browser screenshot --quality 95 --output report.jpg # Get base64 JSON output for programmatic use gsd-browser screenshot --json ``` *** ## `gsd-browser save-pdf` Export the current page as a PDF file. The PDF is rendered using the browser's built-in print engine, which honours CSS print stylesheets. ```bash theme={null} gsd-browser save-pdf [flags] ``` Full file path for the saved PDF (e.g. `./exports/report.pdf`). When omitted, the file is saved to the session directory and the path is printed. Output filename (used when you want the file saved to the default session directory with a specific name). Page size: `A4` (default), `Letter`, `Legal`, or `Tabloid`. Include background graphics and colours in the PDF output. Enabled by default; pass `--print-background false` to disable. **Examples** ```bash theme={null} # Export to A4 PDF (default) gsd-browser save-pdf --output ./report.pdf # US Letter size gsd-browser save-pdf --format Letter --output ./wide-report.pdf # Save to a named file in the session directory gsd-browser save-pdf --filename invoice.pdf ``` *** ## `gsd-browser page-source` Return the HTML source of the current page or a scoped element. ```bash theme={null} gsd-browser page-source [flags] ``` CSS selector to scope the source output to a specific element. Omit to retrieve the full page source. **Examples** ```bash theme={null} # Get the full page HTML gsd-browser page-source # Get the outer HTML of the navigation component gsd-browser page-source --selector "nav" # Get HTML of a specific section gsd-browser page-source --selector "#results-list" ``` *** ## `gsd-browser eval` Evaluate a JavaScript expression in the context of the current page and return its result. Use `--json` to parse the return value as structured JSON rather than a plain string. ```bash theme={null} gsd-browser eval [flags] ``` Any valid JavaScript expression. The expression runs in the page's global scope and has access to `window`, `document`, and all page globals. **Examples** ```bash theme={null} # Read the current scroll position gsd-browser eval "window.scrollY" # Check local storage for a session token gsd-browser eval "localStorage.getItem('auth_token')" # Return a structured object parsed as JSON gsd-browser eval "JSON.stringify({title: document.title, url: location.href})" --json # Count elements matching a selector gsd-browser eval "document.querySelectorAll('.result-item').length" ``` *** ## `gsd-browser har-export` Export all captured network traffic for the current session as a HAR 1.2 JSON file. The network buffer accumulates requests continuously; call this command at any point to flush the buffer to disk. ```bash theme={null} gsd-browser har-export [flags] ``` Output file path for the HAR file (e.g. `./session.har`). When omitted, the file is saved to the session directory and the path is printed. **Examples** ```bash theme={null} # Export all recorded network traffic gsd-browser har-export # Export to a specific path gsd-browser har-export --filename ./evidence/network-capture.har ``` The network buffer accumulates across the entire session. Call `gsd-browser network --clear` if you want to start a fresh capture window before running a specific flow. *** ## `gsd-browser record-start` / `gsd-browser record-stop` Record a named flow session that captures actions, screenshots, and network activity into an evidence bundle. Start the recording before performing actions; stop it when the flow is complete. ```bash theme={null} gsd-browser record-start --name gsd-browser record-stop ``` A human-readable name for this recording (e.g. `checkout-flow-2026-06`). The name is used as part of the bundle filename and is shown in the recordings list. **Additional recording commands** | Command | Description | | -------------------------------------------------- | --------------------------------------------- | | `gsd-browser record-pause` | Pause an active recording without stopping it | | `gsd-browser record-resume` | Resume a paused recording | | `gsd-browser recordings` | List all saved recordings | | `gsd-browser recording-get ` | Get the manifest for a specific recording | | `gsd-browser recording-export --output ` | Export a recording bundle to a directory | | `gsd-browser recording-discard ` | Delete a recording | **Examples** ```bash theme={null} # Start recording a checkout flow gsd-browser record-start --name "checkout-flow-2026-06" gsd-browser navigate https://example.com/cart # ... perform checkout steps ... gsd-browser record-stop # List all recordings gsd-browser recordings # Export a recording to an evidence directory gsd-browser recording-export rec_abc123 --output ./evidence/checkout/ ``` *** ## `gsd-browser debug-bundle` Capture a complete debug bundle — screenshot, console log, network log, timeline, and accessibility tree — in a single command. Use this to collect all diagnostic evidence at a point in time. ```bash theme={null} gsd-browser debug-bundle [flags] ``` Optional suffix to append to the bundle directory name, making it easier to identify in the file system. **Example** ```bash theme={null} # Capture a debug bundle after a suspected failure gsd-browser debug-bundle --name "payment-error" ``` # GSD Browser Interaction Commands: click, type, scroll, drag Source: https://docs.opengsd.net/browser/commands/interaction Complete reference for GSD Browser interaction commands: snapshot, click, type, press, hover, scroll, drag, select, file upload, and viewport control. Interaction commands let you act on page elements the way a real user would — clicking buttons, filling in forms, scrolling, dragging, and more. Most commands accept either a CSS selector or a versioned snapshot ref (e.g. `@v1:e3`). Refs are generated by `gsd-browser snapshot` and are the preferred approach because they are stable, versioned, and fully described by the browser's internal element model. Always re-run `gsd-browser snapshot` after navigation or significant DOM changes before using refs from a previous snapshot. *** ## `gsd-browser snapshot` Scan the page and assign versioned refs (`@vN:eM`) to interactive elements. Refs returned by a snapshot are valid until the page changes; after any navigation or DOM mutation, take a fresh snapshot before using ref-based commands. ```bash theme={null} gsd-browser snapshot [flags] ``` Focus the snapshot on a subset of elements. Accepted values: | Mode | What it captures | | ----------------------- | ------------------------------------------ | | `interactive` (default) | Buttons, inputs, links, and selects | | `form` | Form fields with current values and labels | | `dialog` | Content inside open modals or dialogs | | `navigation` | Navigation links and menus | | `errors` | Error messages and validation hints | | `headings` | `h1`–`h6` elements | | `visible_only` | Every visible element on the page | Scope the snapshot to a specific region of the page using a CSS selector. Maximum number of elements to include. Defaults to `40`. Increase this on complex single-page apps. **Examples** ```bash theme={null} # Default snapshot — interactive elements gsd-browser snapshot # Snapshot only the sign-up form gsd-browser snapshot --selector "#signup-form" --mode form # Capture more elements on a dense UI gsd-browser snapshot --limit 80 # Snapshot visible content for a broad audit gsd-browser snapshot --mode visible_only ``` *** ## `gsd-browser get-ref` Retrieve metadata for a specific element ref, including its bounding box, ARIA role, CSS selector, and structural signature. Use this to inspect an element before interacting with it or to debug a stale-ref problem. ```bash theme={null} gsd-browser get-ref ``` A versioned ref string in `@vN:eM` format, as returned by `gsd-browser snapshot`. **Example** ```bash theme={null} gsd-browser snapshot gsd-browser get-ref @v1:e3 # Prints: role, name, bounding box, selector hint, structural signature ``` *** ## `gsd-browser click` Click an element identified by a CSS selector or by exact coordinates. To click by ref, use `gsd-browser click-ref` instead. ```bash theme={null} gsd-browser click [flags] gsd-browser click --x --y [flags] ``` CSS selector of the element to click. Omit when clicking by coordinates. Horizontal coordinate in CSS pixels. Must be used with `--y`. Vertical coordinate in CSS pixels. Must be used with `--x`. **Examples** ```bash theme={null} # Click a button by CSS selector gsd-browser click "#submit-btn" # Click at exact coordinates gsd-browser click --x 640 --y 360 ``` *** ## `gsd-browser click-ref` Click an element identified by its snapshot ref. Prefer this over `click` when you have a fresh snapshot — refs encode element identity more precisely than CSS selectors. ```bash theme={null} gsd-browser click-ref ``` A versioned ref string in `@vN:eM` format, as returned by `gsd-browser snapshot`. **Example** ```bash theme={null} gsd-browser snapshot gsd-browser click-ref @v1:e2 ``` *** ## `gsd-browser type` Type text into an input element. By default the text is filled atomically; use `--slowly` when you need realistic keystroke-by-keystroke input (e.g. to trigger autocomplete handlers). ```bash theme={null} gsd-browser type [flags] ``` CSS selector of the target input, textarea, or content-editable element. The text to type into the element. Type character-by-character with realistic delays between keystrokes. Useful for triggering autocomplete, search suggestions, or other keystroke-driven event listeners. Clear any existing value in the field before typing the new text. Press Enter after typing to submit the field or form. **Examples** ```bash theme={null} # Type an email address into the email input gsd-browser type "input[name=email]" "hello@example.com" # Clear a pre-filled field and type a new value gsd-browser type "#search" "gsd-browser docs" --clear-first # Type slowly to trigger autocomplete, then submit gsd-browser type "#city-input" "San Fra" --slowly --submit ``` *** ## `gsd-browser fill-ref` Type text into an element identified by its snapshot ref. ```bash theme={null} gsd-browser fill-ref [flags] ``` A versioned ref string in `@vN:eM` format, as returned by `gsd-browser snapshot`. The text to type into the element. Clear any existing value before typing. Press Enter after typing. Type character-by-character instead of atomically filling the field. **Example** ```bash theme={null} gsd-browser snapshot gsd-browser fill-ref @v1:e1 "user@example.com" ``` *** ## `gsd-browser press` Dispatch a keyboard event for a single key or a key combination. Use key names from the DOM `KeyboardEvent.key` spec, joined by `+` for modifiers. ```bash theme={null} gsd-browser press ``` Key name or combination. Examples: `Enter`, `Escape`, `Tab`, `ArrowDown`, `Meta+A`, `Control+C`, `Shift+Tab`. **Examples** ```bash theme={null} # Press Enter to submit gsd-browser press Enter # Select all text gsd-browser press Meta+A # Dismiss a modal with Escape gsd-browser press Escape # Move focus to the next form field gsd-browser press Tab ``` *** ## `gsd-browser hover` Move the mouse pointer over an element to trigger hover states, tooltips, or dropdown menus that only appear on mouse-over. ```bash theme={null} gsd-browser hover ``` CSS selector of the element to hover over. **Example** ```bash theme={null} # Reveal a dropdown menu gsd-browser hover "#nav-products" gsd-browser snapshot --mode navigation # Now snapshot the revealed menu items ``` *** ## `gsd-browser scroll` Scroll the page up or down. Use `--direction` to choose the direction and `--amount` to control how far. ```bash theme={null} gsd-browser scroll --direction [--amount ] ``` Scroll direction: `up` or `down`. Number of pixels to scroll. Defaults to `300`. **Examples** ```bash theme={null} # Scroll the page down 300 px (default) gsd-browser scroll --direction down # Scroll the page up 500 px gsd-browser scroll --direction up --amount 500 ``` *** ## `gsd-browser select-option` Select an option from a `` element. The option label (visible text) or value attribute to select. **Example** ```bash theme={null} # Select "Canada" from a country dropdown gsd-browser select-option "select[name=country]" "Canada" # Select by value attribute gsd-browser select-option "#plan-select" "pro" ``` *** ## `gsd-browser set-checked` Set the checked state of a checkbox or radio button. Pass `--checked` to check the element; omit it to uncheck. ```bash theme={null} gsd-browser set-checked [--checked] ``` CSS selector of the checkbox or radio `` element. Set the element to the checked state. Omit this flag to uncheck the element. **Examples** ```bash theme={null} # Check the "Accept terms" checkbox gsd-browser set-checked "#accept-terms" --checked # Uncheck a newsletter opt-in box gsd-browser set-checked "input[name=newsletter]" ``` *** ## `gsd-browser drag` Drag an element from a source to a target using either CSS selectors or explicit coordinates. The drag movement is interpolated across several steps to produce realistic pointer events. ```bash theme={null} gsd-browser drag [flags] gsd-browser drag --from-x --from-y --to-x --to-y [flags] ``` CSS selector of the element to drag from. CSS selector of the element to drop onto. Starting X coordinate in CSS pixels (coordinate-based mode). Starting Y coordinate in CSS pixels (coordinate-based mode). Ending X coordinate in CSS pixels (coordinate-based mode). Ending Y coordinate in CSS pixels (coordinate-based mode). Number of interpolation steps between start and end positions. Higher values produce smoother motion. Defaults to `10`. Mouse button held during the drag: `left` (default), `right`, or `middle`. **Examples** ```bash theme={null} # Drag a card from one list column to another gsd-browser drag ".card:first-child" ".column-done" # Drag by coordinates for pixel-precise control gsd-browser drag --from-x 100 --from-y 200 --to-x 400 --to-y 200 # Increase steps for smoother animation-sensitive drag gsd-browser drag "#slider-thumb" "#slider-end" --steps 30 ``` *** ## `gsd-browser upload-file` Set one or more files on a `` element. Pass local file paths as space-separated positional arguments. ```bash theme={null} gsd-browser upload-file [ ...] ``` CSS selector of the `` element. One or more local file paths to attach to the input. **Examples** ```bash theme={null} # Upload a single file gsd-browser upload-file "input[type=file]" /home/user/report.pdf # Upload multiple files at once gsd-browser upload-file "#file-picker" ./photo1.jpg ./photo2.jpg ./photo3.jpg ``` *** ## `gsd-browser act-instruction` Execute a short natural-language instruction by planning concrete primitive steps (click, type, select-option, set-checked, drag, scroll) against the live page and dispatching them. Use this when the action isn't one of the built-in `gsd-browser act` semantic patterns — for example, "choose California from State" or "click the second Delete button". ```bash theme={null} gsd-browser act-instruction [flags] ``` Short action-oriented instruction, e.g. `"click Continue"`, `"enter 'alice@example.com' into Email"`, or `"choose California from State"`. Return the inferred action plan without executing it. Useful for inspecting which element the planner selected before committing to the action. CSS selector that constrains planning to a specific form, dialog, panel, or page region. Use this when the page has repeated controls. Block execution when the inferred plan confidence is below this threshold (between `0` and `1`). Fails closed on ambiguous instructions instead of guessing. Cap on primitive steps the instruction may execute. Defaults to a small bounded sequence. **Examples** ```bash theme={null} # Type into a labelled input by name gsd-browser act-instruction "enter 'alice@example.com' into Email" # Constrain planning to a specific form and require high confidence gsd-browser act-instruction "click Continue" --scope "#signup-form" --min-confidence 0.7 # Inspect the plan before executing gsd-browser act-instruction "click the second Delete button" --scope "#row-42" --dry-run # Pick a value from a dropdown gsd-browser act-instruction "choose California from State" ``` Prefer ref-based commands like `click-ref` and `fill-ref` when you have a fresh snapshot and need pixel-precise control. Use `act-instruction` for higher-level intent when the exact selector is unstable or unknown. *** ## `gsd-browser set-viewport` Resize the browser viewport using a named preset or exact pixel dimensions. Use this to test responsive layouts or simulate device screen sizes. ```bash theme={null} gsd-browser set-viewport [flags] ``` A named viewport preset: | Preset | Dimensions | | --------- | ----------- | | `mobile` | 390 × 844 | | `tablet` | 768 × 1024 | | `desktop` | 1280 × 800 | | `wide` | 1920 × 1080 | Viewport width in pixels. Use with `--height` for custom dimensions. Viewport height in pixels. Use with `--width` for custom dimensions. **Examples** ```bash theme={null} # Switch to a mobile viewport gsd-browser set-viewport --preset mobile # Set a custom resolution for a specific test gsd-browser set-viewport --width 1440 --height 900 # Switch to wide desktop and take a screenshot gsd-browser set-viewport --preset wide gsd-browser screenshot --full-page --output wide-layout.png ``` # GSD Browser Navigation Commands: navigate, back, wait-for Source: https://docs.opengsd.net/browser/commands/navigation Complete reference for GSD Browser navigation commands: navigate, back, forward, reload, wait-for, and global flags that apply to every command. Navigation commands control where the browser goes and how long it waits to get there. Every command in this group operates on the active tab of the current session; use the `--session` global flag when you need to target a named parallel instance. Before using any element-based command after navigation, run `gsd-browser snapshot` to capture fresh, versioned refs for the new page state. ## Global Flags These flags are accepted by **every** `gsd-browser` command, not just navigation commands. Emit machine-readable JSON on stdout instead of human-readable text. Errors are also written as JSON to stderr. Target a named daemon session. Use this when you have multiple parallel browser instances running side-by-side. Path to a custom Chrome or Chromium binary. Overrides the value set in your config file. Connect to an already-running Chrome instance via a Chrome DevTools Protocol (CDP) endpoint (e.g. `ws://localhost:9222`). Accepts both `ws://` and `http://` endpoints. Skip the lead-time sleeps that gsd-browser inserts between narrated actions. Useful in CI where speed matters more than realistic pacing. *** ## `gsd-browser navigate` Navigate the active tab to a URL. The command waits for the page to load before returning. Combine with a subsequent `gsd-browser wait-for` call when you need finer control over the ready condition. ```bash theme={null} gsd-browser navigate [flags] ``` The fully-qualified URL to navigate to (e.g. `https://example.com/login`). **Examples** ```bash theme={null} # Basic navigation gsd-browser navigate https://example.com # Navigate in a named session gsd-browser navigate https://example.com --session staging # Navigate and get structured output gsd-browser navigate https://example.com --json ``` *** ## `gsd-browser back` Go back one step in the active tab's navigation history — the browser equivalent of clicking the Back button. ```bash theme={null} gsd-browser back ``` **Example** ```bash theme={null} gsd-browser navigate https://example.com/step-2 gsd-browser back # Now on the previous page ``` *** ## `gsd-browser forward` Go forward one step in the active tab's navigation history — the browser equivalent of clicking the Forward button. ```bash theme={null} gsd-browser forward ``` **Example** ```bash theme={null} gsd-browser back gsd-browser forward # Back where you started ``` *** ## `gsd-browser reload` Reload the current page. ```bash theme={null} gsd-browser reload ``` **Example** ```bash theme={null} # Reload the active page gsd-browser reload ``` *** ## `gsd-browser wait-for` Block until a specified page condition becomes true. Use `wait-for` after actions that trigger asynchronous changes — navigation, form submission, AJAX calls, or animations — before your next interaction step. ```bash theme={null} gsd-browser wait-for --condition [--value ] [--timeout ] [--threshold ] ``` The condition to wait for. Supported values: | Condition | Description | | ------------------- | ----------------------------------------------------------------- | | `selector_visible` | An element matching `--value` appears in the DOM and is visible | | `selector_hidden` | An element matching `--value` is removed or hidden | | `url_contains` | The current URL contains the substring in `--value` | | `network_idle` | No pending network requests for a short period | | `delay` | Wait a fixed number of milliseconds (set with `--value`) | | `text_visible` | Text matching `--value` appears on the page | | `text_hidden` | Text matching `--value` disappears from the page | | `request_completed` | A network request whose URL contains `--value` completes | | `console_message` | A console message containing `--value` is logged | | `element_count` | The count of elements matching `--value` satisfies `--threshold` | | `region_stable` | The element at `--value` stops changing (useful after animations) | Condition-specific value: a CSS selector, URL substring, text string, or delay in milliseconds depending on the chosen `--condition`. Maximum time to wait in milliseconds before the command fails. Defaults to `10000` (10 seconds). Comparison expression for `element_count`, e.g. `>=3`, `==0`, `<5`. **Examples** ```bash theme={null} # Wait for the page to finish all network activity gsd-browser wait-for --condition network_idle # Wait for a specific element to appear (up to 30 s) gsd-browser wait-for --condition selector_visible --value "#content" --timeout 30000 # Wait until the URL changes to the dashboard gsd-browser wait-for --condition url_contains --value "/dashboard" # Wait for a success message to appear gsd-browser wait-for --condition text_visible --value "Your order has been placed" # Wait until at least 5 result items are rendered gsd-browser wait-for --condition element_count --value ".result-item" --threshold ">=5" # Wait for an element to stop animating before capturing a screenshot gsd-browser wait-for --condition region_stable --value "#hero-banner" ``` # GSD Browser Session, Daemon, and Vault Command Reference Source: https://docs.opengsd.net/browser/commands/session-management Reference for GSD Browser daemon, session state, viewer, and vault commands: health, save-state, restore-state, vault-save, vault-login. Session management commands control the background daemon that powers every `gsd-browser` operation, named browser sessions that let you run parallel instances, the live authenticated viewer, and the encrypted credential vault. Most users never need to start or stop the daemon manually — it auto-starts on the first command and shuts down when no longer needed — but these commands give you full control when you need it. *** ## Daemon Commands The gsd-browser daemon is the long-running background process that owns the Chrome instance and handles all CDP communication. Each named session gets its own daemon process. ### `gsd-browser daemon start` Start the background daemon. You rarely need to call this directly; any `gsd-browser` command will auto-start the daemon if one is not already running. ```bash theme={null} gsd-browser daemon start ``` **Example** ```bash theme={null} # Pre-warm the daemon before running your first command gsd-browser daemon start # Start a daemon for a named session gsd-browser daemon start --session staging ``` *** ### `gsd-browser daemon stop` Stop the running daemon for the current (or specified) session. The Chrome process managed by that daemon is also terminated. ```bash theme={null} gsd-browser daemon stop ``` **Example** ```bash theme={null} # Stop the default session daemon gsd-browser daemon stop # Stop a named session daemon gsd-browser daemon stop --session staging ``` *** ### `gsd-browser daemon health` Check whether the daemon is running and healthy. Returns the daemon status and any error reason. This command does not start the daemon if it is not already running. ```bash theme={null} gsd-browser daemon health ``` **Example** ```bash theme={null} gsd-browser daemon health # Daemon: running # Get structured output for scripting gsd-browser daemon health --json ``` *** ## Session State Commands Use `--session ` on any command to target a named parallel browser instance. Named sessions share no cookies, storage, or page state with each other. The following commands let you persist and restore an entire browser context (cookies, localStorage, sessionStorage) across runs. ### `gsd-browser save-state` Save the current browser context (cookies, local storage, session storage) to disk under a named profile. ```bash theme={null} gsd-browser save-state [--name ] ``` Profile name for the saved state. Defaults to `"default"` when omitted. **Example** ```bash theme={null} # Log in, then save state so you can restore it later gsd-browser navigate https://example.com/login --session work # ... complete login ... gsd-browser save-state --name work-authenticated ``` *** ### `gsd-browser restore-state` Restore a previously saved browser context from disk, loading cookies and storage without navigating or logging in again. ```bash theme={null} gsd-browser restore-state [--name ] ``` Profile name of the state to restore. Defaults to `"default"` when omitted. **Example** ```bash theme={null} # Restore a logged-in session from a prior save gsd-browser restore-state --name work-authenticated gsd-browser navigate https://example.com/dashboard # Lands directly on the dashboard (already logged in) ``` *** ## Viewer Commands The live viewer lets you watch and interact with an active browser session through a web-based UI, protected by a rotating auth token. Share the viewer URL with a teammate to give them real-time visibility into an automation run. ### `gsd-browser view` Open the live viewer for the current session. GSD Browser prints a localhost URL and opens it in your default browser. ```bash theme={null} gsd-browser view [flags] ``` Print the viewer URL without opening it in a browser. Useful when you need to pass the URL to another tool. Open the history-focused viewer, showing a scrollable timeline of past actions rather than the live frame. **Example** ```bash theme={null} # Open the live viewer gsd-browser view # Get the URL without opening it VIEW_URL=$(gsd-browser view --print-only | tail -1) echo "$VIEW_URL" ``` The viewer URL contains an authentication token. Treat it like a password — do not commit it to source control or share it in public channels. *** ## Vault Commands The vault stores credentials encrypted at rest, keyed by a profile name. The daemon decrypts credentials only when needed to perform a login. Set the `GSD_BROWSER_VAULT_KEY` environment variable before starting the daemon to enable vault encryption. ### `gsd-browser vault-save` Store a set of credentials in the encrypted vault under a profile name. ```bash theme={null} gsd-browser vault-save --profile --url --username --password ``` A unique profile name for this credential set (e.g. `my-app-prod`). The login URL for this credential profile. The username or email address for this credential. The password. This value is encrypted at rest using the `GSD_BROWSER_VAULT_KEY` environment variable. **Example** ```bash theme={null} # Store credentials for the production app export GSD_BROWSER_VAULT_KEY="my-secret-encryption-key" gsd-browser vault-save \ --profile my-app-prod \ --url https://example.com/login \ --username admin@example.com \ --password "s3cr3t!" ``` *** ### `gsd-browser vault-list` List all vault profile names. Credentials (usernames and passwords) are never shown. ```bash theme={null} gsd-browser vault-list ``` **Example** ```bash theme={null} gsd-browser vault-list # my-app-prod # my-app-staging ``` *** ### `gsd-browser vault-login` Navigate to the login URL stored in a vault profile and automatically fill and submit the login form using the stored credentials. ```bash theme={null} gsd-browser vault-login --profile ``` The profile name of the credentials to use for login. **Example** ```bash theme={null} # Log in to the production app using stored credentials gsd-browser vault-login --profile my-app-prod # Verify login succeeded gsd-browser wait-for --condition url_contains --value "/dashboard" gsd-browser screenshot --output ./login-success.png ``` Combine `vault-login` with `save-state` to capture an authenticated browser state that you can restore with `restore-state` in future runs, avoiding repeated login flows. # GSD Browser MCP Server: Connect AI Agents via MCP Source: https://docs.opengsd.net/browser/concepts/mcp-server Run gsd-browser mcp to expose 50+ automation tools, live resources, and executable prompts to Cursor, Claude Desktop, or any MCP-compatible AI agent. The MCP server is the recommended path for connecting AI agents to GSD Browser. Running `gsd-browser mcp` starts a Model Context Protocol server that exposes the entire daemon surface — navigation, interaction, snapshots, recordings, vault, network control, and more — as over 50 discoverable tools, live resources, and executable prompts. Any MCP-compatible client connects to it with a single configuration block and immediately gains access to the full browser automation platform. ## Start the MCP server Most MCP clients manage the server process for you. Point your client at `gsd-browser mcp` and it handles startup, shutdown, and restarts automatically. ```bash theme={null} gsd-browser mcp ``` The server communicates over stdin/stdout using the JSON-RPC MCP protocol. The daemon starts automatically when the first tool call arrives. Run the MCP surface over Streamable HTTP for hosted or cloud deployments. Generate a token and bind to a public interface: ```bash theme={null} export GSD_BROWSER_MCP_AUTH_TOKEN="$(openssl rand -hex 32)" gsd-browser mcp --http --host 0.0.0.0 --port 8788 ``` Expose the service over HTTPS via your proxy or platform, then point remote clients at: ``` https://your-domain.example/mcp Authorization: Bearer ``` For local development without auth (loopback only): ```bash theme={null} gsd-browser mcp --http --host 127.0.0.1 --port 8788 ``` Non-loopback hosts refuse unauthenticated startup by default. Pass `--no-auth` only when you have intentionally secured the endpoint at the network layer. To use OpenGSD console tokens with per-request usage tallying, set the verifier URL before starting: ```bash theme={null} export GSD_BROWSER_MCP_AUTH_VERIFY_URL="https://mcp.opengsd.dev/api/mcp/tokens/verify" gsd-browser mcp --http --host 0.0.0.0 --port 8788 ``` The server validates each request against the console, counts `tools/call` requests against the user's quota, and forwards throttle responses when the console returns `429`. ## Tool categories The MCP server exposes 50+ tools grouped into logical categories. Call `tools/list` from any connected client to see the current full surface. `browser_navigate`, `browser_back`, `browser_forward`, `browser_reload`, `browser_wait_for` — control page navigation and wait for conditions like `network_idle`, `selector_visible`, `url_contains`, and `region_stable`. `browser_snapshot`, `browser_get_ref` — scan the page and assign versioned refs (`@v1:e1`), then inspect individual refs for bounding boxes, ARIA data, and structural signatures. The primary mechanism for reliable interaction. See [Snapshots & Refs](/browser/concepts/snapshots-refs). `browser_click_ref`, `browser_fill_ref`, `browser_hover_ref`, `browser_click`, `browser_type`, `browser_press`, `browser_scroll`, `browser_drag`, `browser_select_option`, `browser_set_checked`, `browser_upload_file`, `browser_set_viewport` — precise element interaction using refs or CSS selectors. `browser_click_ref` accepts an optional `double_click: true` to dispatch a DOM `dblclick` instead of a single click, which some inline-edit and grid components require. `browser_act`, `browser_act_instruction`, `browser_find_best` — natural language intent execution. `browser_act` covers 15 built-in patterns (fill email, fill password, submit form, accept cookies, click next, dismiss dialog, open menu, and more). `browser_act_instruction` accepts a free-form instruction like `"click Continue"` or `"enter alice@example.com into Email"` and plans concrete primitive steps against the live page — use it when the intent isn't a built-in pattern. Both tools share the self-healing action cache. See [Free-form instructions with `browser_act_instruction`](#free-form-instructions-with-browser-act-instruction). `browser_analyze_form`, `browser_fill_form` — inspect a form's structure and fill multiple fields in one call using labels, name attributes, or ARIA identifiers. `browser_screenshot`, `browser_zoom_region`, `browser_save_pdf`, `browser_visual_diff` — capture screenshots, zoom into regions, export PDFs, and run visual regression comparisons against a stored baseline. `browser_view`, `browser_goal`, `browser_takeover`, `browser_release_control`, `browser_annotation_request`, `browser_step`, `browser_abort`, `browser_pause`, `browser_resume`, `browser_sensitive_on`, `browser_sensitive_off` — open the authenticated viewer, set goal banners, let a human take over and annotate, then hand control back to the agent. `browser_record_start`, `browser_record_stop`, `browser_recordings`, `browser_recording_export`, `browser_recording_validate`, `browser_generate_replayable_test` — capture flows as rich, redacted evidence bundles and auto-convert them to commit-ready Playwright regression tests. `browser_session_list`, `browser_session_new`, `browser_session_close`, `browser_session_save`, `browser_session_restore` — manage isolated browser contexts. See [Sessions](/browser/concepts/sessions). `browser_mock_route`, `browser_block_urls`, `browser_clear_routes`, `browser_har_export`, `browser_trace_start`, `browser_trace_stop` — intercept and mock requests, block URLs, export HAR files, and start CDP traces. `browser_vault_save`, `browser_vault_login`, `browser_vault_list`, `browser_save_state`, `browser_restore_state` — store encrypted credentials and persist full browser state across sessions for repeatable authenticated flows. `browser_console`, `browser_network`, `browser_timeline`, `browser_debug_bundle`, `browser_session_summary`, `browser_check_injection`, `browser_evaluate` (alias: `browser_eval`) — inspect console logs, network traffic, the action timeline, and get a full debug bundle (screenshot + console + network + a11y) when an agent gets stuck. `browser_evaluate` runs arbitrary JavaScript in the active page and safely returns the result; `browser_eval` is an identical short alias for agents that prefer the shorter name. `browser_list_pages`, `browser_switch_page`, `browser_close_page`, `browser_list_frames`, `browser_select_frame` — manage multiple tabs opened by navigation or JavaScript, and work inside iframes. `browser_batch` — run a sequence of actions atomically in a single round-trip. Highly recommended for complex multi-step flows where partial state errors must be avoided. Supported step actions include `navigate`, `reload`, `click`, `type`, `select_option`, `key_press`, `press`, `wait_for`, `assert`, `click_ref` (supports `double_click: true`), `fill_ref`, `hover`, `hover_ref`, `scroll`, `snapshot`, `diff`, and `eval`. `browser_action_cache` (stats / get / put / clear) — inspect, populate, and manage the self-healing intent-to-selector cache. See [Snapshots & Refs](/browser/concepts/snapshots-refs). ## Reloading the current page with `browser_reload` `browser_reload` exposes the daemon's native page reload as an MCP tool. Use it to refresh dynamic content (long-polled dashboards, "load more" lists that need to restart from a clean state) or to recover from a stale page after an error. It returns the same structured page state as `browser_navigate`, so agents can branch on the response in the same way. Reload only takes an optional `session` argument: ```json theme={null} { "name": "browser_reload", "arguments": { "session": "checkout-flow" } } ``` Always follow `browser_reload` with `browser_snapshot` before interacting with elements — refs from the previous page version are no longer valid. Inside `browser_batch`, use the `reload` step instead of a separate tool call so the reload stays in the same atomic round-trip: ```json theme={null} { "name": "browser_batch", "arguments": { "steps": [ { "action": "navigate", "url": "https://example.com/orders" }, { "action": "reload" }, { "action": "wait_for", "condition": "selector_visible", "value": "#orders-table" }, { "action": "snapshot" } ] } } ``` ## Free-form instructions with `browser_act_instruction` `browser_act_instruction` accepts a short natural-language instruction, plans concrete primitive steps against the live DOM, and dispatches them through the same engine that powers `browser_click`, `browser_type`, `browser_select_option`, `browser_set_checked`, `browser_drag`, and `browser_scroll`. Reach for it when the action isn't one of the built-in `browser_act` semantic patterns — for example "choose California from State", "drag the price slider to the right", or "scroll the comments panel down". The tool accepts: | Field | Type | Description | | ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `instruction` | string (required) | Short action-oriented instruction, e.g. `"click Continue"`, `"enter 'alice@example.com' into Email"`, `"choose California from State"`. | | `dry_run` | boolean | When `true`, return the planned steps and confidence without executing them. Defaults to `false`. | | `scope` | string | CSS selector that constrains planning to a form, dialog, panel, or other page region. Use this when a page has repeated controls (e.g. multiple "Save" buttons). | | `min_confidence` | number | Block execution when the inferred plan confidence is below this threshold. Use this to fail closed on ambiguous instructions instead of guessing. | | `max_steps` | integer | Cap on primitive steps the instruction may execute. Defaults to a small bounded sequence. | | `session` | string | Named session for parallel browser instances. | A typical guarded execution looks like this: ```json theme={null} { "name": "browser_act_instruction", "arguments": { "instruction": "enter 'alice@example.com' into Email", "scope": "#signup-form", "min_confidence": 0.7 } } ``` To inspect the plan before committing — useful when an instruction might select the wrong control on a dense page — pass `dry_run: true`: ```json theme={null} { "name": "browser_act_instruction", "arguments": { "instruction": "click the second 'Delete' button", "scope": "#row-42", "dry_run": true } } ``` The response contains the inferred primitive (`click`, `type`, `select_option`, …), the target element, and a confidence score. If the plan looks correct, re-issue the call without `dry_run` to execute it. If confidence is low or the target is wrong, tighten `scope` or rewrite the instruction. Prefer `browser_act` first for the 15 built-in semantic patterns (`fill_email`, `submit_form`, `accept_cookies`, etc.) — they are faster and benefit from the action cache. Fall back to `browser_act_instruction` when the action isn't a built-in pattern, and to ref-based primitives (`browser_click_ref`, `browser_fill_ref`) when you need exact pixel-perfect control. ## Resources Resources give your agent live context without issuing a full tool call. Read them in your agent loop after navigation to get up-to-date page state cheaply. | Resource URI | What it returns | | --------------------------------- | --------------------------------------------------------------------- | | `gsd-browser://latest-snapshot` | Triggers a fresh snapshot and returns versioned refs + page structure | | `gsd-browser://current-state` | Full debug bundle: screenshot, console, network, timeline, a11y | | `gsd-browser://active-recordings` | List of in-progress recording bundles | | `gsd-browser://timeline` | Recent action timeline | | `gsd-browser://current-refs` | The refs from the most recent snapshot, without re-scanning | ## Executable prompts Built-in prompts are multi-step executable workflows that encode the [agent best practices](https://github.com/open-gsd/gsd-browser/blob/main/docs/AGENT-BEST-PRACTICES.md) directly. Ask your MCP client to run them by name. | Prompt | What it does | | ---------------------------- | --------------------------------------------------------------------------------------------------------- | | `robust_login_flow` | Navigates to a login page, fills credentials, submits, asserts the logged-in state, and saves the session | | `full_page_audit` | Runs snapshot, console, network, visual diff, and debug bundle in parallel and synthesizes the results | | `create_evidence_bundle` | Records a flow with annotations and exports a redacted, replayable bundle | | `evidence_creation_workflow` | Full record → export → generate Playwright test pipeline | | `autonomous_research_task` | Open-ended research flow with structured extraction and evidence capture | | `debug_stuck_agent_flow` | Collects debug bundle, console, network, and timeline to diagnose a stuck agent | ## Response envelopes Every `tools/call` response from the MCP server includes a standardized envelope: ```json theme={null} { "summary": "Clicked @v2:e2 — button 'Search'", "structured_data": { ... }, "suggested_next_actions": [ "Call browser_wait_for with condition network_idle", "Re-snapshot to get fresh refs after navigation" ], "evidence_refs": ["recording://rec_abc123"], "raw_fallback": "..." } ``` Follow the `suggested_next_actions` on every call — they contain high-signal hints that significantly reduce the number of round-trips an agent needs to complete a task. ## Client configuration Add the following to your Claude Desktop MCP configuration file (`.mcp.json` or `claude_desktop_config.json`): ```json theme={null} { "mcpServers": { "gsd-browser": { "command": "gsd-browser", "args": ["mcp"] } } } ``` To pre-configure the browser path and vault key: ```json theme={null} { "mcpServers": { "gsd-browser": { "command": "gsd-browser", "args": ["mcp"], "env": { "GSD_BROWSER_BROWSER_PATH": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "GSD_BROWSER_VAULT_KEY": "your-strong-key-here" } } } } ``` Add the MCP server in Cursor's `mcp.json` or VS Code's MCP settings. The configuration format is the same as Claude Desktop: ```json theme={null} { "mcpServers": { "gsd-browser": { "command": "gsd-browser", "args": ["mcp"], "env": { "GSD_BROWSER_BROWSER_PATH": "/usr/bin/chromium", "GSD_BROWSER_VAULT_KEY": "your-strong-key-here" } } } } ``` For a named session per project (strongly recommended), add the session flag to `args`: ```json theme={null} "args": ["mcp", "--session", "my-project"] ``` For remote agents pointing at a hosted HTTP server: ```json theme={null} { "mcpServers": { "gsd-browser": { "transport": "http", "url": "https://your-domain.example/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN_HERE" } } } } ``` Cloud instances that use OpenGSD console tokens require a valid token from the OpenGSD console. Each `tools/call` request is validated and counted against the token's quota. If you have cloned the gsd-browser repository, run `./scripts/mcp-quickstart.sh cursor` (or `claude` / `vscode` / `generic`) for tailored setup instructions and copy-paste config snippets for your specific client. ## How the MCP adapter works The MCP server is a thin, high-fidelity adapter over the same daemon client that the CLI uses. When your agent calls a tool, the server translates the JSON-RPC request directly to the daemon's internal API, attaches the standardized response envelope, and returns the result. You get automatic daemon lifecycle management, named session routing, and all the reliability guarantees of the CLI — plus the discoverability and structured envelopes that MCP provides. Daemons started on behalf of an MCP client follow the same idle-shutdown and version-mismatch auto-restart rules as the CLI. Tune `GSD_BROWSER_IDLE_SHUTDOWN_SECONDS` in your MCP client's `env` block to control how long an inactive agent session holds a Chrome process open. See [Daemon lifecycle and idle shutdown](/browser/concepts/sessions#daemon-lifecycle-and-idle-shutdown). ``` MCP Client (Cursor / Claude / VS Code) │ JSON-RPC over stdio or HTTP ▼ gsd-browser mcp ──────────────────────────────────────────────────────► daemon ──► Chrome (thin adapter) (same daemon client as CLI) ``` This architecture means the entire 90+ command CLI surface is available through MCP — the 50+ exposed tools are the highest-value subset curated for agent workflows, with agent-optimized descriptions and envelopes added on top. # GSD Browser Sessions: Isolated Browser Contexts Source: https://docs.opengsd.net/browser/concepts/sessions Named sessions isolate cookies, storage, and cache per workflow. Run parallel agents, persist auth state, and scope the action cache and vault per session. A session in GSD Browser is an isolated browser context with its own cookies, local storage, service worker cache, and browser identity. When you target a named session, GSD Browser spins up a separate daemon instance and browser profile dedicated to that name. Sessions enable parallel agent tasks, clean separation between test scenarios, and persistent authentication states that survive across multiple runs. ## The default session If you run any command without `--session`, GSD Browser uses a single shared default session. This is fine for simple scripting and one-off tasks. For anything that requires isolation — multiple agents running concurrently, different user accounts, or separate test environments — use named sessions. ## Targeting a named session Add `--session ` to any command to route it to that session's daemon instance: ```bash theme={null} gsd-browser --session checkout navigate https://myapp.com/checkout gsd-browser --session checkout snapshot gsd-browser --session checkout click @v1:e2 ``` ```bash theme={null} # A second session running in parallel gsd-browser --session dashboard navigate https://myapp.com/dashboard gsd-browser --session dashboard snapshot ``` Both sessions run independently — different Chrome windows, different cookies, zero cross-contamination. ## Daemon management per session Each named session runs its own daemon. Use the `daemon` subcommands with `--session` to manage a specific session's daemon: ```bash theme={null} # Start a specific session's daemon explicitly gsd-browser --session checkout daemon start # Check daemon health for a session gsd-browser --session checkout daemon health # Stop a specific session's daemon gsd-browser --session checkout daemon stop ``` ## Daemon lifecycle and idle shutdown Each session's daemon is long-lived but not permanent. To keep idle sessions from holding Chrome processes open forever, the daemon automatically exits when it has been idle for a configurable window, and the next CLI or MCP request transparently starts a fresh one. ### Idle shutdown The daemon tracks the time since the last IPC request it handled. After the configured idle window passes with no in-flight requests, it shuts down gracefully through the same path as `daemon stop` — cleaning up the browser, marking the session manifest as stopped, and releasing the IPC endpoint. The next command on that session auto-starts a new daemon, so the behavior is invisible to scripts and agents. Configure the window with `GSD_BROWSER_IDLE_SHUTDOWN_SECONDS`: ```bash theme={null} # Default: shut down after 1 hour (3600 seconds) of inactivity gsd-browser --session checkout navigate https://myapp.com # Aggressive: shut down after 5 minutes (useful for short-lived CI jobs) export GSD_BROWSER_IDLE_SHUTDOWN_SECONDS=300 gsd-browser --session checkout navigate https://myapp.com # Disable idle shutdown entirely (long-running interactive sessions) export GSD_BROWSER_IDLE_SHUTDOWN_SECONDS=0 gsd-browser --session checkout daemon start ``` Set the variable when launching the daemon — either before the first command that starts it, or in the `env` block of your MCP client configuration. The daemon reads it once at startup. ### Auto-restart on version mismatch When you upgrade gsd-browser, the running daemon for a session may still be the previous version. On the next request, the CLI compares its own version against the version recorded in the session manifest. If they differ, the CLI stops the live daemon and starts a new one built from the current binary before forwarding the request. No manual `daemon restart` is required after an upgrade. ## Saving and restoring browser state Persist the full browser state — cookies, local storage, session storage — to disk so it can be restored later. This is the recommended way to preserve authenticated states across daemon restarts. ```bash theme={null} # Save state for the current session gsd-browser --session myapp save-state myapp-auth # Restore state into a session gsd-browser --session myapp restore-state myapp-auth ``` Saved states survive daemon restarts and machine reboots. After restoring, the session is ready to use immediately — the browser picks up authentication cookies and storage from the saved snapshot. ## What sessions scope Named sessions are more than just browser profiles. Several GSD Browser subsystems use the session name as a namespace: | Subsystem | Scoped per session? | | ------------------------------------------- | ------------------- | | Cookies & local storage | ✅ Yes | | Service worker & cache | ✅ Yes | | Action cache (self-healing intent mappings) | ✅ Yes | | Credential vault entries | ✅ Yes | | Recording bundles & annotations | ✅ Yes | | Timeline and diagnostic logs | ✅ Yes | This means the action cache learned from a `checkout` session does not bleed into a `dashboard` session, and vault credentials stored for `checkout` are not accessible to `dashboard`. ## Common patterns Log in once, save the session state, then restore it on every future run to skip the login flow: ```bash theme={null} # First run: log in and save gsd-browser --session myapp navigate https://myapp.com/login gsd-browser --session myapp act --intent fill_email gsd-browser --session myapp act --intent fill_password gsd-browser --session myapp act --intent submit_form gsd-browser --session myapp wait-for --condition network_idle gsd-browser --session myapp save-state myapp-auth # All future runs: restore and continue gsd-browser --session myapp restore-state myapp-auth gsd-browser --session myapp navigate https://myapp.com/dashboard ``` Run two independent agents at the same time without any interference: ```bash theme={null} # Terminal 1 gsd-browser --session agent-a navigate https://site.com/page-a gsd-browser --session agent-a snapshot # Terminal 2 (simultaneously) gsd-browser --session agent-b navigate https://site.com/page-b gsd-browser --session agent-b snapshot ``` Give each test a fresh session so cookies and state from one scenario never affect another: ```bash theme={null} gsd-browser --session test-anonymous navigate https://myapp.com gsd-browser --session test-logged-in restore-state myapp-auth gsd-browser --session test-logged-in navigate https://myapp.com/dashboard ``` ## Sessions in MCP When using the MCP server, pass the session name in the server `args` or as an environment variable so every tool call is automatically routed to the right session: ```json theme={null} { "mcpServers": { "gsd-browser-checkout": { "command": "gsd-browser", "args": ["mcp", "--session", "checkout"] } } } ``` Using a named session per project keeps the action cache and vault entries scoped to that project. Over time, the self-healing cache becomes more effective because it learns from every successful interaction in that specific session context. # Snapshots & Versioned Element Refs in GSD Browser Source: https://docs.opengsd.net/browser/concepts/snapshots-refs Learn how gsd-browser snapshot assigns versioned refs like @v1:e1, why they are stale-safe, which snapshot modes exist, and how the action cache works. Versioned element refs are GSD Browser's core mechanism for reliable, deterministic browser interaction. Rather than asking you to write CSS selectors or XPath expressions that silently break when the DOM changes, GSD Browser scans the live page, assigns each interactive element a stable ref, and version-stamps the entire set. Any interaction command that uses a ref from an older snapshot version is automatically rejected — you always know when you are working with fresh data. ## How a snapshot works Run `gsd-browser snapshot` on any loaded page. The daemon traverses the live DOM, identifies interactive and semantically meaningful elements, and assigns each one a ref in the format `@vN:eM` — where `N` is the snapshot version number and `M` is the element index within that snapshot. ```bash theme={null} gsd-browser snapshot ``` Example output on `https://example.com`: ``` @v1:e1 [a] "More information..." (href="/more") ``` After you navigate or the page changes, take a new snapshot: ```bash theme={null} gsd-browser navigate https://example.com/search gsd-browser snapshot ``` The version counter increments — every ref from this snapshot starts with `@v2:`: ``` @v2:e1 [input] type="search" placeholder="Find docs..." @v2:e2 [button] "Search" @v2:e3 [a] "Advanced search" ``` Passing `@v1:e1` to a command after taking snapshot v2 raises a stale-ref error immediately, before any interaction reaches Chrome. This fail-fast behaviour prevents the subtle wrong-element bugs that plague selector-based automation. Always take a fresh snapshot after navigation, form submission, dialog interactions, or any other action that changes the page structure. Old refs do not automatically refresh — they become stale and will be rejected. ## Snapshot modes The default snapshot captures interactive elements only. Pass `--mode` to focus on a specific semantic category: | Mode | What it captures | | ----------------------- | -------------------------------------------------------------- | | `interactive` (default) | Buttons, links, inputs, selects, and other actionable elements | | `form` | All form fields, labels, and submit controls | | `dialog` | Elements inside open dialogs and modals | | `navigation` | Nav links, breadcrumbs, and pagination controls | | `errors` | Visible error messages, validation feedback, and alerts | | `headings` | Page headings (h1–h6) for structural orientation | | `visible_only` | Every visible element, not limited to interactive ones | ```bash theme={null} # Capture only form fields on a checkout page gsd-browser snapshot --mode form # Capture everything visible for a full-page audit gsd-browser snapshot --mode visible_only ``` You can also scope a snapshot to a part of the page with `--selector`: ```bash theme={null} gsd-browser snapshot --selector "#main-content" ``` ## Interacting with refs All interaction commands accept either a ref or a CSS selector. Use refs whenever you have a current snapshot — they are more robust than selectors because the daemon validates the version stamp before acting. ```bash Click theme={null} gsd-browser click @v2:e2 # or by selector gsd-browser click "button[type='submit']" ``` ```bash Type / Fill theme={null} gsd-browser type @v2:e1 "search query" gsd-browser fill-ref @v2:e1 "search query" --clear-first ``` ```bash Hover theme={null} gsd-browser hover-ref @v2:e3 ``` ## Inspecting a specific ref `gsd-browser get-ref` returns full metadata for any ref — bounding box, ARIA role and name, element tag, structural signature, and the resolved CSS selector the daemon uses internally: ```bash theme={null} gsd-browser get-ref @v2:e1 ``` ```json theme={null} { "ref": "@v2:e1", "tag": "input", "type": "search", "aria_role": "searchbox", "aria_label": "Find docs...", "placeholder": "Find docs...", "bounding_box": { "x": 120, "y": 80, "width": 400, "height": 40 }, "selector": "#search-input" } ``` This is particularly useful when debugging why an interaction failed or when you want to understand the structural context of an element. ## Best practices for AI agents Read the `gsd-browser://latest-snapshot` MCP resource (or call `browser_snapshot`) after every navigation and after any action that changes the DOM. This gives your agent fresh, versioned refs before it attempts any interaction. Use `browser_act` or `browser_find_best` for common intents (fill email, click submit, accept cookies, etc.) before dropping down to ref-based interaction. Semantic tools use the action cache automatically and are more resilient to minor DOM changes. When `browser_act` doesn't cover your case, or when you need to click a very specific element, take a snapshot and use the resulting refs. Refs give you exact, version-validated targeting. After clicking a button that triggers a navigation or a form submission that refreshes the page, always re-snapshot before your next interaction. The snapshot version will increment and give you fresh, valid refs for the new page state. ## The action cache and self-healing Every time an agent successfully maps an intent (like `fill_email`) to a concrete selector on a given page, GSD Browser can store that mapping in the action cache. On future visits to the same page, the cache is consulted first — if the mapping is still valid, the interaction proceeds immediately without another round-trip to find the element. ```bash theme={null} # Inspect action cache statistics gsd-browser action-cache stats # View cached mappings for the current session gsd-browser action-cache get # Clear the cache if you want to start fresh gsd-browser action-cache clear ``` The cache is scoped per [session](/browser/concepts/sessions). A `--session checkout` cache never contaminates a `--session dashboard` cache. Over long-running agent projects, the cache makes interactions progressively faster and more robust — the system effectively learns the page's element structure from prior successes. Use named sessions with a consistent name per project. The action cache accumulates knowledge across every run on that session, giving you compounding reliability gains over time. # GSD Browser MCP Setup for Claude, Cursor, and VS Code Source: https://docs.opengsd.net/browser/guides/ai-agent-setup Wire GSD Browser into Claude Desktop, Cursor, VS Code Copilot, or GSD Pi in minutes using the Model Context Protocol stdio transport. GSD Browser exposes its full automation surface — 50+ tools, live resources, and executable prompts — through the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP). Connecting your AI agent takes one config block and a restart. Once connected, your agent can navigate pages, interact with elements via stable versioned refs, record evidence bundles, control the live viewer, and more — all without writing a line of browser code. ## Prerequisites Install GSD Browser before configuring any client: ```bash theme={null} cargo install --path cli ``` Verify the installation: ```bash theme={null} gsd-browser --version ``` ## Connect Your Agent Open your Claude Desktop configuration file: * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` Add the `gsd-browser` entry inside `mcpServers`: ```json claude_desktop_config.json theme={null} { "mcpServers": { "gsd-browser": { "command": "gsd-browser", "args": ["mcp"] } } } ``` Restart Claude Desktop. The GSD Browser tools appear automatically in the tool list. Set `GSD_BROWSER_VAULT_KEY` and `GSD_BROWSER_BROWSER_PATH` in an `"env"` block inside the server entry to configure your vault encryption key and Chrome path before the daemon first starts. Open **Cursor Settings** → **MCP** tab → **Add Server**. Fill in the fields: | Field | Value | | ------- | ------------- | | Name | `gsd-browser` | | Command | `gsd-browser` | | Args | `mcp` | Save and reload the window. Cursor discovers the available tools automatically. Alternatively, add the entry directly to your Cursor MCP config file: ```json .cursor/mcp.json theme={null} { "mcpServers": { "gsd-browser": { "command": "gsd-browser", "args": ["mcp"], "env": { "GSD_BROWSER_BROWSER_PATH": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "GSD_BROWSER_VAULT_KEY": "your-strong-key-here" } } } } ``` Create or edit `.vscode/mcp.json` at the root of your workspace: ```json .vscode/mcp.json theme={null} { "servers": { "gsd-browser": { "type": "stdio", "command": "gsd-browser", "args": ["mcp"] } } } ``` VS Code picks up the file automatically. Open the **GitHub Copilot Chat** panel and switch to **Agent** mode — GSD Browser tools are available immediately. The `"type": "stdio"` field is required for VS Code's MCP client. Claude Desktop and Cursor infer the transport automatically. GSD Browser ships as a bundled extension in GSD Pi called `browser-tools`. Enable it with a single command: ```bash theme={null} /gsd extensions enable browser-tools ``` No additional configuration is needed — GSD Pi manages the daemon lifecycle and session isolation automatically. Use `/gsd extensions list` to confirm the extension is active. ## Verify the Connection After restarting your client, ask your agent: > "List the available GSD Browser tools." The agent should respond with the full tool manifest (50+ entries). You can also ask it to read a live resource: > "Read the gsd-browser://latest-snapshot resource and describe what's on the current page." ## Remote / Hosted Mode If your MCP client is hosted (not running locally), expose the server over HTTP instead of stdio: ```bash theme={null} export GSD_BROWSER_MCP_AUTH_TOKEN="$(openssl rand -hex 32)" gsd-browser mcp --http --host 0.0.0.0 --port 8788 ``` Point your remote client at `https://your-domain.example/mcp` with the `Authorization: Bearer ` header. Non-loopback hosts refuse unauthenticated startup by default. Pass `--no-auth` only when you are certain the endpoint is not publicly reachable. ## Best Practices for AI Agents Follow these rules to get reliable, reproducible results from your connected agent. Call `browser_snapshot` (or read the `gsd-browser://latest-snapshot` resource) after every navigation or major DOM change. Refs are versioned — `@v1:e1`, `@v2:e3`, etc. — and become stale the moment the page updates. Stale refs return an error; retake a snapshot to get fresh ones. ``` browser_navigate → browser_snapshot → use @v1:* refs → page changes → browser_snapshot → use @v2:* refs ``` Use `browser_act` with a semantic intent (e.g., `submit_form`, `accept_cookies`, `fill_email`) for common patterns. Semantic actions are self-healing and require no prior snapshot. Fall back to snapshot + ref tools only when you need precision on a complex widget. Pass `--session ` (or the `session` parameter in MCP calls) to create an isolated browser context per project. Named sessions also persist the action cache across runs, so the agent learns stable selector mappings over time. ```json theme={null} { "command": "gsd-browser", "args": ["mcp", "--session", "my-project"] } ``` If a `_ref` tool returns a stale-ref error, do not retry with the same ref. Call `browser_snapshot` immediately to obtain a fresh `@v(N+1):*` set, then repeat the interaction. Every GSD Browser MCP tool returns a structured envelope with a `suggested_next_actions` field. These are concrete, high-signal hints generated from the current page state. Reading and acting on them is the fastest path to robust automation. ## Built-in Prompts GSD Browser ships executable multi-step prompts you can invoke directly from your agent: Handles cookie banners, fills credentials, waits for auth, and saves session state — all in one prompt. Runs snapshot, console, network, and visual diff checks in parallel and synthesizes findings. Starts a recording, annotates key decision points, exports the bundle, and generates a Playwright regression test. Captures a debug bundle, console log, network log, and timeline to explain why the agent is stuck. Ask your agent: *"Use the gsd-browser prompt `robust_login_flow` with `start_url` set to `https://app.example.com/login`."* # Manage Login Credentials Securely with the Auth Vault Source: https://docs.opengsd.net/browser/guides/authentication-vault Store encrypted credentials in the GSD Browser vault, automate login flows, save session state, and skip repeated logins across agent runs. The GSD Browser authentication vault stores credentials in an encrypted format on disk, separate from your automation scripts and prompts. Instead of embedding usernames, passwords, or tokens in agent instructions or environment variables, you store them once with a vault key and reference them by profile name in every subsequent run. The vault also integrates with session state — log in once, save the authenticated browser context, and restore it instantly in later runs without repeating the login flow. ## Store Credentials Add a credential entry to the vault using a logical profile name: ```bash theme={null} gsd-browser vault-save \ --profile myapp-login \ --url https://app.example.com/login \ --username user@example.com \ --password secret ``` Credentials are encrypted at rest in the GSD Browser config directory using the key defined by `GSD_BROWSER_VAULT_KEY`. Never pass raw credentials in agent prompts or CLI history — store them once here and reference the profile name everywhere else. Set `GSD_BROWSER_VAULT_KEY` to a strong, unique value before storing any credentials. If you lose the vault key, stored credentials cannot be recovered. For MCP clients, set the key in the `"env"` block of your MCP server configuration so the daemon always starts with the correct key. ## Log In Automatically Use a stored credential profile to navigate to the configured login page and complete the form automatically: ```bash theme={null} gsd-browser vault-login --profile myapp-login ``` The `vault-login` command navigates to the URL stored in the profile, finds the login form, fills the username and password fields with the stored values, and submits the form. No credentials appear in your shell history or process list. In MCP mode, use the `browser_vault_login` tool with the same `profile` parameter. The `robust_login_flow` built-in prompt also integrates with the vault automatically. ## Save and Restore Session State After a successful login, save the authenticated browser context so future runs can skip the login step entirely: ```bash theme={null} gsd-browser vault-login --profile myapp-login ``` ```bash theme={null} gsd-browser assert --checks '[{"kind": "url_contains", "text": "/dashboard"}]' ``` ```bash theme={null} gsd-browser save-state --name myapp-authenticated ``` GSD Browser writes a session state file (cookies, local storage, session storage) to the config directory. ```bash theme={null} gsd-browser restore-state --name myapp-authenticated gsd-browser navigate https://app.example.com/dashboard ``` The browser context loads with the saved authentication state. The login page is bypassed entirely. Combine named sessions with session state for maximum efficiency. Use `--session myapp` so the restored state, action cache, and browser context all share the same isolated namespace across multiple automation runs. ## List Vault Profiles List all stored credential profiles (values are never shown): ```bash theme={null} gsd-browser vault-list ``` ## Full Authenticated Automation Workflow ```bash theme={null} gsd-browser vault-save \ --profile myapp-login \ --url https://app.example.com/login \ --username user@example.com \ --password secret ``` ```bash theme={null} gsd-browser vault-login --profile myapp-login gsd-browser wait-for --condition url_contains --value /dashboard gsd-browser save-state --name myapp-authenticated ``` ```bash theme={null} gsd-browser restore-state --name myapp-authenticated gsd-browser navigate https://app.example.com/dashboard # Continue automation from the authenticated state ``` ## Best Practices for AI Agents Store credentials with `vault-save` during initial setup. In all agent prompts and MCP calls, reference the vault profile name — the agent never sees the actual password. For repeated automation runs, restore a saved session instead of logging in each time. This is faster and eliminates the risk of triggering bot-detection on the login page. Session state has a finite lifetime. When `restore-state` followed by a navigate lands on the login page, repeat the `vault-login` → `save-state` cycle to refresh the stored state. Run `gsd-browser recording-validate` on any evidence bundle that was captured in an authenticated session. The validator confirms that cookies and tokens were stripped before export. # Watch and Control the Browser Live with GSD Viewer Source: https://docs.opengsd.net/browser/guides/live-viewer Watch the agent live, pause and step through actions, take manual control, annotate moments, and share the viewer URL with your team. The GSD Browser live viewer gives you — and any collaborator — a real-time window into exactly what the agent's browser is doing. You can watch passively, pause and step through actions one at a time, take manual control of the keyboard and mouse, annotate key moments, and hand control back to the agent without breaking the session. Every action the agent takes is narrated in a scrollable history panel alongside the live frame. ## Start the Viewer Use `--session` so every command in the flow attaches to the same browser context, viewer, and history. ```bash theme={null} gsd-browser --session demo navigate https://example.com ``` ```bash theme={null} gsd-browser --session demo view ``` GSD Browser prints a localhost URL (e.g. `http://127.0.0.1:7878/viewer?token=...`) and opens it in your default browser. The URL includes a one-time security token — share it only with collaborators who should have access. If you need the URL without auto-opening (for example, to pass it to another tool): ```bash theme={null} VIEW_URL=$(gsd-browser --session demo view --print-only | tail -1) echo "$VIEW_URL" ``` Display a visible goal message so collaborators understand what the agent is doing: ```bash theme={null} gsd-browser --session demo goal "Complete the checkout flow" ``` Clear it when the step is done: ```bash theme={null} gsd-browser --session demo goal --clear ``` Keep issuing CLI or MCP commands. The viewer reflects every action in real time — clicks, typing, navigation, and failures all appear with target rings, cursor animations, and narration entries. ```bash theme={null} gsd-browser --session demo snapshot gsd-browser --session demo click-ref @v1:e3 gsd-browser --session demo fill-ref @v1:e1 "user@example.com" gsd-browser --session demo act --intent submit_form ``` Stop the daemon when no further browser work is needed: ```bash theme={null} gsd-browser --session demo daemon stop ``` ## Viewer Controls The viewer exposes controls directly in the browser UI. You can also use keyboard shortcuts. | Control | Keyboard Shortcut | Effect | | ------------ | ----------------- | ----------------------------------------------------------------- | | Pause | `Space` | Blocks the agent before its next narrated action | | Resume | `Space` | Allows agent actions to continue | | Step | `→` (Right Arrow) | Allows exactly one action, then returns to paused | | Abort | `Esc` | Aborts the next queued action | | Refs overlay | `R` | Shows or hides bounding boxes and labels for interactive elements | ## Human Takeover Take full manual control of the browser without terminating the session: The agent pauses immediately. The session remains live — cookies, auth state, and page context are all preserved. Use your mouse and keyboard in the viewer to click, type, scroll, or navigate. All manual actions are captured in the narration history. The agent picks up from the exact page state you left it in. It re-snapshots automatically before its next action. In MCP mode, use `browser_takeover` to pause and `browser_release_control` to hand back programmatically. ## Annotation Tools Mark important moments directly in the viewer so they appear in the narration log and any exported evidence bundle. Highlight regions of the page with freehand drawing to call attention to specific elements. Attach text annotations to the current frame — these become timestamped entries in the narration history. Flag elements in the viewer so the agent's next snapshot includes a prioritized hint for that region. Every annotation streams to the MCP server and appears in the narration log. Retrieve the full log at any time. Request an annotation from the CLI — a prompt appears in the viewer for the human collaborator to fill in: ```bash theme={null} gsd-browser --session demo annotation-request "Please confirm the price shown here" ``` ## Review History Open a history-focused view without issuing new browser actions: ```bash theme={null} gsd-browser --session demo view --history ``` History items show pending, success, and failure states. Hover an entry in the viewer to preview the captured frame around that action. ## Fast Agent Runs For agent-only runs where no human needs the cursor lead-in animation, use `--no-narration-delay`. The narration history is still recorded — only the lead-time sleep is skipped. ```bash theme={null} gsd-browser --session demo --no-narration-delay navigate https://example.com gsd-browser --session demo --no-narration-delay click-ref @v1:e2 ``` ## When to Use the Live Viewer Let a compliance officer watch the agent complete a regulated workflow and annotate the key attestation steps in real time. Pause and step through a failing flow action-by-action to pinpoint exactly where the agent goes wrong. Record the viewer session — including manual takeovers and annotations — as a rich, labeled training dataset. Let a QA engineer watch the agent run a user story and intervene at any point to verify or correct behavior. Recordings started during an active viewer session produce the highest-quality evidence bundles because they capture both agent actions and human annotations in a single enriched timeline. Start a recording with `gsd-browser --session demo record-start --name my-flow` before your viewer session for the richest output. # Control Network Traffic: Mocking, Blocking, and Capture Source: https://docs.opengsd.net/browser/guides/network-control Mock API routes, block noisy URLs, capture HAR files, run CDP traces, and intercept requests for testing and performance profiling. GSD Browser gives you precise control over every network request the browser makes. You can mock API responses to test edge cases, block analytics and ad traffic to keep automation clean, capture a full HAR file for debugging, run a CDP trace for performance profiling, or inspect the live network log at any time. All network control commands work in both CLI and MCP contexts and apply immediately to the current browser session. ## Mock API Routes Return a fixed response for any URL pattern without hitting a real server: ```bash theme={null} gsd-browser mock-route \ --url "**/api/users" \ --body '{"users": []}' \ --status 200 ``` Simulate error states and loading delays: ```bash Server error theme={null} gsd-browser mock-route \ --url "**/api/data" \ --body '{"error": "internal server error"}' \ --status 500 ``` ```bash Slow response (3 s delay) theme={null} gsd-browser mock-route \ --url "**/api/data" \ --body '{"ok": true}' \ --delay 3000 ``` Remove all active mocks when you are done: ```bash theme={null} gsd-browser clear-routes ``` Route mocks apply to the current session only. They are cleared automatically when the session ends. Always call `clear-routes` before switching to a different test scenario within the same session. ## Block URLs Prevent specific requests from leaving the browser entirely. This is useful for eliminating analytics noise, ad networks, and third-party tracking during automation: ```bash theme={null} gsd-browser block-urls "**/analytics*" "**/ads*" "**/tracking*" ``` Blocking analytics and ad URLs during test runs reduces flakiness caused by third-party request timeouts. Add a `block-urls` call at the start of any test session that visits pages with heavy third-party scripts. ## Export a HAR File Export all captured network traffic for the current session as a HAR 1.2 JSON file. GSD Browser records every request automatically — export the buffer at any point: ```bash theme={null} gsd-browser har-export --filename traffic.har ``` Open the resulting `.har` file in [HAR Analyzer](https://toolbox.googleapps.com/apps/har_analyzer/) or import it directly into browser DevTools for inspection. The network buffer accumulates continuously. Call `gsd-browser network --clear` if you want to reset the capture window before a specific flow, then export with `har-export` afterward. ## Run a CDP Trace Capture a Chrome DevTools Protocol performance trace for deep profiling of rendering, scripting, and network timing: ```bash theme={null} gsd-browser trace-start ``` Navigate, interact, and exercise the code paths you want to measure. ```bash theme={null} gsd-browser trace-stop ``` Load the output file in `chrome://tracing` or [Perfetto](https://ui.perfetto.dev/) to visualize the timeline. ## Inspect the Network Log Read the current network log at any time without exporting a full HAR: ```bash theme={null} gsd-browser network gsd-browser network --filter errors gsd-browser network --filter fetch-xhr ``` Combine with `--json` for programmatic parsing: ```bash theme={null} gsd-browser network --filter errors --json ``` ## Use Cases Set up route mocks before navigating so your automation runs against controlled data — no test accounts, seeding, or teardown required. Block analytics, ad, and telemetry URLs to eliminate flakiness from slow third-party requests and keep your HAR files clean and focused. Use `har-export` after a problematic flow to capture every request. Share the `.har` file with your team or attach it to a bug report. Use CDP traces alongside HAR captures to correlate network timing with rendering and scripting bottlenecks on complex pages. ## Common Patterns ```bash theme={null} gsd-browser mock-route --url "**/api/users" --body '{"error": "not found"}' --status 404 gsd-browser navigate https://app.example.com/users gsd-browser assert --checks '[{"kind": "text_visible", "text": "not found"}]' gsd-browser clear-routes ``` ```bash theme={null} gsd-browser trace-start gsd-browser navigate https://app.example.com gsd-browser wait-for --condition network_idle gsd-browser har-export --filename audit.har gsd-browser trace-stop ``` ```bash theme={null} gsd-browser block-urls "**/analytics*" "**/doubleclick*" "**/googletagmanager*" gsd-browser navigate https://app.example.com # ... automation steps ... gsd-browser har-export --filename clean-traffic.har ``` # Record Browser Sessions and Export Evidence Bundles Source: https://docs.opengsd.net/browser/guides/recording-evidence Capture named recordings, export shareable evidence bundles with network HAR and screenshots, and generate Playwright regression tests. GSD Browser treats every recorded session as a first-class audit artifact. A recording captures network traffic, annotated screenshots, and a full narration log — all packaged into a portable evidence bundle you can share, archive, or automatically convert into a Playwright regression test. This workflow is designed for flows that need to be reproduced, audited, or handed to a compliance team. ## Start and Stop a Recording Begin a recording before you start the actions you want to capture: ```bash theme={null} gsd-browser record-start --name checkout-bug-2026-05 ``` Perform your browser actions — through the CLI, MCP tools, or manual takeover in the live viewer. Then stop the recording: ```bash theme={null} gsd-browser record-stop ``` In MCP mode, use `browser_record_start` and `browser_record_stop`. Recordings started during an active live viewer session are automatically enriched with human annotations and frame-level context. ## List and Export Recordings List all saved recordings: ```bash theme={null} gsd-browser recordings ``` Export a completed recording into a self-contained, shareable bundle: ```bash theme={null} gsd-browser recording-export --output ./evidence/ ``` ### What a Recording Bundle Contains A complete HTTP Archive of every network request and response made during the session, including headers and bodies. Automatic screenshots captured at key interaction points, plus any manual screenshots taken during the session. A timestamped, annotated action timeline showing every step the agent (or human) took, with success/failure state. A `manifest.json` documenting the recording metadata, redaction details, and state restoration hints. ## Validate a Bundle Before sharing or archiving a bundle, validate it to confirm it is complete: ```bash theme={null} gsd-browser recording-validate ./evidence/checkout-bug-2026-05 ``` The validator confirms the bundle manifest, redaction details, and state restoration hints are all present. ## Generate a Playwright Test Turn any recording into a Playwright regression test from the action timeline automatically: ```bash theme={null} gsd-browser generate-test --name checkout-flow --output tests/checkout.spec.ts ``` Always review the generated test before committing it. The generator uses versioned refs (`@vN:eM`) as starting locators — replace them with stable Playwright locators (`getByRole`, `getByText`, etc.) and tune assertion strictness before running in CI. The generator embeds review comments directly in the output to guide you. The generated test includes: * A `test.describe` block with step-by-step replay of every recorded action * DOM assertions per step (element counts, text content) * Screenshot reference comments for visual cross-checking ## Take Screenshots and Save PDFs Capture the current page state at any point during a session: ```bash Screenshot theme={null} gsd-browser screenshot --output page.png ``` ```bash Full-page PDF theme={null} gsd-browser save-pdf --output page.pdf --format A4 ``` Screenshots and PDFs can be included as supporting evidence alongside exported recording bundles. ## Export Network Traffic Export all network requests captured during the session as a HAR file at any time: ```bash theme={null} gsd-browser har-export --filename session.har ``` ## CI Integration Use exported bundles and generated tests in your CI pipeline: ```yaml .github/workflows/regression.yml theme={null} - name: Validate evidence bundle run: gsd-browser recording-validate "$BUNDLE_DIR" --json - name: Run reviewed regression test run: npx playwright test tests/checkout-regression.spec.ts --reporter=list ``` Store reviewed generated tests in your repository under `tests/e2e/`. Store exported bundles as CI artifacts for audit and replay. Re-record when major UI changes invalidate the existing test. ## Full Evidence Workflow ```bash theme={null} gsd-browser --session checkout record-start --name checkout-regression ``` Run your browser actions via CLI, MCP, or manual takeover. Use `annotation-request` at key decision points to embed "why this step matters" notes in the narration log. ```bash theme={null} gsd-browser --session checkout annotation-request "Confirm total before payment" ``` ```bash theme={null} gsd-browser --session checkout record-stop ``` ```bash theme={null} gsd-browser recordings gsd-browser recording-export --output ./evidence/checkout-regression ``` ```bash theme={null} gsd-browser recording-validate ./evidence/checkout-regression ``` ```bash theme={null} gsd-browser generate-test \ --name checkout-regression \ --output tests/e2e/checkout.spec.ts ``` Open `tests/e2e/checkout.spec.ts`, replace ephemeral refs with stable locators, and run `npx playwright test` locally before committing. # Install GSD Browser on macOS, Linux, or Windows Source: https://docs.opengsd.net/browser/installation Install GSD Browser via npm, a one-line shell script, pre-built binaries from GitHub Releases, or by building from source with Cargo. GSD Browser ships as a single self-contained binary that includes both the CLI client and the background daemon. Pick the installation method that fits your environment — all methods produce the same `gsd-browser` command. ## Requirements Chrome or Chromium must be installed on the machine where the daemon will run. On Windows, Microsoft Edge also works — GSD Browser auto-discovers Chrome or Edge from standard install locations (including `Program Files`, `Program Files (x86)`, and `LocalAppData`) as well as your `PATH`. On macOS and Linux, the daemon checks the usual Chrome and Chromium locations and falls back to a `PATH` search. If your browser lives somewhere non-standard, point to it with `--browser-path /path/to/chrome` or set `GSD_BROWSER_BROWSER_PATH` in your environment. GSD Browser runs natively on macOS, Linux, and Windows. The Windows daemon uses named pipes for local IPC, so no extra setup (such as WSL) is required. ## Install methods Installing via npm puts `gsd-browser` on your `PATH` through the standard Node.js global bin mechanism — no manual download or PATH editing required. ```bash theme={null} npm install -g @opengsd/gsd-browser ``` The npm package resolves the correct platform binary automatically. It supports macOS arm64, macOS x64, Linux arm64, Linux x64, and Windows x64. The shell installer downloads the correct binary for your platform, places it in `~/.local/bin` (or `/usr/local/bin` with sudo), and optionally sets up the agent skill pack. ```bash theme={null} bash <(curl -fsSL https://raw.githubusercontent.com/open-gsd/gsd-browser/main/install.sh) ``` To also install and register the Codex Plugin in one pass: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/open-gsd/gsd-browser/main/install.sh | bash -s -- --codex-plugin ``` Download the binary for your platform directly from [GitHub Releases](https://github.com/open-gsd/gsd-browser/releases), then make it executable and move it onto your `PATH`. | Platform | Asset name | | --------------------- | ----------------------------- | | macOS (Apple Silicon) | `gsd-browser-darwin-arm64` | | macOS (Intel) | `gsd-browser-darwin-x64` | | Linux (ARM64) | `gsd-browser-linux-arm64` | | Linux (x64) | `gsd-browser-linux-x64` | | Windows (x64) | `gsd-browser-windows-x64.exe` | ```bash theme={null} # macOS / Linux example chmod +x gsd-browser-darwin-arm64 mv gsd-browser-darwin-arm64 /usr/local/bin/gsd-browser ``` The Windows binary runs natively — the daemon uses named pipes for local IPC and auto-discovers Chrome or Microsoft Edge from standard install paths and `PATH`. WSL is not required. Build from source if you want a custom feature set (such as the stealth backend) or need to run from a local checkout. ```bash theme={null} git clone https://github.com/open-gsd/gsd-browser.git cd gsd-browser cargo install --path cli ``` To build with an alternative backend: ```bash theme={null} # Stealth/anti-detection backend cargo install --path cli --no-default-features --features stealth # Chromey backend (fresher CDP definitions + adblock) cargo install --path cli --no-default-features --features chromey-backend ``` Rust 1.75 or later is required. Install Rust via [rustup.rs](https://rustup.rs) if you don't have it already. ## Verify your installation Run the following command to confirm `gsd-browser` is on your `PATH` and print the installed version: ```bash theme={null} gsd-browser --version ``` ## Start the daemon The daemon starts automatically the first time you run any browser command, so you don't need to start it manually in most workflows. To pre-warm it explicitly or verify it is running: ```bash theme={null} gsd-browser daemon start ``` Check its health at any time without triggering a new start: ```bash theme={null} gsd-browser daemon health ``` ## Configuration (optional) GSD Browser merges configuration from five sources in order of increasing precedence: 1. Built-in defaults 2. User config: `~/.gsd-browser/config.toml` 3. Project config: `./gsd-browser.toml` 4. Environment variables: `GSD_BROWSER_*` 5. CLI flags A minimal project config looks like this: ```toml gsd-browser.toml theme={null} [browser] path = "/usr/bin/chromium" headless = true [daemon] port = 9222 host = "127.0.0.1" [artifacts] dir = "./browser-artifacts" ``` Common environment variable overrides: ```bash theme={null} export GSD_BROWSER_BROWSER_PATH=/usr/bin/chromium export GSD_BROWSER_BROWSER_HEADLESS=true export GSD_BROWSER_VAULT_KEY=your-strong-encryption-key export GSD_BROWSER_ARTIFACTS_DIR=./browser-artifacts ``` When using the MCP server, place `GSD_BROWSER_*` environment variables in your MCP client's server `env` configuration block rather than your shell profile. This ensures the daemon inherits them when the MCP client spawns the process. # GSD Browser: AI-Powered Browser Automation CLI Source: https://docs.opengsd.net/browser/introduction GSD Browser is a native Rust CLI for Chrome/Chromium automation via CDP. Persistent daemon, 90+ commands, and 50+ MCP tools for AI agent integration. GSD Browser is a native Rust browser automation CLI that drives Chrome and Chromium through the Chrome DevTools Protocol (CDP). Unlike script-based frameworks, it runs a persistent background daemon that owns the full browser lifecycle — page routing, network hooks, action timeline, and session state — while a thin CLI client sends it commands. AI agents connect through the MCP server mode (`gsd-browser mcp`), which exposes over 50 discoverable tools, live resources, and executable prompts to any MCP-compatible client. ## What makes GSD Browser different GSD Browser is designed for serious, auditable, human-collaborative agentic web work. Several capabilities set it apart from conventional browser automation tools. `gsd-browser snapshot` scans the page and assigns stable refs like `@v1:e1`. Refs are version-stamped and stale-safe — old refs from a previous snapshot are automatically rejected when the DOM changes. `gsd-browser view` opens a real-time localhost workbench so humans can watch, annotate, take over control, pause, step through actions, and resume — without interrupting the agent loop. Record any flow as a rich, redacted evidence bundle. Bundles auto-convert to commit-ready Playwright regression tests via `browser_generate_replayable_test`. `browser_act` and `find_best` cover 15 built-in intent patterns — fill email, submit form, accept cookies, paginate, and more — so agents express *what* to do, not *how*. Successful intent-to-selector mappings persist in a per-session cache. Future runs reuse them automatically, making long-running agent projects progressively more reliable. `gsd-browser vault-save` stores credentials encrypted on disk. `browser_vault_login` replays them without ever exposing raw secrets in prompts or logs. Mock routes, block URLs, export HAR files, and start CDP traces — all in the same tool, with no separate proxy or plugin required. `gsd-browser mcp` exposes the entire daemon surface as MCP tools, resources, and executable prompts. Connect Cursor, Claude Desktop, VS Code Copilot, or any MCP client instantly. ## Architecture overview The daemon starts automatically the first time you run any browser command. It maintains an open Chrome instance, tracks page targets, buffers console and network logs, manages named sessions, and serves all commands over a local loopback HTTP channel. The CLI and the MCP server both talk to the same daemon — they share identical semantics and reliability guarantees. ``` ┌─────────────────┐ JSON-RPC ┌──────────────────────┐ │ gsd-browser │ ◄────────────────► │ daemon (localhost) │ │ CLI / MCP │ │ browser lifecycle │ └─────────────────┘ │ page routing │ │ session state │ └──────────────────────┘ │ CDP ┌────────▼─────────┐ │ Chrome / Chromium │ └──────────────────┘ ``` The daemon starts automatically on the first browser command. You rarely need to manage it manually. Use `gsd-browser daemon health` to inspect its state without triggering a start. ## Primary paths Choose the path that fits your workflow: Install via npm, one-line script, pre-built binary, or build from source. Start the daemon, navigate a page, take a snapshot, and interact with elements in minutes. Connect any MCP-compatible AI agent to the full GSD Browser surface in one command. # GSD Browser Quickstart: First Session in Minutes Source: https://docs.opengsd.net/browser/quickstart Start the daemon, navigate to a page, take a snapshot to get versioned element refs, interact with them, and capture a screenshot in under five minutes. This guide walks you through your first GSD Browser session. You will start the daemon, navigate to a page, take a snapshot to get versioned element refs, interact with those refs, and capture a screenshot. By the end, you will understand the core CLI workflow and know where to go next for AI agent integration. Make sure you have [installed GSD Browser](/browser/installation) and that Chrome or Chromium is available on your machine before continuing. ## CLI quickstart The daemon starts automatically on the first browser command, but you can also pre-warm it explicitly: ```bash theme={null} gsd-browser daemon start ``` Verify it is running: ```bash theme={null} gsd-browser daemon health ``` Send the browser to any page. The daemon opens Chrome if it isn't already running. ```bash theme={null} gsd-browser navigate https://example.com ``` You can combine navigation with an instant screenshot: ```bash theme={null} gsd-browser navigate https://example.com --screenshot ``` A snapshot scans the current page and assigns stable versioned refs to every interactive element. Refs look like `@v1:e1`, `@v1:e2`, and so on. The version prefix ensures stale refs from a previous snapshot are automatically rejected. ```bash theme={null} gsd-browser snapshot ``` Example output: ``` @v1:e1 [a] "More information..." (href="/more") @v1:e2 [input] type="search" placeholder="Search..." @v1:e3 [button] "Search" ``` Always take a fresh snapshot after navigation or any DOM change. Old refs become stale when the page state changes. See [Snapshots & Refs](/browser/concepts/snapshots-refs) for a full explanation. Pass a ref directly to `click`. GSD Browser resolves it to the live DOM element — no CSS selector guessing required. ```bash theme={null} gsd-browser click @v1:e1 ``` You can also click by CSS selector when you prefer: ```bash theme={null} gsd-browser click "#submit-btn" ``` Target an input by its ref and provide the text to type: ```bash theme={null} gsd-browser type @v1:e2 "hello world" ``` Add `--submit` to press Enter after typing, or `--clear-first` to empty the field before filling it: ```bash theme={null} gsd-browser type @v1:e2 "hello world" --clear-first --submit ``` Save the current viewport as an image. Both JPEG and PNG are supported. ```bash theme={null} gsd-browser screenshot --output page.png --format png ``` Capture the full scrollable page: ```bash theme={null} gsd-browser screenshot --output full.png --format png --full-page ``` When you are done, stop the daemon and close the browser: ```bash theme={null} gsd-browser daemon stop ``` ## Useful CLI options Every `gsd-browser` command accepts these global flags: | Flag | Purpose | | ----------------------- | ------------------------------------------------------------ | | `--json` | Return structured JSON output instead of human-readable text | | `--session ` | Target a named session for isolated browser state | | `--browser-path ` | Path to a specific Chrome or Chromium binary | | `--cdp-url ` | Attach to an already-running Chrome instance | For example, to get JSON output from a snapshot: ```bash theme={null} gsd-browser snapshot --json ``` ## AI agent path: MCP server If you are connecting an AI agent rather than scripting the CLI directly, use the MCP server instead. It exposes the full GSD Browser surface as 50+ discoverable tools, live resources, and executable prompts to any MCP-compatible client. Start the MCP server on stdio (most clients manage the process for you): ```bash theme={null} gsd-browser mcp ``` Or run it as an HTTP server for remote and cloud agents: ```bash theme={null} export GSD_BROWSER_MCP_AUTH_TOKEN="$(openssl rand -hex 32)" gsd-browser mcp --http --host 0.0.0.0 --port 8788 ``` Client configuration, tool categories, resources, prompts, and remote hosting. Deep dive into versioned refs — the core mechanism for reliable agent interaction. ## What to explore next Isolate browser state, run parallel agent tasks, and persist authentication across runs. Understand versioned refs, snapshot modes, and the action cache. Connect Cursor, Claude Desktop, or any MCP-compatible agent. # GSD Core Context Commands: Mapping and Intelligence Source: https://docs.opengsd.net/core/commands/context-commands Reference for GSD Core codebase intelligence commands — mapping, knowledge graphs, learning extraction, doc ingestion, and ideation tools. The context commands build and query the shared intelligence layer that informs GSD's planning and execution agents. Use them to map an unfamiliar codebase, maintain a live knowledge graph, harvest reusable patterns from completed phases, import existing documentation into `.planning/`, and explore ideas before committing to a plan. Most of these commands can run before or after project initialization. *** ## `/gsd-map-codebase` Analyze a codebase with parallel mapper agents to produce structured reference documents. **Syntax** ```bash theme={null} /gsd-map-codebase /gsd-map-codebase --fast /gsd-map-codebase --fast --focus arch /gsd-map-codebase --query "authentication" /gsd-map-codebase --query status /gsd-map-codebase --query diff /gsd-map-codebase --query refresh ``` **What it does** In full mode, spawns four parallel `gsd-codebase-mapper` agents — one per focus area — that each write their output documents directly to `.planning/codebase/`. The orchestrator only collects confirmations, keeping context usage minimal. In fast mode a single agent handles a chosen focus area. In query mode the command interrogates the live codebase intelligence index without spawning any mapper agents. **Produces** (full mode) | Document | Focus | | ------------------------------------ | ------------------------------ | | `.planning/codebase/STACK.md` | Technology stack | | `.planning/codebase/INTEGRATIONS.md` | External integrations | | `.planning/codebase/ARCHITECTURE.md` | System architecture | | `.planning/codebase/STRUCTURE.md` | Directory and module structure | | `.planning/codebase/CONVENTIONS.md` | Coding conventions | | `.planning/codebase/TESTING.md` | Test strategy and coverage | | `.planning/codebase/CONCERNS.md` | Quality concerns and tech debt | **When to use** * Run before `/gsd-new-project` on brownfield codebases to understand existing code first. * Run after significant refactoring to refresh the codebase map. * Skip on greenfield projects with no code yet, or on codebases with fewer than 5 files. **Flags** Lightweight scan mode. Spawns one mapper agent instead of four. Faster and lower-context than the full map. Optionally combine with `--focus` to target a specific area. Focus area for `--fast` mode. Accepted values: `tech`, `arch`, `quality`, `concerns`, `tech+arch` (default when `--fast` is used alone). Codebase intelligence query mode. Requires `intel.enabled: true` in your config. Sub-commands: * `query [term]` — search the index for a term * `status` — show index freshness and statistics * `diff` — show changes since the last map run * `refresh` — spawn a refresh agent to rebuild the index *** ## `/gsd-graphify` Build, query, and inspect the project knowledge graph. **Syntax** ```bash theme={null} /gsd-graphify build /gsd-graphify query "authentication" /gsd-graphify status /gsd-graphify diff ``` **What it does** Manages a structured knowledge graph in `.planning/graphs/` that captures nodes (phases, files, decisions, patterns) and their relationships. Requires `graphify.enabled: true` in your config. All operations run inline — no subagents are spawned. **Subcommands** Build or rebuild the knowledge graph from the current project state. Runs `graphify update`, copies output artifacts to `.planning/graphs/`, and writes a diff snapshot. Typical builds complete in 15–60 seconds. Search the graph for a term. Returns matched nodes grouped by type, with edge relationships and confidence tiers (EXTRACTED / INFERRED / AMBIGUOUS). Show graph freshness (STALE or FRESH), last build time, node count, edge count, and hyperedge count. Also reports source commit staleness when available. Show node and edge changes since the previous build snapshot. Run `build` twice to generate a baseline before using `diff`. *** ## `/gsd-extract-learnings N` Extract reusable patterns, decisions, and lessons from a completed phase. **Syntax** ```bash theme={null} /gsd-extract-learnings 5 /gsd-extract-learnings --all ``` **What it does** Reads the completed phase's `PLAN.md`, `SUMMARY.md`, `VERIFICATION.md`, `UAT.md`, and `STATE.md` artifacts and distills them into a structured `LEARNINGS.md` covering decisions made, lessons learned, patterns discovered, and surprises encountered. These learnings feed back into future discuss and plan sessions. **Produces** `{phase_num}-LEARNINGS.md` — structured learning capture for decisions, lessons, patterns, and surprises. **Flags** Extract learnings from all completed phases in the current milestone in one pass rather than targeting a single phase. *** ## `/gsd-ingest-docs` Bootstrap `.planning/` from existing ADRs, PRDs, SPECs, and docs. **Syntax** ```bash theme={null} /gsd-ingest-docs /gsd-ingest-docs docs/adr/ --mode new /gsd-ingest-docs --mode merge --manifest docs/ingest.yaml ``` **What it does** Builds the full `.planning/` setup — or merges into an existing one — from multiple pre-existing planning documents in a single pass. Discovers files by directory convention (`docs/adr/`, `docs/prd/`, `docs/specs/`, `docs/rfc/`) or via an explicit `--manifest` YAML file. Auto-synthesizes most conflicts using the precedence rule `ADR > SPEC > PRD > DOC`, surfaces unresolved conflicts in `INGEST-CONFLICTS.md`, and blocks destination writes when unresolved contradictions exist. Hard cap of 50 documents per invocation. **Produces** In `--mode new`: `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`.\ In `--mode merge`: appended phases and requirements derived from the ingested docs.\ When conflicts exist: `.planning/INGEST-CONFLICTS.md` with three buckets — auto-resolved, competing-variants, unresolved-blockers. **Flags** Ingestion mode. Accepted values: * `new` — bootstrap `.planning/` from scratch (default when `.planning/` is absent) * `merge` — append to an existing `.planning/` setup (default when `.planning/` is present) Path to a YAML file listing `{path, type, precedence?}` per document. Use when directory-convention discovery is insufficient or you need custom precedence overrides. *** ## `/gsd-docs-update` Generate or update project documentation verified against the codebase. **Syntax** ```bash theme={null} /gsd-docs-update /gsd-docs-update --force /gsd-docs-update --verify-only ``` **What it does** Generates and updates up to nine documentation files for the project. Each doc type is written by a `gsd-doc-writer` subagent that explores the codebase directly — no hallucinated paths, phantom endpoints, or stale signatures. Existing docs with GSD markers are preserved and updated; hand-written docs are preserved by default unless `--force` is set. **Flags** Skip preservation prompts and regenerate all docs regardless of existing content or GSD markers. Overwrites hand-written and GSD-managed docs alike. Check existing docs for accuracy against the codebase without writing any files. Reports VERIFY marker count and discrepancies found. *** ## `/gsd-explore [topic]` Run a Socratic ideation session before committing to a plan. **Syntax** ```bash theme={null} /gsd-explore /gsd-explore "authentication strategy" /gsd-explore "should we use GraphQL or REST?" ``` **What it does** Opens an open-ended Socratic ideation session. Guides you through exploring an idea via probing questions, optionally spawns targeted research, and routes outputs to the appropriate GSD artifacts — notes, todos, seeds, research questions, requirements, or new phases. Use this when you want to think through an idea before formalizing it into a phase. *** ## `/gsd-spike [idea]` Run 2–5 focused feasibility experiments to validate an idea. **Syntax** ```bash theme={null} /gsd-spike "WebSocket real-time sync" /gsd-spike "Stripe subscription billing" --quick /gsd-spike --wrap-up /gsd-spike frontier ``` **What it does** Spikes an idea through experiential exploration — builds focused experiments to validate feasibility and produce verified knowledge for the real build. Each spike produces 2–5 experiments stored in `.planning/spikes/`. In frontier mode (no argument, or `frontier` as the argument) it analyzes your existing spike landscape and proposes integration and frontier spikes instead of building new ones. Does not require prior `/gsd-new-project` setup. **Produces** Experiment files in `.planning/spikes/` plus a `MANIFEST.md` tracking all spikes. With `--wrap-up`: a persistent project skill file capturing the spike findings. **Flags** Skip decomposition and alignment questioning and jump straight to building. Use when you already know exactly what to spike. Use plain-text numbered lists instead of interactive menus. Required for non-Claude runtimes. Package spike findings into a persistent project skill for use in future build conversations. Runs the `spike-wrap-up` workflow. *** ## `/gsd-sketch [idea]` Generate throwaway HTML mockups to explore UI directions. **Syntax** ```bash theme={null} /gsd-sketch "dashboard layout" /gsd-sketch "onboarding flow" --quick /gsd-sketch --wrap-up /gsd-sketch frontier ``` **What it does** Explores design directions through throwaway HTML mockups before committing to implementation. Produces 2–3 variants per sketch for comparison. Mockups are stored in `.planning/sketches/`. Loads any existing spike findings to ground mockups in real data shapes and validated interaction patterns. In frontier mode it analyzes existing sketches and proposes consistency fixes and new frontier sketches. Does not require prior project setup. **Produces** Variant HTML files in `.planning/sketches/` plus a `MANIFEST.md`. With `--wrap-up`: a persistent project skill capturing the design findings. **Flags** Skip mood and direction intake and jump straight to decomposition and building. Use when the design direction is already clear. Use plain-text numbered lists instead of interactive menus. Required for non-Claude runtimes. Package sketch design findings into a persistent project skill for use in future build conversations. Runs the `sketch-wrap-up` workflow. # GSD Core Management Commands: Config and Workspaces Source: https://docs.opengsd.net/core/commands/manage-commands Reference for GSD Core management commands — configuration, skill surfaces, updates, workspaces, workstreams, idea capture, threads, and utility tasks. The management commands handle everything outside the project lifecycle itself: configuring GSD's behavior, managing parallel workspaces and workstreams, capturing lightweight tasks and ideas, and performing safe housekeeping operations like undo and cleanup. Most of these commands work at the tool or workspace level rather than the phase level. *** ## `/gsd-settings` Interactive six-section configuration wizard. **Syntax** ```bash theme={null} /gsd-settings ``` **What it does** Opens an interactive multi-section configuration wizard that walks you through GSD settings across six areas: Planning, Execution, Docs & Output, Features, Model & Pipeline, and Misc. Reads the current `config.json`, presents your existing values, merges your answers, and writes the updated config with a confirmation display and quick command references. Use `/gsd-config` for advanced knobs and integration settings. *** ## `/gsd-config` Configure GSD settings — common toggles, advanced knobs, integrations, and model profiles. **Syntax** ```bash theme={null} /gsd-config /gsd-config --advanced /gsd-config --integrations /gsd-config --profile quality ``` **What it does** Consolidated configuration command with mode routing. Without a flag it runs the same interactive multi-section configuration wizard as `/gsd-settings`. With `--advanced` it exposes power-user knobs across planning, execution, discussion, cross-AI, git, and runtime settings. With `--integrations` it manages third-party API keys, code-review CLI routing, and agent-skill injection. With `--profile` it switches your model profile without any interactive prompts. **Flags** Open the advanced settings wizard covering planning granularity, timeouts, branch templates, cross-AI execution configuration, and runtime tuning. Open the integrations settings wizard covering API keys (Brave, Firecrawl, Exa), review CLI routing, and agent-skill injection configuration. Switch the active model profile without interactive prompts. Accepted values: `quality`, `balanced`, `budget`, `inherit`. *** ## `/gsd-surface` Toggle which skill commands are surfaced without reinstalling GSD. **Syntax** ```bash theme={null} /gsd-surface list /gsd-surface status /gsd-surface profile standard /gsd-surface disable utility /gsd-surface enable audit_review /gsd-surface reset ``` **What it does** Manages the runtime skill surface by reading and writing `~/.claude/.gsd-surface.json` and re-staging the active skills directory in place. Use this to reduce context token usage from skill definitions by disabling clusters you don't need, or to switch between surface profiles. **Valid cluster names:** `core_loop`, `audit_review`, `milestone`, `research_ideate`, `workspace_state`, `docs`, `ui`, `ai_eval`, `ns_meta`, `utility` **Subcommands** Show all enabled and disabled clusters and skills with their approximate token cost. Alias for `list`, plus a summary of the base profile and install-time profile. Switch the base surface profile. Accepted values: `core`, `standard`, `full`. Comma-separate profile names to compose multiple profiles (no spaces), e.g., `profile core,audit_review`. Add a cluster to the disabled list and immediately remove its skills from the active surface. Remove a cluster from the disabled list and restore its skills to the active surface. Delete `.gsd-surface.json` and return to the install-time profile defaults. *** ## `/gsd-update` Update GSD to the latest version with changelog display. **Syntax** ```bash theme={null} /gsd-update /gsd-update --sync /gsd-update --reapply /gsd-update --next ``` **What it does** Checks for a new version of GSD, fetches and displays the changelog, prompts for confirmation, then runs the update, clears caches, and reminds you to restart. Handles both local and global installations. Without a flag it targets `@latest`. **Flags** Sync managed GSD skills across all runtime roots. Use after an update if you work across multiple runtimes and want to keep skill definitions aligned. Supports `--from`, `--to`, `--dry-run`, and `--apply` sub-flags. Reapply local modifications after a GSD update. Performs a three-way merge between the pristine baseline, your user-modified backup, and the newly installed version to recover your customizations. Target the `@next` release-candidate dist-tag instead of `@latest`. Use to install or refresh a release candidate (e.g., `1.4.0-rc.1`). Also accepted as `--rc`. *** ## `/gsd-workspace` Manage isolated GSD workspace environments. **Syntax** ```bash theme={null} /gsd-workspace --new /gsd-workspace --new --name feature-x --repos myrepo --strategy worktree /gsd-workspace --list /gsd-workspace --remove feature-x ``` **What it does** Creates, lists, and removes isolated workspace environments — each with independent `.planning/` directories and repo copies. Workspaces use either a git worktree strategy (faster, shares object store) or a full clone strategy (fully isolated, higher disk usage). **Flags** Create a new isolated workspace. Combine with `--name`, `--repos`, and `--strategy` to configure it. List all active GSD workspaces in `~/gsd-workspaces/` with their status and current phase. Remove a named workspace and clean up any associated worktrees. Pass the workspace name as the next argument. Name for the new workspace. Used with `--new`. Comma-separated list of repositories to include in the workspace. Used with `--new`. Isolation strategy for the new workspace. Accepted values: * `worktree` — git worktree (faster, shares object store) * `clone` — full clone (fully isolated, higher disk usage) *** ## `/gsd-workstreams` Manage parallel workstreams for concurrent milestone work. **Syntax** ```bash theme={null} /gsd-workstreams list /gsd-workstreams create payments /gsd-workstreams status payments /gsd-workstreams switch payments /gsd-workstreams progress /gsd-workstreams complete payments /gsd-workstreams resume payments ``` **What it does** Manages parallel workstreams that let multiple milestone tracks run concurrently. Each workstream is an isolated context with its own phase state. Switching workstreams sets the active context for subsequent GSD commands. Completing a workstream archives it to `milestones/`. Defaults to `list` when no subcommand is provided. **Subcommands** List all workstreams with name, status, current phase, and progress. Create a new workstream. After creation, run `/gsd-new-milestone --ws [name]` to set up its milestone. Show detailed phase breakdown and state information for the named workstream. Set the named workstream as active for the current session. Show a progress summary across all workstreams. Archive the named workstream to `milestones/`. Set the named workstream as active and prompt you to run `/gsd-resume-work --ws [name]`. *** ## `/gsd-capture` Capture ideas, tasks, notes, and seeds to their destination. **Syntax** ```bash theme={null} /gsd-capture "refactor the auth module to use JWTs" /gsd-capture --note "talked to design team — they want rounded corners" /gsd-capture --backlog "add dark mode support" /gsd-capture --seed "migrate to Rust when team grows" /gsd-capture --list ``` **What it does** Routes a captured item to the right destination in the GSD system based on the flag you use. Without a flag it creates a structured todo. With `--note` it appends a timestamped note. With `--backlog` it adds to the ROADMAP.md backlog section with 999.x numbering. With `--seed` it plants a forward-looking idea with trigger conditions in `.planning/seeds/`. **Flags** Create a structured todo in `.planning/todos/`. Zero-friction idea capture. Appends a timestamped note, lists existing notes, or promotes a note to a todo or phase. Add an idea to the ROADMAP.md backlog parking lot with 999.x phase numbering. Capture a forward-looking idea with trigger conditions as `.planning/seeds/SEED-NNN-slug.md`. Open an interactive todo browser and action router for pending todos. *** ## `/gsd-thread` Manage persistent context threads for cross-session work. **Syntax** ```bash theme={null} /gsd-thread "investigating the N+1 query in orders" /gsd-thread list /gsd-thread list --open /gsd-thread list --resolved /gsd-thread status auth-refactor /gsd-thread close auth-refactor /gsd-thread resume auth-refactor ``` **What it does** Creates, lists, closes, and resumes persistent context threads — lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase. Threads keep a named context alive so you can return to it without losing track of where you left off. **Subcommands** List all threads. Add `--open` to show only open threads, or `--resolved` to show only closed ones. Show the current status and context summary for a thread identified by its slug. Mark a thread as resolved. Resume a thread by restoring its context into the current session. *** ## `/gsd-quick` Execute an ad-hoc task with GSD guarantees but skip optional agents. **Syntax** ```bash theme={null} /gsd-quick "add rate limiting to the upload endpoint" /gsd-quick "fix flaky test in auth suite" --validate /gsd-quick "update CORS headers" --discuss /gsd-quick "investigate caching options" --research /gsd-quick "add pagination to the orders API" --full /gsd-quick list /gsd-quick status upload-rate-limit /gsd-quick resume upload-rate-limit ``` **What it does** Executes small, ad-hoc tasks with GSD guarantees — atomic commits, `STATE.md` tracking — using a shorter pipeline than full phase execution. Quick tasks live in `.planning/quick/` and update the "Quick Tasks Completed" table in `STATE.md`, not `ROADMAP.md`. By default, research, discussion, plan-checking, and verification agents are all skipped. **Flags** Enable the complete quality pipeline: discussion + research + plan-checking + post-execution verification. One flag for everything. Enable plan-checking (max 2 iterations) and post-execution verification only, without discussion or research. Run a lightweight discussion phase before planning to surface assumptions and clarify gray areas. Spawn a focused research agent before planning to investigate implementation approaches, library options, and pitfalls. **Subcommands** List all quick tasks with slug, date, and status (complete, in-progress, or abandoned). Show the status, plan description, and last action for a specific quick task by slug. Resume a specific in-progress quick task by slug, restoring plan context and continuing execution. *** ## `/gsd-fast [task]` Execute a trivial inline task with no planning overhead. **Syntax** ```bash theme={null} /gsd-fast "fix typo in README" /gsd-fast "bump version to 1.2.1 in package.json" /gsd-fast "add missing semicolons in config.ts" ``` **What it does** Executes a trivial task directly in the current context without spawning subagents or generating any plan files. Designed for tasks you can describe in one sentence and execute in under two minutes — typo fixes, config tweaks, small refactors, forgotten commits, simple additions. Use `/gsd-quick` for anything that needs research, multi-step planning, or verification. *** ## `/gsd-undo` Safe git revert for phase and plan commits. **Syntax** ```bash theme={null} /gsd-undo --last 5 /gsd-undo --phase 03 /gsd-undo --plan 03-02 ``` **What it does** Rolls back GSD phase or plan commits safely using the phase manifest, with dependency checks and a mandatory confirmation gate before execution. Shows you exactly what will be reverted and warns about downstream phases that depend on the work you're about to undo. **Flags** Show the most recent `N` GSD commits for interactive selection. You choose which to revert from the list. Revert all commits for phase `NN`. Uses the phase manifest first, then falls back to git log pattern matching. Revert all commits for a specific plan identified by phase number and plan number (e.g., `03-02` for phase 3, plan 2). *** ## `/gsd-cleanup` Archive phase directories and prune stale branches. **Syntax** ```bash theme={null} /gsd-cleanup ``` **What it does** Archives phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`. Use this when `.planning/phases/` has accumulated directories from past milestones and you want to keep the working directory clean. Always shows you a dry-run summary of what will be moved and waits for confirmation before archiving. *** ## `/gsd-help` Show available GSD commands and usage guidance. **Syntax** ```bash theme={null} /gsd-help /gsd-help --brief /gsd-help --full /gsd-help workflow /gsd-help --brief ship ``` **What it does** Displays GSD reference content at the tier you request. Output is strictly reference material — no project-specific analysis, git status, file context, or next-step suggestions are included. **Flags** One-page tour of all GSD commands with short descriptions and common usage patterns. Single-line refresher per command. Fastest lookup when you just need a syntax reminder. Complete reference output covering every command, every flag, and all usage notes. Display the reference section for a single topic, e.g., `/gsd-help workflow` or `/gsd-help ship`. Signature plus a one-line summary for a single topic. Compact scoped lookup — e.g., `/gsd-help --brief plan-phase`. # GSD Core Project Commands: Milestones and Lifecycle Source: https://docs.opengsd.net/core/commands/project-commands Reference for GSD Core project lifecycle commands — milestones, phase management, session handoffs, health checks, and statistics. The project commands manage everything above the individual phase: milestone boundaries, phase-list edits, session handoffs, and overall project health. Use them to start and complete version cycles, restructure your roadmap, save and restore work across sessions, and audit the integrity of your `.planning/` directory. *** ## `/gsd-new-milestone [name]` Start a new version cycle for an existing project. **Syntax** ```bash theme={null} /gsd-new-milestone /gsd-new-milestone "v1.1 Notifications" /gsd-new-milestone "v2.0 Payments" --reset-phase-numbers ``` **What it does** The brownfield equivalent of `/gsd-new-project`. Your project already exists and `PROJECT.md` has its history. This command gathers what's next, updates `PROJECT.md` with the new milestone goals, then runs a full requirements → roadmap cycle. Phase numbering continues from where the previous milestone left off unless you reset it. **Produces** | Artifact | Purpose | | --------------------------- | ------------------------------------------- | | `.planning/PROJECT.md` | Updated with new milestone goals | | `.planning/REQUIREMENTS.md` | Scoped requirements for this milestone | | `.planning/ROADMAP.md` | Phase structure (continuing numbering) | | `.planning/STATE.md` | Reset for the new milestone | | `.planning/research/` | Domain research for new features (optional) | **Flags** Restart phase numbering from 1 for the new milestone instead of continuing from the last milestone's final phase number. **Next step:** Run `/gsd-plan-phase [N]` to begin the first phase of the new milestone. *** ## `/gsd-milestone-summary [version]` Generate a comprehensive milestone report for team onboarding and review. **Syntax** ```bash theme={null} /gsd-milestone-summary /gsd-milestone-summary v1.0 ``` **What it does** Reads completed milestone artifacts — `ROADMAP.md`, `REQUIREMENTS.md`, `CONTEXT.md`, `SUMMARY.md`, `VERIFICATION.md`, `RESEARCH.md`, and `RETROSPECTIVE.md` files — and produces a structured seven-section human-friendly overview of what was built, how, and why. After generation, offers an interactive Q\&A session so new team members can explore the context further. Omit the version to default to the current or latest milestone. **Produces** `.planning/reports/MILESTONE_SUMMARY-v{version}.md` covering: Overview, Architecture, Phases, Key Decisions, Requirements, Tech Debt, and Getting Started. *** ## `/gsd-complete-milestone` Archive a completed milestone and prepare for the next version. **Syntax** ```bash theme={null} /gsd-complete-milestone ``` **What it does** Marks the current milestone complete by verifying all phases have `SUMMARY.md` files, gathering stats (phase count, plan count, git range, LOC, timeline), archiving the roadmap and requirements to `.planning/milestones/`, collapsing `ROADMAP.md` to a single summary line, updating `PROJECT.md` with the shipped version, and tagging the release in git. Checks for a passing audit before proceeding — if no audit exists it recommends running `/gsd-audit-milestone` first. **Produces** | Artifact | Purpose | | --------------------------------------------- | -------------------------------------------- | | `.planning/milestones/v{ver}-ROADMAP.md` | Archived roadmap for this milestone | | `.planning/milestones/v{ver}-REQUIREMENTS.md` | Archived requirements with completion status | | `git tag v{ver}` | Version tag (if `git.create_tag` is enabled) | *** ## `/gsd-audit-milestone` Verify a milestone met its definition of done before archiving. **Syntax** ```bash theme={null} /gsd-audit-milestone /gsd-audit-milestone v1.2 ``` **What it does** Aggregates `VERIFICATION.md` files from all completed phases, checks requirements coverage, identifies tech debt and deferred gaps, then spawns an integration checker to verify cross-phase wiring. Produces a structured audit report with a `passed` or `gaps_found` status. Run this before `/gsd-complete-milestone`. Omit the version to audit the current milestone. **Produces** `.planning/v{version}-MILESTONE-AUDIT.md` — coverage report with status verdict, gap list, and recommended remediation steps. *** ## `/gsd-phase` CRUD operations for phases in `ROADMAP.md`. **Syntax** ```bash theme={null} /gsd-phase "Add payment provider integration" /gsd-phase --insert 3 "Urgent security patch" /gsd-phase --remove 7 /gsd-phase --edit 4 /gsd-phase --edit 4 --force ``` **What it does** Manages your phase list with a single consolidated command. Without a flag it adds a new integer phase to the end of the current milestone. With `--insert` it creates a decimal phase (e.g., `3.1`) between existing phases for urgent work. With `--remove` it deletes a future phase and renumbers subsequent phases. With `--edit` it updates fields of an existing phase in place. **Flags** Insert an urgent work phase as a decimal (e.g., `3.1`) immediately after phase `N`. Pass the description as the remaining argument. Remove future phase `N` and renumber all subsequent phases to keep the sequence clean. Edit any field of existing phase `N` in place — name, goal, complexity, or mode. Skip the confirmation gate when editing. Use with `--edit` only. *** ## `/gsd-mvp-phase N` Guide MVP vertical-slice planning for an existing phase. **Syntax** ```bash theme={null} /gsd-mvp-phase 2 /gsd-mvp-phase 2.1 ``` **What it does** Prompts you for a structured "As a / I want to / So that" user story, runs a SPIDR splitting check to catch stories that are too large for a single phase, rewrites the phase goal in `ROADMAP.md` with `**Mode:** mvp`, then delegates to `/gsd-plan-phase` which auto-detects MVP mode. The phase must already exist in `ROADMAP.md` — this command converts an existing phase, it does not create new ones. *** ## `/gsd-resume-work` Restore full context from your last session and resume where you left off. **Syntax** ```bash theme={null} /gsd-resume-work ``` **What it does** Loads `STATE.md` (or reconstructs it if missing), detects any `.continue-here` checkpoint files left by `/gsd-pause-work`, finds incomplete plans that have no corresponding `SUMMARY.md`, presents your current status, and routes you to the most appropriate next action. *** ## `/gsd-pause-work` Save a complete context handoff before ending a session. **Syntax** ```bash theme={null} /gsd-pause-work /gsd-pause-work --report ``` **What it does** Creates a `.continue-here.md` handoff file that captures your exact position in the phase, all work completed so far, remaining tasks, key decisions made, and any active blockers. Commits the file as a WIP commit and prints resume instructions for your next session. **Flags** Generate a session report (`SESSION_REPORT.md`) summarizing what was accomplished this session, in addition to creating the standard handoff file. *** ## `/gsd-manager` Interactive multi-phase command center for power users. **Syntax** ```bash theme={null} /gsd-manager /gsd-manager --analyze-deps ``` **What it does** Opens a single-terminal dashboard showing all phases with visual status indicators, recommends the optimal next action for each, and dispatches work — discuss runs inline while plan and execute run as background agents. Designed for parallelizing work across phases: you can discuss one phase while another is planning or executing in the background. Exit when you finish managing or when all phases complete and the milestone lifecycle triggers. **Flags** Run a dependency analysis across all phases before opening the dashboard. Shows which phases block others and recommends an optimal execution order. *** ## `/gsd-health` Validate `.planning/` directory integrity and diagnose issues. **Syntax** ```bash theme={null} /gsd-health /gsd-health --repair /gsd-health --context ``` **What it does** Scans your `.planning/` directory for missing required files, invalid `config.json` values, inconsistent state, and orphaned plan files. Reports every issue with an actionable fix suggestion. With `--repair` it automatically resolves any issues it can fix safely. **Flags** Automatically repair any issues that can be safely fixed — missing directories, malformed state entries, and orphaned artifacts. Check the current session's context utilization instead of the `.planning/` directory. Reports one of three states: healthy (under 60%), warning (60–70%, recommend starting a new thread with `/gsd-thread`), or critical (70%+, reasoning quality may degrade). *** ## `/gsd-stats` Display a project statistics dashboard. **Syntax** ```bash theme={null} /gsd-stats ``` **What it does** Reads your `.planning/` directory and git history to display comprehensive project metrics: phase progress, plan execution counts, requirements completion percentage, git commit stats, file change counts, lines of code, and project timeline. No arguments or flags needed — run it any time you want a snapshot of where the project stands. # GSD Core Quality Commands: Review, Debug, and Security Source: https://docs.opengsd.net/core/commands/quality-commands Reference for GSD Core quality and debugging commands — code review, testing, security, UI audits, debugging sessions, and cross-AI peer review. The quality commands give you structured tools for reviewing, hardening, and debugging your work. They operate independently of the main phase pipeline so you can run them at any point — immediately after execution, as a retroactive audit, or in response to a reported bug. Each command targets a distinct quality concern: code correctness, test coverage, security posture, visual design, or debugging a live issue. *** ## `/gsd-code-review N` Review phase changes for bugs, security issues, and code quality problems. **Syntax** ```bash theme={null} /gsd-code-review 3 /gsd-code-review 3 --depth=deep /gsd-code-review 3 --fix /gsd-code-review 3 --fix --auto /gsd-code-review 3 --files src/auth.ts,src/session.ts ``` **What it does** Spawns a `gsd-code-reviewer` agent to analyze source files changed during the specified phase. Produces a `REVIEW.md` artifact in the phase directory with severity-classified findings. With `--fix`, spawns a `gsd-code-fixer` agent to apply the found issues. All three depth levels use the phase's `SUMMARY.md` and git diff to scope the file set. **Produces** `{padded_phase}-REVIEW.md` — findings classified as Critical, Warning, or Info, with file references and remediation suggestions. **Flags** Review depth. Accepted values: * `quick` — Pattern-matching only (\~2 min) * `standard` — Per-file analysis with language-specific checks (\~5–15 min, default) * `deep` — Cross-file analysis including import graphs and call chains (\~15–30 min) Comma-separated explicit file list. Bypasses `SUMMARY.md` extraction and git diff scoping entirely. Highest precedence for file selection. Example: `--files src/api.ts,src/middleware.ts`. After review completes (or if `REVIEW.md` already exists), auto-apply fixes. Spawns a `gsd-code-fixer` agent. Combines with the sub-flags below. Expand the fix scope to include Info-level findings in addition to the default Critical + Warning. Enable a fix → re-review iteration loop, capped at 3 cycles, until no Critical or Warning findings remain. *** ## `/gsd-audit-fix` Autonomous audit-to-fix pipeline: find issues, classify, fix, test, commit. **Syntax** ```bash theme={null} /gsd-audit-fix --source audit-uat /gsd-audit-fix --source audit-uat --severity high /gsd-audit-fix --source audit-uat --max 10 /gsd-audit-fix --source audit-uat --dry-run ``` **What it does** Runs a specified audit, classifies each finding as auto-fixable or manual-only, then autonomously fixes the auto-fixable subset with test verification and atomic commits per fix. Use this when you have a set of audit findings you want resolved without manual intervention for each one. **Flags** Which audit to run. Default: `audit-uat`. Pass the audit type name as the value. Minimum severity to process. Accepted values: `high`, `medium`, `all`. Default: `medium`. Maximum number of findings to fix in a single run. Default: `5`. Classify findings and show the classification table — auto-fixable vs manual-only — without applying any fixes. *** ## `/gsd-add-tests N` Generate unit and end-to-end tests for a completed phase. **Syntax** ```bash theme={null} /gsd-add-tests 4 /gsd-add-tests 4 focus on edge cases in the pricing module ``` **What it does** Analyzes the implementation files from the specified phase using its `SUMMARY.md`, `CONTEXT.md`, and `VERIFICATION.md` as specifications. Classifies each file as TDD (unit tests), E2E (browser tests), or Skip, presents the test plan for your approval, then generates tests following RED-GREEN conventions. Any additional instructions you include after the phase number are passed through to the test generator. **Produces** Test files committed with message `test(phase-{N}): add unit and E2E tests from add-tests command`. *** ## `/gsd-secure-phase N` Retroactively verify threat mitigations for a completed phase. **Syntax** ```bash theme={null} /gsd-secure-phase 3 /gsd-secure-phase ``` **What it does** Audits threat mitigations for a completed phase in one of three modes: if a `SECURITY.md` already exists it audits and verifies the mitigations; if only a `PLAN.md` with a threat model exists it runs the analysis from those artifacts; if the phase was never executed it exits with guidance. Omit the phase number to default to the last completed phase. **Produces** Updated `{phase_num}-SECURITY.md` — threat list with mitigation status and any remaining gaps. *** ## `/gsd-ui-review N` Six-pillar visual frontend audit of implemented code. **Syntax** ```bash theme={null} /gsd-ui-review 5 /gsd-ui-review ``` **What it does** Conducts a retroactive six-pillar visual audit of the frontend code implemented in the specified phase. Each pillar is graded 1–4. Works on any project regardless of framework. Omit the phase number to default to the last completed phase. **Produces** `{phase_num}-UI-REVIEW.md` — graded assessment across the six pillars with specific improvement recommendations per finding. *** ## `/gsd-validate-phase N` Retroactive Nyquist test coverage audit for a completed phase. **Syntax** ```bash theme={null} /gsd-validate-phase 2 /gsd-validate-phase ``` **What it does** Audits Nyquist validation coverage for a completed phase. If a `VALIDATION.md` already exists it audits and fills any gaps. If no `VALIDATION.md` exists but a `SUMMARY.md` does it reconstructs the validation state from available artifacts. Omit the phase number to default to the last completed phase. **Produces** Updated `VALIDATION.md` and generated test files covering any previously unvalidated paths. *** ## `/gsd-debug [description]` Systematic debugging with persistent state across context resets. **Syntax** ```bash theme={null} /gsd-debug "login fails with 401 after token refresh" /gsd-debug --diagnose "memory leak in the image processor" /gsd-debug list /gsd-debug status auth-401-fix /gsd-debug continue auth-401-fix ``` **What it does** Applies the scientific method to debugging. The orchestrator gathers symptoms, spawns a `gsd-debugger` agent for isolated investigation, handles checkpoints to persist state across context resets, and spawns continuation agents when needed. Subcommands let you list active sessions, check the status of a specific session by slug, or continue an interrupted session. **Flags** Diagnose only. Returns a Root Cause Report with findings but does not apply a fix. **Subcommands** List all active (unresolved) debug sessions. Show the current status of a specific debug session identified by its slug. Resume an interrupted debug session by slug, restoring all prior investigation context. *** ## `/gsd-forensics [description]` Post-mortem investigation for failed or stuck GSD workflows. **Syntax** ```bash theme={null} /gsd-forensics "plan-phase got stuck on phase 4" /gsd-forensics ``` **What it does** Investigates what went wrong during a GSD workflow execution. Reads git history, `.planning/` artifacts, and filesystem state to detect anomalies — stuck loops, missing artifacts, abandoned work, crash/interruption patterns — and generates a structured forensic report. Read-only investigation only: it never modifies your project source files. Omit the description to be prompted interactively. **Produces** `.planning/forensics/report-{timestamp}.md` — evidence-based findings, anomaly list, root cause analysis, and recommended corrective actions. *** ## `/gsd-eval-review N` Audit AI phase evaluation coverage. **Syntax** ```bash theme={null} /gsd-eval-review 6 /gsd-eval-review ``` **What it does** Conducts a retroactive evaluation coverage audit of a completed AI phase. Checks whether the evaluation strategy defined in `AI-SPEC.md` was actually implemented in the phase's output. Produces a scored verdict with a list of gaps and a remediation plan. Omit the phase number to default to the last completed phase. **Produces** `{phase_num}-EVAL-REVIEW.md` — coverage score, verdict (pass/fail), gap list, and remediation steps. *** ## `/gsd-review --phase N` Cross-AI peer review of phase plans from external AI CLIs. **Syntax** ```bash theme={null} /gsd-review --phase 3 /gsd-review --phase 3 --gemini --codex /gsd-review --phase 3 --all ``` **What it does** Invokes one or more external AI CLIs to independently review the plan files for the specified phase. Collects all responses and writes a structured `REVIEWS.md` that you can feed back into planning via `/gsd-plan-phase --reviews`. Detects which CLIs are installed and available before dispatching. **Produces** `{phase_num}-REVIEWS.md` — per-reviewer feedback with severity classification (HIGH / MEDIUM / LOW) for each concern. **Flags** The phase whose plans you want reviewed. Include Gemini CLI as a reviewer. Include a separate Claude CLI session as a reviewer. Include Codex CLI as a reviewer. Include OpenCode as a reviewer (uses the model from your OpenCode config). Include Qwen Code (Alibaba Qwen models) as a reviewer. Include Cursor agent as a reviewer. Include Antigravity CLI as a reviewer. Also accepted as `--antigravity`. Include CodeRabbit as a reviewer. Include a local Ollama server as a reviewer. Include a local LM Studio server as a reviewer. Include a local llama.cpp server as a reviewer. Include every available CLI and running local model server as reviewers. # GSD Core Workflow Commands: Phase Pipeline Reference Source: https://docs.opengsd.net/core/commands/workflow-commands Reference for every phase-pipeline command in GSD Core — from project initialization through discussion, planning, execution, verification, and shipping. The workflow commands form the backbone of GSD Core's phase pipeline. Each command maps to one discrete step in the loop: initialize → discuss → plan → execute → verify → ship. Run them in order for a new project, or invoke any individual command when you need to repeat or adjust a specific step. All commands read from and write to the `.planning/` directory at your project root. *** ## `/gsd-new-project` Initialize a new project with deep context gathering. **Syntax** ```bash theme={null} /gsd-new-project /gsd-new-project --auto @brief.md ``` **What it does** Walks you through a structured questioning flow, optionally runs domain research, then generates requirements and a phase roadmap. All subsequent workflow commands build on the artifacts this command produces. **Produces** | Artifact | Purpose | | --------------------------- | ------------------------------------ | | `.planning/PROJECT.md` | Project context and goals | | `.planning/config.json` | Workflow preferences | | `.planning/REQUIREMENTS.md` | Scoped requirements | | `.planning/ROADMAP.md` | Phase structure | | `.planning/STATE.md` | Project memory | | `.planning/research/` | Domain research (when research runs) | **Flags** Automatic mode. Skips interactive questioning and runs research → requirements → roadmap without further interaction. Pass your idea document via an `@` reference, for example `--auto @brief.md`. **Next step:** Run `/gsd-plan-phase 1` to begin the first phase. *** ## `/gsd-discuss-phase N` Gather phase context through adaptive questioning before planning. **Syntax** ```bash theme={null} /gsd-discuss-phase 2 /gsd-discuss-phase 3 --auto /gsd-discuss-phase 4 --power /gsd-discuss-phase 5 --assumptions ``` **What it does** Loads prior context from `PROJECT.md`, `REQUIREMENTS.md`, `STATE.md`, and any earlier `CONTEXT.md` files. Scouts the codebase for reusable assets, identifies unresolved gray areas, guides you through a deep-dive on any you choose to discuss, and writes a `CONTEXT.md` that gives the planner and researcher everything they need — so they never have to ask you the same question twice. **Produces** `{phase_num}-CONTEXT.md` — locked decisions and scope guidance for downstream agents. **Flags** Discuss all identified gray areas in one session rather than letting you pick a subset. Auto-answer discussion questions using existing context. Useful in autonomous or CI pipelines where interactive input is not available. Group related gray areas and address them together instead of one at a time. Run a deeper analysis pass on the codebase before presenting gray areas. Power mode. Runs an extended questioning protocol with richer probing — best for complex or ambiguous phases. List the assumptions implicit in the current phase plan instead of opening a discussion session. *** ## `/gsd-ui-phase N` Generate a UI design contract for frontend phases. **Syntax** ```bash theme={null} /gsd-ui-phase 3 ``` **What it does** Orchestrates a `gsd-ui-researcher` and a `gsd-ui-checker` to produce a `UI-SPEC.md` design contract for a frontend phase. Run this before `/gsd-plan-phase` on any phase that involves user-facing components so the planner has a verified UI specification to work from. **Produces** `{phase_num}-UI-SPEC.md` — design contract covering component structure, interaction patterns, and brand alignment. *** ## `/gsd-plan-phase N` Research, plan, and verify a phase — the core planning step. **Syntax** ```bash theme={null} /gsd-plan-phase 1 /gsd-plan-phase 2 --skip-research /gsd-plan-phase 3 --research /gsd-plan-phase 4 --mvp --tdd /gsd-plan-phase --research-phase 2 ``` **What it does** Runs the full planning pipeline: optional domain research → `gsd-planner` agent → `gsd-plan-checker` verification loop → plan approval. By default it auto-detects the next unplanned phase if you omit the phase number. **Produces** `{phase_num}-PLAN.md` files containing executable prompts for each task in the phase, plus `RESEARCH.md` when research runs. **Flags** Force-refresh research even when a `RESEARCH.md` already exists for this phase. Skip research entirely and go straight to planning. Use when the implementation approach is already clear. Research-only mode. Spawns the researcher for phase `N`, writes `RESEARCH.md`, and exits before the planner runs. Useful for cross-phase research or iterating on research alone without replanning. Gap-closure mode. Reads `VERIFICATION.md` and re-plans only to address verified gaps. Skips research. Path to a PRD or acceptance-criteria file. Parses requirements into `CONTEXT.md` automatically, skipping the discuss phase entirely. Example: `--prd docs/prd.md`. Path or glob of ADR files to use instead of a discuss session. Parses locked decisions and scope fences into `CONTEXT.md`. Example: `--ingest docs/adr/*.md`. Vertical MVP mode. Organizes tasks as feature slices (UI → API → DB) instead of horizontal layers. On Phase 1 of a new project, also emits a `SKELETON.md` walking skeleton document. Persist this mode for a phase by adding `**Mode:** mvp` to `ROADMAP.md`. TDD mode. Instructs the planner to organize tasks around test-first RED-GREEN cycles. Replan incorporating cross-AI feedback from a `REVIEWS.md` file produced by `/gsd-review`. Skip the plan-checker verification loop and present the plan immediately after the planner completes. *** ## `/gsd-plan-review-convergence N` Run a cross-AI convergence loop until no HIGH-severity concerns remain. **Syntax** ```bash theme={null} /gsd-plan-review-convergence 3 /gsd-plan-review-convergence 3 --gemini --codex /gsd-plan-review-convergence 3 --all --max-cycles 5 ``` **What it does** Repeatedly runs external AI reviewers against the phase plan, feeds HIGH-severity findings back into the planner via `--reviews`, then re-reviews. Stops when no HIGH concerns remain or the cycle cap is reached. Requires `workflow.plan_review_convergence=true` in your config. **Flags** Use Codex CLI as the reviewer. Default when no reviewer flag is specified. Use Gemini CLI as the reviewer. Use a separate Claude CLI session as the reviewer. Use OpenCode as the reviewer. Use a local Ollama server (OpenAI-compatible, default host `http://localhost:11434`). Configure the model via `review.models.ollama`. Use a local LM Studio server (default host `http://localhost:1234`). Configure the model via `review.models.lm_studio`. Use a local llama.cpp server (default host `http://localhost:8080`). Configure the model via `review.models.llama_cpp`. Use every available CLI and running local model server. Maximum number of replan → review cycles before escalating to you. Default: `3`. *** ## `/gsd-execute-phase N` Execute all plans in a phase with wave-based parallelization. **Syntax** ```bash theme={null} /gsd-execute-phase 2 /gsd-execute-phase 3 --wave 1 /gsd-execute-phase 4 --gaps-only /gsd-execute-phase 5 --interactive ``` **What it does** Discovers all plan files in the phase, analyzes task dependencies, groups them into parallel execution waves, spawns subagents for each wave, and collects results. Phase verification and completion only trigger when no incomplete plans remain after the selected wave finishes. **Flags** Execute only Wave `N` of the phase. Use to pace execution, manage API usage limits, or perform a staged rollout. Execute only gap-closure plans — those with `gap_closure: true` in their frontmatter. Run this after `/gsd-verify-work` creates fix plans. Execute plans sequentially inline (no subagents) with user checkpoints between tasks. Lower token usage, pair-programming style. Best for small phases, bug fixes, and verification gap closures. *** ## `/gsd-verify-work N` Validate built features through conversational UAT with auto-diagnosis. **Syntax** ```bash theme={null} /gsd-verify-work 3 /gsd-verify-work ``` **What it does** Runs a conversational user acceptance test against the features built in the specified phase. Presents one test at a time in plain language, tracks results in a `UAT.md` file, and when issues are found automatically diagnoses root causes, produces fix plans, and queues them for `/gsd-execute-phase`. If you omit the phase number it checks for an active session or prompts you. **Produces** `{phase_num}-UAT.md` — test results with pass/fail status. When issues are found: diagnosed gap descriptions and verified fix plans ready for re-execution. *** ## `/gsd-ship N` Create a pull request and prepare the phase for merge. **Syntax** ```bash theme={null} /gsd-ship 4 /gsd-ship 4 --draft ``` **What it does** Bridges local completion to a merged pull request. Pushes the phase branch, creates a PR with an auto-generated body summarizing what was built, optionally triggers a review, and tracks the merge. Closes the plan → execute → verify → ship loop. **Flags** Open the pull request as a draft instead of a ready-for-review PR. Use when you want the branch visible to your team but not yet requesting review. *** ## `/gsd-progress` Check where you are and what comes next. **Syntax** ```bash theme={null} /gsd-progress /gsd-progress --next /gsd-progress --next --auto /gsd-progress --next --auto --converge /gsd-progress --next --auto --converge --codex --max-cycles 4 /gsd-progress --do "add rate limiting to the API" /gsd-progress --forensic ``` **What it does** Your unified situational command. In default mode it shows a progress report and intelligently routes to the next action. With `--next` it advances automatically. With `--do` it maps natural language intent to the most appropriate GSD command, confirms the match, and hands off. `/gsd-progress --next --auto --converge` is the primary hands-free entry point for plan-review convergence: when the next action is planning, the step is routed through `/gsd-plan-review-convergence` instead of `/gsd-plan-phase`, and the converge mode is preserved across the rest of the `--auto` chain. **Flags** Automatically advance to the next logical workflow step. Scans all prior phases for incomplete work before routing. Add `--force` to bypass safety gates. Like `--next`, but after the determined step completes, re-invokes `/gsd-progress --next --auto` automatically to keep chaining steps. Enables hands-free plan → execute → verify progression until a blocking decision is required. When the next routed action is planning (Route 3), run it through the cross-AI plan-review **convergence** loop instead of `/gsd-plan-phase`. `--cross-ai` is accepted as an alias. Requires `workflow.plan_review_convergence: true` — if the flag is set while the feature gate is off, the command fails fast and prints the enable hint instead of silently falling back to standard planning. When combined with `--auto`, converge mode is forwarded into every re-invocation so the entire chain stays under the convergence policy. With `--converge`, reviewer selectors and `--max-cycles N` are forwarded to `/gsd-plan-review-convergence` unchanged: `--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`, and `--max-cycles N`. See [Cross-AI review](/core/guides/cross-ai-review) for the full reviewer matrix. Smart dispatcher. Matches freeform natural language to the best GSD command using routing rules, confirms the match, then hands off execution. Append a 6-check integrity audit after the standard progress report. `workflow.plan_review_convergence` is disabled by default. Enable it with `gsd config-set workflow.plan_review_convergence true` before using `--converge`, or the command will exit with the enable hint. *** ## `/gsd-autonomous` Run all remaining phases without manual intervention. **Syntax** ```bash theme={null} /gsd-autonomous /gsd-autonomous --from 3 /gsd-autonomous --from 2 --to 5 /gsd-autonomous --only 4 /gsd-autonomous --interactive ``` **What it does** Executes every remaining milestone phase in sequence: discuss → plan → execute per phase. Pauses only for user decisions on gray areas, blockers, or validation gates. After all phases complete, runs a milestone audit, completes the milestone, and runs cleanup. **Flags** Start from phase `N` instead of the first incomplete phase. Stop after phase `N` completes instead of continuing to the end of the milestone. Execute only phase `N` — single-phase mode. Run the discuss step inline so you can answer questions directly, then dispatch plan and execute as background agents. Keeps the main context lean while preserving your input on decisions. Use plain-text numbered lists instead of interactive TUI menus. Required for `/rc` remote sessions. # GSD Core Specialist Agents: Roles and Architecture Source: https://docs.opengsd.net/core/concepts/agents Meet GSD Core's specialist agents: researchers, planners, executors, verifiers, and auditors that spawn fresh for each task to eliminate context rot. GSD Core uses a multi-agent architecture where thin orchestrators spawn specialized agents with clean context windows. Rather than accumulating a single long conversation where quality degrades over time, each specialist agent starts fresh — with up to 200K tokens of context, or up to 1M tokens on models that support it — focused only on its assigned task, reading only the artifacts it needs. You do not invoke agents directly. Orchestrators (the workflow commands like `/gsd-plan-phase` and `/gsd-execute-phase`) spawn agents automatically at the right point in the phase loop. What you see in your session is the orchestrator's progress updates; the agents work in parallel in their own isolated context windows. ## How fresh-context subagents work When an orchestrator needs to perform heavy work — researching a domain, writing plans, implementing code — it spawns a subagent with a precisely scoped prompt. That subagent receives: * Its specific agent definition (role, tools, constraints) * The subset of planning artifacts it needs for its task * A model assignment based on the workflow profile The subagent runs to completion, writes its output to disk (a `RESEARCH.md`, a `PLAN.md`, a `SUMMARY.md`), and returns a compact result to the orchestrator. The orchestrator's context never grows with the weight of the subagent's work — only the result arrives back. This architecture is why GSD Core can run four researchers in parallel, spawn multiple executors across wave boundaries, and keep the main session lean throughout a long phase. ## Agent categories ### Researchers Researchers gather ecosystem knowledge before planning begins. They have web access (WebSearch, WebFetch) and Context7 MCP integration for library documentation. All researchers run in parallel — four instances per invocation, each covering a different dimension of the domain. Researches how to implement a specific phase. Runs four parallel instances covering stack, features, architecture, and pitfalls. Produces `RESEARCH.md` with a Package Legitimacy Audit table that removes hallucinated or suspicious packages before they reach the planner. Researches domain ecosystem before roadmap creation during `/gsd-new-project`. Produces `STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, and `PITFALLS.md` in `.planning/research/`. Produces UI design contracts for frontend phases during `/gsd-ui-phase`. Detects your design system state (shadcn, Tailwind, existing tokens) and generates `UI-SPEC.md`. Researches the business domain and real-world evaluation context for AI integration phases. Surfaces expert rubric ingredients, failure modes, and regulatory context for downstream evaluators. ### Planners and checkers Planners create execution plans from the research and context artifacts. Checkers verify plans meet quality standards before any code is written. Creates two to three atomic execution plans per phase, reading `PROJECT.md`, `REQUIREMENTS.md`, `CONTEXT.md`, and `RESEARCH.md`. Each plan contains structured `` elements with explicit acceptance criteria, dependency ordering, and requirement traceability. Runs on the Opus model tier for maximum planning quality. Creates the project roadmap during `/gsd-new-project`. Maps every v1 requirement to a phase, derives success criteria, and validates full coverage before presenting the roadmap for your approval. Verifies plans across eight dimensions before execution is permitted: requirement coverage, task atomicity, dependency ordering, file scope, verification commands, context fit, gap detection, and Nyquist compliance. Runs iteratively — up to three revision cycles — until plans pass all dimensions. Combines the outputs of four parallel project researchers into a single `SUMMARY.md` after `/gsd-new-project`. Runs sequentially after all researchers complete. ### Executors Executors implement plans. Each executor runs in a fresh context window and produces atomic git commits — one commit per completed task — so the implementation history is granular and recoverable. Implements a single `PLAN.md` file. Reads the plan, the phase `CONTEXT.md` and `RESEARCH.md`, and the project-level `PROJECT.md` and `STATE.md`. Makes one atomic git commit per completed task. Writes a `SUMMARY.md` documenting what was built and any deviations from the plan. Multiple executors run in parallel within each wave; waves are sequenced by plan dependency. The executor is the only agent with `Edit` tool access. It can modify source files. All other agents are read-only against implementation code — they analyze, plan, verify, or audit, but they do not change your code. ### Verifiers and auditors Verifiers confirm that what was built satisfies the requirements. Auditors check specific quality dimensions like security, test coverage, and UI consistency. Runs after all executors complete. Performs a goal-backward analysis: checks the codebase against phase goals, runs the test suite, and writes `VERIFICATION.md` with a PASS or FAIL verdict and specific evidence. Also audits test quality — checking for disabled tests, circular test patterns, and weak assertions. Reviews source files for bugs, security vulnerabilities, and code quality problems. Produces a structured `REVIEW.md` with severity-classified findings. Read-only — never modifies the code it reviews. Verifies that the threat mitigations declared in your `PLAN.md` threat model are actually present in the implemented code. Does not scan blindly for new vulnerabilities — it verifies declared mitigations only. Supports ASVS levels 1, 2, and 3 for verification depth. Fills test coverage gaps identified by the Nyquist validation pass. Generates test files but never modifies implementation code. Flags implementation bugs as escalations for you to address. ### Mappers Mappers explore the codebase and produce structured analysis documents for planning and context. Explores your existing codebase and writes seven structured analysis documents to `.planning/codebase/` — stack, architecture, conventions, concerns, structure, testing, and integrations. Runs four parallel instances covering different analysis dimensions. Use this before starting a new project on an existing codebase, or after a phase that significantly restructures the code. ### Debuggers and specialized agents Investigates bugs using a scientific method with persistent session state. Tracks hypotheses, evidence, and eliminated theories across context resets. State is written to `.planning/debug/` and persists until you mark the bug resolved. Appends learnings to a persistent knowledge base on resolution. Deeply analyzes the codebase for a phase in assumptions mode (`discuss_mode: assumptions`). Returns structured assumptions with evidence file paths, confidence levels (Confident, Likely, Unclear), and consequences if wrong — so the discussion starts from what the AI observed rather than from scratch. ## Agent tool permissions Each agent has access only to the tools it needs for its role. The principle of least privilege keeps agents focused and prevents unintended side effects: | Agent | Can write code | Can search web | Can edit files | | ---------------- | ---------------------- | -------------- | -------------- | | Researchers | No | Yes | No | | Planner | No (writes plans only) | No | No | | Plan-checker | No | No | No | | Executor | **Yes** | No | **Yes** | | Verifier | No | No | No | | Codebase mapper | No | No | No | | Debugger | No | Yes | **Yes** | | Security auditor | No | No | No | Checkers, mappers, and auditors are strictly read-only against implementation source. They analyze and report but never change your code. ## Agent spawn patterns The table below maps the major workflow commands to the agents they spawn and the parallelism involved: | Command | Agents spawned | Parallelism | | -------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------ | | `/gsd-new-project` | gsd-project-researcher × 4 → gsd-research-synthesizer → gsd-roadmapper | 4 parallel researchers, then sequential | | `/gsd-discuss-phase` | gsd-assumptions-analyzer (assumptions mode only) | Sequential | | `/gsd-plan-phase` | gsd-phase-researcher × 4 → gsd-research-synthesizer → gsd-planner → gsd-plan-checker | 4 parallel, then sequential (up to 3 check iterations) | | `/gsd-execute-phase` | gsd-executor × N → gsd-verifier | N parallel per wave, then sequential | | `/gsd-map-codebase` | gsd-codebase-mapper × 4 | 4 parallel | | `/gsd-debug` | gsd-debugger | Sequential, interactive | | `/gsd-code-review` | gsd-code-reviewer | Sequential | | `/gsd-secure-phase` | gsd-security-auditor | Sequential | # Context Management and Session Persistence in GSD Core Source: https://docs.opengsd.net/core/concepts/context-management Learn how GSD Core prevents context rot, monitors context usage in real time, guards against prompt injection, and maintains project state across sessions. Context management is the foundational engineering problem that GSD Core was built to solve. Most AI coding setups fail at scale not because the model is incapable, but because the context window fills up, quality degrades silently, and there is no mechanism to resume where you left off. GSD Core addresses this at three levels: architectural design, runtime monitoring, and cross-session persistence. ## What context rot is Context rot is the quality degradation that accumulates as an AI fills its context window with conversation history. The model's attention is finite — as the window fills, the signal-to-noise ratio drops, earlier content receives less attention, and the quality of reasoning and recall quietly degrades. The model does not warn you when this happens. It continues generating output, but that output is less accurate, less consistent, and more likely to contradict earlier decisions. Context rot is why an AI that produces excellent results on a fresh task produces mediocre results on the tenth task in the same session. The model has not changed — its context has degraded. ## Fresh-context subagent architecture GSD Core's primary defense against context rot is architectural: heavy work never runs in the main session. Instead, thin orchestrators spawn specialist subagents, each in its own isolated context window. When you run `/gsd-plan-phase 1`, the orchestrator does not do the planning in your current conversation. It spawns: 1. Four researcher subagents — each with a fresh context window, each focused on one research dimension 2. A synthesizer subagent — reads only the four research outputs, nothing else 3. A planner subagent — reads only `PROJECT.md`, `REQUIREMENTS.md`, `CONTEXT.md`, and `RESEARCH.md` 4. A plan-checker subagent — reads only the generated plans and the phase context None of these agents carries the weight of your conversation history. Each starts clean with up to 200K tokens of headroom — or up to 1M tokens on models like Claude Opus 4.6 and Sonnet 4.6 that support larger windows. The result (a set of approved `PLAN.md` files) arrives in your session without the accumulated cost of the work that produced it. This pattern holds throughout the phase loop: * **Execute:** Each executor subagent gets one plan and a fresh context — parallel executors run simultaneously without sharing state * **Verify:** The verifier reads all summaries and performs a goal-backward check in its own clean window * **Map codebase:** Four mapper subagents explore different dimensions of your codebase in parallel Your main session stays lean. After each major command, run `/clear` to reset the conversation context. GSD Core is designed for this — the state that matters is in `.planning/`, not in conversation memory. ## The context monitor hook Even with fresh-context subagents, some workflows run in the main session for extended periods. The context monitor hook watches your context usage in real time and injects warnings directly into the agent's conversation when usage runs high. The hook works as a pipeline between two components: ```text theme={null} Status line hook (gsd-statusline.js) │ writes context metrics ▼ /tmp/claude-ctx-{session_id}.json │ reads metrics after each tool use ▼ Context monitor hook (gsd-context-monitor.js) │ injects additionalContext warning ▼ Agent sees warning in next turn ``` The status line hook runs on every turn and writes current context metrics (tokens used, remaining percentage, timestamp) to a temporary bridge file. After each tool use, the context monitor reads the bridge file and injects a warning if usage crosses a threshold. ### Warning thresholds | Remaining context | Level | Message injected | | ----------------- | ------------ | ----------------------------------------------------------------------------------- | | > 35% | Normal | No warning | | ≤ 35% | **WARNING** | Wrap up the current task; avoid starting new complex work | | ≤ 25% | **CRITICAL** | Context nearly exhausted; save state with `/gsd-pause-work` and start a new session | The context monitor is advisory only. It injects a warning that the agent sees, but it never blocks tool execution or overrides your commands. A broken monitor exits silently — it cannot interfere with your workflow. ### Debounce behavior To avoid flooding the agent with repeated warnings, the monitor debounces after the first alert: * The first warning fires immediately when a threshold is crossed * Subsequent warnings at the same severity level require five tool uses between them * Severity escalation from WARNING to CRITICAL bypasses the debounce and fires immediately ### Status line The status line hook also renders a persistent status bar in your terminal showing the current model, active task, working directory, and a context usage bar. This gives you a human-readable view of the same context metrics the agent sees internally. ## Prompt guard and read injection scanner GSD Core generates Markdown files that become LLM system prompts. Any user-controlled text that flows into planning artifacts is a potential indirect prompt injection vector — an attacker could embed instructions in a file you ask GSD Core to read, and those instructions could execute in the agent's context. GSD Core includes two defensive hooks: ### Prompt guard (`gsd-prompt-guard.js`) The prompt guard fires on every Write or Edit call to `.planning/` files. It scans the content being written for known injection patterns: * Role override attempts (`"Ignore previous instructions"`, `"You are now..."`) * Instruction bypass patterns * System tag injections If a pattern is detected, the guard logs a warning. The guard is **advisory only** — it does not block the write. The warning surfaces for human review without interrupting the workflow. ### Read injection scanner (`gsd-read-injection-scanner.js`) The read injection scanner fires after every Read tool call. It scans the tool output for embedded instructions in untrusted content — for example, a source file or external document that contains hidden directives designed to manipulate the agent. Like the prompt guard, the scanner is advisory and never blocks the read. Together, the two hooks provide defense-in-depth against the most common prompt injection vectors. ## Cross-session persistence GSD Core maintains project state across sessions without relying on conversation memory. Two files are the backbone of session persistence: ### `STATE.md` `STATE.md` is the living memory of your project. It is updated after every significant action and contains the current position in the phase loop, active decisions and blockers, and metrics. When you start a new session, running `/gsd-progress` reads `STATE.md` and tells you exactly where you left off and what to do next. `STATE.md` is designed to be small and high-signal. It does not hold the full history of every decision — it holds the current state and the most recent decisions that are still active. Historical decisions are archived in phase artifacts. ### `continue-here.md` `continue-here.md` is a structured handoff document written by `/gsd-pause-work`. It captures the current session's momentum: * What was completed in this session * What is currently in progress * What the next concrete step is * Any open questions or blockers When you run `/gsd-resume-work` at the start of a new session, GSD Core reads `continue-here.md` alongside `STATE.md` to restore full context without re-reading the entire conversation history. The agent comes back oriented and ready to continue — not asking you to re-explain the project. ## Practical context discipline Follow these practices to keep context healthy throughout a project: GSD Core is designed for frequent context clears. After `/gsd-new-project`, after `/gsd-plan-phase`, and after `/gsd-execute-phase`, run `/clear` before the next command. All state is in `.planning/` — nothing important is lost. After any break, run `/gsd-progress` before doing anything else. It reads `STATE.md` and tells you exactly where you are and what step is next. This is faster and more accurate than re-reading the conversation history. When the context monitor injects a WARNING, finish your current task and then run `/gsd-pause-work` to save state, `/clear` to reset context, and `/gsd-resume-work` to pick up exactly where you stopped. When the context monitor injects a CRITICAL warning, stop immediately. Run `/gsd-pause-work` to write the handoff, then `/clear`. Do not start new work in a critical context — the output quality will be degraded. # GSD Core Planning Artifacts and Directory Structure Source: https://docs.opengsd.net/core/concepts/planning-artifacts Learn what every file in .planning/ contains, how per-phase artifacts are organized, and how each document feeds into the next stage of the workflow. GSD Core stores all project state in a `.planning/` directory at the root of your repository. Every artifact is plain Markdown or JSON — readable by humans, writable by agents, and committable to git for team visibility. No database, no server, no external service. When you run `/clear` or start a new session, everything the next command needs is already in these files. ## Root-level artifacts The root of `.planning/` holds the project-wide documents that every agent reads on every invocation. ### `PROJECT.md` `PROJECT.md` is the single source of truth for what your project is and what it is not. It captures your project vision, architectural constraints, non-negotiable decisions, and evolution rules — the things that must remain true across every phase and milestone. Every agent reads `PROJECT.md` first, before any phase-specific context. When you approve the roadmap at the end of `/gsd-new-project`, the decisions you made during that conversation are locked into `PROJECT.md` as binding constraints. `PROJECT.md` also includes an optional `## Business Context` section — a four-field block (Customer, Revenue model, Success metric, Strategy notes) positioned between Core Value and Requirements. Use it for monetized or customer-facing projects where business outcomes should inform requirement prioritization; delete the section entirely for internal tools, experiments, or meta workspaces. Each field is one line — a constraint reference, not a business plan — and `Strategy notes` is meant to link out to a dedicated strategy doc rather than duplicate it inline. When the section is present, `/gsd-complete-milestone` reviews it as part of its milestone evolution pass and confirms the customer, revenue model, and success metric are still accurate after shipping; when it has been deleted, the check is skipped automatically. ```markdown theme={null} ## Business Context - **Customer**: [Who pays / who uses — one line] - **Revenue model**: [How it makes money — one line] - **Success metric**: [The number that matters — one line] - **Strategy notes**: [Link to external strategy doc, if any] ``` ### `REQUIREMENTS.md` `REQUIREMENTS.md` contains scoped, numbered requirements in three tiers: * **v1** — must ship in the current milestone * **v2** — planned for a future milestone * **Out of scope** — explicitly excluded Each requirement has a stable ID (for example, `REQ-001`, `REQ-002`). The roadmapper maps every v1 requirement to a phase when it builds `ROADMAP.md`, creating a traceability chain from requirement to phase to plan to implementation to verification. The plan-checker enforces that every plan covers the requirements it claims to address. The verifier enforces that every requirement mapped to the phase is implemented before the phase advances. ### `ROADMAP.md` `ROADMAP.md` is your milestone and phase plan. It lists phases in order, records the status of each phase (planned, in progress, complete), and maps each phase to the `REQUIREMENTS.md` IDs it addresses. The roadmapper agent writes the initial `ROADMAP.md` during `/gsd-new-project`. You approve it before any phase work begins. Use `/gsd-phase` to add, remove, insert, or edit phases after the roadmap is approved. ### `STATE.md` `STATE.md` is the living memory of your project. It is updated after every significant action and contains: * Current position (which phase, which step) * Active decisions and blockers * Metrics (phases completed, requirements covered) * The last known good state for session recovery When you run `/gsd-resume-work` after a break, GSD Core reads `STATE.md` to reconstruct context. When an agent needs to know where the project stands, it reads `STATE.md`. You never need to manually update `STATE.md` — GSD Core keeps it current. ### `config.json` `config.json` is the workflow configuration file. It controls feature flags, model profiles, parallelization settings, and behavior of each workflow step. Edit it directly or use `/gsd-settings` for an interactive configuration interface. ```json theme={null} { "model_profile": "balanced", "workflow": { "discuss_mode": "interview", "nyquist_validation": true, "ui_phase": true, "context_coverage_gate": true }, "parallelization": { "enabled": true } } ``` Common profiles: * `"balanced"` — default; Opus for planning, Sonnet for research and execution * `"quality"` — Opus for all heavy agents * `"budget"` — Haiku and Sonnet throughout ### `continue-here.md` `continue-here.md` is the cross-session handoff document. The `/gsd-pause-work` command writes a structured summary of the current session state — what was completed, what is in progress, and what comes next — so that you (or another session) can pick up exactly where you left off. When you run `/gsd-resume-work`, GSD Core reads `continue-here.md` alongside `STATE.md` to restore full context without re-reading the entire conversation history. ## Per-phase artifacts Each phase gets its own directory under `.planning/phases/`. Directories are named with a two-digit phase number and a slug: `01-authentication`, `02-dashboard`, and so on. ```text theme={null} .planning/phases/ └── 01-authentication/ ├── 01-CONTEXT.md ├── 01-DISCUSSION-LOG.md ├── 01-RESEARCH.md ├── 01-01-PLAN.md ├── 01-02-PLAN.md ├── 01-01-SUMMARY.md ├── 01-02-SUMMARY.md ├── 01-VERIFICATION.md └── 01-UAT.md ``` ### `CONTEXT.md` `CONTEXT.md` captures your implementation preferences for the phase, written by `/gsd-discuss-phase`. It contains a structured `` block of numbered decisions — library choices, design patterns, testing approach, and anything else you specified during the discussion. The planner reads `CONTEXT.md` to understand your preferences before writing plans. The plan-checker runs a decision coverage gate after planning to confirm every trackable decision appears in at least one plan. The verifier runs a second check after execution to confirm decisions were honored in the shipped code. ### `DISCUSSION-LOG.md` `DISCUSSION-LOG.md` is the full audit trail of the discuss-phase conversation. It records every question asked and every answer given, so you can review the reasoning behind any decision in `CONTEXT.md` without re-running the discussion. ### `RESEARCH.md` `RESEARCH.md` contains the synthesized output of the parallel phase researchers. It covers stack research, feature patterns, architectural approaches, and common pitfalls for the specific domain of this phase. The planner reads `RESEARCH.md` alongside `CONTEXT.md` and `REQUIREMENTS.md` to write plans that are grounded in current ecosystem knowledge. Critically, `RESEARCH.md` includes a **Package Legitimacy Audit** table that records the slopcheck verdict for every external package the researchers recommended — `[OK]`, `[SUS]`, or `[SLOP]`. Packages rated `[SLOP]` are removed before the planner ever sees them. ### `PLAN.md` files Each `XX-YY-PLAN.md` file is one atomic execution plan. Plans are numbered sequentially (`01-01`, `01-02`, etc.) and sized to fit in a single fresh executor context window. Each plan contains: * A structured list of `` elements with explicit acceptance criteria * A `read_first` section listing the files the executor must read before starting * A `must_haves` section linking tasks to requirement IDs * A dependency declaration for wave ordering The plan-checker verifies each plan meets eight quality dimensions before approval. Plans that fail are revised automatically. ### `SUMMARY.md` files Each `XX-YY-SUMMARY.md` file is written by the executor after completing its assigned plan. It documents: * What was implemented (with file paths and git commit hashes) * Any deviations from the plan and why * Issues encountered and how they were resolved The verifier reads all `SUMMARY.md` files to understand what the executors claim to have built, then cross-checks those claims against the actual codebase. ### `VERIFICATION.md` `VERIFICATION.md` is written by the verifier agent after all executors complete. It contains a PASS or FAIL verdict with specific evidence — which requirements were satisfied, which tests passed, and which gaps were found. If the verdict is FAIL, the verification report becomes the input for the fix cycle. ### `UAT.md` `UAT.md` is written during `/gsd-verify-work`. It records your manual acceptance testing — the scenarios you tested, the results, and any issues you found. It complements the automated `VERIFICATION.md` with human judgment about whether the phase meets real-world requirements. ## Additional planning directories Beyond phase artifacts, `.planning/` contains several supporting directories: | Directory | Purpose | | ----------- | --------------------------------------------------------------------------------------------------------- | | `research/` | Domain research from `/gsd-new-project` (SUMMARY.md, STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md) | | `codebase/` | Brownfield codebase mapping from `/gsd-map-codebase` | | `debug/` | Active debug sessions from `/gsd-debug` | | `spikes/` | Feasibility experiments from `/gsd-spike` | | `sketches/` | HTML mockups from `/gsd-sketch` | | `threads/` | Persistent cross-session knowledge stores from `/gsd-thread` | | `seeds/` | Forward-looking ideas from `/gsd-capture --seed` | | `todos/` | Captured ideas in `pending/` and `done/` subdirectories | # GSD Core's Five-Step Phase Loop and Workflow Guide Source: https://docs.opengsd.net/core/concepts/workflow Understand GSD Core's phase loop: the five-step Discuss, Plan, Execute, Verify, and Ship cycle that drives every milestone from vision to shipped code. GSD Core organizes all development work into a disciplined, repeatable cycle called the phase loop. Every milestone is broken into numbered phases, and every phase moves through the same five steps in sequence. This structure is what separates GSD Core from ad-hoc AI coding: each step produces artifacts that the next step consumes, so nothing relies on conversation memory and every decision is traceable to a document on disk. ## The five-step phase loop Each phase in your `ROADMAP.md` moves through these steps in order: Before any planning begins, you lock in your implementation preferences by running `/gsd-discuss-phase N`. GSD Core reads the phase description from your roadmap, scans the existing codebase for relevant patterns, and asks targeted questions about gray areas — library choices, design patterns, testing approach, and any decisions where multiple options are viable. Your answers are written to `.planning/phases/XX-name/XX-CONTEXT.md`. Every downstream agent — the planner, the executor, and the verifier — reads this file. Nothing is inferred; everything is explicit. **Outcome:** `CONTEXT.md` containing a `` block of numbered implementation decisions. The `/gsd-plan-phase N` command runs the full research-and-planning pipeline. Four specialist researchers run in parallel, each exploring a different dimension of the implementation domain. A synthesizer combines their findings into `RESEARCH.md`. The planner then reads `PROJECT.md`, `REQUIREMENTS.md`, `CONTEXT.md`, and `RESEARCH.md` together to create two to three atomic execution plans. A plan-checker agent verifies the plans across eight dimensions before they are approved. If plans fail the check, the planner revises them automatically (up to three iterations). The plans are not approved until the checker returns a PASS verdict. **Outcome:** `RESEARCH.md` and one or more `XX-YY-PLAN.md` files containing structured task lists with explicit dependency ordering. The `/gsd-execute-phase N` command analyzes plan dependencies, groups plans into waves, and spawns parallel executor subagents. Each executor runs in a fresh context window — up to 200K tokens, or up to 1M tokens on models that support it — with no accumulated conversation history. Each executor reads only its assigned `PLAN.md` plus the phase context files, implements the tasks, makes an atomic git commit per completed task, and writes a `SUMMARY.md` documenting outcomes and deviations. After all waves complete, a verifier agent runs a goal-backward check against the phase requirements. **Outcome:** Committed code, per-plan `SUMMARY.md` files, and a `VERIFICATION.md` with a PASS or FAIL verdict. The `/gsd-verify-work N` command walks you through a structured user acceptance testing session. You test the implemented features against the phase goals, document your findings, and mark the phase as verified or flag issues. GSD Core reads the automated verification results alongside your UAT notes to build a complete picture of phase quality. If issues are found, GSD Core generates targeted fix plans. The phase is not considered done until both automated verification and UAT pass. **Outcome:** `UAT.md` documenting your acceptance test results and any outstanding issues. The `/gsd-ship N` command reads all phase artifacts — plans, summaries, verification results, and UAT notes — and generates a structured pull request. It archives the phase state, advances `STATE.md` to the next phase, and writes a `continue-here.md` handoff for the next session. **Outcome:** A pull request, archived phase artifacts, and an updated `STATE.md` ready for the next phase. ## How phases map to milestones A **milestone** is a major product goal — a shippable increment that delivers meaningful value. A **phase** is one step toward that milestone. Your `ROADMAP.md` organizes phases under milestones and tracks the status of each. ```text theme={null} Milestone 1: Core Authentication Phase 1: Database schema and user model Phase 2: Registration and login endpoints Phase 3: Session management and JWT Phase 4: Password reset flow Milestone 2: Dashboard Phase 5: Layout and navigation shell Phase 6: Data fetching and charts ... ``` Each phase is small enough to plan, execute, and verify in one session. Phases that are too large produce plans with too many tasks, which executors cannot reliably complete in a single context window. The guideline is two to three atomic plans per phase, each with two to three tasks. When a milestone is complete, run `/gsd-audit-milestone` to check requirement coverage and detect any stubs, then `/gsd-complete-milestone` to archive and tag the work. ## Spec-driven development GSD Core applies a spec-driven development approach: every requirement is written down before any code is written, and every artifact gates the next stage. The flow looks like this: ```text theme={null} User vision │ ▼ REQUIREMENTS.md — scoped requirements with IDs (REQ-001, REQ-002, ...) │ ▼ ROADMAP.md — phases mapped to requirement IDs (traceability guaranteed) │ ▼ CONTEXT.md — implementation preferences per phase │ ▼ RESEARCH.md — ecosystem research per phase │ ▼ PLAN.md — atomic execution tasks referencing requirements and acceptance criteria │ ▼ SUMMARY.md — what was built, deviations from plan │ ▼ VERIFICATION.md — goal-backward check against phase requirements │ ▼ UAT.md — human acceptance testing results ``` The plan-checker enforces that every plan covers the requirements it claims to cover. The verifier enforces that every requirement mapped to the phase is actually implemented. If a requirement is not covered, the phase does not advance. ## Artifact dependency map Each artifact is consumed by specific agents downstream. The table below shows which agents read each planning artifact: | Artifact | Read by | | ------------------------- | ---------------------------------------------------- | | `PROJECT.md` | All agents — planner, executor, verifier, researcher | | `REQUIREMENTS.md` | Planner, plan-checker, verifier, auditor | | `ROADMAP.md` | Orchestrators, roadmapper | | `STATE.md` | All agents — decisions, blockers, current position | | `CONTEXT.md` (per phase) | Researcher, planner, executor | | `RESEARCH.md` (per phase) | Planner, plan-checker | | `PLAN.md` (per plan) | Executor, plan-checker | | `SUMMARY.md` (per plan) | Verifier, state tracking | Nothing is held in conversation memory. If you run `/clear` between steps, everything the next agent needs is already on disk. ## Namespace routing GSD Core ships six **namespace meta-skills** as top-level entry points for the phase pipeline. Each namespace router maps natural-language intent to the correct concrete command: | Namespace | Command | Routes to | | --------------------- | --------------- | ---------------------------------------- | | Phase pipeline | `/gsd-workflow` | discuss, plan, execute, verify, progress | | Project lifecycle | `/gsd-project` | milestones, audits, summary | | Quality gates | `/gsd-quality` | code review, debug, security, UI audit | | Codebase intelligence | `/gsd-context` | map, graphify, docs, learnings | | Management | `/gsd-manage` | config, workspace, workstreams, ship | | Exploration | `/gsd-ideate` | explore, sketch, spike, spec, capture | You can always invoke concrete commands directly (for example, `/gsd-plan-phase 1`). The namespace routers exist to reduce the token cost of skill discovery — six entries instead of eighty-six. # Configure Git Branching Strategy for GSD Core Projects Source: https://docs.opengsd.net/core/configuration/git-branching Set up GSD Core's git branching strategy — none, phase, or milestone — with custom branch name templates and base branch configuration in config.json. GSD Core can manage git branching automatically as part of the execute-and-ship workflow. By default it works entirely on your current branch, but you can configure it to create a dedicated branch for each phase or each milestone, giving you clean separation for code review and rollback. All branching settings live in the `git` section of `.planning/config.json`. ## Configuration reference ```json theme={null} { "git": { "branching_strategy": "none", "base_branch": "main", "phase_branch_template": "gsd/phase-{phase}-{slug}", "milestone_branch_template": "gsd/{milestone}-{slug}" } } ``` Configure these settings interactively with `/gsd-config --advanced` (Git Customization section) or by editing `config.json` directly. ## Branching strategies All work happens on your current branch. GSD makes no branch decisions — it commits directly to whatever branch you are on when you invoke `/gsd-execute-phase`. This is the right choice for solo development, simple projects, or when you manage branching yourself. ```json theme={null} { "git": { "branching_strategy": "none" } } ``` GSD creates a new branch at the start of each `/gsd-execute-phase` run. The branch is named using `phase_branch_template`. After the phase is verified and shipped, you merge or delete the branch. ```json theme={null} { "git": { "branching_strategy": "phase", "base_branch": "main", "phase_branch_template": "gsd/phase-{phase}-{slug}" } } ``` A phase 3 execution with the slug `user-authentication` would create the branch `gsd/phase-03-user-authentication`. GSD creates one branch for the entire milestone at the start of the first `/gsd-execute-phase` run for that milestone. All phases in the milestone commit to the same branch. The branch is named using `milestone_branch_template` and merged or deleted at `/gsd-complete-milestone`. ```json theme={null} { "git": { "branching_strategy": "milestone", "base_branch": "main", "milestone_branch_template": "gsd/{milestone}-{slug}" } } ``` ## Strategy comparison | Strategy | Branch created | Scope | Merge point | Best for | | ----------- | ----------------------------------------- | --------------------------- | ---------------------------- | ---------------------------------------- | | `none` | Never | Current branch | N/A | Solo development, simple projects | | `phase` | At `execute-phase` start | One phase | User merges after each phase | Code review per phase, granular rollback | | `milestone` | At first `execute-phase` in the milestone | All phases in the milestone | At `complete-milestone` | Release branches, PR per version | ## Template variables Customize the branch name format by editing the template strings in `config.json`. | Variable | Available in | Example output | | ------------- | --------------------------- | ------------------------------------------------------------- | | `{phase}` | `phase_branch_template` | `03` (zero-padded) | | `{slug}` | Both templates | `user-authentication` (lowercase, hyphenated from phase name) | | `{milestone}` | `milestone_branch_template` | `v1.0` | Use any combination of variables and literal text: ```json theme={null} { "git": { "branching_strategy": "phase", "phase_branch_template": "feature/gsd-{phase}-{slug}" } } ``` With the above template, phase 2 named "API layer" produces: `feature/gsd-02-api-layer` For milestone strategy with a custom format: ```json theme={null} { "git": { "branching_strategy": "milestone", "milestone_branch_template": "release/{milestone}" } } ``` This produces: `release/v1.0` ## Base branch Set `git.base_branch` to the integration branch that phase and milestone branches are created from and eventually merged back into. Override this when your repository uses `master`, `develop`, or a named release branch rather than `main`. ```json theme={null} { "git": { "base_branch": "develop" } } ``` GSD also reads `git.base_branch` to determine where to target the pull request created by `/gsd-ship`. Make sure this matches the default branch in your GitHub repository settings. ## Milestone completion merge options When using the `milestone` strategy, `/gsd-complete-milestone` offers you a choice of how to merge the milestone branch back into `base_branch`: | Option | Git command | Result | | -------------------------- | -------------------- | ------------------------------------------------------------------- | | Squash merge (recommended) | `git merge --squash` | Single clean commit representing the entire milestone | | Merge with history | `git merge --no-ff` | Preserves all individual phase commits | | Delete without merging | `git branch -D` | Discards the branch; useful if you shipped via individual phase PRs | | Keep branches | (none) | Leaves branches in place for manual handling | ## Tags on milestone completion By default, GSD creates a git tag (`v[X.Y]`) when a milestone completes. Disable this if you have your own release tagging workflow: ```json theme={null} { "git": { "create_tag": false } } ``` ## /gsd-quick branch template Optionally configure an automatic branching strategy for `/gsd-quick` ad-hoc tasks: ```json theme={null} { "git": { "quick_branch_template": "gsd/quick-{num}-{slug}" } } ``` When set, `/gsd-quick` creates a branch named with the task ID and a slug derived from the task description before running. When `null` (the default), `/gsd-quick` works on your current branch. Use the `phase` strategy with a short review cycle to get clean, reviewable PRs for each unit of work. Use the `milestone` strategy when your team reviews releases as a whole rather than individual phases. # GSD Core External Service Integrations Configuration Source: https://docs.opengsd.net/core/configuration/integrations Configure web research APIs, cross-AI review CLI routing, custom agent skills, code quality tooling, and parallelization settings in .planning/config.json. GSD Core integrates with external services and tools through `.planning/config.json`. Most integration settings are connectivity concerns — API keys, CLI routing, and path configuration — and are intentionally kept separate from workflow toggles. Configure them interactively with `/gsd-config --integrations` or by editing `config.json` directly. ## Web research GSD Core uses web search during the research phase of `/gsd-plan-phase`. Three providers are supported. GSD auto-detects which are available by checking for API keys in environment variables or key files, but you can override detection explicitly. ```json theme={null} { "brave_search": "your-brave-api-key", "firecrawl": "your-firecrawl-api-key", "exa_search": "your-exa-api-key" } ``` | Setting | Environment variable | Key file | Description | | -------------- | -------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------ | | `brave_search` | `BRAVE_API_KEY` | `~/.gsd/brave_api_key` | Brave Search API key for web research. Used as the primary search provider during plan-phase research. | | `firecrawl` | `FIRECRAWL_API_KEY` | `~/.gsd/firecrawl_api_key` | Firecrawl API key for deep-crawl scraping of documentation sites and reference pages. | | `exa_search` | `EXA_API_KEY` | `~/.gsd/exa_api_key` | Exa Search API key for semantic similarity search across technical content. | API keys are masked in all GSD output — keys with 8+ characters display as `****`. The plaintext value is written to `config.json`, which is the security boundary. Never commit `config.json` to a public repository with real API keys in it. Set keys via `/gsd-config --integrations` to benefit from masking in confirmation output, or write them directly to `config.json` and restrict file permissions appropriately. ## Cross-AI review CLI routing Configure which shell command GSD invokes for each AI reviewer when running `/gsd-review`. Keys under `review.models.` map a reviewer flavor to an executable command. When a key is absent, GSD uses each CLI's configured default. ```json theme={null} { "review": { "models": { "claude": "claude", "codex": "codex exec --model gpt-5.3-codex", "gemini": "gemini -m gemini-2.5-pro", "opencode": "opencode run --model anthropic/claude-sonnet-4-6", "qwen": "qwen-code", "cursor": "cursor-agent", "ollama": "codellama", "lm_studio": "mistral-7b-instruct", "llama_cpp": "llama3" }, "default_reviewers": ["gemini", "codex"] } } ``` | Slug | Reviewer | Notes | | ------------ | ------------------------- | ------------------------------------------------ | | `claude` | Claude (separate session) | Defaults to the current session model when unset | | `codex` | Codex CLI | e.g. `"codex exec --model gpt-5.3-codex"` | | `gemini` | Gemini CLI | e.g. `"gemini -m gemini-2.5-pro"` | | `opencode` | OpenCode | e.g. `"opencode run --model claude-sonnet-4-6"` | | `qwen` | Qwen Code | | | `cursor` | Cursor agent | | | `coderabbit` | CodeRabbit | | | `agy` | Antigravity CLI | | | `ollama` | Ollama server | Value is the model name, e.g. `"codellama"` | | `lm_studio` | LM Studio | Value is the model name | | `llama_cpp` | llama.cpp | Value is the model name | Use `review.default_reviewers` to set the reviewers that `/gsd-review` runs when invoked without explicit reviewer flags. Set it to `null` (the default) to run all detected reviewers automatically. ## Custom agent skills injection Inject custom skill files into GSD subagent prompts to give specific agent types project-specific instructions that go beyond what `CLAUDE.md` provides. Skills are read at spawn time and injected as an `` block in the agent's prompt. ```json theme={null} { "agent_skills": { "gsd-executor": ["skills/testing-standards", "skills/api-conventions"], "gsd-planner": ["skills/architecture-rules"], "gsd-verifier": ["skills/acceptance-criteria"] } } ``` Each value is an array of directory paths relative to your project root. Each path must contain a `SKILL.md` file. GSD validates paths for safety and rejects any path that would escape the project root. | Agent type | Role | | ------------------------ | ----------------------------- | | `gsd-executor` | Executes implementation plans | | `gsd-planner` | Creates phase plans | | `gsd-checker` | Verifies plan quality | | `gsd-verifier` | Post-execution verification | | `gsd-researcher` | Phase research | | `gsd-project-researcher` | New-project research | | `gsd-debugger` | Diagnostic agents | | `gsd-codebase-mapper` | Codebase analysis | | `gsd-advisor` | Discuss-phase advisors | | `gsd-roadmapper` | Roadmap creation | Configure agent skills interactively via `/gsd-config --integrations`, which validates the paths before writing to config. ## Code quality tooling GSD Core integrates with optional structural analysis tooling that augments `/gsd-code-review`. The `code_quality` namespace is additive — each tool is independently opt-in and off by default. ```json theme={null} { "code_quality": { "fallow": { "enabled": true, "scope": "phase", "profile": "standard" } } } ``` | Setting | Default | Description | | ----------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code_quality.fallow.enabled` | `false` | Enable the fallow structural pre-pass for `/gsd-code-review`. When enabled, GSD runs fallow before the agent review and embeds a **Structural Findings** section in `REVIEW.md`. | | `code_quality.fallow.scope` | `"phase"` | Analysis scope: `"phase"` covers files changed in the current review; `"repo"` covers the entire repository. | | `code_quality.fallow.profile` | `"standard"` | Fallow profile passed to the pre-pass runner: `"minimal"`, `"standard"`, or `"strict"`. | ## Parallelization GSD Core runs independent plans simultaneously using git worktrees. Configure how many agents can run in parallel and when parallel execution kicks in. ```json theme={null} { "parallelization": { "enabled": true, "max_concurrent_agents": 3, "min_plans_for_parallel": 2 } } ``` | Setting | Default | Description | | ---------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `parallelization.enabled` | `true` | Master switch for parallel execution. Set `false` to run plans sequentially. | | `parallelization.max_concurrent_agents` | `3` | Maximum number of agent processes running simultaneously. Lower this value if your environment has limited resources or API rate constraints. | | `parallelization.min_plans_for_parallel` | `2` | Minimum number of plans required before parallel execution is used. Phases with fewer plans always run sequentially. | When parallelization is enabled, executor agents commit with `--no-verify` to avoid build lock contention (for example, Cargo lock conflicts in Rust projects). The orchestrator validates hooks once after each wave completes. Set `parallelization.enabled: false` if you need pre-commit hooks to run on every individual commit. Run `/gsd-manager --analyze-deps` before starting a multi-phase autonomous run. It scans your ROADMAP for dependency relationships and presents a parallelization plan showing which phases can safely run in parallel versus which must wait on a predecessor. # GSD Core Model Profiles: Tiers, Routing, and Effort Source: https://docs.opengsd.net/core/configuration/model-profiles Assign model tiers to agents with built-in profiles, use dynamic routing to escalate on failure, and tune per-agent effort for cost-effective AI usage. GSD Core assigns a model tier to each of its specialized agents based on the active model profile. Rather than running every agent on the most expensive model, profiles let you allocate compute intentionally — Opus for the agents where reasoning quality drives the outcome, Sonnet for workhorses, and Haiku for fast scanners and mappers. Dynamic routing and effort control let you push that further: start cheap and escalate only when an agent fails its quality gate. ## Built-in profiles Set `model_profile` in `config.json` or switch profiles instantly with `/gsd-config --profile `. Uses Opus for all decision-making agents and Sonnet for verification. Best for quota-rich environments and critical architecture work where output quality is the top priority. Uses Opus for planning agents only and Sonnet for everything else. The default profile for most development work — strong planning quality at a reasonable cost. Uses Sonnet for code-writing and Haiku for research and verification. Ideal for high-volume work, less critical phases, or when API costs are a constraint. Biases toward Opus for agents where reasoning quality matters most (planner, debugger) and Haiku for lightweight tasks. A middle path between quality and budget. All agents use the current session model. Use this for non-Anthropic providers (OpenRouter, local models) or when you want to control the model entirely from your runtime's configuration. ## Agent tier assignments The table below shows how the five most-used agents resolve under each profile. The tier names (Opus, Sonnet, Haiku) are resolved to runtime-native model IDs when `runtime` is set in `config.json`. | Agent | `quality` | `balanced` | `budget` | `adaptive` | `inherit` | | ---------------------- | --------- | ---------- | -------- | ---------- | --------- | | `gsd-planner` | Opus | Opus | Sonnet | Opus | Inherit | | `gsd-executor` | Opus | Sonnet | Sonnet | Sonnet | Inherit | | `gsd-phase-researcher` | Opus | Sonnet | Haiku | Sonnet | Inherit | | `gsd-verifier` | Sonnet | Sonnet | Haiku | Sonnet | Inherit | | `gsd-codebase-mapper` | Sonnet | Haiku | Haiku | Haiku | Inherit | The full catalog covers all 33 shipped agents with explicit per-profile tier assignments. These five represent the most frequently invoked agents during a standard phase lifecycle. ### Per-agent overrides Override individual agents without changing the profile for everything else. This is useful when you want one agent to use a more powerful model than the profile assigns. ```json theme={null} { "model_profile": "balanced", "model_overrides": { "gsd-executor": "opus", "gsd-codebase-mapper": "haiku" } } ``` Valid override values: `opus`, `sonnet`, `haiku`, `inherit`, or a fully-qualified model ID such as `"openai/o3"` or `"google/gemini-2.5-pro"`. ### Per-phase-type model assignment The `models` block lets you tune at the phase level without knowing individual agent names. Specify a tier for each phase type and GSD applies it to all agents in that category. ```json theme={null} { "model_profile": "balanced", "models": { "planning": "opus", "research": "sonnet", "execution": "opus", "verification": "sonnet" } } ``` | Phase type | Agents included | | -------------- | -------------------------------------------------------------------------------------------- | | `planning` | `gsd-planner`, `gsd-roadmapper`, `gsd-pattern-mapper` | | `research` | `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-codebase-mapper`, `gsd-ui-researcher` | | `execution` | `gsd-executor`, `gsd-debugger`, `gsd-doc-writer` | | `verification` | `gsd-verifier`, `gsd-plan-checker`, `gsd-nyquist-auditor`, `gsd-ui-checker` | **Resolution precedence (highest to lowest):** 1. `model_overrides[]` — per-agent exception, wins over everything 2. `dynamic_routing.tier_models[]` — when dynamic routing is enabled 3. `models[]` — coarse phase-level tier 4. `model_profile` — global profile tier per agent 5. Runtime default ## Dynamic routing with failure-tier escalation Dynamic routing lets agents start on a cheaper tier and escalate automatically when the orchestrator detects a soft failure (plan-check FLAG, verification inconclusive). Enable it with `dynamic_routing.enabled: true`. ```json theme={null} { "dynamic_routing": { "enabled": true, "tier_models": { "light": "haiku", "standard": "sonnet", "heavy": "opus" }, "escalate_on_failure": true, "max_escalations": 1 } } ``` Each agent is pre-assigned to one of three default tiers based on its role: | Tier | Examples | Use case | | ---------- | ---------------------------------------------------------------- | --------------------------------------------------------- | | `light` | `gsd-codebase-mapper`, `gsd-nyquist-auditor`, `gsd-plan-checker` | Fast mappers, scanners, low-stakes audits | | `standard` | `gsd-executor`, `gsd-verifier`, `gsd-phase-researcher` | Default workhorse agents | | `heavy` | `gsd-planner`, `gsd-roadmapper`, `gsd-debugger` | Deep reasoning — these agents are already at the top tier | | Key | Type | Default | Description | | -------------------------------------- | ---------- | ------- | ------------------------------------------------------------------------ | | `dynamic_routing.enabled` | boolean | `false` | Master switch. `true` activates the dynamic resolver. | | `dynamic_routing.tier_models.light` | tier alias | (none) | Model for the light tier, typically `haiku`. | | `dynamic_routing.tier_models.standard` | tier alias | (none) | Model for the standard tier, typically `sonnet`. | | `dynamic_routing.tier_models.heavy` | tier alias | (none) | Model for the heavy tier, typically `opus`. | | `dynamic_routing.escalate_on_failure` | boolean | `true` | When `false`, every attempt uses the default tier regardless of failure. | | `dynamic_routing.max_escalations` | integer | `1` | Hard cap on retry escalations per agent invocation. | ## Effort control Control the reasoning effort of each agent invocation independently of model tier. The universal effort ladder is: ``` minimal < low < medium < high < xhigh < max ``` Effort is rendered per-runtime: `output_config.effort` for Claude, `model_reasoning_effort` for Codex. Cross-provider clamping applies: `max` is Anthropic-only and clamps to `xhigh` on Codex; `minimal` is Codex-only and clamps to `low` on Claude. ```json theme={null} { "effort": { "default": "high", "routing_tier_defaults": { "light": "low", "standard": "high", "heavy": "xhigh" }, "agent_overrides": { "gsd-planner": "max" } } } ``` | Key | Default | Description | | --------------------------------------- | --------- | -------------------------------------------------------------------- | | `effort.default` | `"high"` | Global fallback effort level when no tier or agent override matches. | | `effort.routing_tier_defaults.light` | `"low"` | Effort for light-tier agents. | | `effort.routing_tier_defaults.standard` | `"high"` | Effort for standard-tier agents. | | `effort.routing_tier_defaults.heavy` | `"xhigh"` | Effort for heavy-tier agents. | | `effort.agent_overrides.` | (none) | Per-agent effort override; beats all tier defaults. | **Effort precedence (highest to lowest):** 1. Invocation override (e.g. `--effort` flag on `resolve-execution`) 2. `effort.agent_overrides[]` 3. `effort.routing_tier_defaults[]` 4. `effort.default` 5. `"high"` (universal default) ## Model policy presets Model policy presets let you pick a provider family and a budget level, and have GSD materialize the concrete `(opus, sonnet, haiku)` tier mappings for you — no need to spell out every model ID by hand. Use a preset when you want a known-good mapping for a given vendor; fall back to `generic` when you want full control over individual model IDs. ```json theme={null} { "model_policy": { "provider": "anthropic", "budget": "high" } } ``` | Key | Type | Values | Description | | -------------------------------------- | ------ | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model_policy.provider` | enum | `openai`, `anthropic`, `anthropic-fable`, `google`, `qwen`, `generic` | Declares the model provider. Known providers unlock catalog-backed presets. `generic` treats all model IDs as opaque strings — no prefix inference, no reasoning-effort defaults. | | `model_policy.budget` | enum | `high`, `medium`, `low` | Selects a budget tier when using a known provider. GSD materializes the matching catalog preset into explicit tier mappings at resolve time. Ignored when `provider` is `generic`. | | `model_policy.high` / `medium` / `low` | string | model ID | Tier model IDs for `generic` provider only. | ### Anthropic presets GSD ships two Anthropic-family presets so you can decide whether to stay on the standard Opus 4.8 lineup or opt into Claude Fable 5 for top-tier routing. Both presets share the Sonnet 4.6 and Haiku 4.5 fallback tiers; they only differ at the high end. | Provider | Budget | high | medium | low | | ----------------- | ------ | ------------------ | ------------------- | ------------------- | | `anthropic` | high | `claude-opus-4-8` | `claude-opus-4-8` | `claude-sonnet-4-6` | | `anthropic` | medium | `claude-opus-4-8` | `claude-sonnet-4-6` | `claude-haiku-4-5` | | `anthropic` | low | `claude-haiku-4-5` | `claude-haiku-4-5` | `claude-haiku-4-5` | | `anthropic-fable` | high | `claude-fable-5` | `claude-fable-5` | `claude-sonnet-4-6` | | `anthropic-fable` | medium | `claude-opus-4-8` | `claude-sonnet-4-6` | `claude-haiku-4-5` | | `anthropic-fable` | low | `claude-haiku-4-5` | `claude-haiku-4-5` | `claude-haiku-4-5` | Use `anthropic-fable` when you want Claude Fable 5 — an Opus-tier model with a 1M-token context window, 128K max output, and adaptive thinking at the `xhigh` effort level — to handle high-budget Opus and Sonnet routing. The `medium` and `low` budgets fall back to the same Opus 4.8 / Sonnet 4.6 / Haiku 4.5 mix as the standard `anthropic` preset, so opting in only affects the top tier. Claude Fable 5 is available through Anthropic direct, Anthropic on Vertex AI, Amazon Bedrock, and OpenRouter. Make sure your selected runtime can reach at least one of those providers before switching to the `anthropic-fable` preset. If you set `context_window: 1000000` to use Claude Fable 5's full 1M-token window, GSD also enables adaptive context enrichment (deeper SUMMARY.md and anti-pattern reads). ## Profile philosophy | Profile | Philosophy | When to use | | ---------- | -------------------------------------------------------- | ------------------------------------------------- | | `quality` | Opus for all decision-making, Sonnet for verification | Quota available; critical architecture work | | `balanced` | Opus for planning only, Sonnet for everything else | Normal development (recommended default) | | `budget` | Sonnet for code-writing, Haiku for research/verification | High-volume work, less critical phases | | `inherit` | All agents follow the session model | Non-Anthropic providers, OpenRouter, local models | # GSD Core Configuration Settings and Options Reference Source: https://docs.opengsd.net/core/configuration/settings Configure GSD Core in .planning/config.json using the interactive wizard, /gsd-config flags, or direct JSON edits for workflow toggles and core settings. GSD Core stores all project configuration in `.planning/config.json`. The file is created automatically when you run `/gsd-new-project` and updated whenever you use the configuration commands. You can edit it directly or use the interactive configuration tools — both approaches produce the same result, and unrelated keys are always preserved on write. ## Interactive configuration with /gsd-settings Run `/gsd-settings` to open a six-section interactive wizard that walks you through every configurable workflow toggle and model profile setting. Answers are merged into your project's `config.json` without overwriting keys you do not touch. ```bash theme={null} /gsd-settings ``` The wizard is organized into six sections: | Section | Settings covered | | -------------------- | ---------------------------------------------------------------------------- | | **Planning** | Research, Plan Checker, Pattern Mapper, Nyquist, UI Phase, UI Gate, AI Phase | | **Execution** | Verifier, TDD Mode, Code Review, Code Review Depth, UI Review | | **Docs & Output** | Commit Docs, Skip Discuss, Worktrees | | **Features** | Intel, Graphify | | **Model & Pipeline** | Model Profile, Auto-Advance, Branching | | **Misc** | Context Warnings, Research Questions mode | At the end of the session you can optionally save the full settings object to `~/.gsd/defaults.json` so future projects start from the same baseline configuration. ## Targeted configuration with /gsd-config Run `/gsd-config` for a more focused configuration experience. Without flags it covers the most common toggles. Use flags to access power-user settings, integrations, or to switch model profiles with a single command. ```bash theme={null} /gsd-config # Common toggles: model, research, plan_check, verifier, branching /gsd-config --advanced # Power-user knobs: timeouts, templates, cross-AI, runtime /gsd-config --integrations # API keys, review CLI routing, agent-skill injection /gsd-config --profile quality # Switch to quality model profile /gsd-config --profile balanced # Switch to balanced model profile /gsd-config --profile budget # Switch to budget model profile /gsd-config --profile inherit # All agents inherit the session model ``` To use the `adaptive` profile, run `/gsd-config` without flags and select it from the interactive wizard's Model & Pipeline section. ## Core settings | Setting | Options | Default | Description | | ------------------- | ----------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `mode` | `interactive`, `yolo` | `interactive` | `interactive` confirms decisions at each workflow step. `yolo` auto-approves everything — useful for prototyping where speed matters more than review. | | `granularity` | `coarse`, `standard`, `fine` | `standard` | Controls how many tasks the planner generates per phase. `coarse` produces 2–4 tasks, `standard` 4–6, `fine` 6–10. | | `model_profile` | `quality`, `balanced`, `budget`, `adaptive`, `inherit` | `balanced` | Model tier assignment for each agent type. See [Model Profiles](/core/configuration/model-profiles) for the full agent-to-tier mapping. | | `runtime` | `claude`, `codex`, `gemini`, `qwen`, `opencode`, and others | (none) | Active runtime for runtime-aware profile resolution. When set, profile tiers resolve to runtime-native model IDs. | | `context_window` | any integer | `200000` | Context window size in tokens. Set `1000000` for 1M-context models. Values ≥ 500,000 enable adaptive context enrichment. | | `response_language` | language code | (none) | Language for all agent responses, e.g. `"pt"`, `"ko"`, `"ja"`. Propagates to every spawned agent for cross-phase consistency. | ## Workflow toggles All workflow toggles follow the **absent = enabled** pattern. If a key is missing from `config.json`, the feature defaults to `true`. | Setting | Default | Description | | ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | | `workflow.research` | `true` | Run domain investigation before planning each phase. Disable with `--skip-research` per run or set `false` to skip globally. | | `workflow.plan_check` | `true` | Run the plan verification loop after planning (up to 3 iterations). | | `workflow.verifier` | `true` | Run post-execution verification against phase goals before shipping. | | `workflow.auto_advance` | `false` | Automatically chain discuss → plan → execute without stopping between steps. | | `workflow.tdd_mode` | `false` | Enable TDD pipeline as a first-class execution mode. The planner applies red-green-refactor sequencing to behavior-adding tasks. | | `workflow.code_review` | `true` | Enable `/gsd-code-review` and the fix pipeline. Set `false` to gate the command project-wide. | | `workflow.security_enforcement` | `true` | Enable threat-model-anchored security verification via `/gsd-secure-phase`. | `workflow.auto_advance: false` is the safe default. Set it to `true` only when your requirements are stable and you are comfortable with phases advancing without manual confirmation. ## Common configuration combinations The following combinations of settings are commonly used together: | Scenario | `mode` | `granularity` | `model_profile` | `research` | `plan_check` | `verifier` | | ------------------ | ------------- | ------------- | --------------- | ---------- | ------------ | ---------- | | Prototyping | `yolo` | `coarse` | `budget` | `false` | `false` | `false` | | Normal development | `interactive` | `standard` | `balanced` | `true` | `true` | `true` | | Production release | `interactive` | `fine` | `quality` | `true` | `true` | `true` | ## Global defaults Save settings as global defaults so every new project starts from the same baseline. GSD reads `~/.gsd/defaults.json` when creating a new `config.json` and merges global defaults as the starting configuration. Per-project settings always override globals. ```bash theme={null} /gsd-settings # Offers to save to ~/.gsd/defaults.json at the end of the session ``` You can also write to the global defaults file directly: ```json theme={null} { "model_profile": "balanced", "granularity": "standard", "workflow": { "research": true, "plan_check": true, "verifier": true } } ``` ## Example config.json The following example shows a typical production project configuration: ```json theme={null} { "mode": "interactive", "granularity": "fine", "model_profile": "quality", "context_window": 200000, "response_language": null, "workflow": { "research": true, "plan_check": true, "verifier": true, "auto_advance": false, "tdd_mode": false, "code_review": true, "code_review_depth": "standard", "security_enforcement": true, "security_asvs_level": 1, "security_block_on": "high" }, "git": { "branching_strategy": "phase", "base_branch": "main" } } ``` # Running GSD Core Autonomously Without Intervention Source: https://docs.opengsd.net/core/guides/autonomous-mode Run all remaining phases hands-free with /gsd-autonomous, oversee parallel phases with /gsd-manager, and configure auto-advance in config.json. GSD Core is designed to run without you watching every step. Autonomous mode lets you fire off an entire multi-phase delivery and come back when it is done, or use the interactive manager to oversee parallel phase work from a single terminal. Understanding when to use each mode — and how to keep human checkpoints when you need them — is the key to getting the most out of GSD Core's parallelization. ## /gsd-autonomous — hands-free phase execution Run `/gsd-autonomous` to execute all remaining phases in your roadmap without any human intervention. GSD runs each phase through the full discuss → plan → execute → verify loop in sequence, skipping phases that are already complete. ```bash theme={null} /gsd-autonomous # Run all remaining phases /gsd-autonomous --from 3 # Start from phase 3 /gsd-autonomous --to 5 # Run up to and including phase 5 /gsd-autonomous --from 3 --to 5 # Run phases 3 through 5 /gsd-autonomous --only 4 # Run only phase 4 /gsd-autonomous --interactive # Answer discuss questions inline; plan and execute run as background agents ``` | Flag | Effect | | --------------- | --------------------------------------------------------------------------------------- | | `--from N` | Start autonomous execution from phase N; phases before N are skipped | | `--to N` | Stop after completing phase N | | `--only N` | Execute only phase N in single-phase mode | | `--interactive` | Run discuss inline with user input, then dispatch plan and execute as background agents | `/gsd-autonomous` without `--interactive` commits code and advances STATE.md without asking for confirmation at each phase. Review your ROADMAP.md and REQUIREMENTS.md carefully before running fully autonomous mode on a project for the first time. ## /gsd-manager — interactive multi-phase command center Run `/gsd-manager` to open a dashboard that shows the status of all phases and lets you dispatch work to individual phases from a single terminal. Unlike `/gsd-autonomous`, the manager does not run phases sequentially on its own — it gives you a visual command center to orchestrate phase work interactively. ```bash theme={null} /gsd-manager # Open the command center dashboard /gsd-manager --analyze-deps # Scan ROADMAP for phase dependencies before parallel execution ``` The manager runs discuss-phase commands inline in the terminal so you can answer questions directly. Plan and execute commands run as background agents, emitting `[checkpoint]` markers at every wave and plan boundary so the stream never times out on long-running phases. If a background phase fails partway through, look for `[checkpoint]` in the transcript to identify the last confirmed wave boundary and resume from there. You can configure per-step flags that the manager appends automatically to every dispatched command: ```json theme={null} { "manager": { "flags": { "discuss": "--auto", "plan": "--skip-research", "execute": "--validate" } } } ``` ## Auto-advance via config Set `workflow.auto_advance: true` in `.planning/config.json` to automatically chain discuss → plan → execute without stopping between steps. This is a project-level toggle — once set, every phase command that completes successfully will immediately invoke the next step. ```json theme={null} { "workflow": { "auto_advance": true } } ``` Enable or disable it interactively via `/gsd-settings` or `/gsd-config`: ```bash theme={null} /gsd-settings # Interactive six-section configuration wizard /gsd-config # Focused interactive config for common toggles ``` ## When to use autonomous vs interactive mode Choosing the right mode depends on how much confidence you have in your requirements and how much you want to inspect intermediate artifacts. * Your requirements and ROADMAP are well-defined and stable * You are running repeated phases on a familiar domain * You want to leave work running overnight or between sessions * The project is in a `yolo` mode prototype and speed matters more than review * You are working on a novel architecture or unfamiliar domain * Your requirements have open questions that need human judgment * Each phase has significant infrastructure changes worth reviewing * You want to run cross-AI review between discuss and plan ## Keeping human checkpoints with --interactive The `--interactive` flag on `/gsd-autonomous` strikes a balance between automation and oversight. GSD runs the discuss step inline so you can answer questions directly, then dispatches plan and execute as background agents. This keeps the main context lean while preserving your input on implementation decisions before any code is written. ```bash theme={null} /gsd-autonomous --interactive # Discuss inline, plan and execute as background agents ``` Combine `--interactive` with `--from N` to let earlier phases run fully autonomous while you stay hands-on for a specific phase range: `/gsd-autonomous --from 4 --to 6 --interactive`. ## Discuss-phase skip for fully captured projects If your PROJECT.md and REQUIREMENTS.md already capture all developer preferences and implementation decisions, skip the discuss step entirely by setting `workflow.skip_discuss: true`. GSD will write a minimal CONTEXT.md from the ROADMAP phase goal and proceed directly to planning. ```json theme={null} { "workflow": { "skip_discuss": true } } ``` `skip_discuss` only affects `/gsd-autonomous`. Running `/gsd-discuss-phase` directly always runs the full session regardless of this setting. # GSD Core Code Review: Quality Gates and Audit Commands Source: https://docs.opengsd.net/core/guides/code-review Use GSD Core's code review, audit-fix pipeline, test generation, security verification, and Nyquist coverage audit commands to ship with confidence. GSD Core ships several quality gate commands that you can run at any point after a phase has been executed. Each command is independent — you can run just a quick code review after execution, deep security verification before shipping, or the full pipeline for production-critical phases. All commands produce structured Markdown artifacts that feed back into the planning loop. ## Code review Run `/gsd-code-review N` to review all files changed during a phase. The reviewer agent classifies findings by severity — Critical, Warning, and Info — and writes a structured `REVIEW.md` that you can act on immediately or feed into the fix pipeline. ```bash theme={null} /gsd-code-review 3 # Standard review for phase 3 /gsd-code-review 2 --depth=deep # Deep cross-file review /gsd-code-review 4 --files src/auth.ts,src/api.ts # Review specific files only /gsd-code-review 3 --fix # Review then fix Critical + Warning findings /gsd-code-review 3 --fix --all # Review then fix all findings including Info /gsd-code-review 3 --fix --auto # Review, fix, and re-review until clean (max 3 iterations) ``` | Flag | Effect | | --------------------- | -------------------------------------------------------------------------- | | `--depth=quick` | Pattern-matching only, approximately 2 minutes | | `--depth=standard` | Per-file analysis with language-specific checks, 5–15 minutes (default) | | `--depth=deep` | Cross-file analysis including import graphs and call chains, 15–30 minutes | | `--files file1,file2` | Review explicit comma-separated files; skips SUMMARY/git scoping | | `--fix` | Auto-fix Critical and Warning findings after review | | `--fix --all` | Expand fix scope to include Info-level findings | | `--fix --auto` | Fix-and-re-review loop, capped at 3 iterations | **Produces:** `{phase}-REVIEW.md` with severity-classified findings; `{phase}-REVIEW-FIX.md` when `--fix` is used You can set a default review depth in config with `workflow.code_review_depth: "quick" | "standard" | "deep"`. Override it per run with `--depth=`. Set `workflow.code_review: false` to gate the command project-wide. ### Structural pre-pass with fallow Enable the optional fallow structural analysis pre-pass to catch architectural issues before the agent review runs. Set `code_quality.fallow.enabled: true` in `config.json` and GSD will produce a `{phase}/FALLOW.json` artifact and embed a **Structural Findings** section in `REVIEW.md`. ```json theme={null} { "code_quality": { "fallow": { "enabled": true, "scope": "phase", "profile": "standard" } } } ``` ## Autonomous audit-to-fix pipeline Run `/gsd-audit-fix` to run a full audit, classify all findings, auto-fix what can be fixed safely, verify each fix with tests, and commit atomically — all without manual intervention. ```bash theme={null} /gsd-audit-fix # Audit-uat, fix medium+ issues (max 5) /gsd-audit-fix --severity high # Only process high-severity findings /gsd-audit-fix --dry-run # Preview the classification table without fixing /gsd-audit-fix --max 10 --severity all # Fix up to 10 issues of any severity /gsd-audit-fix --source audit-uat # Specify which audit to run (default: audit-uat) ``` | Flag | Effect | | ------------------------------ | ----------------------------------------------------------------------------- | | `--source ` | Audit to run (default: `audit-uat`) | | `--severity high\|medium\|all` | Minimum severity to process (default: `medium`) | | `--max N` | Maximum number of findings to fix in one run (default: 5) | | `--dry-run` | Classify findings and print a classification table without applying any fixes | **Produces:** Fix commits with test verification for each resolved finding; a classification report listing finding type, severity, and disposition ## Test generation Run `/gsd-add-tests N` after a phase completes to generate a test suite for the code it produced. The command reads the phase's PLAN.md and SUMMARY.md to understand what was built and generates tests that verify the expected behavior. ```bash theme={null} /gsd-add-tests 2 # Generate tests for phase 2 ``` **Produces:** Test files committed alongside the phase code If you prefer tests written before implementation, enable TDD mode instead. Set `workflow.tdd_mode: true` in `config.json` or pass `--tdd` to `/gsd-plan-phase`. In TDD mode, the planner generates tasks that start with a failing test before any implementation code is written. ## Security threat verification Run `/gsd-secure-phase N` to retroactively verify that threat mitigations were implemented for a completed phase. The command reads the phase's threat model (from PLAN.md or an existing SECURITY.md) and walks through each threat to confirm the mitigation was actually applied. ```bash theme={null} /gsd-secure-phase # Audit the last completed phase /gsd-secure-phase 5 # Audit a specific phase ``` The command operates in three modes depending on what artifacts exist: Audits and verifies existing threat mitigations against the shipped code. Generates SECURITY.md from planning artifacts and then verifies mitigations. Exits with guidance — security verification requires executed code to analyze. **Produces:** `{phase}-SECURITY.md` with per-threat verification results Configure security enforcement settings in `config.json`: ```json theme={null} { "workflow": { "security_enforcement": true, "security_asvs_level": 1, "security_block_on": "high" } } ``` ## Nyquist coverage audit Run `/gsd-validate-phase N` to perform a retroactive Nyquist test coverage audit — verifying that the test coverage written during execution maps correctly to the requirements laid out in the phase plan. ```bash theme={null} /gsd-validate-phase 2 # Nyquist coverage audit for phase 2 ``` **Produces:** A coverage mapping report that identifies requirements with missing or insufficient test coverage, written to the phase directory The Nyquist audit uses the same coverage mapping engine as the plan-phase research step (controlled by `workflow.nyquist_validation`). Running `/gsd-validate-phase` gives you retroactive coverage analysis on phases that were executed before Nyquist was enabled, or after requirements have been revised. ## Quality gate summary Review phase changes by depth level. Use `--fix --auto` for a fully autonomous review-and-fix loop. Autonomous audit-to-fix pipeline with severity filtering, dry-run preview, and atomic commits. Generate a test suite for any completed phase based on its plan and implementation artifacts. Retroactive threat mitigation verification anchored to OWASP ASVS levels. Nyquist test coverage audit that maps requirements to tests and flags gaps. # Cross-AI Plan Review: Get Peer Feedback Before Writing Code Source: https://docs.opengsd.net/core/guides/cross-ai-review Send phase plans to multiple AI reviewers with /gsd-review, feed the results into replanning, and automate convergence with /gsd-plan-review-convergence. Cross-AI review lets you send your phase plans to multiple AI providers simultaneously and collect structured feedback before any code is written. Each reviewer produces an independent assessment of the plan's feasibility, risks, and gaps, and GSD synthesizes the results into a single `REVIEWS.md` artifact that the planner can consume directly to drive a more informed replan. ## Running /gsd-review Run `/gsd-review --phase N` to dispatch your phase plans to one or more AI reviewers. GSD reads the phase's PLAN.md files, assembles a review prompt that includes the roadmap, requirements, and context, and sends it to each selected reviewer in parallel. ```bash theme={null} /gsd-review --phase 2 # Run default configured reviewers /gsd-review --phase 2 --gemini # Gemini CLI only /gsd-review --phase 2 --codex # Codex CLI only /gsd-review --phase 2 --claude # Separate Claude session /gsd-review --phase 2 --opencode # OpenCode review /gsd-review --phase 2 --qwen # Qwen Code review /gsd-review --phase 2 --cursor # Cursor agent review /gsd-review --phase 2 --agy # Antigravity CLI review /gsd-review --phase 2 --all # Every available reviewer in parallel ``` | Flag | Reviewer | Requires | | ------------------------- | ------------------------- | ------------------------------------------------------- | | `--gemini` | Gemini CLI | `gemini` CLI installed and authenticated | | `--claude` | Claude (separate session) | `claude` CLI installed | | `--codex` | Codex CLI | `codex` CLI installed | | `--opencode` | OpenCode | `opencode` CLI installed | | `--qwen` | Qwen Code | Qwen CLI installed and API key set | | `--cursor` | Cursor agent | Cursor configured with agent access | | `--agy` / `--antigravity` | Antigravity CLI | Free with Google credentials | | `--all` | All detected reviewers | Each respective CLI must be installed and authenticated | **Produces:** `{phase}-REVIEWS.md` — a structured document containing each reviewer's feedback, severity classifications, and specific concerns about the plan ## Default reviewer configuration Rather than specifying reviewer flags on every run, set `review.default_reviewers` in `config.json` to scope the no-flag `/gsd-review` call to a subset of reviewers you always want: ```json theme={null} { "review": { "default_reviewers": ["gemini", "codex"] } } ``` With this config set, running `/gsd-review --phase 2` with no flags will use Gemini and Codex. Explicit reviewer flags override this setting for that run. `--all` always runs the full detected set regardless of config. ## How REVIEWS.md feeds back into planning After `/gsd-review` completes, pass `--reviews` to `/gsd-plan-phase` to replan using the cross-AI feedback as additional context. The planner reads `REVIEWS.md`, incorporates HIGH and MEDIUM concerns into revised task sequencing and risk mitigation, and produces an updated set of PLAN.md files. ```bash theme={null} /gsd-review --phase 2 --all # Step 1: collect reviews /gsd-plan-phase 2 --reviews # Step 2: replan with review feedback ``` `--reviews` skips the research step by default — it assumes your RESEARCH.md is still valid and focuses the planner's attention on addressing the specific concerns raised in REVIEWS.md. Combine `--reviews --research` to force a full research refresh before replanning. ## Automated convergence loop GSD exposes two entry points into the plan → review → replan loop: * **`/gsd-progress --next --auto --converge`** — the preferred hands-free surface. When `--next` routes to planning, the step is dispatched through `/gsd-plan-review-convergence` automatically, and converge mode is preserved across the rest of the `--auto` chain (plan → execute → verify → next phase). Use this when you want one command to drive the whole milestone under the convergence policy. * **`/gsd-plan-review-convergence N`** — the direct command. Use this when you only want to converge the plan for a specific phase without running the rest of the workflow. Both surfaces require `workflow.plan_review_convergence: true` and accept the same reviewer flags and `--max-cycles N`. `--cross-ai` is accepted as an alias for `--converge` on `/gsd-progress`. ```bash theme={null} # Direct convergence on a single phase /gsd-plan-review-convergence 3 # Default reviewers, 3 cycles max /gsd-plan-review-convergence 3 --codex # Codex-only convergence loop /gsd-plan-review-convergence 3 --all # All reviewers /gsd-plan-review-convergence 3 --all --max-cycles 5 # Extend cap to 5 cycles # Hands-free via /gsd-progress (planning steps route through convergence) /gsd-progress --next --auto --converge /gsd-progress --next --auto --converge --codex --max-cycles 4 /gsd-progress --next --auto --cross-ai --all ``` Either way, the underlying loop is the same — `/gsd-progress --next --auto --converge` just wires it into the standard workflow router so you do not have to invoke it phase-by-phase. If you request `--converge` while `workflow.plan_review_convergence` is `false`, the command stops before planning and prints the enable hint instead of silently falling back to `/gsd-plan-phase`. Spawns a planning agent to produce PLAN.md for the phase. Dispatches the plan to selected AI reviewers in parallel. Parses the `CYCLE_SUMMARY` from REVIEWS.md to count unresolved HIGH-severity concerns. If HIGH count is zero, the loop exits successfully. If HIGH count is non-zero and cycles remain, replans with `--reviews` feedback and repeats from Step 2. If the HIGH count stops decreasing across cycles, the command warns about a stall and offers the choice to proceed manually or extend the cycle cap. `/gsd-plan-review-convergence` is disabled by default. Enable it by setting `workflow.plan_review_convergence: true` in `config.json` before running the command. ## Configuring per-reviewer model selection You can specify which model each reviewer CLI should use by setting `review.models.` in `config.json`. When a key is absent, GSD uses each CLI's configured default. ```json theme={null} { "review": { "models": { "gemini": "gemini-2.5-pro", "opencode": "anthropic/claude-sonnet-4-6", "qwen": "qwen-max" } } } ``` Set these values interactively via `/gsd-config --integrations`. ## Prerequisites Before using cross-AI review, verify that each reviewer you plan to use is installed, authenticated, and reachable from your terminal. **Cloud CLIs (Gemini, Codex, OpenCode, Qwen, Cursor):** Run the CLI with `--version` or a simple query to confirm it is installed and authenticated with a valid API key. **Antigravity (agy):** Free with Google credentials. Install the CLI and authenticate with your Google account before running. Local model servers (Ollama, LM Studio, llama.cpp) are supported as reviewers in `/gsd-plan-review-convergence` but not in `/gsd-review`. Use `/gsd-plan-review-convergence` with the `--ollama`, `--lm-studio`, or `--llama-cpp` flags to run the full convergence loop against a local model. # Starting a New Project: GSD Core Initialization Guide Source: https://docs.opengsd.net/core/guides/new-project Set up a new GSD Core project using the interactive wizard, a spec file, or existing design documents such as ADRs and PRDs, then plan your first phase. Every GSD Core project begins with a single initialization step that captures your goals, requirements, and roadmap before any code is written. Running `/gsd-new-project` creates a structured `.planning/` directory that all subsequent workflow commands read from, giving every subagent a fresh, focused context window instead of a growing pile of chat history. ## Interactive initialization Run `/gsd-new-project` with no flags to enter the interactive flow. GSD will walk you through a series of questions about your project, gathering the information it needs to generate a complete planning foundation. ```bash theme={null} /gsd-new-project ``` During the interactive session you will be prompted to describe: * **Project name and purpose** — a plain-language description of what you are building and why * **Target users and use cases** — who will use the system and what problems it solves for them * **Key requirements** — functional and non-functional constraints (performance, security, compliance) * **Technology preferences** — preferred languages, frameworks, and infrastructure choices * **Known constraints** — timelines, team size, integration dependencies Answer each prompt as concisely or as thoroughly as you like. GSD synthesizes your answers into structured artifacts rather than storing raw conversation, so more detail produces more accurate planning output. GSD requires no existing `.planning/PROJECT.md` to run. If one already exists, the command exits with a warning to protect your current project state. ## Automated initialization from a spec file If you already have a PRD, RFC, or design document, pass it directly to `/gsd-new-project` with `--auto` to skip the interactive questions entirely. ```bash theme={null} /gsd-new-project --auto @spec-file.md ``` GSD reads the referenced document, extracts project goals, requirements, and constraints automatically, and generates all planning artifacts without prompting you. Use this path when your spec file already captures enough context to produce a meaningful roadmap. The `@` prefix is the standard way to reference a file in your project. GSD resolves the path relative to your project root. You can pass any Markdown file — PRD, RFC, user story map, or architecture doc. ## What gets created Both initialization paths produce the same set of artifacts in `.planning/`: High-level project description, goals, target users, and success criteria. All agents read this file to understand what they are building. Structured functional and non-functional requirements. The plan-phase and verify-phase use these as the acceptance baseline. Milestone and phase breakdown. Defines the delivery sequence that `/gsd-autonomous`, `/gsd-manager`, and all phase commands follow. Live project state: which phases are complete, in progress, or pending. Updated automatically after each phase transition. Project configuration: model profile, granularity, workflow toggles, and integration settings. Edit via `/gsd-settings` or `/gsd-config`. ## Bootstrapping from existing documents If your repository already contains ADRs, PRDs, SPECs, or other structured documentation, use `/gsd-ingest-docs` instead of starting from scratch. This command scans your repository, classifies each document, and synthesizes the results into a complete `.planning/` setup. ```bash theme={null} /gsd-ingest-docs # Scan repo root, auto-detect mode /gsd-ingest-docs docs/ # Only ingest documents under docs/ /gsd-ingest-docs --manifest ingest.yaml # Use explicit precedence manifest ``` `/gsd-ingest-docs` operates in two modes detected automatically: * **`new`** — no `.planning/` directory exists; creates a full project setup from your documents * **`merge`** — `.planning/` already exists; merges ingested content with your current project state When documents contradict each other, `/gsd-ingest-docs` produces an `INGEST-CONFLICTS.md` file that categorizes conflicts into three buckets: * **Auto-resolved** — GSD chose the higher-precedence document and recorded its reasoning * **Competing variants** — multiple valid options exist; GSD flags them for your review * **Unresolved blockers** — LOCKED-vs-LOCKED ADR contradictions that require human resolution before planning can begin The command hard-blocks on unresolved blockers. Resolve them in your source documents or use `--manifest ingest.yaml` to assign explicit precedence before re-running. `/gsd-ingest-docs` caps at 50 documents per invocation. For larger document sets, split the ingest into multiple runs using the `--manifest` flag to control precedence across batches. ## Next steps After initialization, run `/gsd-progress` to see a summary of your new project and the recommended next command. For most projects, that will be `/gsd-discuss-phase 1` to begin the first phase's context-gathering discussion. ```bash theme={null} /gsd-progress # Show project status and recommended next step ``` # GSD Core Phase Lifecycle: From First Discussion to Ship Source: https://docs.opengsd.net/core/guides/phase-lifecycle Walk through every step of a GSD Core phase, from discuss through plan, execute, verify, and ship, with all commands and artifacts explained. Every phase in GSD Core follows the same five-step loop: discuss, plan, execute, verify, ship. Each step runs in a fresh subagent context window, which means the AI starts each step with exactly the context it needs rather than a polluted history of everything that happened before. This architecture is why GSD maintains consistent output quality even on large projects with many phases. ## Step 1 — Discuss the phase Before any planning begins, run `/gsd-discuss-phase N` to surface implementation decisions that would otherwise become hidden assumptions inside a plan. The command asks targeted questions about the phase, records your answers, and writes a structured context document for the planner to consume. ```bash theme={null} /gsd-discuss-phase 1 # Interactive discussion for phase 1 /gsd-discuss-phase 1 --all # Discuss all gray areas without a selection step /gsd-discuss-phase 3 --auto # Auto-select recommended defaults for phase 3 /gsd-discuss-phase 1 --batch # Group questions for batch intake /gsd-discuss-phase 2 --analyze # Add trade-off analysis during discussion /gsd-discuss-phase 1 --power # Bulk answers from a prepared answers file /gsd-discuss-phase 3 --assumptions # Surface Claude's assumptions before planning ``` | Flag | Effect | | --------------- | ----------------------------------------------------------------------------------------------- | | `--all` | Skip area selection and discuss every gray area interactively | | `--auto` | Auto-select recommended defaults for all questions; no user input required | | `--batch` | Group related questions together for faster batch intake | | `--analyze` | Adds trade-off analysis to each decision before recording the answer | | `--power` | Reads a pre-prepared answers file and applies answers in bulk | | `--assumptions` | Generates a list of Claude's current assumptions about the phase without an interactive session | **Produces:** `{phase}-CONTEXT.md` (structured implementation decisions), `{phase}-DISCUSSION-LOG.md` (full audit trail of the session) ## Step 2 — Plan the phase Run `/gsd-plan-phase N` to research the problem domain, decompose work into executable plans, and verify that each plan fits within a fresh 200k-token context window. The planner reads your ROADMAP, REQUIREMENTS, and CONTEXT documents and produces one PLAN.md per parallel execution wave. ```bash theme={null} /gsd-plan-phase 1 # Research + plan + verify for phase 1 /gsd-plan-phase 1 --skip-research # Skip domain research (familiar territory) /gsd-plan-phase 1 --tdd # Enable red-green-refactor task sequencing /gsd-plan-phase 1 --mvp # Organize tasks as vertical feature slices /gsd-plan-phase 2 --granularity fine # Override granularity for this run only /gsd-plan-phase 1 --bounce # Run external validation after planning /gsd-plan-phase 2 --reviews # Replan with cross-AI review feedback /gsd-plan-phase 2 --gaps # Gap-closure mode (reads VERIFICATION.md) /gsd-plan-phase 2 --prd design.md # Use a PRD file instead of discuss output ``` | Flag | Effect | | ---------------------------------------- | ------------------------------------------------------------------------------- | | `--skip-research` | Skip domain research (useful when the domain is well understood) | | `--research` | Force re-research even when RESEARCH.md already exists | | `--gaps` | Gap-closure mode — reads VERIFICATION.md to address open issues, skips research | | `--prd ` | Use a PRD file as phase context instead of the discuss-phase output | | `--mvp` | Planner organizes tasks as vertical feature slices (UI→API→DB) | | `--tdd` | Apply red-green-refactor sequencing to eligible behavior-adding tasks | | `--granularity ` | Override planning granularity for this invocation only | | `--bounce` | Run external plan validation script after planning | | `--reviews` | Feed REVIEWS.md cross-AI feedback back into replanning | **Produces:** `{phase}-RESEARCH.md`, one or more `{phase}-{N}-PLAN.md` files, `{phase}-VALIDATION.md` Set `workflow.research: false` in `config.json` to permanently skip research for all phases. You can also skip it per-run with `--skip-research` without changing config. ## Step 3 — Execute the phase Run `/gsd-execute-phase N` to execute all plans in the phase. GSD groups plans into dependency-ordered waves and runs each wave in parallel using git worktrees, so independent plans execute simultaneously without conflicting. Each executor agent starts with a clean context window and the full plan as its sole input. ```bash theme={null} /gsd-execute-phase 1 # Execute all waves in phase 1 /gsd-execute-phase 1 --wave 2 # Execute only Wave 2 (resume after interruption) /gsd-execute-phase 1 --gaps-only # Execute only gap-closure plans after verify-work /gsd-execute-phase 1 --interactive # Execute plans sequentially with user checkpoints ``` | Flag | Effect | | --------------- | ---------------------------------------------------------------------------------------------------------------- | | `--wave N` | Execute only the specified wave; useful for resuming after an interruption | | `--gaps-only` | Execute only gap-closure plans (those created by verify-work to fix failing requirements) | | `--interactive` | Execute plans sequentially inline with user checkpoints between tasks; lower token usage, pair-programming style | **Produces:** Per-plan `{phase}-{N}-SUMMARY.md` files, git commits for all code changes, and `{phase}-VERIFICATION.md` when the phase finishes Wave-based parallelization uses git worktrees by default. If your environment does not support worktrees, set `workflow.use_worktrees: false` in `config.json` to fall back to sequential execution. ## Step 4 — Verify the work Run `/gsd-verify-work N` to perform user acceptance testing against the phase goals. The verifier walks through what was built, checks each requirement from CONTEXT.md and REQUIREMENTS.md, and generates fix plans for anything that did not meet the acceptance criteria. ```bash theme={null} /gsd-verify-work 1 # UAT for phase 1 ``` **Produces:** `{phase}-UAT.md` with acceptance status per requirement; fix plans for any failures that require remediation before shipping Do not skip verification before running `/gsd-ship`. The ship command expects a passing verification record. If you need to ship with known gaps, address them with `/gsd-plan-phase --gaps` and re-execute before shipping. ## Step 5 — Ship the phase Run `/gsd-ship N` to create a GitHub pull request from the completed phase work. GSD generates a rich PR body from your planning artifacts — requirements addressed, key decisions, verification evidence — so reviewers have full context without reading the planning files directly. ```bash theme={null} /gsd-ship 1 # Create PR for phase 1 /gsd-ship 1 --draft # Create as a draft PR ``` **Prerequisites:** `gh` CLI installed and authenticated, phase verified by `/gsd-verify-work` **Produces:** GitHub PR with auto-generated body, STATE.md updated to mark the phase as shipped ## Tracking progress Use `/gsd-progress` at any point to see where you are in the lifecycle and what the recommended next step is. ```bash theme={null} /gsd-progress # Show project status and next recommended step /gsd-progress --next # Auto-advance to the next workflow step /gsd-progress --do "fix the auth bug" # Dispatch freeform intent to the best command /gsd-progress --forensic # Standard report + 6-check integrity audit ``` Reads STATE.md and automatically dispatches the next logical command — discuss, plan, execute, verify, or ship — without asking. Accepts a freeform description of what you want to do and routes it to the most appropriate GSD command. Appends a six-check integrity audit: STATE consistency, orphaned handoffs, deferred scope drift, memory-flagged pending work, blocking TODOs, and uncommitted code. ## Complete lifecycle at a glance `/gsd-discuss-phase N` → captures decisions → writes CONTEXT.md `/gsd-plan-phase N` → researches domain → decomposes work → writes PLAN.md files `/gsd-execute-phase N` → runs plans in parallel waves → writes code commits and SUMMARY.md files `/gsd-verify-work N` → runs acceptance tests → writes UAT.md and any fix plans `/gsd-ship N` → creates GitHub PR → updates STATE.md # Install GSD Core into Any AI Coding Runtime in Minutes Source: https://docs.opengsd.net/core/installation Install GSD Core with a single npx command. The interactive installer configures your chosen runtime, scope, and hooks in under two minutes. GSD Core installs as a set of commands, agents, workflows, and hooks into the configuration directory of your AI coding runtime. The installer handles all runtime-specific adaptation automatically — you answer a few questions, and it writes the correct files to the correct paths. ## Requirements Before you begin, confirm your environment meets these prerequisites: * **Node.js** ≥ 22.0.0 * **npm** ≥ 10.0.0 Check your versions with: ```bash theme={null} node --version npm --version ``` If you need to manage multiple Node.js versions, use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm). GSD Core requires Node.js 22 for its native fetch support and ESM compatibility. ## Run the installer Run the installer with a single command: ```bash theme={null} npx @opengsd/gsd-core@latest ``` The installer is interactive and will guide you through the setup. Do not copy files from `agents/` or `commands/` directly — the installer applies runtime-specific transformations that are required for each target environment. ## Interactive installer walkthrough The installer prompts you to choose which AI coding runtime to target. Select the one you use — for example, Claude Code, Gemini CLI, Codex, or Cursor. If you use multiple runtimes, run the installer once per runtime, or pass `--all` to install for every supported runtime at once. Choose between a **global** install (affects all projects on your machine) or a **local** install (affects only the current project directory). * **Global** is recommended for most users. Commands and agents are available in every project. * **Local** is useful when you need project-specific GSD configurations or want to keep GSD isolated to one repository. The installer lists the files it will write — commands, agents, workflows, references, templates, and hooks — along with their destination paths. Review the list and confirm to proceed. For most runtimes, the installer registers GSD's runtime hooks automatically: * **Status line hook** — displays model, task, directory, and context usage bar * **Context monitor hook** — injects agent-facing warnings when context runs low * **Prompt guard hook** — scans `.planning/` writes for injection patterns For Claude Code, the installer also pre-populates `settings.json` with the permissions GSD needs, eliminating first-run approval prompts. ## Command prefixes by runtime GSD Core ships the same commands to every runtime, but the invocation syntax differs. Use the correct prefix for your runtime: Commands use the **hyphen form**: ```text theme={null} /gsd-command-name ``` **Examples:** ```text theme={null} /gsd-new-project /gsd-plan-phase 1 /gsd-execute-phase 1 ``` Commands use the **colon form** — Gemini namespaces all plugin commands under the plugin ID: ```text theme={null} /gsd:command-name ``` **Examples:** ```text theme={null} /gsd:new-project /gsd:plan-phase 1 /gsd:execute-phase 1 ``` The installer rewrites all body-text references to the colon form automatically during a `--gemini` install. When following walkthroughs written for Claude Code, replace every `/gsd-` prefix with `/gsd:`. Commands use the **dollar-prefix skill form**: ```text theme={null} $gsd-command-name ``` **Examples:** ```text theme={null} $gsd-new-project $gsd-plan-phase 1 $gsd-execute-phase 1 ``` Codex CLI version **≥ 0.130.0** is required for full GSD Core compatibility. Run `codex --version` to check. ## Runtime-specific install flags If you prefer to skip the interactive prompts, pass runtime and scope flags directly: ```bash theme={null} # Claude Code, global npx @opengsd/gsd-core@latest --claude --global # Gemini CLI, global npx @opengsd/gsd-core@latest --gemini --global # Codex, local npx @opengsd/gsd-core@latest --codex --local # Cursor, global npx @opengsd/gsd-core@latest --cursor --global # Windsurf / Devin Desktop, global (--windsurf and --devin-desktop are equivalent) npx @opengsd/gsd-core@latest --windsurf --global npx @opengsd/gsd-core@latest --devin-desktop --global # Antigravity, global npx @opengsd/gsd-core@latest --antigravity --global # Cline, global npx @opengsd/gsd-core@latest --cline --global # All supported runtimes, global npx @opengsd/gsd-core@latest --all --global ``` Windsurf rebranded to **Devin Desktop**. Both `--windsurf` and `--devin-desktop` select the same runtime — use whichever name matches the product you have installed. Global skills always land in `~/.codeium/windsurf/`. ## Workspace directory migrations Two runtimes have moved their **local** (workspace) install directories to new canonical paths. Fresh `--local` installs write to the new path; the legacy path is still recognized for backward compatibility, so existing projects keep working without manual changes. Global install paths (`~/.codeium/windsurf/`, `~/.gemini/antigravity/`) are unchanged. | Runtime | New workspace path | Legacy path (still recognized) | | ------------------------ | ------------------ | ------------------------------ | | Windsurf / Devin Desktop | `.devin/skills/` | `.windsurf/skills/` | | Antigravity | `.agents/` | `.agent/` | When upgrading an existing project, you have two options: * **Do nothing.** GSD continues to read from the legacy path. This is the safest option for projects shared across teammates who may not have upgraded yet. * **Migrate to the new path.** Re-run the installer with `--local` in your project directory. GSD writes new artifacts under the canonical path and the legacy directory can be removed once every collaborator is on a current GSD release. ```bash theme={null} # Migrate a project from .windsurf/skills/ → .devin/skills/ npx @opengsd/gsd-core@latest --windsurf --local # Migrate a project from .agent/ → .agents/ npx @opengsd/gsd-core@latest --antigravity --local ``` ## Verify the installation After the installer completes, open your runtime and run: ```text theme={null} /gsd-new-project ``` If the command is recognized and begins asking you questions about your project, the installation succeeded. For Gemini CLI users, run `/gsd:new-project` instead. ## Start your first project Once GSD Core is installed, run `/gsd-new-project` to begin. The command walks you through an interactive session to define your project, runs parallel research agents to understand your domain, generates a `REQUIREMENTS.md` and `ROADMAP.md`, and leaves you ready to start the phase loop. See the [Quickstart](/core/quickstart) guide for a complete walkthrough of your first project from install to shipped phase. ## Updating GSD Core To update to the latest stable release, run the same install command again — the installer is idempotent and backs up any locally modified files to `gsd-local-patches/` before overwriting: ```bash theme={null} npx @opengsd/gsd-core@latest ``` To install the release candidate channel instead, use your runtime's update command: ```text theme={null} /gsd-update --next ``` # GSD Core: Spec-Driven Development for AI Coding Agents Source: https://docs.opengsd.net/core/introduction GSD Core is a spec-driven framework that keeps AI coding agents on track across sessions — fresh context, persistent artifacts, and verified output. GSD Core is a lightweight meta-prompting, context-engineering, and spec-driven development framework that sits on top of any AI coding runtime. Rather than replacing your editor or AI assistant, GSD Core gives it structure: a repeatable phase loop, a set of specialist subagents, and a `.planning/` directory of human-readable artifacts that survive every session boundary, every `/clear`, and every context reset. ## The problem GSD Core solves Most AI-coding setups work well for small tasks but degrade silently as projects grow. Three forces cause the breakdown: **Context rot.** As a conversation grows, the AI fills its context window with accumulated back-and-forth. Recall weakens, reasoning degrades, and output quality quietly drops — without any warning to you or the model. **No shared memory between sessions.** Start a new session and the AI knows nothing about yesterday's decisions, your architecture choices, or the bugs you already ruled out. You spend the first ten minutes re-explaining what already happened. **No verification that code works.** Most AI coding flows end at "execution complete." Nothing checks that what was built actually satisfies the requirements, passes tests, or matches the design you approved. GSD Core solves all three. Heavy research, planning, and execution work runs in fresh-context subagents so context rot never accumulates. Structured artifacts like `STATE.md`, `CONTEXT.md`, and `continue-here.md` persist everything important across session boundaries. And the Verify step walks through what was built, diagnoses gaps, and generates fix plans before a phase is declared done. ## Supported runtimes GSD Core installs its commands, agents, and hooks into whichever AI coding runtime you use. The same phase loop and artifact structure work across all of them. The installer handles all runtime-specific adaptation at install time. You never need to copy or modify files from the `agents/` or `commands/` directories manually. ## How it works GSD Core structures every milestone as a repeatable five-step loop, one phase at a time: 1. **Discuss** — capture your implementation decisions before anything is planned 2. **Plan** — run parallel research agents, decompose work into atomic tasks, verify the plan fits a fresh context window 3. **Execute** — run plans in parallel execution waves; each executor starts with a clean context window of up to 200K tokens 4. **Verify** — walk through what was built, run tests, diagnose gaps, and produce fix plans before declaring done 5. **Ship** — create the PR, archive the phase artifacts, and move to the next phase Each step produces artifacts that feed the next. Nothing is held in conversation memory — everything is written to disk in `.planning/` as plain Markdown and JSON. ## Get started Install GSD Core with one command and walk through the interactive setup for your runtime. Initialize your first project, run the five-step phase loop, and ship your first PR. # GSD Core Quickstart: From Install to Shipped Phase Source: https://docs.opengsd.net/core/quickstart Walk through a complete GSD Core project cycle — initialize, discuss, plan, execute, verify, and ship your first phase in one session. This guide walks you through your first complete GSD Core project cycle. By the end, you will have initialized a project, run the full five-step phase loop, and created a pull request for your first shipped phase. Each step takes two to five minutes; the full cycle typically runs in under an hour for a well-scoped phase. The commands below use the Claude Code / Copilot / OpenCode / Kilo hyphen form (`/gsd-command-name`). If you are on Gemini CLI, replace `/gsd-` with `/gsd:`. If you are on Codex, replace `/gsd-` with `$gsd-`. If you have not already installed GSD Core, run the installer now: ```bash theme={null} npx @opengsd/gsd-core@latest ``` The installer prompts for your runtime and installation scope. For full details, see the [Installation](/core/installation) guide. After the installer completes, open your AI coding runtime in your project directory. Run the new-project command to set up your project's planning artifacts: ```text theme={null} /gsd-new-project ``` GSD Core guides you through an interactive session to capture your project vision, constraints, and scope. It then spawns four parallel research agents to explore your domain — one each for stack, features, architecture, and common pitfalls. **What gets created:** | File | Purpose | | --------------------------- | ----------------------------------------------------- | | `.planning/PROJECT.md` | Project vision, constraints, and evolution rules | | `.planning/REQUIREMENTS.md` | Scoped v1/v2 requirements with IDs | | `.planning/ROADMAP.md` | Phase breakdown with status tracking | | `.planning/STATE.md` | Living session memory — decisions, blockers, position | | `.planning/config.json` | Workflow configuration | | `.planning/research/` | Domain research from the parallel researchers | Review the generated `ROADMAP.md` and approve it when prompted. GSD Core will not proceed until you confirm the roadmap reflects what you intend to build. After `/gsd-new-project` completes, run `/clear` (or your runtime's equivalent) to start the phase loop with a fresh context window. GSD Core is designed around fresh contexts — all important state lives in `.planning/`, not in conversation history. Lock in your implementation preferences before planning begins: ```text theme={null} /gsd-discuss-phase 1 ``` GSD Core reads your `ROADMAP.md` and asks targeted questions about the implementation choices for Phase 1 — library preferences, design patterns, testing approach, and any gray areas where there are multiple valid options. Your answers are written to `.planning/phases/01-*/CONTEXT.md`. **Why this matters:** most plan quality issues happen because the AI makes assumptions that a discussion would have prevented. Running discuss-phase before plan-phase ensures the planner has your explicit preferences, not inferred ones. Answer each question, then move on when the discussion is complete. Run the planner to research, decompose, and verify the work: ```text theme={null} /gsd-plan-phase 1 ``` GSD Core spawns four parallel phase researchers (stack, features, architecture, pitfalls), synthesizes their findings into `RESEARCH.md`, then passes everything to the planner. The planner creates two to three atomic execution plans, each sized to fit in a single fresh context window. A plan-checker agent then reviews the plans across eight dimensions — requirement coverage, task atomicity, dependency ordering, context fit, and more. If the plans fail the check, the planner revises them automatically (up to three iterations) before surfacing the result to you. **What gets created:** ```text theme={null} .planning/phases/01-phase-name/ 01-CONTEXT.md ← your preferences from discuss-phase 01-RESEARCH.md ← synthesized ecosystem research 01-01-PLAN.md ← first atomic execution plan 01-02-PLAN.md ← second atomic execution plan (if needed) ``` Review the plans when prompted and approve them to proceed. Run the executor to implement the plans: ```text theme={null} /gsd-execute-phase 1 ``` GSD Core analyzes the plan dependencies, groups plans into waves, and spawns parallel executor subagents — each with a fresh context window of up to 200K tokens. Each executor reads only its assigned plan, makes an atomic git commit per completed task, and writes a `SUMMARY.md` documenting what it built and any deviations from the plan. After all executors complete, a verifier agent runs a goal-backward check: it walks through what was built, runs your test suite, and writes `VERIFICATION.md` with a PASS or FAIL verdict and specific evidence. Subagents run in a separate context window — their work is invisible to the main session while in progress. Do not interrupt the session. Research and planning agents routinely take one to five minutes to complete. Run user acceptance testing on what was built: ```text theme={null} /gsd-verify-work 1 ``` GSD Core reads `VERIFICATION.md` and walks you through a structured UAT session. You test the implemented features against the phase goals, document your findings, and mark the phase as verified or flag issues for a fix cycle. **What gets created:** ```text theme={null} .planning/phases/01-phase-name/ 01-VERIFICATION.md ← automated verification results 01-UAT.md ← your acceptance test results ``` If verification reveals problems, GSD Core generates a targeted fix plan. Run `/gsd-debug "description"` for a guided debugging session, or re-run `/gsd-execute-phase 1` after adjusting the plan. Create a pull request for the verified work: ```text theme={null} /gsd-ship 1 ``` GSD Core reads the phase artifacts — plans, summaries, and verification results — and generates a structured pull request body with sections for what changed, why, and how it was verified. It then archives the phase state and advances `STATE.md` to the next phase. Your first phase is shipped. Run `/clear` and start the loop again with `/gsd-discuss-phase 2` for the next phase. Run `/gsd-progress` at any time to see exactly where you are in the project lifecycle and what the next recommended step is. If you need to pause and resume later, run `/gsd-resume-work` at the start of your next session to restore full context from `.planning/continue-here.md`. ## Full command reference The table below summarizes the commands you used and their key flags: | Command | Purpose | Key flags | | ---------------------- | ---------------------------------------- | ----------------------------------------- | | `/gsd-new-project` | Initialize project artifacts and roadmap | `--auto @file.md` to ingest from a PRD | | `/gsd-discuss-phase N` | Capture implementation preferences | `--chain` to auto-advance to planning | | `/gsd-plan-phase N` | Research, plan, and verify | `--skip-research` when domain is familiar | | `/gsd-execute-phase N` | Run plans in parallel waves | — | | `/gsd-verify-work N` | Run user acceptance testing | — | | `/gsd-ship N` | Create PR and archive phase | `--draft` for a draft PR | | `/gsd-progress` | Show current position and next step | `--next` to auto-detect and run next step | ## Next steps Understand the five-step phase loop and how spec-driven development structures your work. Learn what each file in `.planning/` contains and how artifacts feed into each other. Explore the specialist subagent system and understand what each agent does. Learn how GSD Core prevents context rot and maintains state across sessions. # Corpus and extraction Source: https://docs.opengsd.net/graph/corpus Choose source files, write explicit relationships, and review inferred facts. With no configured corpus, GSD Graph discovers documentation directories such as `.planning`, `docs`, `doc`, `wiki`, and `architecture`. It also checks top-level files such as `README.md`, `CHANGELOG.md`, `AGENTS.md`, and `CLAUDE.md`. It does not index the whole repository or all of `src/` by default. ## Choose sources Add roots to project sync: ```bash theme={null} gsd-graph sync --corpus ./specs --corpus ./adr ``` Use the explicit build pipeline when you want to supply the corpus directly: ```bash theme={null} gsd-graph build --corpus ./docs ``` Set `corpus` in `.gsd-graph/config.json` for a persistent corpus choice. Use `sync --full` after changes that require all sources to be re-extracted. ## Write explicit relationships The deterministic extractor reads structured content such as headings, wiki links, edge lines, JSONL records, and supported YAML/frontmatter fields. ```markdown theme={null} [[Auth]] --part_of--> [[API]] [[RateLimit]] --causes--> [[429s]] ``` Free prose alone does not produce typed relationship edges. Confidence tiers are `EXTRACTED`, `INFERRED`, and `AMBIGUOUS`; retrieval favors stronger evidence. ## Extract from prose Prompt mode prepares an extraction request for your host agent: ```bash theme={null} gsd-graph sync --llm ``` The agent reads `.gsd-graph/.prompt-extract.json` and writes the requested result to `.gsd-graph/.prompt-extract-result.json`. Apply it with: ```bash theme={null} gsd-graph prompt apply extract ``` The CLI does not call an endpoint in prompt mode. Your host agent's own model and data handling still apply. For direct endpoint calls, use `sync --llm http` and configure `llm.http` with `provider`, `model`, and `api_key_env`; `base_url` is optional. The supported provider formats are OpenAI and Anthropic. LLM candidates receive `INFERRED` confidence and LLM provenance. Unknown types or predicates go through the same ontology review gate as deterministic extraction. ## Choose an ontology | Pack | Purpose | | ------------- | ------------------------------------------------ | | `general` | General relationships; the default | | `engineering` | Services, incidents, requirements, and decisions | | `research` | Papers, claims, and authors | ```bash theme={null} gsd-graph init --ontology engineering gsd-graph ontology show gsd-graph ontology validate ``` Inspect candidates before resolving them: ```bash theme={null} gsd-graph review summary gsd-graph review list gsd-graph review accept gsd-graph review reject ``` Use `review accept --extend-ontology` when you intend to extend the schema. `gsd-graph ontology eject` writes the active pack and accepted extensions into a local pack you can commit. # Installation Source: https://docs.opengsd.net/graph/installation Install the CLI, enable a project, and update your GSD Graph setup. You need Node.js 22 or newer and npm 10 or newer, as required by the package. Run project commands from the repository you want to index. ## Install the CLI ```bash theme={null} npm install -g @opengsd/gsd-graph ``` Enable the current project and register supported MCP hosts: ```bash theme={null} gsd-graph enable --mcp ``` `enable` installs the agent skill and project hooks, writes `.gsd-graph/config.json`, and runs a full sync of the discovered corpus. It mirrors settings into `.planning/config.json` only when that file already exists. Use `gsd-graph enable --skip-sync` to install the integration without building the graph. See [MCP setup](/graph/mcp) for host registration and restart steps. ## Run without a global install Use the scoped package name so npx resolves the binary: ```bash theme={null} npx -y @opengsd/gsd-graph enable npx -y @opengsd/gsd-graph status ``` For reproducible automation, pin a release rather than resolving the latest package on each run. ## Use the library Install a project dependency when application code imports the Node.js API: ```bash theme={null} npm install @opengsd/gsd-graph ``` The package includes TypeScript declarations. A local installation also makes `npx gsd-graph` available in that project. ## Update ```bash theme={null} npm install -g @opengsd/gsd-graph@latest gsd-graph --version ``` Continue with the [quickstart](/graph/quickstart). # GSD Graph Source: https://docs.opengsd.net/graph/introduction Build a local relationship graph from project documents and answer questions with source citations. GSD Graph stores relationships from your documentation and planning files as subject–predicate–object triples with source provenance. You can follow dependency chains, inspect decisions, and answer questions from a focused subgraph. The default extraction and answer paths run locally without an API key. Optional LLM stages add prose extraction and grounded answers. GSD Graph runs independently of GSD Core, GSD Path, and Python graphify. Install the CLI and ask a question about an explicit relationship chain. Keep your graph current and choose between ask, query, pack, and why. Register the MCP server and choose which write tools to enable. Learn what gets indexed and how prose becomes relationships. ## How it works ```text theme={null} extract → normalize → store → query → ground → maintain ``` The canonical store is `.gsd-graph/graph.v1.json`. Queries retrieve relevant nodes, triples, paths, and citations. Answers use this evidence and can abstain when there is no supporting subgraph. Use GSD Graph for relationships in project knowledge. For source-code callers, imports, and change impact, use a code graph tool. GSD Graph does not scan all of `src/` by default. See the [source repository](https://github.com/open-gsd/gsd-graph) and [release history](https://github.com/open-gsd/gsd-graph/blob/main/CHANGELOG.md). # MCP setup Source: https://docs.opengsd.net/graph/mcp Connect GSD Graph to your agent and enable graph writes only when needed. Register the MCP server from your project directory: ```bash theme={null} gsd-graph mcp install ``` The installer supports Claude Code, Codex, Cursor, and a project `.mcp.json`. Restart your host after registration, then check the installation: ```bash theme={null} gsd-graph mcp doctor ``` Select hosts explicitly when needed: ```bash theme={null} gsd-graph mcp install --host claude --host project ``` ## Default tools | Tool | Purpose | | ------------------- | -------------------------------------------------- | | `graph_status` | Counts and graph health | | `graph_query` | Query, neighborhood, path, and filter operations | | `graph_pack` | Evidence subgraph with citations | | `graph_answer` | Grounded answers and global themes | | `graph_why` | Cited explanations of paths | | `graph_resolve` | Resolve terms to node IDs | | `graph_diff` | Compare against a graph baseline | | `graph_communities` | Detect themes; read-only unless writing is enabled | | `graph_review_list` | Inspect pending review items | The resources `gsd-graph://report` and `gsd-graph://communities` expose the human report and community themes for agent briefings. ## Enable write tools | Permission | Tools | | -------------------------------------------------- | ------------------------------- | | `--allow-build` or `mcp.allow_build` | `graph_build`, `graph_sync` | | `--allow-review-write` or `mcp.allow_review_write` | `graph_review_resolve` | | `--allow-assert` or `mcp.allow_assert` | `graph_assert`, `graph_retract` | For example, register with build permission: ```bash theme={null} gsd-graph mcp install --allow-build ``` Restart the host after changing registration. Write permissions are off by default; choose them for the work you want your agent to perform. ## Manual launch A global package installation provides the stdio server: ```bash theme={null} gsd-graph-mcp ``` Use an absolute store path when the MCP host does not start in your project: ```bash theme={null} gsd-graph-mcp --dir /absolute/path/to/project/.gsd-graph ``` # Quickstart Source: https://docs.opengsd.net/graph/quickstart Build a graph from an explicit relationship chain and inspect a cited answer. Complete [installation](/graph/installation) first. This example uses explicit relationships so the default extractor can build a multi-hop path without an LLM. Run it in a project where you can add a documentation file. Create `docs/graph-example.md` with this content: ```markdown theme={null} # Supply chain [[Drought]] --causes--> [[Crop Failure]] [[Crop Failure]] --causes--> [[Food Shortage]] ``` ```bash theme={null} gsd-graph enable gsd-graph status ``` `enable` indexes the discovered documentation corpus. Check the node and triple counts in status. In an already enabled project, use `gsd-graph sync`. ```bash theme={null} gsd-graph ask "why does drought cause food shortage?" gsd-graph why "Drought" "Food Shortage" ``` Check that the answer cites the relationship chain in `docs/graph-example.md`. To inspect the evidence used for an answer: ```bash theme={null} gsd-graph pack "why does drought cause food shortage?" ``` After changing your documents, refresh the graph: ```bash theme={null} gsd-graph sync ``` You can also export an interactive view: ```bash theme={null} gsd-graph export --format html --open ``` Ordinary prose does not automatically become typed relationships. If an answer abstains, inspect your corpus and extraction mode before assuming it is a failure. Continue with [daily use](/graph/workflow), [corpus and extraction](/graph/corpus), or [MCP setup](/graph/mcp). # Reference and troubleshooting Source: https://docs.opengsd.net/graph/reference Find store files, output modes, common commands, and recovery steps. ## Store files | Path under `.gsd-graph/` | Role | | ------------------------ | -------------------------------------------------- | | `graph.v1.json` | Canonical graph used by native queries and answers | | `config.json` | Project configuration | | `sources.manifest.json` | Source fingerprints for incremental sync | | `review-queue.json` | Candidates that need review | | `ontology.lock.json` | Resolved ontology snapshot | | `episodes.jsonl` | Recorded assertions and retractions | | `snapshots/` | Saved canonical graphs | | `graph.json` | Disposable viewer projection | | `GRAPH_REPORT.md` | Human summary | | `communities/` | Disposable theme reports | ## Output and store selection Interactive `ask`, `why`, `status`, `query`, and `top` commands can render human output. Use `--json` for machine output; piped output and CI also use JSON. ```bash theme={null} gsd-graph --json status gsd-graph --dir ./my-store status ``` `GSD_GRAPH_DIR` also selects the store. The default is `.gsd-graph`. ## Additional commands | Command | Purpose | | ------------------------------------- | -------------------------------------- | | `gsd-graph sync --full --report` | Re-extract and write a report | | `gsd-graph communities detect` | Detect corpus themes | | `gsd-graph export --format mermaid` | Export a diagram | | `gsd-graph export --format graphml` | Export GraphML | | `gsd-graph export --format cypher` | Export Cypher | | `gsd-graph embeddings build` | Build an opt-in embedding sidecar | | `gsd-graph embeddings status` | Inspect the embedding sidecar | | `gsd-graph ask "question" --semantic` | Use semantic seed fallback when needed | | `gsd-graph eval` | Run answer-quality cases | Embeddings use an OpenAI-compatible provider and require separate configuration. They are optional; ordinary extraction and retrieval remain deterministic. ## Troubleshooting | Symptom | Next step | | -------------------------- | ------------------------------------------------------------------------------------ | | No graph found | Run `gsd-graph enable` in the project | | `corpus_not_found` | Add a documentation source or pass `--corpus` | | Answer abstains | Inspect `query` and `pack`; add explicit relationships or use LLM extraction | | Graph is stale | Run `sync` and inspect `.last-sync-status.json` | | Hook does not run | Check hook registration, branch, configuration, CLI availability, and CI environment | | `build_locked` | Wait for the active writer; verify its PID before treating a lock as stale | | Review queue grows | Inspect `review summary` and choose an ontology that fits your corpus | | MCP tools do not appear | Restart the host and run `mcp doctor` | | MCP writes are unavailable | Enable the specific [write permission](/graph/mcp#enable-write-tools) | An abstention can mean no seeds matched, matched seeds were disconnected, or the retrieved subgraph was empty. Inspect any returned suggestions and the source relationships before widening retrieval. # Daily use Source: https://docs.opengsd.net/graph/workflow Refresh project knowledge, retrieve evidence, and maintain facts over time. Start by checking freshness, then retrieve the evidence you need: ```bash theme={null} gsd-graph status gsd-graph sync gsd-graph ask "what requirements depend on authentication?" ``` Run `sync` when your corpus has changed. It fingerprints source files, skips unchanged content, re-extracts changed content, and removes provenance for deleted sources. A triple remains while it still has supporting provenance. ## Choose a query | Goal | Command | | ------------------------------------- | ---------------------------------------------------- | | Answer a relationship question | `gsd-graph ask "question"` | | Browse a term's neighborhood | `gsd-graph query authentication` | | Retrieve evidence for your own answer | `gsd-graph pack "question"` | | Explain a connection between terms | `gsd-graph why "Auth" "API"` | | Find a path between known node IDs | `gsd-graph path ` | | Summarize corpus themes | `gsd-graph ask "what are the main themes?" --global` | | Inspect central nodes | `gsd-graph top` | Agents should use `ask` or `pack` rather than load the entire store into context. Keep answers grounded in the returned citations. An abstention is a valid result. ## Automatic updates `enable` installs this hook script: ```text theme={null} .gsd-graph/hooks/gsd-graph-update.sh ``` Connect it to your agent's Bash `PostToolUse` hook. With `enabled` and `auto_update` set, matching Git commands start a detached incremental sync on the default branch. Hooks skip CI. Set `sync_on_feature_branches: true` in `.gsd-graph/config.json` to opt into feature-branch updates, or run `sync` manually. Check `.gsd-graph/.last-sync-status.json` for the result. Failed detached syncs also retain `.last-sync-failure.out` and `.last-sync-failure.err`. For other editors, use a filesystem watcher or install a Git post-commit hook: ```bash theme={null} gsd-graph watch ``` ```bash theme={null} gsd-graph hook install-git ``` ## Record and correct facts `assert` and `retract` record changes in `episodes.jsonl`. Full rebuilds replay these episodes, so asserted facts and retractions survive a rebuild. ```bash theme={null} gsd-graph assert "Drought" causes "Crop Failure" gsd-graph retract gsd-graph supersede ``` These writes still pass ontology and provenance checks. Inspect the review queue when a fact is not accepted. `supersede` records a decision reversal; superseded facts receive lower retrieval priority and are marked in citations. ## Save and restore ```bash theme={null} gsd-graph snapshot save before-corpus-change gsd-graph snapshot list gsd-graph diff ``` `gsd-graph snapshot restore before-corpus-change` restores the canonical graph. Sidecar files may lag afterward. `gsd-graph repair` regenerates the disposable projection; `gsd-graph report` refreshes the human report. # Installation Source: https://docs.opengsd.net/loop/installation Install the five skills, connect your GitHub repository, and check build and review readiness. `@opengsd/gsd-loop` installs five Agent Skills and provides deterministic repository setup and readiness checks. The package never launches an agent; discover, spec, build, review, and scheduling run inside your coding agent. After setup, follow the [quickstart](/loop/quickstart). ## Supported hosts | Agent application | Skill location | Invocation | | -------------------------------------------------------------------------------------- | -------------------------- | ------------------------ | | [Codex](https://developers.openai.com/codex/skills/) | `~/.agents/skills` | `$gsd-loop-*` | | [Claude Code](https://code.claude.com/docs/en/skills) | `~/.claude/skills` adapter | `/gsd-loop-*` | | [Cursor](https://cursor.com/docs/skills) | `~/.cursor/skills` adapter | `/gsd-loop-*` | | [Gemini CLI](https://geminicli.com/docs/cli/creating-skills/) | `~/.gemini/skills` adapter | Natural-language request | | [Grok Build](https://docs.x.ai/build/features/skills-plugins-marketplaces) | `~/.grok/skills` adapter | `/gsd-loop-*` | | [Kimi Code](https://www.kimi.com/code/docs/en/kimi-code-cli/customization/skills.html) | `~/.agents/skills` | `/skill:gsd-loop-*` | `~/.agents/skills` is the canonical source for Codex and Kimi. Claude, Cursor, Gemini, and Grok use symlinks from their native global directories when supported and safe copies otherwise. Installing a skill does not install, authenticate, select, or launch a model or agent application. ## Prerequisites Standalone skill installation requires Node.js 18 or newer, including `npm` and `npx`. It does not require Git, a GitHub repository, an authenticated `gh` CLI, or an installed agent harness. Using the skills requires a supported agent harness with shell access. `init` and repository setup additionally require: * Git; * the [`gh` CLI](https://cli.github.com/) authenticated with push access. Creating a repository also requires a configured Git author name and email. Before review, the repository must have a real successful CI check. gsd-loop can require an existing check, but it does not invent an always-green workflow. Creating or updating the dedicated required-CI ruleset also requires repository administration access or a custom role with permission to edit repository rules. Without that permission, setup keeps the build lane ready and leaves review blocked. ## Choose an onboarding path ### Install before GitHub Install the five skills before creating or connecting a GitHub repository: ```bash theme={null} npx @opengsd/gsd-loop@latest install --dry-run npx @opengsd/gsd-loop@latest install ``` This command does not prepare labels, CI rules, or repository-local state. After the repository is on GitHub, run `init` from its local checkout to finish repository setup. ### Install and initialize together Run this inside an existing GitHub checkout: ```bash theme={null} npx @opengsd/gsd-loop@latest init ``` `init` previews every planned change and asks once before it: * installs or updates all five skills; * verifies GitHub access; * creates the five queue/review `gsd:*` labels without replacing existing labels; the first discovery pass creates `gsd:map` when needed; * locally excludes `.gsd/scheduled_tasks.lock` so native scheduling cannot make the main checkout look dirty to a builder pass; * when one successful check is selected, creates or updates only the dedicated `gsd-loop required CI` ruleset. It does not detect an agent CLI, request autonomous permissions, write runner configuration, or start background work. If review is not already protected and no successful CI check exists yet, setup exits with status `3` after making the build lane ready. Add CI through the first spec/build issue, wait for it to run successfully, then rerun `init` before starting the reviewer. GitHub repository plans do not all expose rulesets for private repositories. When the account plan or repository permissions prevent the dedicated ruleset, `init` keeps the build lane ready, leaves review blocked, and reports the limitation. It never rewrites unrelated branch protection. ### Start from an empty directory Interactive `init` offers a private repository named after the directory. It creates `main` with one empty initial commit, so no project files are staged or invented. For unattended setup, repository creation requires every external choice: ```bash theme={null} npx @opengsd/gsd-loop@latest init --yes \ --create-repo \ --repo OWNER/NAME \ --visibility private ``` In native Windows PowerShell: ```powershell theme={null} npx @opengsd/gsd-loop@latest init --yes ` --create-repo ` --repo OWNER/NAME ` --visibility private ``` The equivalent Command Prompt command is: ```bat theme={null} npx @opengsd/gsd-loop@latest init --yes --create-repo --repo OWNER/NAME --visibility private ``` `--yes` never implies `--create-repo`. Automatic creation is limited to an empty, non-Git directory. ### Choose CI explicitly When several successful checks exist, interactive setup asks which one to require. Unattended setup must identify it: ```bash theme={null} npx @opengsd/gsd-loop@latest init --yes --required-check test ``` ## Readiness checks Human-readable checks: ```bash theme={null} npx @opengsd/gsd-loop@latest doctor npx @opengsd/gsd-loop@latest doctor --review-ready ``` Machine-readable output: ```bash theme={null} npx @opengsd/gsd-loop@latest doctor --json --repo OWNER/NAME ``` Exit status `0` means the requested readiness level passed, `1` is an operational failure, `2` is invalid usage, and `3` means setup is safely waiting for human action. ## Skill installation options Select which hosts receive native adapters or choose adapter behavior when necessary: ```bash theme={null} npx @opengsd/gsd-loop@latest install --agents codex,cursor,gemini,grok,kimi npx @opengsd/gsd-loop@latest install --adapter-mode copy ``` The canonical five-skill bundle is always installed because every adapter references it and Codex and Kimi use it directly. `--agents` limits the native adapter directories added for Claude, Cursor, Gemini, and Grok. Before writing, the installer preflights the canonical bundle and every selected adapter destination. A conflicting unowned path stops the installation before anything is replaced. Each replacement is staged beside its destination and restores that destination from its backup if the replacement fails. Use `--home PATH` only for an alternate user profile or isolated test root. On native Windows, the canonical skill directory is `%USERPROFILE%\.agents\skills`. Claude, Cursor, Gemini, and Grok adapters are installed under `%USERPROFILE%\.claude\skills`, `%USERPROFILE%\.cursor\skills`, `%USERPROFILE%\.gemini\skills`, and `%USERPROFILE%\.grok\skills`. PowerShell users can preview an alternate profile without WSL: ```powershell theme={null} npx @opengsd/gsd-loop@latest install --dry-run --home "$env:USERPROFILE\gsd-loop-profile" ``` The Python 3.10+ source-checkout installer remains a skill-only fallback when installing through npm or npx is unavailable. Node.js 18+ is still required to execute the bundled deterministic helpers: ```bash theme={null} python3 scripts/install-global.py --dry-run python3 scripts/install-global.py ``` After installing or updating, start a new agent session. See [skill commands](/loop/skills) and [troubleshooting](/loop/troubleshooting). # GSD Loop Source: https://docs.opengsd.net/loop/introduction Turn ideas into GitHub issues, build pull requests, and review the evidence before you merge. GSD Loop is a GitHub work queue for coding agents. You define and approve the work. Agents build pull requests and review them against the approved issue. You decide when to merge. Install the skills, prepare your repository, and run a build and review. Learn the stages, issue contracts, labels, and human decisions. Use the skills in Codex, Claude Code, Cursor, Gemini CLI, Grok Build, or Kimi Code. Schedule separate build and review passes in a supported host. ## How work moves ```mermaid theme={null} flowchart TD Idea[Clear idea] --> Spec Uncertain[Uncertain effort] --> Discover --> Spec Spec --> Issue[GitHub issue] Issue --> Ready[You add gsd:ready] Ready --> Build --> PR[Pull request] --> Review Review --> Repair[Blocking findings] --> Build Review --> Approved[gsd:approved] --> Merge[You merge] ``` Discovery is optional. Use it when decisions must be resolved before you can write a clear issue. Build and review each handle one unit of work per pass. ## Your responsibilities * Read every queue issue and add `gsd:ready` only when you approve its scope. * Answer `gsd:blocked` questions and remove the label when resolved. * Resolve `gsd:escalated` items before returning them to automation. * Review the PR evidence and merge when satisfied. GSD Loop never merges, enables auto-merge, or force-pushes. `gsd:approved` records review evidence; it does not replace your merge decision. The [source repository](https://github.com/open-gsd/gsd-spec-build-loop) contains the playbooks, installer, and deterministic helpers. # Quickstart Source: https://docs.opengsd.net/loop/quickstart Prepare a GitHub repository and take a clear idea through specification, build, and review. For this walkthrough, you need Node.js 18 or newer, Git, an authenticated `gh` CLI with push access, and a [supported coding agent](/loop/skills). Use a local checkout of a GitHub repository. Review also needs required CI checks on its default branch. From the local checkout, run: ```bash theme={null} npx @opengsd/gsd-loop@latest init ``` Read the preview and approve the changes. Setup installs the five skills, prepares labels, and checks readiness. It can require an existing successful CI check when your permissions and GitHub plan support rulesets. If you have not created a repository yet, you can first run `npx @opengsd/gsd-loop@latest install`. See [installation](/loop/installation). Start a new agent session in your project and invoke `gsd-loop-spec` using [your host's syntax](/loop/skills). In Codex: ```text theme={null} $gsd-loop-spec ``` Describe who needs the change, what they should be able to do, and what is out of scope. Answer the interview questions and review the proposed issue. For an uncertain effort, start with `gsd-loop-discover` instead. Read the filed GitHub issue. Check its `O-N` outcomes and `X-N` exclusions. Add `gsd:ready` to each issue you approve. Creating an issue does not approve it. Open a build session and invoke `gsd-loop-build`. In Codex: ```text theme={null} $gsd-loop-build ``` The builder repairs eligible rework first. Otherwise, it claims the oldest safe ready issue, implements it in an isolated worktree, and opens a PR. Check review readiness: ```bash theme={null} npx @opengsd/gsd-loop@latest doctor --review-ready ``` Open a separate review session and invoke `gsd-loop-review`. In Codex: ```text theme={null} $gsd-loop-review ``` Read the verdict. Blocking findings return the PR to `gsd:rework`. Complete evidence results in `gsd:approved`. Run another build and review pass when repair is needed. Check the final diff, required CI, and review evidence. Merge the PR when you are satisfied. The loop stops short of merging. If setup reports that review is blocked because no successful CI check exists, add real CI through a spec/build issue, wait for it to pass, then rerun `init`. Review does not treat missing required checks as success. Use [scheduling](/loop/scheduling) to repeat build and review passes, or [troubleshooting](/loop/troubleshooting) when a pass cannot continue. # Publishing releases Source: https://docs.opengsd.net/loop/releasing Configure trusted publishing and publish the gsd-loop npm package from main. This guide is for maintainers of `@opengsd/gsd-loop`. To update your installed skills, see [troubleshooting](/loop/troubleshooting). Releases use npm Trusted Publishing from GitHub Actions. The workflow publishes the package and creates a matching GitHub Release tagged `vVERSION` from the package's exact published commit. It uses a short-lived OIDC identity and does not require an `NPM_TOKEN` secret. ## Configure the GitHub environment 1. Open **Settings → Environments** for the repository. 2. Create an environment named `npm`. 3. Under **Deployment branches and tags**, select **Selected branches and tags**. 4. Add a deployment **branch** rule named `main`. The environment rule prevents a workflow selected from another branch or tag from receiving the npm publishing identity. ## Configure the trusted publisher Open the settings for `@opengsd/gsd-loop` on npm, add a GitHub Actions trusted publisher, and enter these values exactly: | npm field | Value | | -------------------- | --------------------- | | Organization or user | `open-gsd` | | Repository | `gsd-spec-build-loop` | | Workflow filename | `publish.yml` | | Environment name | `npm` | | Allowed actions | `npm publish` | The filename is case-sensitive and must be entered without the `.github/workflows/` path. ## Publish a release 1. Merge a green PR containing the version bump and release changes into `main`. 2. Confirm CI is green on `main`. 3. Open **Actions → Publish release → Run workflow**. 4. Select `main` and run the workflow. 5. Confirm the workflow succeeded, the version appears on npm, and the matching `vVERSION` entry appears under GitHub Releases. The workflow refuses to publish from another branch. `npm publish` runs the package's `prepublishOnly` tests before uploading it, and npm automatically generates provenance for this public package when trusted publishing succeeds. Before publishing, the driver verifies that the selected commit is still the tip of `main` and that the `ci` workflow succeeded for that exact commit. It is retry-safe: registry and GitHub API failures stop the run, while a confirmed missing destination is repaired without republishing an existing package. When npm already has the version, its `gitHead` metadata identifies the exact commit that the matching GitHub Release must target. # Scheduling Source: https://docs.opengsd.net/loop/scheduling Repeat build or review passes with native recurring tasks and clear stop conditions. Scheduling requires a host with native recurring tasks. Each task wakes one lane, runs one pass, records the result, and applies the scheduling policy. ## Start a lane Open the build session and invoke `gsd-loop-schedule` using [your host's syntax](/loop/skills). Build is the default lane. To schedule review, open a separate session, invoke the skill, and explicitly request review. The skill checks repository readiness before creating a task. Review requires `doctor --review-ready` to pass. It updates a matching task instead of creating a duplicate and refuses another active builder for the same repository. ## Cadence and stop conditions The scheduling skill defines this policy: | Result | Task behavior | | ----------------------------- | ------------------------------------------------ | | Productive pass | Reset the idle count and repeat after 15 minutes | | Idle pass | Repeat after 60 minutes | | Three consecutive idle passes | Pause the task | | Blocked pass | Pause and report the cause | Credentials, permissions, unrelated dirty worktrees, and escalations can block a pass. The task requires the final `GSD_LOOP_RESULT` line; missing or malformed output is blocked, never inferred to be success. Resolve a reported blocker before invoking the scheduling skill again. After an idle pause, use it again when new work is available. ## Keep sessions separate Build and review use separate chats and scheduled tasks. Never schedule discovery or spec: they require a human. The scheduler does not merge PRs, enable auto-merge, force-push, or run multiple builders for one repository. If the host has no native recurring-task capability, run each build or review pass manually. GSD Loop does not start a shell loop or launch another agent CLI. # Skill commands Source: https://docs.opengsd.net/loop/skills Find the command syntax for your agent and choose the stage to run. Install the skills first and start a new agent session in your project. Enter these commands in the agent chat, not in a shell. | Stage | Command | | -------- | -------------------- | | Discover | `$gsd-loop-discover` | | Spec | `$gsd-loop-spec` | | Build | `$gsd-loop-build` | | Review | `$gsd-loop-review` | | Schedule | `$gsd-loop-schedule` | | Stage | Command | | -------- | -------------------- | | Discover | `/gsd-loop-discover` | | Spec | `/gsd-loop-spec` | | Build | `/gsd-loop-build` | | Review | `/gsd-loop-review` | | Schedule | `/gsd-loop-schedule` | | Stage | Command | | -------- | --------------------------------- | | Discover | `Use the gsd-loop-discover skill` | | Spec | `Use the gsd-loop-spec skill` | | Build | `Use the gsd-loop-build skill` | | Review | `Use the gsd-loop-review skill` | | Schedule | `Use the gsd-loop-schedule skill` | | Stage | Command | | -------- | -------------------------- | | Discover | `/skill:gsd-loop-discover` | | Spec | `/skill:gsd-loop-spec` | | Build | `/skill:gsd-loop-build` | | Review | `/skill:gsd-loop-review` | | Schedule | `/skill:gsd-loop-schedule` | ## Choose a stage | Skill | Use it to | Session | | ------------------- | -------------------------------------------------- | ------------------------ | | `gsd-loop-discover` | Map an uncertain effort or advance an existing map | Interactive | | `gsd-loop-spec` | Turn a clear idea or cleared map into queue issues | Interactive | | `gsd-loop-build` | Repair one PR or build one ready issue | Build only | | `gsd-loop-review` | Audit one PR and record a verdict | Review only | | `gsd-loop-schedule` | Create or update a recurring build or review task | The lane being scheduled | Discovery and spec may share a session. Keep build and review in separate sessions. Each direct stage invocation runs one pass and stops. Use [scheduling](/loop/scheduling) for repeated passes. The installed skills include the playbooks and their deterministic helpers. You do not need a globally installed `gsd-loop` shell command to run a stage. The npm CLI installs skills and prepares repositories; it does not launch agents. # Troubleshooting Source: https://docs.opengsd.net/loop/troubleshooting Recover from setup failures, missing skills, blocked work, and interrupted passes. Start with the readiness check for the lane you want to run: ```bash theme={null} npx @opengsd/gsd-loop@latest doctor npx @opengsd/gsd-loop@latest doctor --review-ready ``` ## Setup and upgrades * **Upgrading from `0.4.0`:** rerun `init` or `install` with version `0.4.1` to bundle the outcome helper required by discovery and specification. * **Upgrading from `0.3.0`:** rerun `init` or `install` with version `0.4.1` to refresh the installed skills and deterministic helpers. * **Upgrading from `0.2.5`:** rerun `init` or `install` with version `0.4.1` to add the interactive discovery workflow and its deterministic map helpers. * **Upgrading from `0.2.3` or `0.2.4`:** rerun `init` with version `0.4.1` to install discovery and the corrected Claude skill entry points. Upgrades from `0.2.3` also install the build linkage guard and Grok adapter, and locally exclude `.gsd/scheduled_tasks.lock`. Use `install` instead only when repository setup is not wanted. * **Upgrading from `0.2.2`:** rerun `init` or `install` with version `0.4.1` so review outcome synchronization recognizes the repository identity returned by the `gh` CLI for linked issues. * **Upgrading from `0.2.1`:** rerun `init` or `install` with version `0.4.1` to add the native Cursor and Gemini adapters. Existing canonical and Claude installs remain installer-owned and update safely. * **Upgrading from `0.2.0`:** stop any old `npx ... run build|review` processes. Version `0.4.1` ignores their `.git/gsd-loop` state; remove that directory only after confirming no old runner process is active. * **A skill is not visible:** start a new agent session. Gemini can run `/skills reload`; Grok can inspect `/skills`; Cursor users should open a new chat and reload Cursor if the skill remains absent. * **Review remains blocked:** allow CI to complete successfully, rerun `init`, and select the check when prompted. * **Native scheduling is unavailable:** run the build or review skill manually for another bounded pass. Do not substitute an external agent launcher. * **Native adapter symlink creation fails:** rerun with `--adapter-mode copy`. * **The installer refuses a path:** preserve and inspect it. gsd-loop never overwrites an unowned destination. ## A queue item is blocked Read the issue's question, answer it, then remove `gsd:blocked`. Leave `gsd:ready` on the issue so the builder can select it again. For `gsd:escalated`, read the issue or PR explanation and resolve the cause before removing the label. Escalation can mean the contract is unclear, a required check is missing, or repeated repair has not converged. Removing the label alone does not fix the cause. ## A pass was interrupted Run the same lane skill again. The builder checks Git and GitHub for unfinished work, open PRs, and stale claims before selecting new work. Do not start another builder for the same repository while the first is active. The reviewer can repair labels and outcome checkboxes from a verdict that still matches the commit, linked issue, and contract. A new commit or contract edit requires a fresh review. Do not mark outcomes complete by hand to bypass review. ## Scheduled work stopped Read the last task result. Three consecutive idle passes pause the task. Credentials, permissions, unrelated dirty worktrees, and escalations also pause it. Resolve the reported cause, then invoke `gsd-loop-schedule` in the lane's session to update the task. See [scheduling](/loop/scheduling). # Workflow and issue contracts Source: https://docs.opengsd.net/loop/workflow Understand discovery, specification, build, review, and the labels that control the queue. The GitHub issue defines the product scope. The builder implements its `O-N` outcomes; the reviewer checks the result against them. `X-N` exclusions state what must remain outside the change. ## Discover an uncertain effort Run `gsd-loop-discover` with a human present. A discovery map records the destination, decisions, unresolved questions, scope boundary, and delivery slices. It uses `gsd:map` and never enters the build queue. An advance resolves at most one frontier decision. Once the frontier is clear, a pass may re-chart the effort, graduate it to specification, or stop. The map and decision issues preserve context between sessions. Use one writer per map. ## Specify the work Run `gsd-loop-spec` for a clear idea or a cleared discovery map. The agent reads the code, interviews you, and drafts issues with outcomes, exclusions, code pointers, testing notes, and a manual walkthrough. Review the complete draft before it is filed. Each delivery slice becomes a separate queue issue. A dependency uses `Needs #N merged`; closing the predecessor without merged code does not satisfy it. Add `gsd:ready` to each approved issue. When scope changes after filing, update the issue contract through spec. A contract edit requires fresh review evidence even if the PR commit is unchanged. ## Build one unit of work The builder checks for interrupted work, then gives eligible `gsd:rework` PRs priority. If no repair is selected, it chooses the oldest safe `gsd:ready` issue whose dependencies are satisfied. It skips maps, blocked or escalated issues, and issues already claimed by another worker. Implementation happens in an isolated worktree. The builder tests the outcomes and opens a PR linked to the issue. Ambiguity goes back to you as a blocking question; the builder must not invent product scope. Run only one builder per repository. Issue assignment is a cooperative claim, not an atomic lock. ## Review one PR Run the reviewer in a separate session. It checks the linked issue, current commit, contract fingerprint, implementation, and required CI. Its verdict has blocking findings, advisory findings, and merge evidence. Required CI and dependency security remain independent gates. A manifest or lockfile change needs a machine-readable comparison of baseline and branch advisories. New high or critical advisories block approval. Missing required checks cannot count as green CI. A trusted verdict identifies the commit, issue, and contract version. The reviewer can restore labels and outcome checkboxes from matching evidence after an interruption. New commits or contract edits require a fresh review; changing only outcome checkboxes preserves the contract fingerprint. Three blocking verdicts on distinct commits since the last human-cleared escalation move the PR to `gsd:escalated` instead of continuing repair. ## Read the labels | Label | Meaning | Your next action | | --------------- | ----------------------------------- | --------------------------------------------------- | | `gsd:map` | Discovery planning state | Resolve decisions, then pass cleared slices to spec | | `gsd:ready` | You approved an issue for build | Leave it queued for the builder | | `gsd:blocked` | An issue needs your answer | Answer, then remove this label | | `gsd:rework` | A PR has blocking review findings | Let the builder repair it | | `gsd:approved` | Review evidence is complete | Inspect the evidence and decide whether to merge | | `gsd:escalated` | Automation needs human intervention | Resolve the cause, then remove this label | Approval can be invalidated when the commit, linked issue, contract, or required merge evidence changes. Always read the latest verdict before merging. See [skill commands](/loop/skills) to run a stage and [troubleshooting](/loop/troubleshooting) to resume blocked work. # Guard hooks Source: https://docs.opengsd.net/path/guard-hooks Install optional archive and Git guards and understand the host-specific enforcement boundary. Guard hooks add deterministic checks around archive writes, protected Git operations, and pipeline publication. They complement the pipeline's written contracts. Git hooks and native tool hooks have different coverage. ## Install guards Use an initialized Git repository and Python 3.9 or newer. Run from the GSD Path clone when installing project contracts for the first time: ```bash theme={null} node scripts/install.mjs --claude --codex --cursor --project /absolute/path/to/your-project --hooks --dry-run node scripts/install.mjs --claude --codex --cursor --project /absolute/path/to/your-project --hooks ``` Select only the hosts you use. For an existing project with contracts, add guards without replacing those contracts: ```bash theme={null} node scripts/install.mjs --hooks-init --codex --project /absolute/path/to/your-project --dry-run node scripts/install.mjs --hooks-init --codex --project /absolute/path/to/your-project ``` ## Understand enforcement | Layer | What it checks | | ----------------- | ------------------------------------------------------------------------------- | | Git hooks | Commit and push operations through `pre-commit`, `commit-msg`, and `pre-push` | | Native host hooks | Tool calls before execution on selected Claude Code, Codex, and Cursor installs | | Pipeline helpers | State transitions, isolation, archive transactions, and integration proof | The installer resolves the effective Git hooks directory, including `core.hooksPath` and linked worktrees. Native guards reject malformed events or events they cannot validate. Codex requires you to review and trust the project hook configuration in `/hooks`. Until activation is complete, treat the installation as Git-only enforcement. Review changed hook definitions again after updates. ## Recognize expected blocks Guards can reject writes to shipped archives, destructive Git commands, ambiguous shell destinations, changes to routing controls, and publication outside the ship contract. Read the reported reason and use the named pipeline helper or [forensics](/path/recovery) to proceed. The precise command rules and host caveats live in [HOOKS.md](https://github.com/open-gsd/gsd-path/blob/main/HOOKS.md). See [updating](/path/updating) to refresh installed guards. # Installation Source: https://docs.opengsd.net/path/installation Choose global or project-local skills and install the project contracts your pipeline needs. GSD Path has two install layers: host skills and project contracts. Skills provide the router and phase commands. Project contracts add `AGENTS.md`, `WORKFLOW.md`, and the `.gsd-path/` status runtime to the target repository. Selecting Claude Code also installs `.claude/CLAUDE.md`. ## Prerequisites * Node.js 18.17 or newer for the installer. * Python 3.9 or newer for project installs. * Git for branch binding, task isolation, and shipment. * A host from the [supported host table](/path/reference/hosts). The examples use a [clone of GSD Path](/path/quickstart). Commands with `scripts/install.mjs` run from that clone unless the example uses an absolute path. ## Choose where skills live | Scope | Use when | Command from the GSD Path clone | | -------------- | -------------------------------- | -------------------------------------------- | | Global | You use Path across repositories | `node scripts/install.mjs --codex` | | Selected hosts | You use more than one agent | `node scripts/install.mjs --claude --cursor` | | All hosts | You need every supported adapter | `node scripts/install.mjs --all` | Add `--dry-run` first to preview the selected targets without writing files. With no flags in an interactive terminal, `node scripts/install.mjs` opens the installation wizard. For project-local skills, run the installer by absolute path from the target repository. Replace both paths: ```bash theme={null} cd /absolute/path/to/your-project node /absolute/path/to/gsd-path/scripts/install.mjs --codex --local --dry-run node /absolute/path/to/gsd-path/scripts/install.mjs --codex --local ``` ## Add project contracts From the GSD Path clone: ```bash theme={null} node scripts/install.mjs --codex --project /absolute/path/to/your-project --dry-run node scripts/install.mjs --codex --project /absolute/path/to/your-project ``` An initial install refuses existing managed contracts. Use [the update flow](/path/updating) to keep those contracts and refresh managed skills and runtime files. Merge contract changes by hand. For optional archive and Git protection, see [guard hooks](/path/guard-hooks). ## Check the installation ```bash theme={null} node scripts/install.mjs --doctor --project /absolute/path/to/your-project ``` Doctor is a read-only check of skills, hooks, and pipeline state. Restart your agent after installing or updating, then [invoke the router](/path/quickstart). ## Other entry points The package declares the `gsd-path` npm command. If your chosen release is available on npm, you can use `npx gsd-path --all --dry-run` and `npx gsd-path --all` without a clone. The clone instructions above do not depend on npm publication. The Python installer, `scripts/install.py`, also supports global, local, and update installs. The Node CLI owns the interactive wizard. # GSD Path Source: https://docs.opengsd.net/path/introduction Take an idea through defined scope, checked evidence, isolated builds, and verified shipment. GSD Path is a project pipeline for AI coding agents. You approve the scope and plan. Agents research, implement, and review the work. Each handoff is saved in your repository's `.project/` directory, so a new session can resume from files. Install skills, add project rules, and start your first milestone. See what each phase produces and where you make decisions. Continue from saved state or diagnose a blocked pipeline. Find install flags and invocation syntax for your coding agent. ## How a milestone moves ```mermaid theme={null} flowchart LR I[Inspect existing code] --> D[Define] D --> R[Research] R --> C[Decide] C --> P[Plan] P --> B[Build and review] B --> S[Ship] ``` Existing projects start with inspection. New projects start with definition. A small, settled change may use the quick lane. Larger programs add a roadmap and repeat the milestone cycle. See [lanes and gates](/path/workflow) and [multi-milestone programs](/path/programs). ## Start with the router Invoke `gsd-path` explicitly in your agent. The `path` alias runs the same router. It reads saved state and chooses the next valid phase. ```text theme={null} $gsd-path ``` ```text theme={null} /gsd-path ``` A plain prompt such as “continue the project” reports the current handoff when Path owns the project state. It does not advance a phase. Use the explicit router or the named phase skill to continue. The [skill reference](/path/reference/skills) lists phase commands and tools for discussion, documentation audits, migration, diagnosis, and undo. # Move from GSD Core Source: https://docs.opengsd.net/path/migration Preserve Core history and unfinished work while moving a project into GSD Path's gates. The migration skill supports Claude Code and Codex projects with plugin or standalone skill installations. Both products can remain installed. Migration changes which workflow governs the selected project. ## Prepare the project Install or [update GSD Path](/path/updating), stop active Core work, and preserve pending edits. Reach a clean Git baseline before Path binds its branch. Keep `.planning/`; it remains the project's Core history. In Codex, invoke: ```text theme={null} $gsd-path-migrate ``` In Claude Code, invoke `/gsd-path-migrate`. Provide the project path and tell the skill whether Core came from a plugin or standalone skills. ## Review the import The skill prepares an external bundle with a file copy, hash manifest, and `IMPORT.md`. It carries constraints, decisions, exclusions, unfinished requirements, and source references. Completed Core plans remain historical evidence; they do not count as passed Path gates. Review the proposed host and hook changes. A project-level plugin override may be limited by host policy, and disabling a plugin does not remove separate hooks or skills. The skill must verify the effective state in your environment. ## Enter Path After reviewing `IMPORT.md`, hand it to the explicit Path router. Path inspects the code and asks you to approve intent. When inspection finishes, pass the absolute `IMPORT.md` path to define again using the command in the import's Handoff section. This is also required in a fresh session. Keep the bundle and any rollback receipts available. For host-specific cutover, hook settings, and rollback rules, read [MIGRATE.md](https://github.com/open-gsd/gsd-path/blob/main/MIGRATE.md). # Multi-milestone programs Source: https://docs.opengsd.net/path/programs Use a charter and roadmap to deliver a larger outcome through approved milestones. A program adds durable scope and decisions above the milestone cycle. Use it when the outcome needs a sequence of milestones with separate delivery gates. ## Establish the program 1. Define the program outcome, constraints, and vetoes in `.project/CHARTER.md`. 2. Research open questions and record program decisions in `.project/SYNTHESIS.md`. 3. Review and approve the milestone slicing in `.project/ROADMAP.md`. 4. Derive the first milestone's intent from its approved roadmap entry. These program files remain active after a milestone ships. Each milestone still needs its own intent, plan, build evidence, and ship gate. ## Move between milestones After integration validates, the router binds a new unused `gsd-path/M00N` branch at the current `origin/main`. It then inspects the current code and documentation and defines the next milestone. Research and decision phases run when its roadmap entry has open questions. The first milestone after roadmap approval starts at milestone definition; brownfield inspection has already run at program start when required. ## Plan ahead during build Lookahead planning stores the next milestone's work under `.project/next/`. It does not change the active build's task contracts or bind another milestone branch. At the milestone boundary, the router promotes the track through the pipeline helper and checks plan drift. ## Change program direction An explicit ruling can abandon a building milestone, archive its partial work, and return to roadmap slicing. Give that ruling through the router. Do not delete tasks or edit archived evidence to reshape the plan. See [recovery and discussion](/path/recovery) for raising a concern before changing an approved contract. # Quickstart Source: https://docs.opengsd.net/path/quickstart Install GSD Path from a clone and start a milestone in an existing Git repository. You need Node.js 18.17 or newer, Python 3.9 or newer available as `python3` or `python`, Git, and a [supported agent host](/path/reference/hosts). Use an existing Git repository with a clean working tree and an `origin/main` branch for this walkthrough. Run these commands in the directory where you keep source repositories: ```bash theme={null} git clone https://github.com/open-gsd/gsd-path.git cd gsd-path node scripts/install.mjs --codex --dry-run node scripts/install.mjs --codex ``` Replace `--codex` with your host flag, combine flags such as `--claude --cursor`, or use `--all` for every supported host. Stay in the GSD Path clone. Replace `/absolute/path/to/your-project` with your target repository's absolute path: ```bash theme={null} node scripts/install.mjs --codex --project /absolute/path/to/your-project --dry-run node scripts/install.mjs --codex --project /absolute/path/to/your-project ``` This installs project rules and the local status runtime. If managed contracts already exist, installation refuses to overwrite them. Follow [updating an existing project](/path/updating) instead. Start a new agent session in your target repository so it loads the skills. Invoke the router: ```text theme={null} $gsd-path ``` ```text theme={null} /gsd-path ``` For OpenCode stable, ask the agent to load and use the `gsd-path` skill. Describe what you want to achieve, who will use it, how you will know it works, and what is out of scope. Review the linked intent draft before approval. Review the wave summary and task scope before approving build. The router stops for required decisions. A directly invoked phase skill stops at its handoff; invoke the router again to continue. Build produces task evidence and wave reviews. Ship checks the final criteria and asks for approval. If review blocks, the pipeline prepares patch work. Follow [shipping](/path/shipping) for direct and pull-request modes. Read the phase outputs, approval gates, and quick-lane rules. # Resume, discuss, and recover Source: https://docs.opengsd.net/path/recovery Continue from saved state, resolve open questions, and diagnose blocked work without bypassing gates. GSD Path saves handoffs in `.project/`. Resume in the same project directory with the explicit router. A fresh session reads those files to recover the current phase. ## Inspect status ```text theme={null} $gsd-path status ``` ```text theme={null} /gsd-path status ``` Status reports without advancing. Invoke the router without `status` when you want to continue. Follow the linked artifact and exact next action it returns. ## Discuss an assumption or decision Use `$gsd-path-discuss` in Codex or `/gsd-path-discuss` on slash-command hosts during a non-shipped phase. Discussion reads phase artifacts and records the conversation in `discuss/DIALOGUE.md` and `discuss/ANSWERS.md`. A required follow-up remains pending until its named owner records how it was applied or acknowledged. It cannot silently disappear or waive an approved criterion. Discussion does not change phase state or commit code. ## Diagnose blocked work Use `$gsd-path-forensics` or `/gsd-path-forensics` for read-only diagnosis. Keep the exact error and the canonical artifact it names. If a helper fails, follow its diagnosis and recovery contract; do not repair state or Git by hand. For an intent correction or structural plan problem during a blocked build, use the pipeline's [build recovery contract](https://github.com/open-gsd/gsd-path/blob/main/skills/gsd-path/references/build-recovery.md). The recovery path preserves valid landed work and returns contract changes to the phase that owns them. ## Undo unpublished work Invoke `gsd-path-undo` for helper-owned undo. Do not substitute a manual reset, delete an archive, or start a competing build to escape a blocked state. ## Common symptoms | Symptom | Next action | | --------------------------------------------- | ------------------------------------------------------------------------ | | New skills do not appear | Restart your agent session and check [host paths](/path/reference/hosts) | | “Continue” only prints status | Invoke the explicit router | | Installer refuses existing contracts | Use [the update flow](/path/updating) | | Required discussion follow-up blocks progress | Read the answer and its named owner action | | All work passed but shipment is pending | Check PR merge and integration proof in [shipping](/path/shipping) | | State is foreign, ambiguous, or invalid | Use forensics and follow the reported recovery route | For installation health, run `node scripts/install.mjs --doctor --project /absolute/path/to/your-project` from the GSD Path clone. # Project artifacts Source: https://docs.opengsd.net/path/reference/artifacts Find the files that hold scope, decisions, task contracts, verification, and shipment history. All paths below are relative to `.project/`. Read the canonical artifact when a summary disagrees with it. Do not hand-edit state to move the pipeline. | Path | Purpose | | ------------------------------- | -------------------------------------------------------------------- | | `STATE.md` | Phase, milestone branch, integration choice, and archive transaction | | `REPOSITORY.md` | Approved binding for a newly created GitHub repository | | `CHARTER.md` | Program scope, constraints, and vetoes | | `ROADMAP.md` | Approved milestone slicing | | `SYNTHESIS.md` | Program decisions | | `intent/INTENT.md` | Milestone outcome, criteria, constraints, and vetoes | | `research/evidence-codebase.md` | Inspection findings | | `research/DOCS-AUDIT.md` | Documentation claim verdicts and remediation queue | | `research/RESEARCH.md` | Research dispatch manifest | | `research/evidence-*.md` | Research evidence | | `research/SYNTHESIS.md` | Milestone decisions | | `plan/PLAN.md` | Waves, dependencies, intent coverage, and project Verify | | `tasks/T###-slug.md` | Task scope, allowed files, criteria, and recorded results | | `review/` | Wave evidence, final reviews, and patch findings | | `discuss/DIALOGUE.md` | Append-only discussion transcript | | `discuss/ANSWERS.md` | Answers, named owners, and disposition receipts | | `next/` | Lookahead planning for the next program milestone | | `LESSONS.md` | Optional lessons carried into later planning | | `archive/` | Frozen milestone artifacts and manifests | ## What stays active after ship State, repository binding, lessons, lookahead, and program-level charter, roadmap, and synthesis remain active. Milestone artifacts move into a named archive directory. See [shipping](/path/shipping) for archive protection and integration rules. ## What has authority User rulings come first. Program charter constraints apply to all milestones. Intent criteria and vetoes constrain later work. Settled synthesis decisions and the current phase or task contract further define the work. If sources conflict, the pipeline stops and surfaces the conflict. A task log or review cannot waive an intent criterion. See [the operating rules](https://github.com/open-gsd/gsd-path/blob/main/AGENTS.md) for the full authority and handoff contracts. # Supported hosts Source: https://docs.opengsd.net/path/reference/hosts Choose installer flags and find the router syntax for each supported coding agent. Support means an installer target and dispatch contract exist. Live milestone evidence and guard coverage are tracked separately in the [host trust matrix](https://github.com/open-gsd/gsd-path/blob/main/docs/trust-validation/HOST-MATRIX.md). Use that matrix when evaluating a particular release. | Host | Install flag | Router invocation | | ------------------ | --------------- | ---------------------- | | Codex | `--codex` | `$gsd-path` or `$path` | | Claude Code | `--claude` | `/gsd-path` or `/path` | | Grok | `--grok` | `/gsd-path` or `/path` | | OpenCode v2 | `--opencode` | `/gsd-path` or `/path` | | GitHub Copilot CLI | `--copilot` | `/gsd-path` or `/path` | | Qwen Code | `--qwen` | `/gsd-path` or `/path` | | Antigravity CLI | `--antigravity` | `/gsd-path` or `/path` | | Cursor | `--cursor` | `/gsd-path` or `/path` | | Zed | `--zed` | `/gsd-path` or `/path` | | Kiro | `--kiro` | `/gsd-path` or `/path` | | Kimi Code | `--kimi` | `/gsd-path` or `/path` | For OpenCode stable, ask the agent to load and use the `gsd-path` skill. Individual phases retain the `gsd-path-` prefix on every host. ## Locate installed skills Codex and Zed share `~/.agents/skills`. Claude Code uses `~/.claude/skills`, and Cursor uses `~/.cursor/skills`. Other hosts use their host-specific roots. Project-local installs use the corresponding project skill directories. Run the installer with `--dry-run` to see resolved paths for your selected hosts. Run `node scripts/install.mjs --help` from the clone for flags and root overrides. Restart the host after installing or updating. ## Check the enforcement boundary Git hooks protect Git operations across hosts. Native tool hooks are installed for selected Claude Code, Codex, and Cursor targets. Codex needs manual trust activation. See [guard hooks](/path/guard-hooks) and the trust matrix for limitations. # Skill reference Source: https://docs.opengsd.net/path/reference/skills Find the router, phase skills, and tools that work alongside the pipeline. Use `$skill-name` in Codex and `/skill-name` on slash-command hosts. The router is the normal entry point. A directly invoked phase skill handles its phase and stops at a handoff. ## Router and phases | Skill | Purpose | | ------------------- | ---------------------------------------------------------- | | `path` | Short alias for `gsd-path` | | `gsd-path` | Read state and route the next phase; `status` is read-only | | `gsd-path-inspect` | Map existing code and audit documentation | | `gsd-path-define` | Define intent or a program charter | | `gsd-path-research` | Gather evidence for open questions | | `gsd-path-decide` | Record decisions supported by evidence | | `gsd-path-roadmap` | Slice a program into milestones | | `gsd-path-plan` | Create waves, task contracts, and verification coverage | | `gsd-path-build` | Dispatch implementation, verify tasks, and review waves | | `gsd-path-ship` | Run final review, archive, and integrate | ## Supporting skills | Skill | Purpose | | --------------------- | ---------------------------------------------------------- | | `gsd-path-discuss` | Record questions and decisions during a non-shipped phase | | `gsd-path-docs-audit` | Check documentation claims against the code | | `gsd-path-loop` | Run a bounded check and fix loop from a `LOOP.md` contract | | `gsd-path-forensics` | Diagnose a stuck pipeline without changing it | | `gsd-path-migrate` | Import Core context and review hook coexistence | | `gsd-path-undo` | Undo unpublished work through pipeline helpers | Discussion does not approve or advance phases. The loop runner does not advance gates, commit, or push. See [recovery](/path/recovery) before attempting to repair a blocked run. Source: [installed skill catalog](https://github.com/open-gsd/gsd-path/blob/main/README.md#skills). # Shipping and integration Source: https://docs.opengsd.net/path/shipping Review final evidence and complete shipment through direct integration or a user-merged pull request. Shipping proves that the milestone meets its approved criteria, preserves its evidence, and integrates the result with `main`. A passing build alone is not a completed shipment. ## Before shipping Every task and wave review must pass. Ship runs the project Verify through its owned runtime and checks the final gap verdicts. Any `not-met`, `unverifiable`, or blocked result prevents shipment. If final review finds a contract gap, it returns the finding through patch planning and build. Reviewers report findings; they do not edit product code. ## Choose an integration mode The project has an integration default, and a milestone can override it before build. Use the pipeline to make this choice; do not hand-edit state. | Mode | Integration behavior | Your action | | ------------ | ---------------------------------------------------------------------- | --------------------------------------------- | | Direct | Path creates and pushes the canonical non-fast-forward merge to `main` | Approve shipment after reviewing the evidence | | Pull request | Path creates or reuses its GitHub PR | Merge the approved PR with a merge commit | Pull-request mode requires a merge commit. Squash and rebase merges do not satisfy Path's two-parent integration proof. Path does not auto-merge the PR. ## Archive and prove integration Ship creates one `.project/`-only commit on the bound milestone branch. It moves milestone artifacts to `.project/archive/` with a manifest. The integration validator checks the merge, the milestone tag, and ancestry on `origin/main` before the router reports the milestone as shipped. If a PR is still awaiting merge, the router returns to ship. It does not start the next milestone. Archives become read-only when committed, including while PR integration is pending. See the [archive contract](https://github.com/open-gsd/gsd-path/blob/main/WORKFLOW.md) for transaction and retry rules. ## Let the pipeline own publication All milestone work uses the branch recorded in state, such as `gsd-path/M001`. The ship transaction owns publication from that branch. Do not use a separate push, PR, or general-purpose release workflow to bypass it. If shipment stops during an archive or integration transaction, preserve the files and follow [the recovery flow](/path/recovery). # Update an installation Source: https://docs.opengsd.net/path/updating Refresh skills and managed runtime files while preserving project contracts and active milestones. Run these commands from your GSD Path clone. Preview updates before applying them, then restart the agent session so it reloads the skills. ## Update global skills ```bash theme={null} git pull node scripts/install.mjs --update --dry-run node scripts/install.mjs --update ``` `--update` refreshes hosts that already have GSD Path installed. Add host flags to select specific installations. Existing managed skills move to `disabled-gsd-skills` beside each skill root before replacement. ## Refresh an existing project ```bash theme={null} node scripts/install.mjs --update --project /absolute/path/to/your-project --dry-run node scripts/install.mjs --update --project /absolute/path/to/your-project ``` This refreshes managed `.gsd-path/` files and retains `AGENTS.md`, `WORKFLOW.md`, and `.claude/CLAUDE.md`. Compare upstream contract changes and merge them by hand. The installer does not rewrite active `.project/` artifacts. ## Update project-local skills Run from the target repository using the absolute installer path: ```bash theme={null} cd /absolute/path/to/your-project node /absolute/path/to/gsd-path/scripts/install.mjs --update --local --dry-run node /absolute/path/to/gsd-path/scripts/install.mjs --update --local ``` ## Refresh hooks and runtime | Need | Flag with `--project PATH` | | ------------------------------------------------------------- | ----------------------------------- | | Refresh managed runtime and installed guard scripts | `--hooks-refresh` | | Also refresh native settings and Git hooks | `--hooks-refresh-full` | | Add guards to an existing project while keeping its contracts | `--hooks-init` plus your host flags | See [guard hooks](/path/guard-hooks) for host activation requirements. A refresh refuses unrecognized files rather than overwriting them. ## Check the result ```bash theme={null} node scripts/install.mjs --doctor --project /absolute/path/to/your-project ``` Restart the host, then ask the router for status. For detailed migration notes on older contracts, read [UPDATE.md](https://github.com/open-gsd/gsd-path/blob/main/UPDATE.md). # Phases and approvals Source: https://docs.opengsd.net/path/workflow Understand the milestone lifecycle, saved evidence, and decisions that need your approval. The router selects work from saved project state. You control the scope, approval gates, and unresolved decisions. Each phase leaves a reviewable file for the next phase. ## Phase outputs | Phase | What happens | What you review | | -------- | ------------------------------------------------------------ | -------------------------------------------------------- | | Inspect | Map existing code and audit documentation claims | Codebase evidence and documentation conflicts | | Define | Record the outcome, users, criteria, constraints, and vetoes | `intent/INTENT.md` and intent playback | | Research | Investigate open questions; record skipped dimensions | Evidence files and the research manifest | | Decide | Turn cited evidence into decisions | `research/SYNTHESIS.md`; unresolved `NEEDS-USER` choices | | Plan | Map criteria to tasks, dependencies, and verification | `plan/PLAN.md` and the wave summary | | Build | Implement tasks, verify isolated patches, and review waves | Task logs, escalations, and wave reviews | | Ship | Check final criteria, archive, and integrate | Final review and shipment approval | Paths in this table are relative to `.project/`. [Programs](/path/programs) also use a charter and a roadmap above the milestone loop. ## Start from the actual project For an existing repository, inspection runs before definition. Documentation conflicts need your ruling: fix the documentation, fix the code, or accept the drift. Inspection does not resolve the conflict for you. For a new project, definition starts with the intended result. State what is in scope and what is excluded. Vetoes remain binding during research, planning, and implementation. ## Choose a lane The quick lane applies to at most two deliverable tasks in one wave with no open questions or cross-wave risk, as defined in the [full guide](https://github.com/open-gsd/gsd-path/blob/main/FULL.md#quick-lane). It may skip research and decision work using settled inputs. If the plan outgrows that contract, it returns to the standard lane and research. The standard lane gathers evidence before planning. Program milestones derive their scope from the approved roadmap and revisit research when questions remain. ## Approve a concrete artifact A handoff names the outcome, links the review file, and states the next action. Read that file before approving. Plan approval creates a checkpoint before build begins. Final-review patch selection also needs your approval before patch planning starts. A discussion answer does not approve a plan or advance a phase. ## How build verifies work Task contracts name allowed files, acceptance criteria, interfaces, and a Verify command. The orchestrator checks those briefs before dispatch. Parallel tasks use isolated named branches and worktrees; a serial dispatch works on the bound milestone branch. Task landing stays serial. The orchestrator reruns each task's Verify against its isolated patch. Wave review uses that recorded evidence. The project Verify runs at ship through the final-review runtime. A wave advances only after all its tasks and its wave review pass. For the full agent contract, read [WORKFLOW.md](https://github.com/open-gsd/gsd-path/blob/main/WORKFLOW.md). # GSD Pi Auto Mode: Autonomous Project Execution Loop Source: https://docs.opengsd.net/pi/concepts/auto-mode Auto Mode runs GSD Pi through planning, implementation, verification, and milestone completion — with configurable budgets, timeouts, and controls. Auto Mode is GSD Pi's autonomous execution engine. When you run `/gsd auto`, Pi takes the current project state, derives the next unit of work from the database, and runs the full development loop — planning, implementing, verifying, committing, and advancing — without you having to orchestrate each step. You can walk away and come back to built, committed, tested code with clean git history. ## How the Loop Works Auto Mode operates as a state machine driven by the SQLite database at your project root. For each unit of work, Pi creates a fresh context window, injects a focused prompt with all relevant context pre-loaded (task plan, prior summaries, decisions register, roadmap excerpt), executes the work, persists the result, and dispatches the next unit. The loop flows through these phases for each slice: ``` Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice ↓ (all slices done) Validate Milestone → Complete Milestone ``` * **Plan** — Pi scouts the codebase, researches relevant documentation, and decomposes the slice into tasks with clear must-haves * **Execute** — Pi runs each task in its own fresh context window; no context bloat from previous tasks * **Complete** — Pi writes task summaries, generates a UAT script, marks the roadmap, and commits * **Reassess** — Pi checks whether the roadmap still makes sense given what was learned during execution * **Validate Milestone** — after all slices complete, Pi reconciles success criteria against actual results before sealing the milestone ## Controlling Auto Mode ### Start ```text theme={null} /gsd auto ``` Starts or resumes auto mode. Pi derives the latest state from the database and picks up where it left off. ### Pause Press **Escape** to pause auto mode. The conversation is preserved and the current unit's state is saved. You can inspect the work, ask Pi questions, or read the planning files — then resume when ready. ### Resume ```text theme={null} /gsd auto ``` Resuming is the same command as starting. Pi checks the database for an in-progress unit and continues from the current position. ### Advance One Step ```text theme={null} /gsd next ``` Execute one unit of work and pause. Use this when you want to stay close to the work and review each step before Pi continues. ### Stop ```text theme={null} /gsd stop ``` Gracefully stops auto mode after the current unit completes. You can run this from a separate terminal while auto mode is running in another. ### Interrupt Immediately Press **Escape** during an active unit to interrupt Pi mid-execution. Pi saves whatever state it has written so far and pauses. Run `/gsd auto` to recover and continue. ## Planning Depth By default, Pi uses `light` planning depth — a focused milestone discussion flow that writes context and roadmap artifacts immediately. For projects that benefit from more up-front discovery, enable `deep` planning mode: ```yaml theme={null} planning_depth: deep ``` You can also opt in when creating a project or milestone: ```text theme={null} /gsd new-project --deep /gsd new-milestone --deep ``` Deep mode runs a staged discovery flow before milestone planning: ``` Workflow Preferences → Project Context → Requirements → Research Decision → Optional Project Research → Milestone Context / Roadmap ``` This produces `PROJECT.md`, `REQUIREMENTS.md`, and optional research artifacts (`STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md`) before any slice planning begins. ## Budget Controls Configure a spending ceiling and enforcement policy in `.gsd/PREFERENCES.md`: ```yaml theme={null} budget_ceiling: 25.00 budget_enforcement: pause ``` Pi logs a warning when the ceiling is hit but continues running. Use this when you want visibility without hard stops. ```yaml theme={null} budget_enforcement: warn ``` Pi pauses auto mode when the ceiling is reached and waits for you to review and resume. This is the default when a `budget_ceiling` is set. ```yaml theme={null} budget_enforcement: pause ``` Pi stops auto mode entirely when the ceiling is hit. Use this for strict cost control in unattended runs. ```yaml theme={null} budget_enforcement: halt ``` Check current spend at any time: ```text theme={null} /gsd status ``` The dashboard shows per-unit cost, running totals, and projections. ## Timeout Supervision Three timeout tiers protect against runaway sessions: | Timeout | Setting | Default | Behavior | | ------- | ---------------------- | ------- | ------------------------------------------------------------------------------- | | Soft | `soft_timeout_minutes` | 20 min | Sends Pi a wrap-up signal to finish durable output | | Idle | `idle_timeout_minutes` | 10 min | Detects stalls and intervenes | | Hard | `hard_timeout_minutes` | 30 min | Starts timeout recovery; pauses auto mode only if recovery cannot make progress | Configure them in `.gsd/PREFERENCES.md`: ```yaml theme={null} auto_supervisor: soft_timeout_minutes: 20 idle_timeout_minutes: 10 hard_timeout_minutes: 30 ``` The timeout system is designed to be recovery-aware. When a unit is actively writing durable progress during hard timeout recovery, Pi defers its final cancellation check to give the unit time to finalize before stopping. ## Verification Pi can run your project's test and lint commands automatically after every task execution. Set them in `.gsd/PREFERENCES.md`: ```yaml theme={null} verification_commands: - npm run lint - npm run test verification_auto_fix: true verification_max_retries: 2 ``` When verification fails, Pi sees the output and attempts to fix the issues before advancing to the next task. If Pi cannot fix the issues within the retry limit, auto mode pauses so you can intervene. If you don't configure `verification_commands`, Pi attempts to discover your project's checks automatically — it looks for `package.json` scripts (typecheck, lint, test) for JavaScript projects and pytest markers for Python projects. ## Crash Recovery Auto mode persists worker state, dispatch state, and session metadata in the database. If Pi crashes or your machine restarts, run `/gsd auto` again. Pi reconstructs the interrupted unit from the database, reads the surviving session file, synthesizes a recovery briefing from every tool call that completed, and resumes with full context. For unattended overnight runs, headless mode adds automatic crash recovery with exponential backoff: ```bash theme={null} gsd headless auto --max-restarts 3 ``` ## Key Behaviors Every task, planning step, and research phase runs in a clean context window. Pi pre-loads all necessary context (task plan, prior summaries, decisions register, codebase notes) into the dispatch prompt, so the agent starts fully oriented instead of spending tool calls reading files. This eliminates context bloat and keeps quality consistent across long autonomous runs. After each slice completes, Pi reassesses the roadmap. If the work revealed new information that changes the plan — a dependency that turned out to be more complex, a simpler approach that covers multiple planned slices — Pi reorders, adds, or removes future slices before continuing. You can skip reassessment with the `budget` token profile. Pi uses a sliding-window analysis on recent dispatch history to detect stuck loops. On detection, it retries once with a deep diagnostic prompt. If the second attempt also fails, auto mode stops so you can intervene. Run `/gsd forensics` for a structured post-mortem. Pi automatically handles transient provider errors: * Rate limits (429) → waits and retries after the retry-after header or 60 seconds * Server errors (500, 502, 503) → retries after 30 seconds * Permanent errors (invalid key, billing) → pauses and surfaces a clear message No manual intervention needed for transient errors — Pi resumes automatically. Pi generates commit messages from task summaries — not generic "complete task" boilerplate. Each commit reflects what was actually built, giving you a `git log` that reads like a changelog. When context usage reaches 70%, Pi sends itself a wrap-up signal, nudging it to finish durable output — commits, summaries, artifacts — before the context window fills. This prevents a session from hitting the hard context limit mid-task with nothing written to disk. ## Post-Mortem Investigation If auto mode fails or behaves unexpectedly, run `/gsd forensics` for a full analysis: ```text theme={null} /gsd forensics ``` Forensics provides structured anomaly detection, recent unit traces, cost and token breakdowns, doctor integration, and an LLM-guided investigation session with full tool access to diagnose root causes. # GSD Pi Extension System: Bundled and Community Extensions Source: https://docs.opengsd.net/pi/concepts/extensions GSD Pi's extension system adds capabilities through three tiers: non-disableable core, default-enabled bundled, and user-installed community extensions. GSD Pi's capabilities expand through a layered extension system. Extensions add tools, slash commands, UI integrations, and provider connections to Pi. You can enable or disable most extensions per project, install community extensions from npm, and build your own using the extension SDK. ## Extension Tiers Extensions are grouped into three tiers based on their role and configurability: System extensions that are always active. They provide fundamental runtime capabilities that Pi depends on and cannot be disabled. Packaged with Pi and enabled by default. You can toggle these on or off per project using `/gsd extensions enable` and `/gsd extensions disable`. User-installed extensions from npm, a git URL, or a local path. Install them with `gsd install` or `/gsd extensions install`. ## Bundled Extensions These extensions ship with GSD Pi and are enabled by default. Toggle any of them with `/gsd extensions enable ` or `/gsd extensions disable `. Provides a canonical `browser_*` tool surface that Pi uses to open pages, interact with UI elements, take screenshots, run visual diffs, and record sessions. Used during browser-based UAT, E2E flows, and visual verification. **Engine selection.** For browser-facing (web-app) projects, Pi prefers the managed [GSD Browser](/browser/introduction) engine when its CLI is available and the daemon connects at session start. If the connect probe fails or the CLI is missing, Pi falls back to legacy Playwright for that session and records the reason. Non-browser-facing projects stay on Playwright — browser tools are incidental there and the managed daemon's startup cost isn't worth it. The session-start connect probe has a 10-second budget. Falling back to Playwright preserves browser-based UAT instead of blocking the run; the engine actually registered is what later UAT guidance and re-warm-ups see. **Overrides.** Set these in your shell or your provider environment to force a specific engine or tune startup: | Variable | Values | Effect | | -------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GSD_BROWSER_ENGINE` | `gsd-browser` | Force the managed GSD Browser engine. No probe, no fallback. | | `GSD_BROWSER_ENGINE` | `playwright` (alias: `legacy`) | Force legacy Playwright, even on web-app projects. | | `GSD_BROWSER_ENGINE` | `off` | Disable Pi browser tools entirely. | | `GSD_BROWSER_WARMUP` | `0` | Skip eager warm-up. Without warm-up the connect probe can't verify the managed engine, so the default resolves to Playwright; the managed engine still works if you set `GSD_BROWSER_ENGINE=gsd-browser` explicitly. | **UAT modes.** Pi UAT specs labeled `browser-executable`, `live-runtime`, `mixed`, or `human-experience` always run against whichever engine is registered for the session — the canonical `browser_*` contract is engine-stable, so prompts and policies don't change with the engine. UAT specs that drive Playwright directly from a shell command should be declared `runtime-executable` so they record runtime evidence instead of browser evidence. **External MCP clients.** `gsd-browser` also ships as a standalone MCP server for external clients (Claude Desktop, Cursor, custom harnesses). Write the entry with `/gsd mcp init`. Setting `GSD_BROWSER_MCP_ENABLED=0` only skips writing that external entry — it does not disable Pi's own browser tools. Enables background async task execution. Pi can dispatch long-running jobs and poll for results without blocking the main agent context. Useful for CI waits, build pipelines, and external API workflows. Allows Pi to start and manage background shell processes — dev servers, watchers, and long-running build processes — and interact with their output across turns. Access the background shell panel with **Ctrl+Alt+B**. Gives Pi the ability to search the web for documentation, library references, API specs, and error resolutions. Powered by Brave Search and Jina Reader. Configure a Brave API key with `/gsd config` to use your own quota. Enables Pi to delegate isolated units of work to subagents — specialist agents (scout, researcher, reviewer, security, tester) that run in their own context windows and report back. Used extensively during parallel task execution and deep planning phases. Adds real-time speech-to-text input. Press **Ctrl+Alt+V** to toggle voice transcription on or off. Supported on macOS and Linux. Transcribed text appears in the input field as you speak. Enables Pi to capture visual context — screenshots, clipboard images, and screen regions — and include them as vision input in prompts. Paste a screenshot with **Ctrl+V** or **Alt+V** to give Pi visual context about a UI, error, or design. Integrates Context7 for accurate, version-specific library documentation lookup. Pi uses this during research and planning phases to fetch up-to-date API references instead of relying on training data. Works out of the box; optionally set `CONTEXT7_API_KEY` for higher rate limits. Provides macOS UI automation via the Accessibility API — Pi can list running apps, capture screenshots, inspect the UI tree, click elements, and type text. Active on macOS only. Routes Pi's interactive questions to remote messaging adapters (Slack, Discord, Telegram) when running unattended. Lets you answer Pi's prompts from your phone or chat app during overnight autonomous runs. Discovers AI coding tool configurations from Claude Code, Cursor, Windsurf, Gemini CLI, and other tools present in the project. Pi can import or reference existing tool configs when setting up a new session. Provides scaffolding commands for building new slash commands and extensions: `/gsd create-slash-command`, `/gsd create-extension`, and `/gsd audit`. Useful when you want to extend Pi's capabilities for your team. Monitors Pi's streaming output against configurable regex patterns at zero context cost. Catches unwanted patterns in real time — useful for enforcing output conventions or blocking sensitive data from appearing in responses. ## Managing Extensions Inspect and control extensions from inside a GSD session: | Command | What it does | | --------------------------------- | ------------------------------------------------------------------------------------- | | `/gsd extensions list` | List all extensions with their status (`enabled`, `disabled`, `[user]` for installed) | | `/gsd extensions enable ` | Enable a disabled bundled extension | | `/gsd extensions disable ` | Disable a bundled extension | | `/gsd extensions info ` | Show extension details, capabilities, and configuration | | `/gsd extensions install ` | Install a community extension from npm, a git URL, or a local path | | `/gsd extensions uninstall ` | Remove a user-installed extension | | `/gsd extensions update [id]` | Update a user-installed npm extension to its latest version | | `/gsd extensions validate ` | Validate an extension directory against the manifest schema | ## Installing Community Extensions Install community extensions from npm using the `gsd install` command from your shell: ```bash theme={null} gsd install ``` Or from inside a GSD session: ```text theme={null} /gsd extensions install ``` Install sources are detected automatically: * Starts with `https://` or ends with `.git` → cloned from git * Contains `/` or `.` and exists on disk → copied from local path * Otherwise → fetched from npm Installed extensions land in `~/.gsd/extensions//` and are available across all projects. Restart GSD after installation to activate a new extension. ### Example: Installing a Community Provider Extension ```bash theme={null} gsd install npm:pi-dashscope ``` This installs the `pi-dashscope` community extension, which adds Alibaba DashScope (ModelStudio) provider support with Qwen3, GLM-5, and other models — with proper OpenAI-compatible endpoint configuration and thinking mode support. Uninstalling an extension warns you if other extensions depend on it. Review dependencies with `/gsd extensions info ` before uninstalling. ## Building Your Own Extension Extensions are npm packages that implement the GSD extension SDK. An extension can contribute: * **Tools** — new tools available to Pi during agent sessions * **Slash commands** — new `/gsd` commands for the TUI * **UI components** — dashboard widgets and visualizer tabs * **Provider integrations** — new LLM providers or model configurations * **Hooks** — event handlers that fire on auto-mode events Validate your extension before publishing: ```bash theme={null} gsd extensions validate ./my-extension ``` See the Extension SDK documentation for the full manifest specification, API reference, and testing guide. # Model Routing and Multi-Provider Configuration in GSD Pi Source: https://docs.opengsd.net/pi/concepts/model-routing GSD Pi supports 15+ LLM providers with per-phase model configuration, dynamic complexity routing, token profiles, and fallback chains. GSD Pi works with a wide range of LLM providers and gives you precise control over which model runs at each phase of the development workflow. You can set a different model for research, planning, implementation, and simpler tasks — letting you optimize for quality where it matters and cost where it doesn't. ## Supported Providers Pi supports the following providers out of the box: Anthropic (Claude), OpenAI, Google Gemini, OpenRouter, Groq, xAI (Grok), Mistral, GitHub Copilot, Amazon Bedrock, Vertex AI (Claude on Google Cloud), Azure OpenAI Ollama, LM Studio, vLLM, SGLang — any OpenAI-compatible endpoint also works via custom configuration in `~/.gsd/agent/models.json` Configure your provider credentials with `/gsd config` inside a session, or export the relevant environment variable before starting Pi. See the [Provider Setup guide](/pi/configuration/providers) for per-provider credential instructions. ## Per-Phase Model Configuration Pi executes different types of work at each phase of the auto-mode loop. Configure which model handles each phase in `.gsd/PREFERENCES.md`: ```yaml theme={null} models: research: claude-sonnet-4-6 planning: claude-opus-4-6 execution: claude-sonnet-4-6 execution_simple: claude-haiku-4-5-20250414 completion: claude-sonnet-4-6 subagent: claude-sonnet-4-6 ``` | Phase | When it runs | | ------------------ | ----------------------------------------------------------------- | | `research` | Milestone and slice research phases | | `planning` | Milestone and slice planning, roadmap creation | | `execution` | Task implementation (the main coding work) | | `execution_simple` | Tasks classified as low-complexity by the dynamic router | | `completion` | Slice and milestone completion summaries | | `subagent` | Delegated subagent sessions (scout, researcher, reviewer, tester) | Omit any phase key to use whichever model is currently active as the default. ## Token Profiles Token profiles provide a quick way to balance cost, quality, and speed across the whole workflow: | Profile | Behavior | | ---------- | ----------------------------------------------------------- | | `budget` | Skips research and reassessment phases; uses lighter models | | `balanced` | All phases run with standard model selection (default) | | `quality` | All phases run; prefers higher-capability models | ```yaml theme={null} token_profile: balanced ``` Token profiles work alongside per-phase model settings. The profile sets the baseline behavior; explicit `models.*` entries override the profile for specific phases. ## Dynamic Model Routing Dynamic routing automatically selects a cheaper model for simple work and reserves your more capable models for complex tasks. It classifies each unit of work into a complexity tier — light, standard, or heavy — and routes accordingly. Enable it in `.gsd/PREFERENCES.md`: ```yaml theme={null} dynamic_routing: enabled: true ``` ### Complexity Tiers | Tier | Typical Work | | ------------ | ------------------------------------------------------------- | | **Light** | Slice completion, UAT, hooks, documentation tasks | | **Standard** | Research, planning, task execution, milestone completion | | **Heavy** | Replanning, roadmap reassessment, complex architectural tasks | The router uses **downgrade-only semantics** — your configured model is always the ceiling. Dynamic routing never upgrades beyond what you've explicitly configured. ### Full Configuration ```yaml theme={null} dynamic_routing: enabled: true tier_models: light: claude-haiku-4-5 standard: claude-sonnet-4-6 heavy: claude-opus-4-6 escalate_on_failure: true # bump tier up on task failure budget_pressure: true # auto-downgrade as budget ceiling approaches cross_provider: true # consider models across all configured providers capability_routing: true # score models by task capability within tier ``` ### Capability-Aware Scoring When `capability_routing: true` is set (the default), Pi scores eligible models within the selected tier against the task's requirements before choosing. Scores are computed across seven dimensions: | Dimension | What it measures | | ------------- | --------------------------------------------- | | `coding` | Code generation and implementation accuracy | | `debugging` | Diagnosing and fixing errors | | `research` | Synthesizing information and exploring topics | | `reasoning` | Multi-step logical reasoning | | `speed` | Latency and throughput | | `longContext` | Handling large codebases and long documents | | `instruction` | Following structured instructions precisely | Different unit types weight these dimensions differently. For example, `execute-task` weights `coding` and `instruction` heavily, while `research-*` units weight `research` and `longContext`. When two models score within 2 points of each other, Pi picks the cheaper one. Cost ties break alphabetically by model ID for deterministic behavior. ### Budget Pressure When `budget_pressure: true` is enabled, Pi progressively downgrades model selection as you approach your spending ceiling: | Budget Used | Effect | | ----------- | ------------------------------------------------------- | | \< 50% | No adjustment | | 50–75% | Standard → Light for eligible units | | 75–90% | More aggressive downgrading | | > 90% | Nearly everything → Light; only Heavy stays at Standard | ## Fallback Chains Configure a list of fallback models for any phase. Pi tries each in order if the primary model fails — useful for rate limits, provider outages, or quota exhaustion: ```yaml theme={null} models: planning: model: claude-opus-4-6 fallbacks: - openrouter/z-ai/glm-5 - openrouter/moonshotai/kimi-k2.5 execution: model: claude-sonnet-4-6 fallbacks: - gpt-4o - gemini-2.5-pro ``` When a model fails, Pi automatically tries the next entry in the `fallbacks` list. No manual intervention required. ## Selecting a Model in Session Switch models interactively from inside a GSD session: ```text theme={null} /model ``` This opens a model picker showing all models from your configured providers. Select a model to switch immediately for the current session. Preferences-file settings take effect on the next auto-mode dispatch. ## Using Multiple Providers Pi can route different phases to different providers. Use the `provider/model` format to target a specific provider: ```yaml theme={null} models: research: openrouter/deepseek/deepseek-r1 planning: claude-opus-4-6 execution: claude-sonnet-4-6 execution_simple: gpt-4o-mini ``` Or use the object form with an explicit `provider` field: ```yaml theme={null} models: planning: model: claude-opus-4-6 provider: bedrock fallbacks: - claude-opus-4-6 ``` ### Cross-Provider Routing When `cross_provider: true` is enabled in dynamic routing, Pi uses its built-in cost table to find the cheapest model at each tier across all configured providers. This can significantly reduce costs when you have multiple providers available. Cross-provider routing requires each target provider to be configured with valid credentials. Pi will not attempt to use a provider that isn't set up. ## Custom and Local Models For providers not built into Pi (Ollama, LM Studio, vLLM, SGLang, or any OpenAI-compatible endpoint), define them in `~/.gsd/agent/models.json`: ```json theme={null} { "providers": { "ollama": { "baseUrl": "http://localhost:11434/v1", "api": "openai-completions", "apiKey": "ollama", "compat": { "supportsDeveloperRole": false, "supportsReasoningEffort": false }, "models": [ { "id": "qwen2.5-coder:7b" }, { "id": "llama3.1:8b" } ] } } } ``` The `models.json` file reloads each time you open `/model` — no restart required to pick up changes. Once defined, reference local models in your per-phase configuration the same way as any cloud model: ```yaml theme={null} models: execution: qwen2.5-coder:7b execution_simple: llama3.1:8b ``` # GSD Pi Project Structure and .gsd/ Directory Layout Source: https://docs.opengsd.net/pi/concepts/project-structure Learn how GSD Pi organizes project state in .gsd/ — the SQLite database, markdown projections, and the Milestone → Slice → Task hierarchy. When GSD Pi initializes in a project, it creates a `.gsd/` directory at the project root. This directory is the single source of truth for everything Pi knows about your project: plans, progress, decisions, codebase knowledge, task summaries, and runtime state. Understanding what lives there helps you read Pi's output, steer the work, and recover if something goes wrong. ## The Source of Truth: `gsd.db` Pi's runtime state lives in a SQLite database at `.gsd/gsd.db`. The database records every milestone, slice, task, requirement, decision, pattern, lesson, summary, and completion event. It runs in WAL mode for safe concurrent access across multiple processes on the same machine. The database is authoritative. Markdown files in `.gsd/` are **projections** — they render the database contents into human-readable form for review, context injection into prompts, and git-friendly history. Editing a markdown file does not change the database unless you explicitly import the change through Pi (for example, with `/gsd migrate` or a dedicated import command). ## Markdown Projections Pi generates and maintains the following key markdown files in `.gsd/`. These files are your primary window into what Pi is doing and what it knows: `STATE.md` reflects the live project state: the active milestone, current slice, active task, and overall progress. Pi regenerates it after every unit transition. Read it to quickly orient yourself when you return to a session. `DECISIONS.md` is a register of architectural and implementation decisions Pi has recorded or that you've explicitly added. Each entry captures what was decided, why, and any constraints it imposes on future work. Editing `DECISIONS.md` directly does not write to the database — use `/gsd knowledge` or let Pi record decisions naturally during planning. `CODEBASE.md` is Pi's synthesized map of the codebase: key modules, entry points, data flows, conventions, and dependencies. Pi writes it on first run and refreshes it with `/gsd codebase update`. It is injected into task prompts to give Pi codebase context without re-reading every file on every turn. `KNOWLEDGE.md` records accumulated project knowledge in three sections: * **Rules** — manually authored operating rules that Pi always respects (file-canonical) * **Patterns** — recurring patterns Pi has observed and stored as memories * **Lessons** — gotchas and lessons learned from previous work, also memory-backed Rules are file-canonical: edit `KNOWLEDGE.md` directly to add or change them. Patterns and Lessons are backed by the `memories` table and projected into the file on session start. `.gsd/PREFERENCES.md` holds project-level configuration in YAML frontmatter: model preferences, planning depth, budget ceiling, verification commands, timeout settings, git behavior, and more. This file is the primary way you tune Pi's behavior for a specific project. Generated during deep planning mode, `REQUIREMENTS.md` records the agreed capability contract using `R###` requirement identifiers grouped by status: Active, Validated, Deferred, and Out of Scope. ## The Milestone → Slice → Task Hierarchy Pi decomposes all work into three levels. Understanding this hierarchy helps you read the planning artifacts and interpret Pi's progress: A milestone is a **shippable increment** — a coherent body of work that moves the project meaningfully forward and can be reviewed and merged as a unit. Each milestone gets a roadmap (`M###-ROADMAP.md`) that defines the slices, success criteria, and completion conditions. Milestones are isolated in git worktrees (when `git.isolation: worktree` is configured) and squash-merged to the main branch when complete. A slice is a **coherent unit of work within a milestone** — a group of related tasks that form a logical step toward the milestone goal. Slices are planned, executed, and completed as a unit. Each slice gets a plan (`S##-PLAN.md`) that describes the slice goal and lists the tasks with their expected inputs and outputs. Slices progress through phases: plan → research (optional) → execute tasks → complete → run UAT → reassess roadmap. A task is an **atomic implementation unit** — a single, focused change that one agent session can complete and commit. Each task gets a plan embedded in the slice plan, and a summary (`T##-SUMMARY.md`) once it completes. Task summaries flow into the next task's context, so later tasks know what earlier tasks built. ## Directory Layout A project after a milestone completes looks like this. Note that worktrees live in `.gsd-worktrees/` — a sibling of `.gsd/` at the project root — not inside `.gsd/` itself: ```text theme={null} / ├── .gsd-worktrees/ # Canonical location for milestone worktrees │ └── M001/ # Git worktree for milestone isolation └── .gsd/ ├── gsd.db # Runtime SQLite database (source of truth) ├── STATE.md # Current milestone / slice / task state ├── DECISIONS.md # Architectural decisions register ├── CODEBASE.md # Synthesized codebase map ├── KNOWLEDGE.md # Rules, patterns, and lessons ├── PREFERENCES.md # Project-level configuration ├── REQUIREMENTS.md # Capability contract (deep mode) │ ├── milestones/ │ └── M001/ │ ├── M001-ROADMAP.md # Milestone roadmap with slice list and success criteria │ ├── M001-CONTEXT.md # Milestone-specific codebase context │ ├── M001-SUMMARY.md # Milestone completion summary │ ├── S01-PLAN.md # Slice plan with task definitions │ ├── S01-ASSESSMENT.md # UAT verdict for this slice │ ├── T01-SUMMARY.md # Task completion summary │ └── T02-SUMMARY.md │ ├── research/ │ ├── STACK.md # Technology stack research (deep mode) │ ├── FEATURES.md # Feature norms research │ ├── ARCHITECTURE.md # Architecture patterns research │ └── PITFALLS.md # Known pitfalls research │ ├── reports/ │ └── M001-report.html # Self-contained HTML milestone report │ ├── exec/ # Sandboxed command output (capped stdout/stderr) ├── runtime/ # Active runtime state and markers └── journal/ # Structured event log for each auto-mode iteration ``` Worktrees created under the legacy `.gsd/worktrees//` location keep working — resolution, listing, merge, and teardown still recognize that path. Only newly created worktrees use the canonical `.gsd-worktrees/` location, so you can upgrade mid-milestone without moving any files. ## Committing `.gsd/` to Git Pi commits planning artifacts to git by default (`git.commit_docs: true`). This gives you a reviewable history of how plans evolved, what decisions were made, and how the milestone progressed. Runtime files like `gsd.db`, exec output, and the `.gsd-worktrees/` directory are automatically added to `.gitignore`. If you prefer to keep all `.gsd/` content local and out of git, set: ```yaml theme={null} git: commit_docs: false ``` Committing the milestone roadmaps, slice plans, and task summaries to git is useful for code review — reviewers can read the planning artifacts alongside the code changes to understand the intent behind each commit. # GSD Pi Git Automation: Commits, PRs, and Branch Isolation Source: https://docs.opengsd.net/pi/configuration/git-automation Control GSD Pi's automatic commits, branch isolation, pull requests, and GitHub sync — configure every aspect of Git automation. GSD Pi manages your Git history automatically — committing after each task, isolating milestone work in branches or worktrees, and optionally creating pull requests and syncing with GitHub Issues. You control every aspect of this behavior through the `git` section of your `PREFERENCES.md` file. ## Git Preferences Add or edit the `git` block in `~/.gsd/PREFERENCES.md` (global) or `.gsd/PREFERENCES.md` (project-level): ```yaml theme={null} git: auto_push: false # Push commits to remote after committing push_branches: false # Push the milestone branch to remote remote: origin # Git remote name (default: origin) snapshots: true # Create WIP snapshot commits during long tasks merge_strategy: squash # "squash" or "merge" isolation: none # "none", "worktree", or "branch" commit_docs: true # Commit .gsd/ planning artifacts to git manage_gitignore: true # Auto-update .gitignore auto_pr: false # Create a PR on milestone completion pr_target_branch: main # Branch to target for auto-created PRs ``` ### Setting Reference The most consequential git setting. Choose how GSD isolates each milestone's work: | Value | Behavior | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `none` (default) | Work happens directly on your current branch. No worktree or milestone branch created. Ideal for hot-reload workflows and small projects. | | `worktree` | Each milestone gets a separate directory at `.gsd-worktrees//` (a sibling of `.gsd/` at the project root) on a `milestone/` branch. Full file isolation. Squash-merged to main on completion. Worktrees created under the legacy `.gsd/worktrees//` location are still recognized for resolution, listing, merge, and teardown. | | `branch` | Work stays in the project root on a `milestone/` branch. No separate directory. Best for submodule-heavy repos where worktrees cause problems. | ```yaml theme={null} git: isolation: worktree ``` See the [Worktrees guide](/pi/guides/worktrees) for full details on each mode. Controls whether GSD squashes all milestone commits into one clean commit on main, or preserves the individual commit history: | Value | Behavior | | ------------------ | ------------------------------------------------------------------------------------------------------------------------ | | `squash` (default) | All commits are squashed into one clean commit on main. Gives a linear history with one meaningful commit per milestone. | | `merge` | Individual commits from the milestone branch are preserved. Use when you want a detailed commit history per task. | ```yaml theme={null} git: merge_strategy: squash ``` When enabled, GSD creates snapshot commits during long-running tasks so work-in-progress is preserved even if the session is interrupted. ```yaml theme={null} git: snapshots: true # default: true ``` Snapshot commits use a `wip:` prefix and are squashed away when the milestone completes. Controls whether GSD commits `.gsd/` planning files (milestones, roadmaps, decisions, etc.) to git alongside code. ```yaml theme={null} git: commit_docs: true # Commit .gsd/ to git (default) ``` Set to `false` to keep all planning artifacts local-only. GSD will add `.gsd/` to `.gitignore` automatically. Useful for teams where only some members use GSD, or when company policy requires a clean repository. When enabled (the default), GSD automatically updates `.gitignore` with its baseline patterns and removes stale entries during self-healing. ```yaml theme={null} git: manage_gitignore: false # Set false to manage .gitignore yourself ``` ## Automatic Pull Requests GSD can create a pull request automatically when a milestone completes. This is designed for teams using branch-based workflows where code goes through PR review before merging. ```yaml theme={null} git: auto_push: true # Required — the branch must be pushed before a PR can be created push_branches: true # Push the milestone branch to remote auto_pr: true # Create a PR on milestone completion pr_target_branch: develop # Target branch (default: main) ``` Automatic PR creation requires the [`gh` CLI](https://cli.github.com/) to be installed and authenticated (`gh auth login`). PR creation failure is non-fatal — GSD logs a warning and continues. ### Manual PR Creation Create a PR from inside a GSD session at any time with `/gsd ship`: ```text theme={null} /gsd ship /gsd ship --draft # Open as draft PR /gsd ship --base develop # Override the target branch /gsd ship --dry-run # Preview without creating ``` Use `/gsd closeout` to finalize a milestone and run any remaining git closeout actions: ```text theme={null} /gsd closeout status # Show pending closeout actions /gsd closeout retry # Retry a failed closeout step /gsd closeout resolve # Mark a step resolved manually ``` ## GitHub Integration GSD can sync milestones, slices, and tasks to GitHub Issues, Milestones, and Projects automatically. Enable and configure it in `PREFERENCES.md`: ```yaml theme={null} github: enabled: true repo: "owner/repo" # Auto-detected from git remote if omitted labels: [gsd, auto-generated] # Labels applied to created issues and PRs project: "Project ID" # Optional GitHub Project board to link ``` | Field | Description | | --------- | ---------------------------------------------------------------------------------------- | | `enabled` | Enable or disable GitHub sync | | `repo` | GitHub repository in `owner/repo` format. Auto-detected from your git remote if not set. | | `labels` | Labels to apply to all GSD-created issues and PRs | | `project` | GitHub Project ID for project board integration | GitHub integration requires the `gh` CLI installed and authenticated. Sync mapping is persisted in `.gsd/.github-sync.json`. GSD is rate-limit aware and skips sync automatically when the GitHub API limit is low. ### GitHub Sync Commands ```text theme={null} /github-sync bootstrap # Initial setup — create Issues and draft PRs from current .gsd/ state /github-sync status # Show sync mapping counts (milestones, slices, tasks) ``` ## Workflow Modes Instead of configuring every git setting individually, set a `mode` to apply sensible defaults for your workflow: ```yaml theme={null} mode: solo # Personal projects mode: team # Shared repos and team workflows ``` | Setting | `solo` | `team` | | ---------------------- | -------- | -------- | | `git.auto_push` | `true` | `false` | | `git.push_branches` | `false` | `true` | | `git.pre_merge_check` | `false` | `true` | | `git.merge_strategy` | `squash` | `squash` | | `git.isolation` | `none` | `none` | | `git.commit_docs` | `true` | `true` | | `unique_milestone_ids` | `false` | `true` | Any explicit preference you set overrides the mode default. Switch modes interactively with `/gsd mode`. ## Commit Format GSD writes commits using the conventional commit format with unit metadata in trailers. Per-task commits carry a `GSD-Task` trailer; milestone-closeout commits created by interactive `gsd_complete_milestone` carry a `GSD-Unit` trailer that names the closed milestone: ``` feat: core type definitions GSD-Task: M001/S01/T01 feat: markdown parser for plan files GSD-Task: M001/S01/T02 chore: complete-milestone M001 GSD-Unit: M001 ``` See [Milestone Completion in Interactive Sessions](/pi/guides/worktrees#milestone-completion-in-interactive-sessions) for when the milestone closeout commit is created and which notices accompany it. Override the default commit type prefix with `git.commit_type`: ```yaml theme={null} git: commit_type: feat # "feat", "fix", "refactor", "docs", "test", "chore", etc. ``` ## Self-Healing Git Issues GSD automatically recovers from common Git problems: Removes `.git/index.lock` only after it's older than 5 minutes, so active git operations on large repos aren't interrupted. Aborts leftover rebase, cherry-pick, or revert state from a killed worker before reconciling merge state. Detects and offers to clean up abandoned worktrees from crashed sessions. Refuses to force-reset a milestone branch if doing so would orphan commits unreachable from the start point. Run `/gsd doctor` to check Git health manually and surface any issues that need attention. # GSD Pi Preferences: Models, Budgets, and Notifications Source: https://docs.opengsd.net/pi/configuration/preferences Set global and project-level preferences to control models, budgets, notifications, Git behavior, and custom instructions for every GSD Pi session. GSD Pi preferences live in a YAML-frontmatter markdown file that you can edit directly or manage through the interactive wizard. Global preferences apply to all projects on your machine, while project-level preferences apply only to the current project and take priority over global values. This gives you a sensible baseline for all work with per-project overrides when needed. | Scope | Path | Applies to | | ------- | ----------------------- | ---------------------------- | | Global | `~/.gsd/PREFERENCES.md` | All projects on this machine | | Project | `.gsd/PREFERENCES.md` | Current project only | Open the interactive preferences wizard from inside a GSD session: ```text theme={null} /gsd prefs # Open global preferences wizard /gsd prefs project # Open project-level wizard /gsd prefs status # Show current merged values and skill resolution ``` ## Preferences File Format Preferences use YAML frontmatter in a markdown file. Everything between the `---` delimiters is parsed as YAML; any markdown below is ignored by GSD but useful for your own notes. ```yaml theme={null} --- version: 1 models: execution: claude-sonnet-4-6 planning: claude-opus-4-6 token_profile: balanced budget_ceiling: 25.00 budget_enforcement: pause auto_supervisor: soft_timeout_minutes: 20 hard_timeout_minutes: 30 idle_timeout_minutes: 10 notifications: enabled: true on_milestone: true on_attention: true custom_instructions: - "Always use TypeScript strict mode" - "Prefer functional patterns over classes" --- ``` ## Merge Behavior When both a global and a project preferences file exist, GSD merges them with these rules: * **Scalar fields** (e.g., `budget_ceiling`, `token_profile`): the project value wins if set * **Object fields** (e.g., `models`, `git`, `auto_supervisor`): shallow-merged, project overrides per-key * **Array fields** (e.g., `always_use_skills`, `custom_instructions`): concatenated, global first then project ## Model Settings Control which LLM model GSD uses for each phase of the auto-mode pipeline. ```yaml theme={null} models: research: claude-sonnet-4-6 planning: claude-opus-4-6 execution: claude-sonnet-4-6 execution_simple: claude-haiku-4-5-20250414 completion: claude-sonnet-4-6 subagent: claude-sonnet-4-6 ``` | Phase | Description | | ------------------ | --------------------------------------------------- | | `research` | Milestone and slice research phases | | `planning` | Milestone and slice planning | | `execution` | Task execution (standard complexity) | | `execution_simple` | Task execution (simple tasks, routed by complexity) | | `completion` | Slice and milestone completion | | `subagent` | Delegated child-agent tasks | Use the `provider/model` format to target a specific provider (e.g., `bedrock/claude-sonnet-4-6`). Add a `fallbacks` list to continue automatically if a model is unavailable: ```yaml theme={null} models: planning: model: claude-opus-4-6 fallbacks: - openrouter/z-ai/glm-5 ``` ### Token Profile `token_profile` coordinates model selection, phase skipping, and context compression in one setting: ```yaml theme={null} token_profile: balanced # "budget", "balanced" (default), or "quality" ``` | Profile | Behavior | | ---------- | ------------------------------------------------------------------------------- | | `budget` | Skips research and reassessment phases; uses cheaper models for eligible phases | | `balanced` | Default — all phases run with standard model selection | | `quality` | All phases run; prefers higher-quality models throughout | ### Planning Depth Controls how much upfront discovery runs before milestone planning: ```yaml theme={null} planning_depth: deep # "light" (default) or "deep" ``` Use `deep` for complex greenfield projects. Enable it for a specific project with `/gsd new-project --deep` rather than setting it globally. ## Budget and Safety ```yaml theme={null} budget_ceiling: 25.00 # Maximum USD to spend in auto mode (no $ sign) budget_enforcement: pause # "warn", "pause" (default), or "halt" context_pause_threshold: 80 # Pause at 80% context usage (0 = disabled) ``` | `budget_enforcement` value | Behavior | | -------------------------- | ---------------------------------------- | | `warn` | Log a warning and continue | | `pause` | Pause auto mode at the ceiling (default) | | `halt` | Stop auto mode entirely | ### Auto-Mode Supervision Timeouts ```yaml theme={null} auto_supervisor: soft_timeout_minutes: 20 # Warn the LLM to wrap up idle_timeout_minutes: 10 # Detect stalls and intervene hard_timeout_minutes: 30 # Pause auto mode if no progress ``` GSD sends a "wrap up" signal at the soft timeout, detects stalls at the idle timeout, and pauses the session at the hard timeout if recovery steering can't make durable progress. ## Notifications ```yaml theme={null} notifications: enabled: true local_bell: false # Play terminal bell on questions and auto-mode stops on_complete: true # Notify on unit completion on_error: true # Notify on errors on_budget: true # Notify on budget threshold crossings on_milestone: true # Notify when a milestone finishes on_attention: true # Notify when GSD needs your input ``` On macOS, install `terminal-notifier` for reliable notification delivery: `brew install terminal-notifier`. Without it, GSD falls back to `osascript`, which may not have notification permissions in System Settings. ## Custom Instructions Durable instructions that GSD appends to every session prompt. Use these for project-wide coding standards or conventions you want the agent to follow consistently. ```yaml theme={null} custom_instructions: - "Always use TypeScript strict mode" - "Write tests before implementation" - "Prefer named exports over default exports" ``` For project-specific knowledge that evolves over time — architectural patterns, lessons learned, recurring pitfalls — use the GSD knowledge system (`/gsd knowledge rule`) instead of `custom_instructions`. Knowledge entries are memory-backed and selected contextually; `custom_instructions` appear in every prompt regardless of relevance. ## Skill Routing Control which skills GSD uses during auto mode. Skills are optional extensions that provide domain-specific behavior. ```yaml theme={null} always_use_skills: - debug-like-expert # Always inject this skill prefer_skills: - frontend-design # Prefer this skill when relevant avoid_skills: - aggressive-refactor # Never use this skill skill_rules: - when: task involves authentication use: [clerk] - when: frontend styling work prefer: [frontend-design] - when: working with legacy code avoid: [aggressive-refactor] ``` | Setting | Behavior | | ------------------- | ---------------------------------------- | | `always_use_skills` | Always included in every dispatch prompt | | `prefer_skills` | Included with a preference indicator | | `avoid_skills` | Never selected, even if relevant | | `skill_rules` | Conditional routing by task description | ### Skill Discovery ```yaml theme={null} skill_discovery: suggest # "auto", "suggest" (default), or "off" ``` | Value | Behavior | | --------- | -------------------------------------------------------- | | `auto` | Skills found and applied automatically | | `suggest` | Skills identified during research but not auto-installed | | `off` | Skill discovery disabled entirely | ## Full Example ```yaml theme={null} --- version: 1 # Model selection models: research: claude-sonnet-4-6 planning: claude-opus-4-6 execution: claude-sonnet-4-6 execution_simple: claude-haiku-4-5-20250414 completion: claude-sonnet-4-6 subagent: claude-sonnet-4-6 # Token optimization token_profile: balanced planning_depth: light # Budget budget_ceiling: 25.00 budget_enforcement: pause context_pause_threshold: 80 # Supervision auto_supervisor: soft_timeout_minutes: 20 idle_timeout_minutes: 10 hard_timeout_minutes: 30 # Notifications notifications: enabled: true local_bell: false on_complete: false on_error: true on_budget: true on_milestone: true on_attention: true # Custom instructions custom_instructions: - "Always write TypeScript, never plain JavaScript" - "Add JSDoc comments to all exported functions" # Skill routing skill_discovery: suggest always_use_skills: - debug-like-expert skill_rules: - when: task involves authentication use: [clerk] --- ``` # Connect LLM Providers to GSD Pi: Anthropic to Ollama Source: https://docs.opengsd.net/pi/configuration/providers Connect Anthropic, OpenAI, Gemini, Ollama, and 10+ other LLM providers to GSD Pi — set API keys, list models, and switch providers per session. GSD Pi supports a wide range of LLM providers. During first-run setup, the onboarding wizard walks you through provider configuration. At any point afterward, re-run the setup wizard to add or change providers. ```bash theme={null} gsd config ``` This opens an interactive wizard that shows which credentials are configured and which are missing. Select a provider to enter or update its credentials. ## Supported Providers | Provider | Environment Variable | Notes | | ------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Anthropic (Claude) | `ANTHROPIC_API_KEY` | Recommended. Deepest integration: built-in web search, extended thinking, prompt caching. Includes Claude Fable 5 (1M context, Opus-tier reasoning). | | OpenAI | `OPENAI_API_KEY` | GPT-4o, o1, o3, and all current OpenAI models. | | Google Gemini | `GEMINI_API_KEY` | Gemini 1.5 Pro, Flash, and Gemini 2.x models. | | OpenRouter | `OPENROUTER_API_KEY` | 200+ models from multiple providers via a single key. | | Groq | `GROQ_API_KEY` | High-throughput inference for Llama, Mixtral, and others. | | xAI (Grok) | `XAI_API_KEY` | Grok-2 and Grok-3 models. | | Mistral | `MISTRAL_API_KEY` | Mistral Large, Small, and Codestral. | | GitHub Copilot | `GH_TOKEN` | OAuth-based — sign in via browser with `gsd config`. | Set any of these as environment variables before starting GSD: ```bash theme={null} export ANTHROPIC_API_KEY="sk-ant-..." gsd ``` Or save them permanently with `gsd config` — keys are stored in `~/.gsd/agent/auth.json` and apply to all projects automatically. | Provider | Auth Method | Configuration | | ---------------------- | ------------------------------- | ------------------------------------------------------------------------------ | | Amazon Bedrock | IAM credentials | `AWS_PROFILE`, or `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` + `AWS_REGION` | | Anthropic on Vertex AI | Application Default Credentials | Run `gcloud auth application-default login`, set `ANTHROPIC_VERTEX_PROJECT_ID` | | Azure OpenAI | API key | `AZURE_OPENAI_API_KEY` | **Bedrock example:** ```bash theme={null} export AWS_PROFILE="my-bedrock-profile" gsd ``` ECS task roles and IRSA (Kubernetes) are detected automatically for Bedrock. **Vertex AI example:** ```bash theme={null} gcloud auth application-default login export ANTHROPIC_VERTEX_PROJECT_ID="my-gcp-project" gsd ``` Local providers run on your machine and require a `~/.gsd/agent/models.json` configuration file so GSD knows the endpoint URL and which models are available. **Ollama:** ```bash theme={null} # Start Ollama and pull a model ollama serve ollama pull llama3.1:8b ``` ```json theme={null} { "providers": { "ollama": { "baseUrl": "http://localhost:11434/v1", "api": "openai-completions", "apiKey": "ollama", "compat": { "supportsDeveloperRole": false, "supportsReasoningEffort": false }, "models": [ { "id": "llama3.1:8b" }, { "id": "qwen2.5-coder:7b" } ] } } } ``` Set `OLLAMA_HOST` to override the default server URL: ```bash theme={null} export OLLAMA_HOST="http://my-ollama-server:11434" ``` For remote Ollama endpoints that require authentication: ```bash theme={null} export OLLAMA_API_KEY="your-bearer-token" ``` **LM Studio, vLLM, SGLang:** Follow the same `models.json` pattern, adjusting `baseUrl` and `apiKey` for your server. Set `compat.supportsDeveloperRole: false` and `compat.supportsReasoningEffort: false` for all local inference servers. ## Listing Available Models List all models GSD can find with your current credentials: ```bash theme={null} gsd --list-models ``` Filter by name or provider: ```bash theme={null} gsd --list-models claude gsd --list-models gpt-4 gsd --list-models openrouter ``` ## Overriding the Model for a Session Pass `--model` when starting GSD to use a specific model for that session, ignoring whatever is set in preferences: ```bash theme={null} gsd --model claude-opus-4-6 gsd --model openrouter/deepseek/deepseek-r1 ``` ## Switching Models In-Session Change the active model without restarting the session: ```text theme={null} /gsd model ``` This opens an interactive model picker showing all available models from your configured providers. The `models.json` file reloads each time you open the picker — no restart needed. You can also switch directly: ```text theme={null} /gsd model claude-haiku-4-5-20250414 ``` ## Claude Fable 5 Claude Fable 5 is an Opus-tier Anthropic model that ships across the Anthropic API, Anthropic on Vertex AI, Amazon Bedrock, and OpenRouter. Pi treats it the same as `claude-opus-4-8`: it advertises a 1M-token context window, 128K max output, image and text input, and adaptive thinking with the `xhigh` effort level enabled by default. Use it when you want maximum reasoning quality on planning, debugging, or long-context refactors and you're willing to spend Opus-tier dollars (or, on a Claude Pro / Max / Team / Enterprise subscription, route through Claude Code for subscription-covered usage). Once your Anthropic credentials are configured, Claude Fable 5 appears in the model picker by ID: ```text theme={null} /gsd model claude-fable-5 ``` Or pin it for a specific phase in `PREFERENCES.md`: ```yaml theme={null} models: planning: claude-fable-5 execution: claude-sonnet-4-6 ``` To use Claude Fable 5 through a non-direct provider, prefix the model ID with the provider: ```yaml theme={null} models: planning: bedrock/claude-fable-5 execution: vertex/claude-fable-5 ``` When invoked through the Claude Code CLI, `claude-fable-5` is also exposed on the heavy routing tier with subscription-covered pricing and the `context-1m-2025-08-07` beta enabled automatically. ## Using Claude Subscriptions via Claude Code If you have a Claude Pro, Max, Team, or Enterprise subscription, authenticate through Anthropic's official Claude Code CLI instead of an API key: ```bash theme={null} # Install and sign into Claude Code claude # Then start GSD — it detects Claude Code automatically gsd ``` GSD detects your local Claude Code installation and routes through it automatically. This is the terms-of-service-compliant path for subscription users — GSD never handles your subscription credentials directly. ## Adding Custom or Unlisted Models Define custom models, local endpoints, and OpenAI-compatible proxies in `~/.gsd/agent/models.json`: ```json theme={null} { "providers": { "my-custom-endpoint": { "baseUrl": "https://my-proxy.example.com/v1", "apiKey": "MY_PROVIDER_API_KEY", "api": "openai-completions", "models": [ { "id": "my-model-id", "name": "My Custom Model", "contextWindow": 128000, "maxTokens": 16384, "cost": { "input": 0.15, "output": 0.60, "cacheRead": 0, "cacheWrite": 0 } } ] } } } ``` The `apiKey` value is the name of the environment variable GSD should read (not the literal key). GSD resolves it automatically at runtime. ## Per-Phase Model Routing Assign different providers or models to different phases of the auto-mode pipeline in `PREFERENCES.md`: ```yaml theme={null} models: research: openrouter/deepseek/deepseek-r1 # Cheaper for research planning: claude-opus-4-6 # Best quality for planning execution: claude-sonnet-4-6 # Balanced for execution execution_simple: claude-haiku-4-5-20250414 # Fast and cheap for simple tasks ``` ## Verifying Your Setup After configuring a provider, verify everything is working: ```bash theme={null} gsd ``` ```text theme={null} /gsd model ``` Your provider's models should appear in the list. ```text theme={null} /gsd doctor ``` GSD checks provider connectivity and reports any credential or configuration issues. If a model doesn't appear, check that: * The environment variable is exported in the current shell * `~/.gsd/agent/models.json` is valid JSON (`cat ~/.gsd/agent/models.json | python3 -m json.tool`) * The local inference server is running (for Ollama, LM Studio, etc.) # GSD Pi Headless Mode: CI/CD, Cron Jobs, and Automation Source: https://docs.opengsd.net/pi/guides/headless-ci Run GSD Pi without a terminal UI for CI pipelines, cron jobs, and automation — with JSON output, exit codes, and remote question routing. GSD Pi's headless mode removes the interactive TUI so you can pipe output, script automation, and run unattended workflows in CI/CD environments. All the same planning and execution logic runs — you just interact with it programmatically instead of through the terminal interface. ## The `gsd headless` Command `gsd headless [subcommand]` is the main entry point for non-interactive use. It spawns a child GSD process in RPC mode, auto-responds to interactive prompts, and exits with a meaningful code when done. ```bash theme={null} # Run auto mode (default subcommand) gsd headless # Run a single unit of work gsd headless next # Instant JSON state snapshot — no LLM calls, ~50ms gsd headless query # Run auto mode with a 10-minute timeout gsd headless --timeout 600000 auto # Create a new milestone from a file and start auto mode gsd headless new-milestone --context brief.md --auto # Create a milestone from inline text gsd headless new-milestone --context-text "Build a REST API with JWT auth" # Pipe context from stdin echo "Build a CLI tool for CSV processing" | gsd headless new-milestone --context - ``` ## Subcommands | Subcommand | Description | | ------------------ | --------------------------------------------------------------------------------------- | | `auto` | Run full auto mode (default when no subcommand given) | | `next` | Execute the next single unit of work | | `status` | Print current project state | | `new-milestone` | Create a new milestone (requires `--context` or `--context-text`) | | `query` | Return an instant JSON snapshot of project state | | `recover` | Reset DB hierarchy and reconstruct from markdown (non-TTY equivalent of `/gsd recover`) | | `dispatch ` | Force-dispatch a specific phase | ## Key Flags | Flag | Description | | ----------------------- | ------------------------------------------------------------- | | `--timeout N` | Overall timeout in milliseconds (default: 300000 / 5 min) | | `--json` | Stream all events as JSONL to stdout | | `--output-format ` | Output format for results | | `--bare` | Minimal output, no decoration | | `--resume ` | Resume a specific session by ID | | `--model ID` | Override the model for this headless session | | `--supervised` | Require human confirmation at key decision points | | `--response-timeout N` | Timeout for individual LLM responses | | `--answers ` | Path to a file of pre-written answers for interactive prompts | | `--events ` | Filter which event types to stream (comma-separated) | | `--context ` | Context file for `new-milestone` (use `-` for stdin) | | `--context-text ` | Inline context text for `new-milestone` | | `--auto` | Chain into auto mode after milestone creation | | `--verbose` | Verbose output for debugging | | `--max-restarts N` | Auto-restart on crash with exponential backoff (default: 3) | ## Exit Codes | Code | Meaning | | ---- | -------------------------------------------------- | | `0` | Success — work completed normally | | `1` | Error — timeout, crash, or unrecoverable failure | | `10` | Blocked — auto mode stopped because it needs input | | `11` | Cancelled — work was cancelled externally | Use exit code `10` in your CI script to detect when GSD has a question that requires human input. You can route those questions to Slack, Discord, or Telegram using the `remote_questions` configuration rather than failing the build. ## Instant State Snapshot with `query` `gsd headless query` returns a single JSON object describing the full project state without starting an LLM session. It's the recommended way for orchestrators and external scripts to inspect GSD state between runs. ```bash theme={null} gsd headless query | jq '.state.phase' # "executing" gsd headless query | jq '.next' # {"action":"dispatch","unitType":"execute-task","unitId":"M001/S01/T03"} gsd headless query | jq '.cost.total' # 4.25 ``` The output includes `state` (current phase, active milestone, progress, blockers), `next` (the next dispatch action), and `cost` (per-worker and aggregate spend). ## Streaming JSON Events Add `--json` to stream all session events as JSONL to stdout. This is useful for log aggregation, monitoring dashboards, and build pipelines that need structured output. ```bash theme={null} gsd headless --json auto > gsd-events.jsonl ``` To capture token telemetry separately: ```bash theme={null} PI_TOKEN_TELEMETRY=1 gsd headless --json auto \ > gsd-events.jsonl \ 2> token-telemetry.jsonl ``` ## Auto-Mode Without the TUI Use `gsd auto` as a shorthand for non-interactive auto mode with pipeable output: ```bash theme={null} gsd auto [args] ``` This is equivalent to `gsd headless auto` for most purposes and respects all the same flags. ## GitHub Actions Example Here's a complete example workflow that runs GSD Pi in CI to continue work on a project, failing gracefully when blocked: ```yaml theme={null} name: GSD Auto Mode on: schedule: - cron: "0 2 * * *" # Run nightly at 2 AM workflow_dispatch: jobs: gsd-auto: runs-on: ubuntu-latest timeout-minutes: 60 steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: actions/setup-node@v4 with: node-version: "22" - name: Install GSD Pi run: npm install -g @opengsd/gsd-pi@latest - name: Configure provider credentials env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: echo "Provider configured via environment" - name: Run GSD headless auto mode env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | gsd headless --timeout 3000000 --json auto \ > gsd-events.jsonl || EXIT_CODE=$? echo "Exit code: ${EXIT_CODE:-0}" if [ "${EXIT_CODE:-0}" -eq 10 ]; then echo "GSD is blocked and needs input — check remote questions channel" exit 0 # Don't fail the build for blocked state fi exit "${EXIT_CODE:-0}" - name: Upload session log if: always() uses: actions/upload-artifact@v4 with: name: gsd-events path: gsd-events.jsonl ``` ## Remote Questions for Unattended Runs When GSD needs to ask a question during headless auto mode, it can route that question to Slack, Discord, or Telegram instead of blocking the process. Configure `remote_questions` in your project's `PREFERENCES.md`: ```yaml theme={null} remote_questions: channel: slack # "slack", "discord", or "telegram" channel_id: "C1234567890" timeout_minutes: 15 # How long to wait for an answer (1–30) poll_interval_seconds: 10 # How often to check for a reply (2–30) ``` With this configured, GSD posts the question to your chosen channel, waits for a reply, and continues execution. If no answer arrives within `timeout_minutes`, GSD exits with code `10`. When `notifications.enabled: true` is set alongside a remote channel, informational notifications — milestone completions, budget alerts, blockers — are also sent to that channel, not just to the desktop. ## Crash Recovery and Auto-Restart Headless auto mode restarts automatically on crash with exponential backoff (5s → 10s → 30s cap, default 3 attempts). Combined with GSD's database-backed state persistence, this enables true overnight "run until done" execution. ```bash theme={null} gsd headless --max-restarts 5 auto ``` Set `--max-restarts 0` to disable auto-restart. SIGINT and SIGTERM always bypass the restart logic and exit immediately. After a crash, run `gsd headless recover` to reset the DB hierarchy and rebuild state from rendered markdown before retrying: ```bash theme={null} gsd headless recover && gsd headless auto ``` # Expose GSD Pi Tools via MCP Server to AI Coding Clients Source: https://docs.opengsd.net/pi/guides/mcp-server Expose GSD Pi's full workflow toolset to Claude Desktop, VS Code Copilot, Cursor, and any MCP-compatible client via stdin/stdout or HTTP. GSD Pi can run as a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server, exposing its planning, execution, and workflow tools to any MCP-compatible AI client. This lets you use GSD Pi's structured project management capabilities — milestone planning, task completion, slice management, roadmap reassessment — directly from Claude Desktop, VS Code Copilot, Cursor, or any other client that supports MCP. ## Starting GSD Pi as an MCP Server Run GSD Pi in MCP server mode over stdin/stdout: ```bash theme={null} gsd --mode mcp ``` The server registers all tools from the GSD agent session and maps MCP `tools/list` and `tools/call` requests to GSD tool definitions. It runs until the transport closes. ## Configuring MCP Clients ### Automatic Setup When GSD detects a Claude Code model during startup, it automatically writes a `.mcp.json` file in your project root with the GSD workflow MCP server configured. No manual steps are needed — start GSD once with Claude Code as the provider and the config is created for you. You can also trigger this manually from inside a GSD session: ```text theme={null} /gsd mcp init ``` ### Manual Configuration Add GSD Pi to your project's `.mcp.json` file: ```json theme={null} { "mcpServers": { "gsd": { "command": "gsd", "args": ["--mode", "mcp"] } } } ``` For HTTP transport (connecting to a running GSD server): ```json theme={null} { "mcpServers": { "gsd": { "url": "http://localhost:3000/mcp" } } } ``` Use `.mcp.json` for shared team configuration you want to commit to the repository. Use `.gsd/mcp.json` for local-only configuration with machine-specific paths or personal credentials. ## Supported Clients Add the `gsd` server entry to your Claude Desktop MCP configuration. GSD's full workflow tool surface becomes available in every Claude conversation. Place `.mcp.json` in the project root. VS Code Copilot discovers it automatically and exposes GSD tools to GitHub Copilot Chat. Add GSD to Cursor's MCP settings to access GSD milestone and task management directly from the Cursor editor. Any client that implements the MCP specification can connect. Use stdio transport for local tools, or HTTP transport for remote setups. ## What Tools Are Exposed The MCP server exposes GSD's complete workflow tool surface, including: * Milestone planning, slice management, and task completion * Roadmap reassessment and requirement tracking * Journal queries and session history * Session management tools (`gsd_execute`, `gsd_status`, `gsd_result`, `gsd_cancel`) for starting and monitoring auto-mode sessions Run `/gsd mcp status` from inside a GSD session to verify the connection and list available tools. ## Cloud MCP Gateway The Cloud MCP Gateway lets remote MCP clients call GSD workflow tools through a local runtime — useful when your AI client can't reach your workstation directly but your workstation can open an outbound connection. ### How It Works 1. A gateway process (`gsd-cloud-mcp-gateway`) runs on a publicly reachable server 2. Your local GSD runtime connects to the gateway with a device token 3. Remote MCP clients send tool calls to the gateway, which forwards them to your local runtime ### Setting Up the Gateway On your gateway server: ```bash theme={null} export GSD_CLOUD_USER_TOKEN="your-long-random-token" gsd-cloud-mcp-gateway --port 8787 ``` ### Pairing a Local Runtime Generate a pairing code, then pair your local machine: ```bash theme={null} # On the gateway server — generate a pairing code curl -sS -X POST "https://your-gateway.example.com/pairing-codes" \ -H "Authorization: Bearer $GSD_CLOUD_USER_TOKEN" # On your local machine — pair with the code gsd-daemon cloud pair \ --gateway "https://your-gateway.example.com" \ --code "PAIRING_CODE" \ --runtime-name "My Laptop" ``` ### Connecting to the Gateway Start the local runtime connection. It maintains a persistent WebSocket to the gateway and forwards tool calls to GSD: ```bash theme={null} gsd-daemon cloud connect --verbose ``` Check connection status at any time: ```bash theme={null} gsd-daemon cloud status ``` To disconnect and remove local credentials: ```bash theme={null} gsd-daemon cloud disconnect ``` ### Connecting Remote MCP Clients Point any MCP client at the gateway MCP endpoint: ``` URL: https://your-gateway.example.com/mcp Authorization: Bearer ``` The gateway forwards calls to the connected local runtime. When multiple runtimes are connected, include `runtimeId` or `projectAlias` in the call to specify which runtime to target. Treat `GSD_CLOUD_USER_TOKEN` and device tokens like passwords. Never commit them to project files or share them in issue trackers. ## JSON-RPC Mode For programmatic integration that doesn't require full MCP protocol, GSD Pi also supports a JSON-RPC interface over stdin/stdout: ```bash theme={null} gsd --mode rpc ``` This is lower-level than MCP and is primarily used by GSD's own headless mode and the VS Code extension bridge. Use `--mode mcp` for standard MCP client integration. ## Managing MCP Connections Inspect and manage MCP server connections from inside a GSD session: | Command | Description | | ------------------------- | -------------------------------------------------- | | `/gsd mcp status` | Show configured servers and connection state | | `/gsd mcp check` | Verify servers are reachable | | `/gsd mcp discover` | List tools available from each server | | `/gsd mcp test` | Send a test call to verify a server | | `/gsd mcp enable ` | Enable a disabled server | | `/gsd mcp disable ` | Disable a server without removing config | | `/gsd mcp import` | Import server config from a file | | `/gsd mcp delete ` | Remove a server from config | | `/gsd mcp init` | Auto-write `.mcp.json` for Claude Code integration | # Bootstrap a New Codebase or Repository with GSD Pi Source: https://docs.opengsd.net/pi/guides/new-project Bootstrap a new GSD Pi project, generate a milestone roadmap, and kick off autonomous implementation — from a blank directory in minutes. GSD Pi's project bootstrapping flow takes you from a blank directory to a structured plan with milestones, slices, and tasks — all stored in a `.gsd/` directory that acts as the living brain of your project. Whether you're starting something greenfield or formalizing an existing codebase, `/gsd new-project` is the entry point. ## Starting a New Project Navigate to the root of the repository (or an empty folder for a greenfield project) and start a GSD session. ```bash theme={null} cd path/to/your-project gsd ``` Inside the GSD session, run the bootstrapping command. Add `--deep` to trigger a staged discovery flow that gathers deeper context before planning. ```text Standard theme={null} /gsd new-project ``` ```text Deep discovery theme={null} /gsd new-project --deep ``` Use `--deep` for complex projects, greenfield builds, or any time you want GSD to ask detailed questions about workflow preferences, requirements, and architecture before planning milestones. GSD will prompt you for the information it needs. Be as specific as you like about: * What the project does and who it's for * Your preferred tech stack and languages * Constraints, non-goals, and anti-patterns to avoid * Any existing code GSD should understand before planning The more context you provide here, the better the generated plan will match your intentions. After your conversation, GSD creates the `.gsd/` directory with everything it needs to manage the project: | File | Purpose | | ----------------- | ------------------------------------------------ | | `STATE.md` | Current project phase and active milestone | | `DECISIONS.md` | Architectural decisions and rationale | | `CODEBASE.md` | Auto-generated codebase summary | | `M001-ROADMAP.md` | The first milestone's slice-by-slice plan | | `M001-CONTEXT.md` | Milestone-level context GSD injects into prompts | In **deep mode**, you'll also see: | File | Purpose | | -------------------------- | ----------------------------------------------------- | | `PROJECT.md` | Vision, users, anti-goals, and constraints | | `REQUIREMENTS.md` | Capability contract with `R###`-numbered requirements | | `research/STACK.md` | Stack and tooling research | | `research/ARCHITECTURE.md` | Architectural patterns and trade-offs | Open `M001-ROADMAP.md` and review the generated milestones and slices. You can edit this file directly or use `/gsd discuss` to talk through any changes with GSD before committing to the plan. To reorganize or reorder milestones interactively, run: ```text theme={null} /gsd rethink ``` When you're happy with the plan, kick off auto mode: ```text theme={null} /gsd auto ``` GSD will research, plan, execute, commit, and repeat — handling the full milestone lifecycle until it finishes or needs your input. ## Starting a New Milestone on an Existing Project Once your project is bootstrapped, use `/gsd new-milestone` to plan the next major chunk of work without losing any existing state. ```text theme={null} /gsd new-milestone ``` Add `--deep` to run the staged discovery flow for the new milestone, which is useful when the scope has shifted significantly or you're entering a new domain. ```text theme={null} /gsd new-milestone --deep ``` `/gsd new-milestone --deep` writes `planning_depth: deep` to `.gsd/PREFERENCES.md` so that all future milestones on this project also use the deep planning flow by default. You can remove or override this setting at any time. ## Managing Your Milestone Queue After creating multiple milestones, use the queue commands to prioritize and reorder work: ```text theme={null} /gsd queue ``` This opens an interactive view of all pending milestones. You can change their order, park milestones you're not ready for yet, or discard ones that are no longer relevant. ## What Happens Under the Hood When you run `/gsd new-project --deep`, GSD runs a multi-step discovery sequence before any milestone planning begins: 1. **Workflow preferences** — captures how you like to work (test-first, documentation style, commit conventions) 2. **Project context** — writes `.gsd/PROJECT.md` with vision, users, and anti-goals 3. **Requirements** — writes `.gsd/REQUIREMENTS.md` with structured `R###`-numbered requirements 4. **Research decision** — decides whether to do deep technical research or proceed directly to planning 5. **Optional project research** — if research is warranted, generates `STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, and `PITFALLS.md` under `.gsd/research/` 6. **Milestone planning** — generates the first milestone's context and roadmap using all the above as input GSD uses `.gsd/` as the single source of truth for project state. The markdown files are human-readable projections you can review, edit, and commit alongside your code. You can commit `.gsd/` files to git to share planning artifacts with your team. Set `git.commit_docs: false` in preferences if you want to keep them local-only. # GSD Pi Web Interface: Dashboard and Live Monitoring Source: https://docs.opengsd.net/pi/guides/web-ui Launch GSD Pi's browser-based dashboard for project management, live session monitoring, file browsing, and preferences — all without the terminal UI. GSD Pi includes a browser-based web interface that gives you a visual project dashboard alongside the terminal. Use it to monitor auto mode in real time, browse your knowledge base, edit preferences, manage multiple projects, and access a built-in terminal emulator — all from a standard web browser. ## Launching the Web Interface Start the web interface from your terminal with the `--web` flag: ```bash theme={null} gsd --web ``` This starts a local web server and opens the GSD dashboard in your default browser. The URL (including port) is printed to the terminal on startup — typically `http://localhost:3000`. You can also pass an optional path to open GSD in a specific project directory: ```bash theme={null} gsd --web /path/to/my-project ``` ### Starting and Stopping with the `web` Subcommand Use the `gsd web` subcommand to manage the web server independently of a GSD session: ```bash theme={null} gsd web # Start the web server gsd web stop # Stop a running web server ``` ### Custom Host and Port Override the default bind address and port with CLI flags: ```bash theme={null} gsd --web --host 0.0.0.0 --port 8080 ``` | Flag | Default | Description | | ------------------- | ----------- | -------------------------------------------- | | `--host` | `localhost` | Bind address for the web server | | `--port` | `3000` | Port for the web server | | `--allowed-origins` | (none) | Comma-separated list of allowed CORS origins | Binding to `0.0.0.0` exposes the web UI on all network interfaces. Only do this on trusted networks or behind a firewall. The web server has no built-in authentication beyond the session token GSD generates at startup. ## What the Web UI Provides A full xterm.js-powered terminal runs inside the browser. Start GSD sessions, run commands, and interact with the TUI without leaving the web interface. A visual overview of milestones, slices, and tasks with progress indicators, dependency graphs, and status badges. Server-sent events push real-time updates as auto mode executes. Watch tasks complete, costs accumulate, and milestone progress advance without refreshing the page. Switch between active sessions, view session history, and resume a previous session — all from the browser sidebar. Browse your project's knowledge base including `KNOWLEDGE.md` rules, patterns, lessons, and architectural decisions stored in `DECISIONS.md`. Edit global and project-level preferences through a guided web form — no need to manually edit YAML frontmatter in `PREFERENCES.md`. Navigate the project directory and `.gsd/` artifact files directly from the browser, with syntax-highlighted viewing. Live cost panels show per-session and per-milestone spending, token usage, and projections based on current burn rate. ## Multi-Project Support The web UI supports multiple projects from a single browser tab. Switch between projects using the `?project=` URL parameter: ``` http://localhost:3000?project=/path/to/other-project ``` You can also change the active project root from within the web UI without restarting the server. Set `GSD_WEB_PROJECT_CWD` as an environment variable to specify the default project when `?project=` is not in the URL: ```bash theme={null} GSD_WEB_PROJECT_CWD=/path/to/my-project gsd --web ``` ## Notification History The web UI tracks all notifications GSD sends during a session — milestone completions, budget alerts, blockers, and attention requests — in a persistent notification panel. Click any notification to jump to the relevant part of the dashboard. ## Platform Notes The GSD Pi web interface is supported on **macOS** and **Linux**. The web build is skipped on Windows due to Next.js webpack compatibility issues with certain system directories. The GSD CLI and TUI remain fully functional on Windows. ## MCP and API Routes The web server exposes a rich set of API routes that power the dashboard. These routes are also available for integrations and tooling: | Route | Description | | -------------------- | -------------------------------- | | `/api/live-state` | SSE stream of live session state | | `/api/projects` | List and switch projects | | `/api/preferences` | Read and write preferences | | `/api/knowledge` | Browse the knowledge base | | `/api/session` | Session management | | `/api/git` | Git status and worktree info | | `/api/notifications` | Notification history | | `/api/history` | Execution history | | `/api/terminal` | Terminal bridge for xterm.js | You can use the `/api/live-state` SSE endpoint to build your own dashboard integrations — pipe the event stream to monitoring tools, Slack webhooks, or any system that can consume server-sent events. # Git Worktree Isolation and Parallel Milestones in GSD Pi Source: https://docs.opengsd.net/pi/guides/worktrees Use Git worktree isolation to run milestones in dedicated checkouts, keep parallel work conflict-free, and merge cleanly back to main. GSD Pi can isolate each milestone's work in its own Git worktree — a separate directory with its own branch, fully decoupled from your main checkout. This prevents in-progress work from bleeding into your dev environment and makes parallel milestone execution possible. Choose the isolation mode that best fits your project structure. ## Isolation Modes GSD supports three isolation modes, set via `git.isolation` in your `PREFERENCES.md`: **Default.** Work happens directly on your current branch. No worktree or milestone branch is created. Best for hot-reload workflows or small projects where branch overhead isn't worth it. Each milestone gets its own directory at `.gsd-worktrees//` (a sibling of `.gsd/` at your project root) on a `milestone/` branch. Work is fully isolated. Squash-merged to main on completion. Work stays in the project root but on a `milestone/` branch. No separate directory. Useful for submodule-heavy repos where worktrees cause symlink problems. Set your preferred mode in `PREFERENCES.md`: ```yaml theme={null} git: isolation: worktree # "none" (default), "worktree", or "branch" ``` Worktree mode requires at least one commit in the repository. In a zero-commit repo, GSD temporarily falls back to `none` mode until the first commit exists, then automatically resolves to `worktree`. ### Worktree Location Newly created worktrees live at `/.gsd-worktrees//` — a sibling of the `.gsd/` state directory, kept at the project root regardless of where `.gsd` state is stored. This keeps every worktree visible next to your project and out of any external state location. **Legacy location still works.** Worktrees created under the older `.gsd/worktrees//` layout remain fully recognized for resolution, listing, merge, and teardown — no migration step is required. Only newly created worktrees use the canonical `.gsd-worktrees/` location, so in-flight milestones survive the upgrade unchanged. If you keep `.gsd/` ignored in your repo, add the canonical location to `.gitignore` as well (GSD does this automatically when `git.manage_gitignore: true`): ```gitignore theme={null} .gsd/ .gsd-worktrees/ ``` ## Worktree CLI Commands Use these commands from your shell (outside a GSD session) to inspect and manage worktrees: ```bash theme={null} gsd worktree list # List all GSD-managed worktrees gsd worktree merge [name] # Merge a worktree back to main gsd worktree clean # Remove only merged or empty worktrees gsd worktree remove # Remove a specific worktree gsd worktree remove --force # Force-remove even with unmerged changes ``` ## In-Session Worktree Commands From inside an active GSD TUI session, use the `/gsd worktree` family of commands (alias: `/gsd wt`): | Command | Description | | ------------------------------------- | ----------------------------------------------------------------------- | | `/gsd worktree list` | Show each worktree's branch, path, diff stats, commit count, and status | | `/gsd worktree merge [name]` | Merge a worktree into main and remove it afterward | | `/gsd worktree clean` | Remove merged or empty worktrees; keep anything with pending changes | | `/gsd worktree remove ` | Remove a named worktree and its branch | | `/gsd worktree remove --force` | Force-remove, discarding unmerged or uncommitted work | `remove --force` permanently discards any unmerged commits and uncommitted changes in the worktree. Always review with `worktree list` before forcing removal. ## Starting a Session in a Specific Worktree Use the `--worktree` flag (short: `-w`) when launching GSD to open a session directly inside a named worktree: ```bash theme={null} gsd --worktree my-feature # Start in the "my-feature" worktree gsd -w # Start in a new auto-named worktree ``` If you omit the name, GSD generates one automatically. ## Merge Behavior When a worktree milestone completes, GSD handles the merge automatically: All task commits land on `milestone/` with conventional commit messages and `GSD-Task` trailers. By default, all commits are squashed into one clean commit on your main branch. Change this with `git.merge_strategy: merge` to preserve individual commits. The worktree directory and milestone branch are removed automatically after a successful merge. ## Milestone Completion in Interactive Sessions When you complete a milestone interactively — by running `gsd_complete_milestone` from inside a chat or TUI session — GSD now closes out the milestone's Git state for you instead of leaving the working tree untouched. On every interactive milestone completion, GSD: 1. **Auto-commits the dirty working tree** on the current branch with a conventional commit message and a `GSD-Unit: ` trailer, so the commit is recognizable as milestone closeout evidence. A clean tree is left alone. 2. **Computes a Closeout Git Verdict** when `git.isolation` is `worktree` or `branch`, and surfaces one of two notices when the situation needs your attention: The milestone was completed outside a `milestone/` worktree or branch even though `git.isolation` is `worktree` or `branch`. GSD commits the work where it sits and emits a warning naming the isolation preference that was not honored this session, so the milestone never closes silently on the wrong branch. The milestone was completed on its `milestone/` branch as expected. GSD commits the work and emits an info notice pointing you at `/gsd worktree merge` to land the branch on your integration branch. Interactive closeout only fires on milestone boundaries. `gsd_task_complete` and `gsd_slice_complete` deliberately do **not** auto-commit — committing at every task or slice would sweep up unrelated working-tree changes. Auto-mode is also untouched: it keeps its existing closeout pipeline. A milestone closeout commit looks like this: ```text theme={null} chore: complete-milestone M003 GSD-Unit: M003 ``` ## Parallel Milestones When you have independent milestones, you can run them simultaneously in separate worktrees. GSD's parallel orchestration engine manages worker processes, coordinates shared project state, and merges back to main when each milestone finishes. Use the `/gsd parallel` commands to manage parallel execution: | Command | Description | | ---------------------------- | ---------------------------------------------------------- | | `/gsd parallel start` | Analyze eligibility and spawn workers for ready milestones | | `/gsd parallel status` | Show all workers with their state, progress, and cost | | `/gsd parallel stop [MID]` | Stop all workers, or a specific milestone's worker | | `/gsd parallel pause [MID]` | Pause all workers, or a specific one | | `/gsd parallel resume [MID]` | Resume paused workers | | `/gsd parallel merge [MID]` | Merge completed milestones back to main | Enable parallel mode in your preferences before using these commands: ```yaml theme={null} parallel: enabled: true max_workers: 2 # 1–4 concurrent workers budget_ceiling: 50.00 # Aggregate cost limit in USD (optional) merge_strategy: "per-milestone" auto_merge: "confirm" # "auto", "confirm", or "manual" ``` Run `/gsd parallel start` and GSD will show you an eligibility report before spawning any workers — including dependency checks and file overlap warnings for milestones that touch the same files. ## Safety Behavior `worktree merge` auto-commits dirty files in the worktree before merging when possible, so you don't lose uncommitted work. Merge stops and reports which files conflict rather than silently failing. Resolve manually, then retry with `/gsd parallel merge `. `worktree clean` never removes worktrees with pending diffs or uncommitted changes — only merged or empty ones. Merge and worktree flows refuse to proceed from a detached project root. Check out your integration branch first. ## Worktree Post-Create Hooks Run a custom script automatically after GSD creates a new worktree — useful for copying `.env` files, symlinking asset directories, or running setup commands the worktree doesn't inherit from the main tree: ```yaml theme={null} git: worktree_post_create: .gsd/hooks/post-worktree-create ``` The hook receives two environment variables: `SOURCE_DIR` (the original project root) and `WORKTREE_DIR` (the newly created worktree path). ```bash theme={null} #!/bin/bash cp "$SOURCE_DIR/.env" "$WORKTREE_DIR/.env" ln -sf "$SOURCE_DIR/assets" "$WORKTREE_DIR/assets" ``` # GSD Pi Setup: Install on macOS, Linux, and Windows Source: https://docs.opengsd.net/pi/installation Install GSD Pi globally with the guided installer or npm. Requires Node.js 22 or later. Platform binaries download automatically on first run. GSD Pi is published as `@opengsd/gsd-pi` on npm and installs as a global `gsd` binary. The recommended path is the interactive guided installer, which walks you through provider setup, configures your first LLM, and verifies the installation — all in one step. ## Prerequisites Before you install, make sure you have the following: | Requirement | Minimum | Recommended | | ------------------------ | ---------------------- | ----------------------------------- | | Node.js | 22.0.0 | 24 LTS | | npm | Bundled with Node.js | Latest LTS bundled version | | Git | 2.20 | Latest stable | | LLM provider credentials | One supported provider | The provider your team already uses | Verify your environment: ```bash theme={null} node --version npm --version git --version ``` ## Install Run the guided installer with `npx`. It installs the package globally, walks you through provider configuration, and confirms the `gsd` command is on your `PATH`: ```bash theme={null} npx @opengsd/gsd-pi@latest ``` For CI or non-interactive environments, pass `--yes` to accept all defaults: ```bash theme={null} npx @opengsd/gsd-pi@latest --yes ``` The guided installer handles the full setup flow — you only need to supply your API key for your chosen LLM provider. If you prefer a direct global install without the guided setup flow, install the package with npm: ```bash theme={null} npm install -g @opengsd/gsd-pi ``` After the install completes, run `gsd config` to configure your LLM provider before starting your first session. If you manage global packages with pnpm, run the setup step first to ensure the global bin directory is on your `PATH`, then use pnpm's package runner: ```bash theme={null} pnpm setup exec $SHELL -l pnpm dlx @opengsd/gsd-pi@latest ``` If pnpm reports that its global bin directory is not on `PATH`, run `pnpm setup`, restart your shell, and retry. ## Verify the Installation Once the install finishes, confirm the `gsd` command is available: ```bash theme={null} gsd --version ``` ```bash theme={null} gsd --help ``` If `gsd` is not found, your npm global bin directory may not be on `PATH`. Find the correct path with: ```bash theme={null} npm prefix -g ``` Add the `bin` subdirectory of that path to your shell profile, then open a new terminal. ## Configure Your Provider If you used the guided installer, your provider is already configured. If you installed directly with npm, run the setup wizard now: ```bash theme={null} gsd config ``` The wizard walks you through: * Choosing an LLM provider (Anthropic, OpenAI, Gemini, OpenRouter, and more) * Entering your API key or signing in via OAuth (GitHub Copilot) * Selecting default model preferences * Optionally configuring tool API keys for web search and documentation lookup You can re-run `gsd config` at any time from your shell to update credentials or add a new provider. ## Platform Binaries Pi ships with native platform binaries for performance-critical operations. They download automatically the first time you run `gsd` — no manual steps required. Supported platforms: arm64 (Apple Silicon) and x64 (Intel) arm64 and x64 x64 Official image available — see the `Dockerfile` in the repository ## Upgrade After the first install, upgrade to the latest version from your shell: ```bash theme={null} gsd upgrade ``` You can also run the upgrade from inside a GSD session with `/gsd update`. ## Migrate From an Older Install If you previously installed the unscoped `gsd-pi` package, remove it before installing the new scoped package to avoid a shadowed binary: ```bash macOS / Linux theme={null} npm uninstall -g gsd-pi @opengsd/gsd-pi rm -f ~/.gsd/.update-check ~/.gsd/agent/managed-resources.json npx @opengsd/gsd-pi@latest ``` ```powershell Windows PowerShell theme={null} npm uninstall -g gsd-pi @opengsd/gsd-pi Remove-Item "$env:USERPROFILE\.gsd\.update-check" -Force -ErrorAction SilentlyContinue Remove-Item "$env:USERPROFILE\.gsd\agent\managed-resources.json" -Force -ErrorAction SilentlyContinue npx @opengsd/gsd-pi@latest ``` ## Uninstall To remove GSD Pi and all local state: ```bash macOS / Linux theme={null} npm uninstall -g @opengsd/gsd-pi rm -rf ~/.gsd ``` ```powershell Windows PowerShell theme={null} npm uninstall -g @opengsd/gsd-pi Remove-Item "$env:USERPROFILE\.gsd" -Recurse -Force -ErrorAction SilentlyContinue ``` Removing `~/.gsd` deletes your global preferences, saved API keys, and all per-project state stored outside your repositories. Back up anything you want to keep before uninstalling. # GSD Pi: Autonomous Local-First Coding Agent for CLI Source: https://docs.opengsd.net/pi/introduction GSD Pi is a command-line coding agent that plans, implements, verifies, and ships software autonomously — from idea to pull request. GSD Pi is a local-first, autonomous coding agent you run from the command line. It handles the full software development lifecycle — breaking your goals into milestones, slices, and tasks, then planning, implementing, verifying, committing, and reporting on the work — all from your terminal. You stay in control: run it fully autonomously and check back when it's done, or stay hands-on and step through each unit of work interactively. ## What GSD Pi Does Pi takes a project goal and decomposes it into a structured hierarchy of work: * **Milestones** — shippable increments that each move your project meaningfully forward * **Slices** — coherent units of work within a milestone, planned and executed together * **Tasks** — atomic implementation units that a single agent session completes and commits Once the work is decomposed, Pi runs the loop: plan → implement → verify → commit → reassess → advance — repeating until the milestone is done or you intervene. Let Pi run unattended through planning, coding, testing, and committing with `/gsd auto`. Step through work unit by unit, inspect state, steer the plan, and resume at any time. Pi isolates milestone work in git worktrees, commits with meaningful messages, and creates PRs when you're ready to ship. All state, decisions, plans, and knowledge live in `.gsd/` — human-readable markdown backed by a local SQLite database. ## Interfaces Pi ships with three ways to interact, depending on your workflow: The terminal UI is the default interface. Run `gsd` to open it — you get a full interactive session with a live dashboard, slash commands, keyboard shortcuts, and real-time progress tracking. ```bash theme={null} gsd ``` Launch the browser-based control plane with `gsd --web`. It offers the same project management surface as the TUI with a visual workflow dashboard. ```bash theme={null} gsd --web ``` Run Pi without any UI in CI pipelines, cron jobs, or scripts using `gsd headless`. It streams structured JSONL events, auto-responds to prompts, and exits with meaningful codes. ```bash theme={null} gsd headless auto ``` ## Key Capabilities Pi works with the LLM provider your team already uses. Supported providers include: **Cloud APIs:** Anthropic (Claude), OpenAI, Google Gemini, OpenRouter, Groq, xAI (Grok), Mistral, GitHub Copilot, Amazon Bedrock, Vertex AI, Azure OpenAI **Local / Self-Hosted:** Ollama, LM Studio, vLLM, SGLang You configure models per phase — a powerful model for planning and a faster model for simpler tasks — and Pi handles routing automatically. Dynamic routing can further optimize cost by selecting cheaper models for lightweight work. Pi runs each milestone in its own git worktree, keeping implementation work isolated from your main checkout. When the milestone completes, Pi squash-merges the work as one clean commit and removes the worktree. Your main branch stays reviewable throughout. Pi's capabilities expand through extensions. Bundled extensions add browser automation, background shell processes, MCP protocol support, web search, voice transcription, visual context capture, GitHub sync, and more. You can install community extensions from npm or build your own. Pi accumulates project knowledge across sessions — architectural decisions, patterns, lessons learned, and codebase understanding — stored in a local SQLite database and projected into human-readable markdown for review and git history. Set a spending ceiling and choose how Pi enforces it: warn and continue, pause for review, or halt immediately. Dynamic model routing can reduce token consumption by 20–50% by using lighter models for simpler work. ## How It Fits Into Your Workflow Pi is designed to work alongside your existing tools, not replace them. It reads and writes your codebase directly, uses git for all version control, runs your existing test and lint commands for verification, and produces PR-ready branches. You review the output in your normal code review workflow — Pi just does the implementation work. Pi stores all project state under `.gsd/` in your project root. This directory contains a SQLite database as the runtime source of truth, plus markdown projections of plans, decisions, summaries, and knowledge for human review. # GSD Pi Quickstart: First Autonomous Coding Session Source: https://docs.opengsd.net/pi/quickstart Start your first GSD Pi session, create a project, run autonomous mode, and ship a pull request — step by step in under ten minutes. This guide walks you through your first complete GSD Pi workflow: launching the TUI, describing a project, letting Pi plan and implement it autonomously, and creating a pull request when the work is done. By the end, you'll have run a full autonomous coding session and seen Pi's milestone → slice → task execution loop in action. ## Before You Begin Make sure GSD Pi is installed and your LLM provider is configured. If you haven't done that yet, follow the [Installation guide](/pi/installation) first. ```bash theme={null} gsd --version # confirm the CLI is available ``` ## Full Autonomous Workflow Navigate to your project directory and launch GSD Pi: ```bash theme={null} cd path/to/your-project gsd ``` The terminal UI opens with a welcome screen. On the first run for a project, Pi creates the `.gsd/` directory to store plans, state, and knowledge. If you haven't set up an LLM provider yet, or want to change your current provider, run the configuration wizard from inside the session: ```text theme={null} /gsd config ``` The wizard lets you enter an API key, sign in via OAuth (GitHub Copilot), or point Pi at a local model (Ollama, LM Studio). You can re-run this any time to add a new provider or rotate credentials. Already configured during install? Skip this step — Pi picks up your saved credentials automatically. Tell Pi what you're building with the new-project command: ```text theme={null} /gsd new-project ``` Pi will ask you to describe the project in plain language. Be as specific or as high-level as you like — Pi will ask follow-up questions to clarify scope, constraints, and success criteria before writing any plans. For a deeper up-front discovery flow that produces structured requirements and research artifacts before planning begins, add the `--deep` flag: ```text theme={null} /gsd new-project --deep ``` Once you approve the project scope, Pi writes the first milestone roadmap to `.gsd/`. With a project and milestone defined, start autonomous execution: ```text theme={null} /gsd auto ``` Pi enters its execution loop: it plans each slice, implements every task in a fresh context window, verifies the work against your project's test and lint commands, commits with meaningful messages, and advances to the next unit automatically. Watch the dashboard for real-time progress — it shows the current milestone, active slice and task, elapsed time, and running cost. Press **Escape** at any time to pause auto mode. The conversation is preserved and you can inspect state, ask questions, or steer the plan. Run `/gsd auto` again to resume. While auto mode runs, Pi cycles through these phases for each slice: 1. **Plan** — scouts the codebase, researches relevant docs, decomposes the slice into tasks 2. **Execute** — implements each task in a fresh context window with full project context pre-loaded 3. **Complete** — writes summaries, generates a UAT script, commits all changes 4. **Reassess** — checks whether the roadmap still makes sense given what was learned 5. **Advance** — moves to the next slice or validates the milestone if all slices are done You can check progress at any time without interrupting auto mode: ```text theme={null} /gsd status ``` When Pi finishes the milestone, create a pull request from the completed work: ```text theme={null} /gsd ship ``` Pi assembles the milestone artifacts, creates a PR branch, and opens the pull request for review. You get a clean, reviewable diff with a structured description generated from the milestone summaries and task history. `/gsd ship` requires the `gh` CLI to be installed and authenticated. If you prefer to create the PR manually, use `/gsd pr-branch` to prepare a clean branch without `.gsd/` commits. ## Quick Single-Task Mode For a small change that doesn't need full milestone planning, use Pi's single-shot print mode: ```bash theme={null} gsd --print "implement a hello world API endpoint in Express" ``` This runs a single focused coding session and exits — no TUI, no planning overhead, just a targeted implementation. Useful for quick fixes, one-off scripts, or exploring how Pi handles a specific task. You can also run a quick task from inside a session: ```text theme={null} /gsd quick "add input validation to the signup form" ``` ## Useful Commands During a Session Once you're inside a GSD session, these commands help you navigate and control the workflow: | Command | What it does | | --------------------- | ---------------------------------------------------------------- | | `/gsd auto` | Start or resume autonomous mode | | `/gsd next` | Execute one unit of work and pause | | `/gsd stop` | Gracefully stop auto mode | | `/gsd status` | Open the workflow visualizer | | `/gsd capture "idea"` | Record a thought for later triage without interrupting auto mode | | `/gsd ship` | Create a pull request from the current milestone | | `/gsd help` | Browse all available commands | ## What to Expect Pi reads your codebase and builds an initial understanding before planning. This one-time scan produces `.gsd/CODEBASE.md` and primes the project memory. All plans live as markdown files in `.gsd/`. You can read, edit, and steer them at any point — Pi picks up changes at the next phase boundary. Press Escape to pause, interact with Pi, then resume. Nothing is lost — state is persisted in the local SQLite database. Configure `verification_commands` in `.gsd/PREFERENCES.md` and Pi runs your lint and test suite after every task, retrying automatically on failure.