gsd-2 Documentation

File: docker/README.md Copy Chapter

GSD Docker Sandbox

Run GSD auto mode inside an isolated Docker sandbox so it cannot touch your host filesystem, SSH keys, or other projects.

Prerequisites Copy Chapter

• Docker Desktop 4.58+ (macOS or Windows; Linux support is experimental)
• At least one LLM provider API key

Docker Images Copy Chapter

Compose Files Copy Chapter

Start with docker-compose.yaml. Copy options from docker-compose.full.yaml when you need them.

Quick Start Copy Chapter

Option A: Docker Sandbox CLI (recommended) Copy Section

Docker Sandboxes provide MicroVM isolation — each sandbox runs in a lightweight VM with its own kernel and private Docker daemon.

# Create a sandbox from the template
docker sandbox create --template ./docker --name gsd-sandbox

# Shell into the sandbox
docker sandbox exec -it gsd-sandbox bash

# Inside the sandbox, run GSD
gsd auto "implement the feature described in issue #42"

Option B: Docker Compose Copy Section

For environments without Docker Sandbox support, use Compose for container-level isolation:

# 1. Configure API keys
cp docker/.env.example docker/.env
# Edit docker/.env with your keys

# 2. Start the sandbox
docker compose -f docker/docker-compose.yaml up -d

# 3. Shell into the container
docker exec -it gsd-sandbox bash

# 4. Run GSD inside the container
gsd auto "implement the feature described in issue #42"

UID/GID Remapping Copy Chapter

The entrypoint handles UID/GID remapping via PUID and PGID environment variables. This avoids permission issues on bind-mounted volumes by matching the container's gsd user to your host UID/GID.

# Find your host UID/GID
id -u  # PUID
id -g  # PGID

Set these in your .env file or in the environment section of the compose file. Defaults to 1000:1000.

Entrypoint Behavior Copy Chapter

The container entrypoint (entrypoint.sh) runs four steps on every start:

1. UID/GID remapping — adjusts the gsd user to match PUID/PGID
2. Pre-create critical files — prevents Docker bind-mount from creating directories where files are expected
3. Sentinel-based bootstrap — runs bootstrap.sh exactly once on first boot
4. Drop privileges — exec gosu gsd for proper PID 1 signal forwarding

No hardcoded user: directive in compose — the entrypoint starts as root, remaps, then drops to gsd.

Two-Terminal Workflow Copy Chapter

GSD's recommended workflow uses two terminals — one for auto mode, one for interactive discussion:

# Terminal 1: auto mode
docker sandbox exec -it gsd-sandbox bash
gsd auto "your task description"

# Terminal 2: discuss / monitor
docker sandbox exec -it gsd-sandbox bash
gsd discuss

With Docker Compose, replace docker sandbox exec with docker exec.

Credential Injection Copy Chapter

Docker Sandbox (automatic) Copy Section

Docker's proxy layer forwards API keys set in your host shell config (~/.bashrc, ~/.zshrc) into the sandbox automatically. Keys are never stored inside the sandbox.

Docker Compose (manual) Copy Section

Copy docker/.env.example to docker/.env and fill in your keys. The .env file is gitignored and never committed.

Network Allowlisting Copy Chapter

If you restrict outbound network access in your sandbox, GSD needs these endpoints:

Customizing the Image Copy Chapter

Build with a specific GSD version:

docker compose -f docker/docker-compose.yaml build --build-arg GSD_VERSION=2.51.0

Cleanup Copy Chapter

# Docker Sandbox
docker sandbox rm gsd-sandbox

# Docker Compose
docker compose -f docker/docker-compose.yaml down -v

Known Limitations Copy Chapter

• macOS/Windows only: Docker Sandboxes require Docker Desktop 4.58+. Linux sandbox support is experimental.
• Environment parity: The sandbox runs Ubuntu (Debian). macOS-only dependencies may not work inside the sandbox.
• Named agent registration: Docker Desktop's built-in named agents (claude, codex, etc.) are registered by Docker itself. Third-party tools cannot register new named agents. GSD uses the generic shell sandbox type with a custom template instead.

File: docs/agents/domain.md Copy Chapter

Domain Docs

How the engineering skills should consume this repo's domain documentation when exploring the codebase.

Before exploring, read these Copy Chapter

• CONTEXT.md at the repo root.
• docs/adr/ — read ADRs that touch the area you're about to work in.

If any of these files don't exist, proceed silently. Don't flag their absence; don't suggest creating them upfront. The producer skill (/grill-with-docs) creates them lazily when terms or decisions actually get resolved.

File structure Copy Chapter

Single-context layout (this repo):

/
├── CONTEXT.md
├── docs/adr/
│   ├── 0001-...md
│   └── 0002-...md
└── src/

Use the glossary's vocabulary Copy Chapter

When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in CONTEXT.md. Don't drift to synonyms the glossary explicitly avoids.

If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for /grill-with-docs).

Flag ADR conflicts Copy Chapter

If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:

Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…

File: docs/agents/issue-tracker.md Copy Chapter

Issue tracker: GitHub

Issues and PRDs for this repo live as GitHub issues on gsd-build/gsd-2 (the upstream remote). Use the gh CLI for all operations.

This clone may have multiple remotes (origin is a personal fork, upstream is the canonical repo). Always pass -R gsd-build/gsd-2 so commands hit the canonical tracker rather than auto-resolving to the fork.

Conventions Copy Chapter

• Create an issue: gh issue create -R gsd-build/gsd-2 --title "..." --body "...". Use a heredoc for multi-line bodies.
• Read an issue: gh issue view <number> -R gsd-build/gsd-2 --json number,title,body,labels,comments --jq '{number, title, body, labels: [.labels[].name], comments: [.comments[].body]}'.
• List issues: gh issue list -R gsd-build/gsd-2 --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]' with appropriate --label and --state filters.
• Comment on an issue: gh issue comment <number> -R gsd-build/gsd-2 --body "..."
• Apply / remove labels: gh issue edit <number> -R gsd-build/gsd-2 --add-label "..." / --remove-label "..."
• Close: gh issue close <number> -R gsd-build/gsd-2 --comment "..."

When a skill says "publish to the issue tracker" Copy Chapter

Create a GitHub issue on gsd-build/gsd-2.

When a skill says "fetch the relevant ticket" Copy Chapter

Run gh issue view <number> -R gsd-build/gsd-2 --comments.

File: docs/agents/triage-labels.md Copy Chapter

Triage Labels

The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.

When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.

needs-triage and needs-info already exist on gsd-build/gsd-2. The other three (ready-for-agent, ready-for-human, wontfix) will be created on first use:

gh label create ready-for-agent -R gsd-build/gsd-2 --description "Fully specified, ready for an AFK agent" --color 0E8A16
gh label create ready-for-human -R gsd-build/gsd-2 --description "Requires human implementation" --color 1D76DB
gh label create wontfix         -R gsd-build/gsd-2 --description "Will not be actioned"          --color CCCCCC

Edit the right-hand column to match whatever vocabulary you actually use.

File: docs/dev/building-coding-agents/01-work-decomposition.md Copy Chapter

Work Decomposition

The universal consensus: Elite engineers never jump from vision to code. They use progressive decomposition through layers of abstraction.

The Compression Ladder Copy Section

Vision → Capabilities → Systems/Architecture → Features → Tasks

Each layer answers a different question:

Core Principles (All 4 Models Agree) Copy Section

• Start with outcomes, not features. Define "done" before anything else. Not "build a login page" but "a user can securely access their dashboard using OAuth."
• Vertical slices over horizontal layers. Build thin end-to-end slices (UI → API → DB) rather than completing all backend before all frontend. Each slice is independently demoable and testable.
• The 1-Day Rule. If a task takes longer than a day, it's not a task — it's a milestone. Break it down further until each item is a single, clear action completable in one sitting.
• Risk-first exploration. Identify the hardest/most uncertain parts first. Spike on unknowns before committing to architecture. "Kill the biggest risks while they are still cheap to fix."
• Interface-first design. Define contracts between components before building them. This enables parallel work and creates natural verification checkpoints.
• MECE decomposition. Tasks should be Mutually Exclusive (no overlap) and Collectively Exhaustive (complete the vision when all are done).

The Recursive Heuristic Copy Section

If something feels fuzzy, break it down one level deeper. Keep decomposing until a task is obvious how to start.

File: docs/dev/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md Copy Chapter

What to Keep & Discard from Human Engineering

KEEP & Amplify Copy Section

DISCARD Copy Section

The New Human Role Copy Section

The core shift: Human = intention + taste. AI = exploration + execution.

File: docs/dev/building-coding-agents/03-state-machine-context-management.md Copy Chapter

State Machine & Context Management

The Fundamental Tension Copy Section

The agent needs to understand the whole project to make good decisions, but any single context window degrades with too much information — not just from token limits but from attention dilution.

Layered Memory Architecture (Universal Agreement) Copy Section

Project Manifest (always loaded, <1000 tokens)
        ↓
Task Context (per-task, relevant files + specs)
        ↓
Retrieval Layer (pull-based, on-demand)
        ↓
Ground Truth (filesystem, git, actual code)

The State Machine Copy Section

The agent should always be in one explicit state:

PLAN → IMPLEMENT → TEST → DEBUG → VERIFY → DOCUMENT

Critical transitions that matter:

• Task completion: Defined by automated tests passing + acceptance criteria met
• Stuck detection: Triggered by repeated failed attempts or missing information
• Plan revision: Triggered when completed tasks reveal wrong assumptions

Key Principles Copy Section

• Summarize aggressively between phases. Don't carry full implementation context forward — carry compressed summaries: what was built, what decisions were made, what interfaces were created.
• Pull-based, not push-based context. Don't preload everything the agent might need. Let it ask for what it discovers it needs.
• Use structured state for reliability. Natural language summaries drift. Use JSON/typed configs for anything the system needs to track. Reserve natural language for reasoning.
• The filesystem is external memory. The codebase itself is the most detailed representation of current state. Hold understanding about code in context, not the code itself.

File: docs/dev/building-coding-agents/04-optimal-storage-for-project-context.md Copy Chapter

Optimal Storage for Project Context

The Universal Answer: Plain Text Files in the Repo + Structured State Store Copy Section

All four models converge on a hybrid approach. The key insight: don't over-engineer with databases and vector stores, but don't under-engineer with a single massive file either.

The Optimal Stack Copy Section

Why Plain Files Win Copy Section

• AI reads files directly — no query language, no ORM, no API calls
• Version control comes free via git
• Human can read and edit with any text editor
• Survives tooling changes — not locked into any system

Why NOT Vector Stores (as primary) Copy Section

• Project context is structured — you know where things are
• Vector stores return approximately relevant results — approximate is often wrong in codebases
• They can't represent state, relationships, or task progress

The Hybrid Format Copy Section

Individual files use YAML frontmatter + Markdown body:

---
status: in_progress
dependencies: [AUTH-01, DB-02]
acceptance_criteria:
  - User can reset password via email
  - Token expires after 30 minutes
---

## Task: Password Reset Flow
[Rich narrative description and context here]

Size Discipline Copy Section

The context system isn't just storage — it's a compression engine. Its job is to maintain maximum useful understanding in minimum token footprint.

File: docs/dev/building-coding-agents/05-parallelization-strategy.md Copy Chapter

Parallelization Strategy

Core Principle Copy Section

Parallelize across boundaries, serialize within them.

The quality of parallelization is directly determined by the quality of interface definitions.

The Diamond Pattern Copy Section

Planning (narrow, serial)
         ↓
   Fan Out (parallel execution)
         ↓
  Convergence (integration verification)
         ↓
    Fan Out (next parallel set)

Phase-by-Phase Strategy Copy Section

Planning: Mostly Serial, with Parallel Spikes

• High-level decomposition must be serial (one coherent act of reasoning)
• Parallelize uncertainty resolution: Multiple spikes investigating different risks simultaneously
• Output: A dependency graph that explicitly identifies what can be parallelized

Execution: Massive Parallelization with Right Topology

Critical insight: The frontend doesn't need the real API — it needs the API contract. Once contracts exist, both sides build in parallel.

Testing: The Most Interesting Story

• Unit tests: Same agent, same context, atomic with code
• Cross-task tests: All parallel by definition
• Integration tests: Parallel across different boundaries
• E2E tests: Serial (exercises whole system)

Verification: Deliberate Redundancy

• Adversarial verification: Separate reviewer agent with fresh context evaluates against spec
• Red-team parallelism: Agent tries to break the implementation

Coordination Rules Copy Section

• Agents communicate through the filesystem, never directly
• Each agent works on a branch — merge on success, discard on failure
• One agent per file at a time (file locking)
• Optimal concurrency: 3–8 simultaneous agents for most projects

Anti-Patterns Copy Section

• ❌ Don't parallelize tasks that modify the same files
• ❌ Don't parallelize interacting decisions
• ❌ Don't skip convergence/integration verification
• ❌ Don't over-parallelize (coordination tax eats gains above ~8 agents)

File: docs/dev/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md Copy Chapter

Maximizing Agent Autonomy & Superpowers

The Foundational Insight Copy Section

Autonomy comes from self-correction, not from getting it right the first time. The power isn't in the initial generation — it's in iteration speed and feedback signal quality.

The Essential Tool Arsenal Copy Section

Self-Verification Architecture Copy Section

Every task completion should self-evaluate against a checklist:

1. Does the code compile?
2. Do all existing tests still pass?
3. Do new tests pass?
4. Does the application actually start?
5. Can I exercise the feature and see expected behavior?
6. Does this match acceptance criteria point by point?

Debugging Superpowers Copy Section

• Temporary instrumentation: Add logging, remove after diagnosis
• Bisection: Walk back through changes to find where regression was introduced
• Minimal reproduction: Strip away everything except exact conditions that trigger failure
• Exploratory tests: Quick throwaway scripts to test hypotheses

Meta-Cognitive Layer Copy Section

• Scratchpad: External reasoning space to track hypotheses, attempts, and outcomes
• Stuck detection: After N failed attempts, trigger step-back with fresh context and explicitly different approach
• Structured escalation: "Here's what I'm trying, here's what I've tried, here's what I think the issue is, here's what I need from you"

The Philosophy Copy Section

You're not trying to build an agent that doesn't make mistakes. You're building one that catches and fixes its own mistakes faster than a human would notice them. Not intelligence — closed-loop execution with rich feedback.

File: docs/dev/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md Copy Chapter

System Prompt & LLM vs Deterministic Split

The Core Separation Principle Copy Section

If you could write an if-else statement that handles it correctly every time, it should not be in the LLM's context. Every token the model spends reasoning about something deterministic is wasted and introduces hallucination risk.

What the LLM Owns Copy Section

What TypeScript/Deterministic Code Owns Copy Section

Modular System Prompt Architecture Copy Section

Base Layer (always present, ~500 tokens)
  → Identity, core behavioral rules, general approach
  
Phase-Specific Layer (swapped based on state)
  → Planning mode: decomposition, interfaces, risks
  → Execution mode: implementation, testing, iteration
  → Debugging mode: diagnosis, hypothesis testing, isolation

Task-Specific Layer (assembled fresh per task)
  → Current spec, acceptance criteria, relevant contracts, prior attempts

Tools Layer
  → Available tool definitions and parameters

Tool Design Philosophy Copy Section

Each tool should do one thing, do it completely, and return structured results the LLM can immediately act on.

Bad: LLM calls readFile → parseJSON → runCommand (3 calls, 3 failure points)
Good: LLM calls runTests(filter) → gets structured pass/fail with locations (1 call, clean result)

Essential Tools Copy Section

Prompt Patterns That Maximize Agency Copy Section

1. Tell it what it CAN do, not what it can't. "Full authority as long as acceptance criteria and tests pass."
2. Explicit permission to iterate. "First attempt doesn't need to be perfect. Write, run, observe, improve."
3. Clear exit conditions. Concrete, measurable, unambiguous definition of "done."
4. Built-in scratchpad. "Write reasoning in thinking blocks. Track attempts and outcomes."
5. Recovery protocol. "After 3 failed approaches, produce structured escalation."

The Meta-Principle Copy Section

Your TypeScript orchestrator is the deterministic skeleton — workflow, state, context, tools, coordination. The LLM is the reasoning muscle — understanding, creativity, judgment, problem-solving. Neither should do the other's job. When you get this right, the LLM becomes dramatically more capable because it's only doing what it's good at, with exactly the context it needs.

File: docs/dev/building-coding-agents/08-speed-optimization.md Copy Chapter

Speed Optimization

The #1 Speed Principle Copy Section

The fastest possible operation is the one you don't perform. Before optimizing any step, ask: does this step need to exist at all?

Speed Levers (Ranked by Impact) Copy Section

1. Minimize LLM Calls

• Batch intent into single calls. Don't generate code, then tests, then docs separately. One call: "implement, test, and document." TypeScript splits the output.
• Deterministic fast paths. Missing import? Syntax error? Fix without an LLM call if the fix is mechanical.
• Audit call chains ruthlessly — most systems have 50%+ unnecessary sequential calls.

2. Make Feedback Loops Instantaneous

• Use test watch mode (no cold start)
• Run only relevant test subsets (track which files affect which tests)
• Incremental builds (hot module reloading)
• Async, non-blocking file writes

3. Precompute Context

• Predict what the agent will need based on task definition
• Pre-load into the prompt — no tool calls needed mid-generation
• Speculative pre-fetching (like CPU cache prefetching)

4. Parallelize Independent Work

• Minimize startup cost for new parallel agents (pre-built templates, warm connections)
• Use the dependency graph to identify independent work automatically

5. Stream Everything, Block on Nothing

• Process tokens as they arrive
• Pipeline parallelism: start formatting code while commit message is still generating

6. Cache Aggressively

• In-memory cache of everything agent might need
• Cross-task caching for unchanged files
• Cache LLM results for deterministic inputs (boilerplate, type definitions)

7. Minimize Token Waste

• Dense context, not verbose context
• Structured formats for structured data
• Minify reference code that's informational, not for modification

Anti-Patterns That Murder Speed Copy Section

The Speed Multiplier Nobody Talks About Copy Section

Failure prediction. Track patterns across tasks. If certain task types fail on first attempt, pre-load extra guidance. Preventing a failed iteration is faster than executing one.

The magical feeling of speed comes from only doing things that matter, and then doing those things as fast as possible. The system should feel like the agent knew what to do and just did it.