### Bash Installation Example

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/templates/research.md

Provides example commands for installing packages using npm or yarn.

```bash
npm install [packages]
# or
yarn add [packages]
```

--------------------------------

### CLI Installation Handling - Auto-install Example

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/references/checkpoints.md

Example of an auto-installable CLI command for GitHub. This demonstrates the protocol of trying a command, failing, and then attempting an automatic installation.

```bash
# Example for gh (GitHub CLI)
# Try command → "command not found" → auto-installable? → yes: install silently, retry
```

--------------------------------

### Stripe User Setup Example

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/templates/user-setup.md

A specific USER-SETUP.md example for Stripe integration, detailing environment variables, account setup, and dashboard configuration for webhooks and products.

```markdown
# Phase 10: User Setup Required

**Generated:** 2025-01-14
**Phase:** 10-monetization
**Status:** Incomplete

Complete these items for Stripe integration to function.

## Environment Variables

| Status | Variable | Source | Add to |
|--------|----------|--------|--------|
| [ ] | `STRIPE_SECRET_KEY` | Stripe Dashboard → Developers → API keys → Secret key | `.env.local` |
| [ ] | `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Stripe Dashboard → Developers → API keys → Publishable key | `.env.local` |
| [ ] | `STRIPE_WEBHOOK_SECRET` | Stripe Dashboard → Developers → Webhooks → [endpoint] → Signing secret | `.env.local` |

## Account Setup

- [ ] **Create Stripe account** (if needed)
  - URL: https://dashboard.stripe.com/register
  - Skip if: Already have Stripe account

## Dashboard Configuration

- [ ] **Create webhook endpoint**
  - Location: Stripe Dashboard → Developers → Webhooks → Add endpoint
  - Endpoint URL: `https://[your-domain]/api/webhooks/stripe`
  - Events to send:
    - `checkout.session.completed`
    - `customer.subscription.created`
    - `customer.subscription.updated`
    - `customer.subscription.deleted`

- [ ] **Create products and prices** (if using subscription tiers)
  - Location: Stripe Dashboard → Products → Add product
  - Create each subscription tier
  - Copy Price IDs to:
    - `STRIPE_STARTER_PRICE_ID`
    - `STRIPE_PRO_PRICE_ID`


```

--------------------------------

### User Setup Frontmatter Schema Example

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/templates/user-setup.md

Example of the `user_setup` field in PLAN.md frontmatter, detailing service-specific configuration requirements.

```yaml
user_setup:
  - service: stripe
    why: "Payment processing requires API keys"
    env_vars:
      - name: STRIPE_SECRET_KEY
        source: "Stripe Dashboard → Developers → API keys → Secret key"
      - name: STRIPE_WEBHOOK_SECRET
        source: "Stripe Dashboard → Developers → Webhooks → Signing secret"
    dashboard_config:
      - task: "Create webhook endpoint"
        location: "Stripe Dashboard → Developers → Webhooks → Add endpoint"
        details: "URL: https://[your-domain]/api/webhooks/stripe, Events: checkout.session.completed, customer.subscription.*"
    local_dev:
      - "Run: stripe listen --forward-to localhost:3000/api/webhooks/stripe"
      - "Use the webhook secret from CLI output for local testing"

```

--------------------------------

### Good: Claude Starts Server, User Visits

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/references/checkpoints.md

This example illustrates the 'good' pattern where the system (Claude) starts the development server, and the user is only required to visit a URL and verify the UI. This is preferred over asking the user to execute commands.

```xml
<task type="auto">
  <name>Start dev server</name>
  <action>Run `npm run dev` in background</action>
  <verify>fetch http://localhost:3000 returns 200</verify>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <what-built>Dashboard at http://localhost:3000/dashboard (server running)</what-built>
  <how-to-verify>
    Visit http://localhost:3000/dashboard and verify:
    1. Layout matches design
    2. No console errors
  </how-to-verify>
</task>
```

--------------------------------

### Bash Installation Commands

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/templates/research-project/STACK.md

Provides example bash commands for installing core, supporting, and development dependencies using npm.

```bash
# Core
npm install [packages]

# Supporting
npm install [packages]

# Dev dependencies
npm install -D [packages]

```

--------------------------------

### Initialize New Project

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/workflows/help/modes/full.md

Use this command to start a new project. It guides you through defining the project's vision, requirements, and roadmap.

```bash
/gsd:new-project
```

--------------------------------

### CLI Installation Handling - Manual Install Prompt

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/references/checkpoints.md

Example of a CLI that is not auto-installable and requires user intervention. The protocol dictates prompting the user to install it manually.

```bash
# Example for npm/pnpm/yarn
# Protocol: Try command → "command not found" → auto-installable? → no: checkpoint asking user to install.
```

--------------------------------

### User Setup Configuration Example

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/templates/phase-prompt.md

This YAML snippet defines the 'user_setup' frontmatter for external services, detailing necessary human configurations like API keys and dashboard settings.

```yaml
user_setup:
  - service: stripe
    why: "Payment processing requires API keys"
    env_vars:
      - name: STRIPE_SECRET_KEY
        source: "Stripe Dashboard → Developers → API keys → Secret key"
      - name: STRIPE_WEBHOOK_SECRET
        source: "Stripe Dashboard → Developers → Webhooks → Signing secret"
    dashboard_config:
      - task: "Create webhook endpoint"
        location: "Stripe Dashboard → Developers → Webhooks → Add endpoint"
        details: "URL: https://[your-domain]/api/webhooks/stripe"
    local_dev:
      - "stripe listen --forward-to localhost:3000/api/webhooks/stripe"
```

--------------------------------

### Initialize New GSD Project

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/workflows/help/modes/default.md

Use this command to start a new project from scratch. It guides you through the initial stages of questioning, research, requirements gathering, and roadmap creation.

```text
/gsd:new-project        # Greenfield: questioning → research → requirements → roadmap
```

--------------------------------

### Generate User Setup File

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/workflows/execute-plan.md

Searches for user setup instructions within a plan file and creates a user setup file if found. Sets a flag indicating the user setup file has been created.

```bash
grep -A 50 "^user_setup:" .planning/phases/XX-name/{phase}-{plan}-PLAN.md | head -50
```

--------------------------------

### Setup GSD Tools and Initialize Workspace Listing

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/workflows/list-workspaces.md

This script sets up the necessary GSD tools and initializes the query for listing workspaces. It handles finding the gsd-tools executable and then runs a query to get initial workspace data.

```bash
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
INIT=$(gsd_run query init.list-workspaces)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```

--------------------------------

### UI Component Verification Example

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/references/checkpoints.md

This example demonstrates a typical workflow for verifying a UI component. It includes an automated task to build the component, another to start a development server, and finally, the human-verify checkpoint to test responsiveness and layout across different devices.

```xml
<task type="auto">
  <name>Build responsive dashboard layout</name>
  <files>src/components/Dashboard.tsx, src/app/dashboard/page.tsx</files>
  <action>Create dashboard with sidebar, header, and content area. Use Tailwind responsive classes for mobile.</action>
  <verify>npm run build succeeds, no TypeScript errors</verify>
  <done>Dashboard component builds without errors</done>
</task>

<task type="auto">
  <name>Start dev server for verification</name>
  <action>Run `npm run dev` in background, wait for "ready" message, capture port</action>
  <verify>fetch http://localhost:3000 returns 200</verify>
  <done>Dev server running at http://localhost:3000</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <what-built>Responsive dashboard layout - dev server running at http://localhost:3000</what-built>
  <how-to-verify>
    Visit http://localhost:3000/dashboard and verify:
    1. Desktop (>1024px): Sidebar left, content right, header top
    2. Tablet (768px): Sidebar collapses to hamburger menu
    3. Mobile (375px): Single column layout, bottom nav appears
    4. No layout shift or horizontal scroll at any size
  </how-to-verify>
  <resume-signal>Type "approved" or describe layout issues</resume-signal>
</task>
```

--------------------------------

### Install Testing Frameworks

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/references/tdd.md

Installs necessary testing frameworks for various languages. Use `npm install -D` for Node.js projects, `pip install` for Python, and built-in tools for Go and Rust.

```bash
npm install -D jest @types/jest ts-jest
```

```bash
npm install -D vitest
```

```bash
pip install pytest
```

--------------------------------

### One-time setup for gsd-core

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/contributing/bootstrap.md

Clones the gsd-core repository, activates the pinned Node version using nvm, and installs dependencies with npm ci.

```bash
# 1. Clone
git clone https://github.com/open-gsd/gsd-core.git
cd gsd-core

# 2. Activate the pinned Node version
nvm use          # nvm
# fnm use        # fnm
# asdf install   # asdf / mise

# 3. Verify the environment (see Validation below)
npm run check:env

# 4. Install dependencies (reproducible, lockfile-driven)
npm ci
```

--------------------------------

### Configuration Example

Source: https://github.com/open-gsd/gsd-core/blob/next/agents/gsd-code-reviewer.md

Example of a configuration block specifying review depth and files to be reviewed.

```yaml
files:
  - path/to/file1.ext
  - path/to/file2.ext
```

--------------------------------

### Release Notes Examples

Source: https://github.com/open-gsd/gsd-core/blob/next/CONTEXT.md

Illustrative examples of different release types and their characteristics.

```shell
RELEASE-NOTES.EXAMPLE.hotfix=v1.41.1 (https://github.com/open-gsd/gsd-core/releases/tag/v1.41.1) - 14 fixes grouped by 6 subgroups
RELEASE-NOTES.EXAMPLE.rc=v1.42.0-rc1 (https://github.com/open-gsd/gsd-core/releases/tag/v1.42.0-rc1) - intro + Added/Changed/Fixed/Documentation taxonomy
RELEASE-NOTES.EXAMPLE.minor-auto-acceptable=v1.41.0 - kept auto-generated body; many small fixes with clean conventional-commit titles
```

--------------------------------

### Install Runtime

Source: https://github.com/open-gsd/gsd-core/blob/next/CONTEXT.md

Installs a specified runtime. It can be a global installation or a local one, with optional configuration directory.

```javascript
install(isGlobal, runtime[, configDir])
```

--------------------------------

### Framework Entry Point Example

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/templates/AI-SPEC.md

A minimal working Python example demonstrating the entry point pattern for the AI system type using the selected framework.

```python
# Minimal working example for this system type
```

--------------------------------

### Install Get Shit Done Redux (Global, RC Channel)

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/RELEASE-v1.42.0-rc.1.md

Installs the Get Shit Done Redux CLI globally using npm, targeting the RC channel for the latest pre-release versions.

```bash
# npm (global, RC channel)
npm install -g @opengsd/get-shit-done-redux@next
```

--------------------------------

### Install Get Shit Done Redux CLI (Next)

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/RELEASE-v1.42.0-rc.1.md

Install the latest release candidate of the Get Shit Done Redux CLI using npm or npx. This command fetches the package from the 'next' distribution tag.

```bash
npx @opengsd/get-shit-done-redux@next
```

```bash
npm install -g @opengsd/get-shit-done-redux@1.42.0-rc1
```

--------------------------------

### Install Latest Pre-release

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/RELEASE-v1.40.0-rc.1.md

Install the latest pre-release version of the Get Shit Done Redux package globally using npm.

```bash
# npm
npm install -g @opengsd/get-shit-done-redux@next
```

--------------------------------

### Initialize New Project

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/workflows/map-codebase.md

Use this command to start a new project and initialize the codebase mapping process. Ensure the environment is clear before running.

```bash
/clear
/gsd:new-project
```

--------------------------------

### Install Specific RC Version

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/RELEASE-v1.42.0-rc.1.md

Installs a specific release candidate version of Get Shit Done Redux globally using npm, pinning to version 1.42.0-rc1.

```bash
# Pin to this exact RC
npm install -g @opengsd/get-shit-done-redux@1.42.0-rc1
```

--------------------------------

### CLI Commands for Phase 1

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/tutorials/your-first-project.md

Example commands to interact with the CLI tool built during Phase 1, demonstrating adding items, listing them, and marking them as done.

```bash
node todo.js add "buy milk"
node todo.js add "write tests"
node todo.js list
node todo.js done 1
node todo.js list
```

--------------------------------

### Check gh CLI Availability and Authentication

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/workflows/inbox.md

Verifies if the GitHub CLI is installed and authenticated. If not, it prints setup instructions.

```bash
which gh && gh auth status 2>&1
```

--------------------------------

### Rollback to Latest Stable Version

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/RELEASE-v1.42.0-rc.1.md

Reverts the Get Shit Done Redux installation to the latest stable release using npx.

```bash
npx @opengsd/get-shit-done-redux@latest
```

--------------------------------

### Agent Configuration for GETTING-STARTED.md

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/workflows/docs-update.md

Configuration for spawning a GSD doc writer agent to generate or update the GETTING-STARTED.md file. Includes project context and Wave 1 outputs.

```python
Agent(
  subagent_type="gsd-doc-writer",
  model="{doc_writer_model}",
  run_in_background=true,
  description="Generate GETTING-STARTED.md for target project",
  prompt="<doc_assignment>
type: getting_started
mode: {create|update|supplement}
preservation_mode: {preserve|supplement|regenerate|null}
project_context: {INIT JSON}
{existing_content: | (include full file content here if mode is update or supplement, else omit this line)}
wave_1_outputs:
  - README.md
  - docs/ARCHITECTURE.md
  - docs/CONFIGURATION.md
</doc_assignment>

{AGENT_SKILLS}

Write the doc file directly. Return confirmation only — do not return doc content."
)
```

--------------------------------

### Install Dependencies and Build SDK

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/contributing/bootstrap.md

Run this command to fix 'Cannot find module' errors by ensuring dependencies are correctly installed from the lockfile and then building the SDK.

```bash
npm ci           # clean install from lockfile
npm run build:sdk
```

--------------------------------

### Initiate Human Verification

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/workflows/execute-phase.md

Command to start the human verification process for a given phase. This command will guide the user through manual testing.

```bash
/gsd:verify-work {X} ${GSD_WS}
```

--------------------------------

### Runtime Configuration Directory Setup

Source: https://github.com/open-gsd/gsd-core/blob/next/commands/gsd/surface.md

Demonstrates how the runtime configuration directory is determined and used for applying surface configurations. It highlights the use of environment variables for overriding default paths.

```bash
# Claude Code — global install
RUNTIME_CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
SCOPE="global"

# Artifact destinations are derived from runtime layout
# via resolveRuntimeArtifactLayout(runtime, RUNTIME_CONFIG_DIR, SCOPE)
# then applySurface(RUNTIME_CONFIG_DIR, layout, manifest, CLUSTERS)
```

--------------------------------

### Next Up Block Example

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/references/ui-brand.md

Used at the end of major completions to guide the user on the next steps, including a primary command and alternatives.

```text
───────────────────────────────────────────────────────────────

## ▶ Next Up

**{Identifier}: {Name}** — {one-line description}

`/clear` then:

`{copy-paste command}`

───────────────────────────────────────────────────────────────

**Also available:**
- `/gsd-alternative-1` — description
- `/gsd-alternative-2` — description

───────────────────────────────────────────────────────────────
```

--------------------------------

### Example User Prompt Options

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/workflows/docs-update.md

Illustrates the user-selectable options for proceeding with or aborting the documentation generation process.

```javascript
[
    { label: "Proceed", description: "Generate all {N} docs in the queue" },
    { label: "Abort", description: "Cancel doc generation" }
  ]
```

--------------------------------

### Vehicle Physics with Rapier RigidBody

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/templates/research.md

Use RigidBody with vehicle-specific settings for ground vehicles. This example demonstrates basic setup with mass and damping.

```typescript
// Source: @react-three/rapier docs
import { RigidBody, useRapier } from '@react-three/rapier'

function Vehicle() {
  const rigidBody = useRef()

  return (
    <RigidBody
      ref={rigidBody}
      type="dynamic"
      colliders="hull"
      mass={1500}
      linearDamping={0.5}
      angularDamping={0.5}
    >
      <mesh>
        <boxGeometry args={[2, 1, 4]} />
        <meshStandardMaterial />
      </mesh>
    </RigidBody>
  )
}
```

--------------------------------

### Install Gemini CLI

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/how-to/set-up-cross-ai-review.md

Install the Gemini CLI using npm. This reviewer is free with Google credentials.

```bash
npm install -g @google/gemini-cli
```

--------------------------------

### Start a New GSD Core Project

Source: https://github.com/open-gsd/gsd-core/blob/next/README.md

Initiates a new project using the GSD Core CLI. This command is used after the GSD Core has been installed.

```bash
/gsd-new-project
```

--------------------------------

### Pin to Specific Pre-release Version

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/RELEASE-v1.40.0-rc.1.md

Install a specific pre-release version (1.40.0-rc.1) of the Get Shit Done Redux package globally using npm.

```bash
npm install -g @opengsd/get-shit-done-redux@1.40.0-rc.1
```

--------------------------------

### Common Test Setup with Node.js Modules

Source: https://github.com/open-gsd/gsd-core/blob/next/TEST-EXAMPLES.md

Sets up the testing environment using built-in Node.js modules and shared helper functions. This is a prerequisite for most test examples.

```javascript
const { test, mock } = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const path = require('node:path');
const childProcess = require('node:child_process');
const { spawnSync } = childProcess;
const {
  createTempProject,
  createTempGitProject,
  cleanup,
} = require('./helpers.cjs');
```

--------------------------------

### Setup Arize Phoenix for Tracing

Source: https://github.com/open-gsd/gsd-core/blob/next/agents/gsd-eval-planner.md

Installs the Arize Phoenix SDK and OpenTelemetry components, then launches the Arize Phoenix application. This is used for tracing and observability when no other tracing tool is detected.

```python
# pip install arize-phoenix opentelemetry-sdk
import phoenix as px
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider

px.launch_app()  # http://localhost:6006
provider = TracerProvider()
trace.set_tracer_provider(provider)

```

--------------------------------

### User Setup Markdown Template

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/templates/user-setup.md

A general template for documenting human-required setup tasks. It includes sections for environment variables, account creation, and dashboard configuration.

```markdown
# Phase {X}: User Setup Required

**Generated:** [YYYY-MM-DD]
**Phase:** {phase-name}
**Status:** Incomplete

Complete these items for the integration to function. Claude automated everything possible; these items require human access to external dashboards/accounts.

## Environment Variables

| Status | Variable | Source | Add to |
|--------|----------|--------|--------|
| [ ] | `ENV_VAR_NAME` | [Service Dashboard → Path → To → Value] | `.env.local` |
| [ ] | `ANOTHER_VAR` | [Service Dashboard → Path → To → Value] | `.env.local` |

## Account Setup

[Only if new account creation is required]

- [ ] **Create [Service] account**
  - URL: [signup URL]
  - Skip if: Already have account

## Dashboard Configuration

[Only if dashboard configuration is required]

- [ ] **[Configuration task]**
  - Location: [Service Dashboard → Path → To → Setting]
  - Set to: [Required value or configuration]
  - Notes: [Any important details]

## Verification

After completing setup, verify with:

```bash
# [Verification commands]
```

Expected results:
- [What success looks like]

---

**Once all items complete:** Mark status as "Complete" at top of file.

```

--------------------------------

### Example VERIFICATION.md with Override

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/references/verification-overrides.md

A complete example of a VERIFICATION.md file including frontmatter with override details and a table showing an overridden item.

```markdown
---
phase: 03-api-layer
verified: 2026-04-05T12:00:00Z
status: passed
score: 3/3
overrides_applied: 1
overrides:
  - must_have: "paginated API responses"
    reason: "Descoped — dataset under 100 items, pagination adds complexity without value"
    accepted_by: "dave"
    accepted_at: "2026-04-04T15:30:00Z"
---

## Phase 3: API Layer — Verification

| # | Truth | Status | Evidence |
|---|-------|--------|----------|
| 1 | REST endpoints return JSON | VERIFIED | curl tests confirm |
| 2 | Paginated API responses | PASSED (override) | Descoped — see override: dataset under 100 items |
| 3 | Authentication middleware | VERIFIED | JWT validation working |
```

--------------------------------

### Logging Initial Session Setup Information

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/workflows/debug.md

Before creating a new debug session file, initial setup information including the session path and status is logged to the console.

```shell
[debug] Session: .planning/debug/{slug}.md
[debug] Status: investigating
[debug] Delegating loop to session manager...
```

--------------------------------

### UAT Session Frontmatter Example

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/templates/UAT.md

This frontmatter section for a UAT session file specifies the status, phase, source files, and timestamps for the testing session. It indicates that the session is diagnosed and provides start and update times.

```markdown
---
status: diagnosed
phase: 04-comments
source: 04-01-SUMMARY.md, 04-02-SUMMARY.md
started: 2025-01-15T10:30:00Z
updated: 2025-01-15T10:45:00Z
---
```

--------------------------------

### Initiate Phase Planning

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/workflows/discuss-phase.md

Command to start planning a specific phase of the project. Use with `/clear`.

```bash
/gsd:plan-phase ${PHASE} ${GSD_WS}
```

--------------------------------

### Create and Configure New Project (Auto Mode)

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/workflows/new-project.md

Creates the .planning directory and runs the gsd_run query to set up a new project configuration with specified auto mode settings. Ensure the .planning directory is added to .gitignore if commit_docs is false.

```bash
mkdir -p .planning
gsd_run query config-new-project '{"mode":"yolo","granularity":"[selected]","parallelization":true|false,"commit_docs":true|false,"model_profile":"quality|balanced|budget|inherit","workflow":{"research":true|false,"plan_check":true|false,"verifier":true|false,"nyquist_validation":true|false,"auto_advance":true},"plan_review":{"source_grounding":true|false},"ship":{"pr_body_sections":[{"heading":"User Stories & Acceptance Criteria","enabled":true|false,"source":"REQUIREMENTS.md ## User Stories || REQUIREMENTS.md ## Acceptance Criteria","fallback":"- Acceptance criteria are covered by the linked requirements and verification evidence."},{"heading":"Risks & Dependencies","enabled":true|false,"source":"PLAN.md ## Risks || PLAN.md ## Dependencies","fallback":"- No known high-risk rollout dependencies."},{"heading":"Success Metrics & Release Criteria","enabled":true|false,"source":"REQUIREMENTS.md ## Definition of Done || VERIFICATION.md ## Release Criteria","fallback":"- Release when automated verification and required manual checks pass."},{"heading":"Stakeholder Review & Approval","enabled":true|false,"template":"- Product owner approval pending for {phase_name}."}]}}'
```

--------------------------------

### Standard Test Structure Example

Source: https://github.com/open-gsd/gsd-core/blob/next/CONTRIBUTING.md

Illustrates a typical test structure using `describe` blocks, `beforeEach`/`afterEach` hooks, and nested `describe` blocks for organizing tests. This structure helps in managing test suites and their specific setups.

```javascript
describe('featureName', () => {
  let tmpDir;

  beforeEach(() => {
    tmpDir = createTempProject();
    // Additional setup specific to this suite
  });

  afterEach(() => {
    cleanup(tmpDir);
  });

  test('handles normal case', () => {
    // Arrange
    // Act
    // Assert
  });

  test('handles edge case', () => {
    // ...
  });

  describe('sub-feature', () => {
    // Nested describes can have their own hooks
    beforeEach(() => {
      // Additional setup for sub-feature
    });

    test('sub-feature works', () => {
      // ...
    });
  });
});
```

--------------------------------

### Install GSD Core CLI

Source: https://github.com/open-gsd/gsd-core/blob/next/README.md

Installs the GSD Core command-line interface using npm. The installer will prompt for your runtime and installation preference (global or local).

```bash
npx @opengsd/gsd-core@latest
```

--------------------------------

### Initialize .planning Directory

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/workflows/new-workspace.md

Creates the .planning directory at the root of the new workspace. This directory is used for planning-related files.

```bash
mkdir -p "$TARGET_PATH/.planning"
```

--------------------------------

### Example Implementation Discussion

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/tutorials/your-first-project.md

Illustrates an interactive exchange where GSD Core asks about storing done items, displaying completed items, and handling non-existent todo files.

```text
> How should done items be stored — mark them in place or move them?
  Mark them in place with a "done" flag.

> Should `todo list` show completed items by default?
  No, hide them unless --all is passed.

> Error format when todos.json doesn't exist yet?
  Create it silently on first add.
```

--------------------------------

### Parallel Execution Example (Wave 1)

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/templates/phase-prompt.md

Demonstrates three independent plans that can run in parallel within the same wave due to no dependencies and no file conflicts.

```yaml
# Plan 01 - User feature
wave: 1
depends_on: []
files_modified: [src/models/user.ts, src/api/users.ts]
autonomous: true

# Plan 02 - Product feature (no overlap with Plan 01)
wave: 1
depends_on: []
files_modified: [src/models/product.ts, src/api/products.ts]
autonomous: true

# Plan 03 - Order feature (no overlap)
wave: 1
depends_on: []
files_modified: [src/models/order.ts, src/api/orders.ts]
autonomous: true
```

--------------------------------

### Install slopcheck

Source: https://github.com/open-gsd/gsd-core/blob/next/agents/gsd-phase-researcher.md

Installs the slopcheck tool, attempting to avoid system package conflicts. This is a best-effort installation.

```bash
pip install slopcheck --break-system-packages 2>/dev/null || pip install slopcheck 2>/dev/null || true
```

--------------------------------

### Example Configured Project Sections

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/workflows/ship.md

Illustrates the structure of custom PR body sections that can be configured for a project. Includes examples for user stories, risks, and stakeholder review.

```json
[
  {
    "heading": "User Stories & Acceptance Criteria",
    "enabled": true,
    "source": "REQUIREMENTS.md ## User Stories || REQUIREMENTS.md ## Acceptance Criteria",
    "fallback": "- Acceptance criteria are covered by the linked requirements and verification evidence."
  },
  {
    "heading": "Risks & Dependencies",
    "enabled": true,
    "source": "PLAN.md ## Risks || PLAN.md ## Dependencies",
    "fallback": "- No known high-risk rollout dependencies."
  },
  {
    "heading": "Stakeholder Review & Approval",
    "enabled": false,
    "template": "- Product owner approval pending for {phase_name}."
  }
]
```

--------------------------------

### Install GSD Core for Cline (Global and Local)

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/how-to/install-on-your-runtime.md

Installs GSD Core for Cline. Global installs write to `~/.cline/`, and local installs write to `./.cline/`. Cline loads rules automatically.

```bash
# Global install (all projects)
npx @opengsd/gsd-core@latest --cline --global

# Local install (this project only)
npx @opengsd/gsd-core@latest --cline --local
```

--------------------------------

### Example Section with Template Token

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/ship-pr-body-sections.md

A sample section configuration demonstrating the use of a template token for dynamic content insertion.

```json
{
  "heading": "Stakeholder Review & Approval",
  "enabled": true,
  "template": "- Product owner approval pending for {phase_name}."
}
```

--------------------------------

### Install Antigravity Globally

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/how-to/install-on-your-runtime.md

Installs Antigravity globally using npx. The installer auto-detects the Antigravity config directory.

```bash
npx @opengsd/gsd-core@latest --antigravity --global
```

--------------------------------

### Create Planning Configuration Directory

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/workflows/new-project.md

Initializes the necessary directory structure for storing project planning configurations.

```bash
mkdir -p .planning

```

--------------------------------

### Install and Verify Slopcheck

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/USER-GUIDE.md

Installs the slopcheck package using pip and verifies its installation by checking the 'express' package.

```bash
pip install slopcheck
# verify: slopcheck install express --json
```

--------------------------------

### Plan a Phase Example

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/references/continuation-format.md

Continuation format for planning a new phase, including available actions for discussion or research.

```markdown
---

## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}

**Phase 2: Authentication** — JWT login flow with refresh tokens

`/clear` then:

`/gsd:plan-phase 2`

---

**Also available:**
- `/gsd:discuss-phase 2` — gather context first
- `/gsd:plan-phase --research-phase 2` — investigate unknowns
- Review roadmap

---
```

--------------------------------

### Apply Cleanup

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/cleanup-get-shit-done-cc.md

Execute the installer without --dry-run to remove leftover get-shit-done-cc artifacts, orphaned hooks, commands, and stale update caches across all runtime configurations.

```bash
npx -y --package=@opengsd/gsd-core@latest -- gsd-core --claude --global
```

--------------------------------

### Install State JSON Schema

Source: https://github.com/open-gsd/gsd-core/blob/next/docs/installer-migrations.md

This JSON structure represents the required fields for an install-state file used by the installer. It includes schema version, runtime, scope, installed version, install mode, and a list of applied migrations.

```json
{
  "schema": 1,
  "runtime": "codex",
  "scope": "global",
  "installed_version": "1.50.0",
  "install_mode": "full",
  "applied_migrations": [
    {
      "id": "2026-05-11-codex-hooks-layout",
      "package_version": "1.50.0",
      "checksum": "sha256:...",
      "applied_at": "2026-05-11T00:00:00.000Z"
    }
  ]
}
```

--------------------------------

### Install Framework Command

Source: https://github.com/open-gsd/gsd-core/blob/next/gsd-core/templates/AI-SPEC.md

Command to install the selected AI framework. Ensure the version is pinned as specified.

```bash
# Install command(s)
```