## File: docker/README.md

# 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

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

## Docker Images

| File | Purpose |
|------|---------|
| `Dockerfile.sandbox` | Runtime sandbox with entrypoint (UID remapping, bootstrap) |
| `Dockerfile.ci-builder` | CI builds — includes build tools, no entrypoint magic |

## Compose Files

| File | Purpose |
|------|---------|
| `docker-compose.yaml` | Minimal zero-config setup — just works with sensible defaults |
| `docker-compose.full.yaml` | Fully documented reference with all options, resource limits, health checks |

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

## Quick Start

### Option A: Docker Sandbox CLI (recommended)

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

```bash
# 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

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

```bash
# 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

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.

```bash
# 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

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

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

```bash
# 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

### Docker Sandbox (automatic)

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 `docker/.env.example` to `docker/.env` and fill in your keys. The `.env` file is gitignored and never committed.

## Network Allowlisting

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

| Purpose | Endpoints |
|---------|-----------|
| LLM APIs | `api.anthropic.com`, `api.openai.com`, `generativelanguage.googleapis.com`, `openrouter.ai` |
| Package registry | `registry.npmjs.org` |
| Research tools | `api.search.brave.com`, `api.tavily.com`, `r.jina.ai` |
| GitHub | `api.github.com`, `github.com` |

## Customizing the Image

Build with a specific GSD version:

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

## Cleanup

```bash
# Docker Sandbox
docker sandbox rm gsd-sandbox

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

## Known Limitations

- **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

# Domain Docs

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

## Before exploring, read these

- **`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

Single-context layout (this repo):

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

## Use the glossary's vocabulary

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

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

# 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

- **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"

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

## When a skill says "fetch the relevant ticket"

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

---

## File: docs/agents/triage-labels.md

# 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.

| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
| -------------------------- | -------------------- | ---------------------------------------- |
| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
| `wontfix`                  | `wontfix`            | Will not be actioned                     |

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:

```bash
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

# Work Decomposition

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

### The Compression Ladder

```
Vision → Capabilities → Systems/Architecture → Features → Tasks
```

Each layer answers a different question:

| Layer | Question |
|-------|----------|
| Vision | What world are we creating? |
| Capabilities | What must the product be able to do? |
| Systems | What infrastructure enables those capabilities? |
| Features | What does the user interact with? |
| Tasks | What exact code gets written? |

### Core Principles (All 4 Models Agree)

- **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

> 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

# What to Keep & Discard from Human Engineering

### KEEP & Amplify

| Practice | Why It Matters More for AI |
|----------|---------------------------|
| **Clear product intent & experience specs** | AI needs direction, not instructions. "How should it feel?" drives architecture. |
| **Acceptance criteria as the backbone** | Becomes TDD at its logical extreme — human writes tests in natural language, AI makes them true. |
| **Vertical slicing** | Even more critical — prevents AI from going deep down a wrong path fast and confidently. |
| **Interface-first approach** | Creates natural checkpoints, makes systems modular and replaceable. |
| **Explicit constraints & non-functional requirements** | Narrows the search space. Without them AI may produce technically correct but strategically wrong systems. |
| **Architecture Decision Records (ADRs)** | Prevents AI from "accidentally" undoing decisions made weeks ago. |
| **Feedback loops** | Build → test → observe → refine. Accelerated to machine speed. |

### DISCARD

| Practice | Why It's Dead Weight |
|----------|---------------------|
| **Estimation rituals** (story points, velocity, sprint planning) | AI doesn't get tired, doesn't context-switch, works at machine speed. |
| **Communication overhead** (standups, design reviews, PR reviews) | Only one communication channel matters: human ↔ agent. |
| **Manual code review for style** | Automated linting + formatting handles this deterministically. |
| **Step-by-step instructions** | Provide outcomes, not "how." |
| **Heavy upfront documentation** | AI can read the entire repo instantly. Document *intent* and *why*, not *how*. |
| **Gradual skill-building** | No ramp-up, no knowledge silos, no "only Sarah knows how that module works." |
| **Defensive architecture against human error** | Tests still needed, but for a different reason: verifying AI's interpretation of intent. |

### The New Human Role

| Responsibility | Description |
|---------------|-------------|
| **Defining "good"** | Vision, personas, experience specs, success metrics |
| **Taste & judgment** | Aesthetics, emotional experience, brand voice |
| **Strategic decisions** | Which problems matter, product pivots |
| **Gut checks at milestones** | Does this *feel* right? |

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

---

---

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

# State Machine & Context Management

### The Fundamental Tension

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)

```
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)
```

| Layer | Content | Access Pattern | Token Impact |
|-------|---------|---------------|--------------|
| **Working Context** (L1) | Current task + 3–5 relevant files | Dynamically assembled per LLM call | 8k–25k tokens |
| **Session/Episodic** (L2) | Compressed history + recent decisions | Auto-summarized at transitions | Summary only |
| **Project Semantic** (L3) | Full codebase summaries, dependency graph, ADRs | Vector + Graph retrieval | Pointers only |
| **Ground Truth** (L4) | Actual files, git history, test results | Agent reads via tools | Zero in prompt |

### The State Machine

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

- **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

# Optimal Storage for Project Context

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

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

| Storage | What Lives Here | Why |
|---------|----------------|-----|
| **Project Manifest** (`PROJECT.md`) | Vision, principles, architecture overview, component status | Always loaded, <1000 tokens, single source of truth |
| **Structured State** (JSON/SQLite/Postgres) | Task status, phase, dependencies, verification results | Machine-parseable, drives state machine transitions |
| **Context Directory** (`.context/` or `.ai/`) | Architecture docs, task specs, decision records | Organized for retrieval, not human browsing |
| **Git Repository** | Actual source code, test results | Ultimate ground truth, never duplicated |
| **Knowledge Graph** (optional at scale) | File → function → dependency relationships | Enables "what breaks if I change this?" queries |

### Why Plain Files Win

- 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)

- 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

Individual files use **YAML frontmatter + Markdown body**:
```yaml
---
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

| File | Target Size |
|------|------------|
| Project Manifest | <1,000 tokens |
| Individual task files (completed) | <500 tokens |
| Architecture doc | <2,000 tokens |

> 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

# Parallelization Strategy

### Core Principle

> Parallelize across boundaries, serialize within them.

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

### The Diamond Pattern

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

### Phase-by-Phase Strategy

#### 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

| Work Type | Strategy |
|-----------|----------|
| **Independent leaf tasks** | Embarrassingly parallel — one agent per module |
| **Dependent chains** | Serial within chain, but chains run in parallel |
| **Convergence points** | Strictly serial — integration verification |

**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

- 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

- ❌ 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

# Maximizing Agent Autonomy & Superpowers

### The Foundational Insight

> 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

| Category | Tools | Why |
|----------|-------|-----|
| **Execution Environment** | Terminal, filesystem, git, package manager | Closes the write → run → debug → verify loop |
| **Verification** | Test runner, linter, type checker, security scanner | Ground truth over self-assessment |
| **Observation** | Logs, browser/renderer, performance profiler | Sees what users would see |
| **Exploration** | Code search, documentation lookup, web research | Self-directed learning |
| **Recovery** | Git revert, branch management, checkpoints | Safety net that enables boldness |

### Self-Verification Architecture

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

- **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

- **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

> 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

# System Prompt & LLM vs Deterministic Split

### The Core Separation Principle

> 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

| Capability | Why LLM |
|-----------|---------|
| Understanding intent | Interpretation, judgment |
| Architectural reasoning | Weighing tradeoffs |
| Code generation | Creative, context-dependent |
| Debugging & diagnosis | Abductive reasoning, hypothesis formation |
| Self-critique & quality assessment | Judgment calls |

### What TypeScript/Deterministic Code Owns

| Capability | Why Deterministic |
|-----------|-------------------|
| State machine transitions | Typed state object, no ambiguity |
| Context assembly | Predict + pre-load what agent needs |
| File operations | Validate paths, handle encoding, manage permissions |
| Test execution & result parsing | Structured results, not raw terminal output |
| Build & environment management | Install deps, start servers, manage ports |
| Code formatting | Run prettier automatically, never waste LLM tokens |
| Task scheduling & dependency resolution | Graph traversal, instant vs 5-second LLM call |
| Summarization triggers | Mechanical workflow, LLM provides content |

### Modular System Prompt Architecture

```
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

> 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

| Tool | Returns |
|------|---------|
| `runTests` | Structured results: pass count, fail count, per-failure details |
| `readFiles` | Batched file contents (array of paths, not one at a time) |
| `writeFile` | Auto-formats before writing |
| `searchCodebase` | Grep-like results with file paths and line numbers |
| `getProjectState` | Manifest + current task spec + related task statuses |
| `updateTaskStatus` | Handles downstream state updates automatically |
| `buildProject` | Structured errors with file paths and line numbers |
| `browserCheck` | Screenshot or structured description of rendered output |
| `commitChanges` | Enforces conventions, runs pre-commit hooks |
| `revertToCheckpoint` | Rolls back to last known good state |

### Prompt Patterns That Maximize Agency

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

> 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

# Speed Optimization

### The #1 Speed Principle

> 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)

#### 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

| Anti-Pattern | Fix |
|-------------|-----|
| Re-verifying things that can't have changed | Dependency-aware selective re-verification |
| Excessive self-reflection on simple tasks | Complexity-based workflow routing |
| Over-summarization between micro-steps | Only full context reset at task boundaries |
| Waiting for human approval on auto-verifiable work | Human checkpoints at milestones, not tasks |
| Quadratic history growth | Aggressive compression at every transition |
| Synchronous blocking tools | Async everything, pipeline parallelism |

### The Speed Multiplier Nobody Talks About

**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.

---