Shotgun Tutorial: Spec-Driven Development for Coding Agents

Learn how to use shotgun-sh/shotgun to plan, specify, and execute large code changes with structured agent workflows and stronger delivery control.

Why This Track Matters

When coding agents work on larger features, they often drift from architecture and produce hard-to-review output. Shotgun uses a structured flow to keep planning, scoping, and execution aligned with your codebase.

This track focuses on:

• router-driven multi-agent lifecycle (research to export)
• planning and drafting execution modes
• codebase indexing, context retrieval, and operations
• production concerns across CI, observability, and security

Current Snapshot (auto-updated)

• repository: shotgun-sh/shotgun
• stars: about 669
• latest release: 0.13.0 (published 2026-04-14)

Mental Model

flowchart LR
    A[Prompt] --> B[Router]
    B --> C[Research]
    C --> D[Specify]
    D --> E[Plan]
    E --> F[Tasks]
    F --> G[Export]
    G --> H[Agent Execution]

Chapter Guide

Chapter	Key Question	Outcome
01 - Getting Started	How do I install and run Shotgun quickly?	Working local baseline
02 - Router Architecture and Agent Lifecycle	How does Shotgun break work into specialized agents?	Clear orchestration model
03 - Planning vs Drafting Execution Modes	When should I use checkpoints versus full-speed runs?	Better control and throughput
04 - Codebase Indexing and Context Retrieval	How does Shotgun build code awareness before writing changes?	Stronger context quality
05 - CLI Automation and Scripting	How do I run Shotgun in scripts and CI flows?	Repeatable automation patterns
06 - Context7 MCP and Local Models	How do docs lookup and local model support work?	Practical integration strategy
07 - Spec Sharing and Collaboration Workflows	How do teams share and iterate specs safely?	Better collaboration lifecycle
08 - Production Operations, Observability, and Security	How do I run Shotgun in production environments?	Ops and governance baseline

What You Will Learn

• how to structure large coding-agent tasks into staged execution
• how to use router modes for safer implementation flow
• how to automate Shotgun in CI and team workflows
• how to harden operations with telemetry, secrets hygiene, and deployment controls

Source References

• Shotgun Repository
• Shotgun CLI Docs
• Context7 Integration Architecture
• Ollama/Local Models Architecture
• CI/CD Docs

Related Tutorials

• OpenCode Tutorial
• Cline Tutorial
• Plandex Tutorial
• HumanLayer Tutorial

---

Start with Chapter 1: Getting Started.

Navigation & Backlinks

• Start Here: Chapter 1: Getting Started
• Back to Main Catalog
• Browse A-Z Tutorial Directory
• Search by Intent
• Explore Category Hubs

Full Chapter Map

1. Chapter 1: Getting Started
2. Chapter 2: Router Architecture and Agent Lifecycle
3. Chapter 3: Planning vs Drafting Execution Modes
4. Chapter 4: Codebase Indexing and Context Retrieval
5. Chapter 5: CLI Automation and Scripting
6. Chapter 6: Context7 MCP and Local Models
7. Chapter 7: Spec Sharing and Collaboration Workflows
8. Chapter 8: Production Operations, Observability, and Security

Generated by AI Codebase Knowledge Builder