Grok Build Source Course · 12 / 24

Coding Agent Design Workbench

The capstone task evolves from a feature list to a runnable system design. Make explicit decisions across nine dimensions — each must include a contract, failure path, validation method, and submittable deliverable.

9 Decisions9 DeliverablesArchitecture + PoCEvidence Review
01 / OBJECTIVES

Course Objectives

Complete System Boundaries

Define the responsibility boundaries of entry points, state ownership, model loops, and external extensions.

Fill in Failure Design

Draw failure paths for tools, security, persistence, recovery, and state notifications.

Produce Reviewable Deliverables

Submit ADRs, contracts, threat models, tests, and a minimal demo — not just conceptual diagrams.

02 / CORE VISUAL

The Complete Agent System at a Glance

03 / BRIEF

Capstone Project Brief

Task

Design a "repo-scale Coding Agent" for a real team. It must at minimum read code, propose a plan, edit files, run validation, and resume interrupted sessions. A minimal PoC is acceptable; the architecture document must cover all nine dimensions.

Hard Constraints
  • Least-privilege by default
  • Every external action is traceable
  • Crash recovery is explainable
  • Sensitive data has a defined landing spot
  • Extension code has a trust boundary
04 / WORKBENCH

Nine-Dimension Decision Cards

ENTRY

Entry Point

Who starts the Agent, and do interactive, CI, and IDE modes share the same core?

Source anchors: pager-bin composition root, shell headless/stdio, ACP gateway.

DeliverableEntry matrix + CLI argument draft + one end-to-end startup sequence diagram.
STATE

State / Concurrency

Who owns session state, and how are model streams and tool tasks cancelled, queued, and returned?

Source anchors: SessionActor, LocalSet, background summary/persistence actor.

DeliverableState ownership diagram + concurrency sequence + race condition test checklist.
MODEL LOOP

Model Loop

How do prompts, streaming output, tool calls, retries, stops, and model switches form a closed loop?

Source anchors: run_loop, turn, tool_dispatch, model_switch, two_pass.

DeliverableModel loop state machine + stop conditions + three API error strategies.
TOOLS

Tool Contract

How are input Schema, return values, errors, timeouts, idempotency, and permission tiers standardized?

Source anchors: ToolKind, Tool Bridge, server__tool, capability filter.

DeliverableTwo JSON Schemas + error classification table + contract tests.
CONTEXT

Context / Memory

When is short-term context compacted; what is written to long-term memory, when is it retrieved, and how is it deleted?

Source anchors: compaction segments, two-pass, memory FTS/embedding/MMR/Dream.

DeliverableToken budget table + compaction algorithm + memory recall and forgetting tests.
SECURITY

Security

What guarantee does each layer — permissions, sandbox, Hooks, network, and plugin trust — provide?

Source anchors: capability, sandbox, Hooks fail-open, plugin-root trust.

DeliverableThreat model + permission matrix + 5 attack scenarios.
RECOVERY

Persistence / Recovery

How are messages, tool results, file checkpoints, and external connection state persisted and replayed?

Source anchors: session persistence, chat persistence, rewind, MCP restart.

DeliverableStorage Schema + crash injection script + RPO/RTO declaration.
OBSERVABILITY

Observability / Privacy

Which events enter logs and metrics; what must be redacted, sampled, or prohibited from leaving the machine?

Source anchors: file-utils events, telemetry enums, MCP status payload.

DeliverableEvent dictionary + redaction table + 3 SLOs and diagnostic queries.
EXTENSIONS

Extension Ecosystem

How are MCP, Plugin, and Hook discovery, versioning, enablement, trust, and uninstallation governed?

Source anchors: marketplace index, manifest, install registry, trust store.

DeliverablePlugin manifest + trust lifecycle + compatibility policy.
05 / SOURCE MAP

Real Source Code Evidence Navigation

Entry & Sessionxai-grok-pager-bin/src/main.rs
xai-grok-shell/src/session/acp_session.rs
Model & Toolssession/acp_session_impl/run_loop.rs
xai-grok-workspace/src/capability.rs
Context & Memorysession/compaction.rs · two_pass.rs
xai-grok-memory/src/
Security & Hooksxai-grok-sandbox
xai-grok-hooks/src/dispatcher.rs
Recovery & Statesession/persistence.rs
mcp_dispatcher.rs · mcp_restart.rs
Extensionsxai-grok-plugin-marketplace/src/
xai-grok-agent/src/plugins/
EVIDENCE EXAMPLE

Every design decision must trace back to a real source branch

// Do not grant trust if plugin root cannot be canonicalized
match dunce::canonicalize(plugin_root) {
    Ok(canonical) => self.trusted.contains(&canonical),
    Err(_) => false,
}

Your design must also specify failure defaults. When policy cannot be read, tool results cannot be parsed, or a checkpoint cannot be restored — the system should respectively stop, degrade, or prompt the user.

crates/codegen/xai-grok-agent/src/plugins/trust.rs
06 / RUBRIC

100-Point Review Rubric

20Boundaries & ADRs
20Contracts & State Machines
25Security & Recovery
20Tests & Observability
15Demo & Evidence

Automatic disqualifiers: submission does not identify where sensitive data lands; high-risk tools have no permission path; crash recovery is claimed but untested; source code references cannot be traced to a file path.

07 / FINAL LAB

Lab: 90-Minute Design Sprint

90 MIN

Final Submission Package
Reviewable design archive

  1. 15 min: Define users, repo, executable permissions, and success criteria.
  2. 20 min: Complete the core visual and nine-dimension decision cards; mark all state owners.
  3. 20 min: Implement one tool contract and a minimal model-to-tool call chain.
  4. 15 min: Inject timeouts, permission denials, and process crashes; record recovery results.
  5. 10 min: Complete data flow, redaction, and plugin trust checks.
  6. 10 min: Self-assess using the rubric; submit 3 ADRs, test records, and a 5-minute demo script.
Takeaway

The maturity of a Coding Agent shows in its boundaries and failure paths. The nine-dimension workbench helps you convert model capabilities into an engineering system that is runnable, recoverable, auditable, and extensible.

Source snapshot note: This page uses the local grok-build-main as its design case library; path anchors come from real source code. The delivery formats in the workbench are course design artifacts and do not claim to be the official architecture template of Grok Build. Students may use other tech stacks, but each decision must be supported by equivalent-quality evidence.