Coding Agent Spec: Overview

Goal: Everything you need to build a working coding agent, in one place. Audience: Engineers who want to build, not just understand. Status: Reproduction-ready specification.

---

Design Principles

1. Standalone - This folder contains everything. No external dependencies.
2. Reproduction-ready - Complete specs, not summaries. You can build from this.
3. Evidence-based - Derived from production agent analysis (Amp Code, Jan 2026).
4. Practical - Ordered by what you need to build first.

---

Spec Structure

coding-agent-spec/
│
├── 00-SPEC-OVERVIEW.md               # This file
│
├── foundations/                       # UNDERSTAND (read first)
│   ├── 01-what-is-a-coding-agent.md  # Mental model
│   └── 02-architecture-overview.md   # Components and data flow
│
├── implementation/                    # BUILD (core agent)
│   ├── 03-agent-loop.md              # State machine spec
│   ├── 04-tool-system.md             # Tool registration + execution
│   ├── 05-core-tools.md              # Read/edit_file/create_file/Bash/glob/Grep
│   ├── 06-context-window.md          # Token management
│   ├── 07-streaming.md               # SSE/delta handling
│   ├── 08-verification.md            # Course correction
│   ├── 09-memory.md                  # AGENTS.md, rules
│   ├── 10-minimal-agent.md           # COMPLETE WORKING SPEC
│   └── 11-threads.md                 # Persistent conversation state
│
├── enhancements/                      # LEVEL UP (production features)
│   ├── 11-subagents.md               # Task delegation
│   ├── 12-course-correction.md       # Meta-agent monitoring
│   ├── 13-multi-model.md             # Model routing
│   ├── 14-advanced-tools.md          # Kraken, look_at, etc.
│   ├── 15-permissions.md             # Trust and safety
│   └── 16-skills.md                  # Extensible domain knowledge
│
├── reference/                         # COPY-PASTE (implementation artifacts)
│   ├── tools/
│   │   └── TOOLS.md                  # Complete tool catalog + schemas
│   ├── prompts/
│   │   └── PROMPTS.md                # Complete prompts (verbatim)
│   └── constants.md                  # All magic numbers
│
└── context/                           # BACKGROUND (optional reading)
    ├── why-coding-agents-matter.md   # Why this space matters
    ├── agi-thesis-deep-analysis.md   # First-principles analysis
    ├── industry-comparison.md        # How others do it
    ├── evidence-sources.md           # Where this came from
    └── open-questions.md             # What we don't know

---

Reading Order

To Build a Minimal Agent (fastest path)

01 → 02 → 03 → 04 → 05 → 10

Skip to 10-minimal-agent.md for the complete spec once you understand the concepts.

To Build a Production Agent

01 → 02 → 03 → 04 → 05 → 06 → 07 → 08 → 09 → 10

To Understand Design Decisions

01 → 02 → context/why-coding-agents-matter.md → context/industry-comparison.md → context/agi-thesis-deep-analysis.md

---

What "Reproduction-Ready" Means

Component	What You Get
Agent loop	State machine diagram + pseudocode + all transitions
Tools	Full JSON schemas, ready for tool_use API
Prompts	Complete text, not summaries
Constants	Every magic number with explanation
Decisions	Explicit choice points with tradeoffs

After reading 10-minimal-agent.md, you should be able to implement a working coding agent in your language of choice.

---

Evidence Base

This spec is derived from reverse-engineering Amp Code (Sourcegraph's AI coding agent):

Source	Version	What It Provided
Production bundle	v0.0.1769212917 (Jan 2026)	Current architecture
Source maps	v0.0.1744408301-dev	Original TypeScript (Rosetta Stone)
Changelog analysis	Apr-Dec 2025	Evolution patterns

The patterns here are validated against production code, not theoretical designs.

---

Quick Start

Want to build right now?

1. Read foundations/02-architecture-overview.md
2. Read implementation/10-minimal-agent.md
3. Copy schemas from reference/tools/
4. Copy prompts from reference/prompts/
5. Implement in your language

---

Status

Section	Status	Notes
Foundations	✅ Complete	2 docs
Implementation	✅ Complete	9 teaching docs + 7 spec docs
Enhancements	✅ Complete	6 docs (advanced topics)
Reference	✅ Complete	Tools, prompts, constants
Context	✅ Complete	5 docs

---

Spec started: 2026-01-24 Based on: Amp Code v0.0.1769212917 Methodology: Production code analysis