GitHub Spec Kit

Executive Summary

Every developer knows the pattern: Design document says one thing, code does another, six months later nobody knows which is correct. Waterfall specs died when code changed. Agile threw out specs entirely. Both failed for the same reason—humans won't maintain documentation when it's divorced from implementation.

GitHub Spec Kit closes the feedback loop: AI agents update documentation when implementation diverges, so specs become living artifacts instead of shelf-ware. The ROI isn't faster development—it's specs that still accurately describe the codebase three months later.

The Documentation Drift Problem

Every codebase has specs that lie. They said one thing at design time, developers changed it during implementation, and nobody updated the docs. Waterfall tried to solve this with upfront perfection—specs froze before coding started. Agile gave up entirely—"working software over comprehensive documentation."

Both failed for the same reason: humans won't maintain documentation when it's divorced from implementation. The feedback loop is too expensive.

I spent 8 years at EDS maintaining three-ring binders of waterfall specs. The specs were beautiful at handoff. Three months later, they were fiction. The human cost of keeping specs synchronized with code was unsustainable.

What If AI Could Close the Loop?

GitHub Spec Kit offers something different: AI agents that update documentation when implementation changes.

The cycle: AI generates code from spec → human fixes what's wrong → human tells AI "update the specs to match reality" → specs evolve instead of ossifying.

I tested this on a production NuGet package. Two features, 7 hours of work, 136 files changed. Every deviation from the original plan became a permanent improvement to the specs—not tribal knowledge that disappears when I leave. Here's what happened.

What Is GitHub Spec Kit?

GitHub Spec Kit structures AI development into phases that generate persistent documentation. Instead of prompting until code works, you run commands that create markdown artifacts: /speckit.specify captures requirements in SPEC.md, /speckit.plan determines technical approach in PLAN.md, /speckit.tasks breaks work into TASKS.md, and /speckit.implement generates code.

These files live alongside your code in specifications/001-feature-name/ . The structure forces you to think before coding—but more importantly, the files become living documentation. When implementation deviates from the plan (and it always does), you tell the AI to update the specs to match reality.

A /speckit.constitution file defines project-wide standards once, guiding all generation. Optional commands like /speckit.clarify catch ambiguities before implementation. The full toolkit is open-source (MIT) at github/spec-kit .

The Post-Implementation Feedback Loop: The Core Innovation

Here's what makes GitHub Spec Kit fundamentally different from traditional documentation: it's designed for AI agents to update specs when implementation diverges from the plan. This isn't about generating code faster—it's about maintaining knowledge that survives team turnover.

Why This Matters: Path Resolution Example

AI generated code using pathPrefix configuration (standard Eleventy approach). It failed in GitHub Pages subdirectory deployment. I fixed it with a custom relativePath filter. Then I spent 20 minutes having AI update SPEC.md and PLAN.md to document why pathPrefix failed and what works instead.

Result: Next developer doesn't try pathPrefix because the spec explains the failure. That's institutional knowledge that survives my departure—not tribal knowledge that walks out the door.

Now let's see this pattern applied to a real production project.

Case Study: WebSpark.HttpClientUtility — A Production .NET NuGet Package

I applied Spec Kit to WebSpark.HttpClientUtility, a .NET 8/9 NuGet package with decorator-pattern HTTP client utilities. Results from two specs:

I'll walk through both specs, showing how Spec Kit moved me from ambiguous goals to shipped releases (v1.5.0 and v1.5.1).

Repository Layout

Here's the repository structure that emerged from the spec-driven process. Note the distinction between .specify/ (Spec Kit framework and templates) and specifications/ (your actual project specs). Each spec directory contains the complete spec-plan-tasks workflow artifacts:

WebSpark.HttpClientUtility/
├─ .specify/                      # Spec Kit framework
│  ├─ memory/constitution.md      # Project principles
│  ├─ templates/                  # Spec templates
│  └─ scripts/                    # Automation scripts
├─ specifications/
│  ├─ 001-static-documentation-site/
│  │  ├─ spec.md                  # 724 lines
│  │  ├─ plan.md                  # 835 lines
│  │  ├─ tasks.md                 # 1,648 lines
│  │  └─ data-model.md
│  └─ 002-clean-compiler-warnings/
│     ├─ spec.md                  # 120 lines
│     ├─ plan.md                  # 258 lines
│     └─ tasks.md                 # 332 lines
├─ src/                           # Library source
│  └─ WebSpark.HttpClientUtility/
│     ├─ ClientService/
│     ├─ Crawler/
│     ├─ MemoryCache/
│     └─ Streaming/
├─ test/                          # 520 tests (×2 frameworks)
│  └─ WebSpark.HttpClientUtility.Test/
├─ docs/                          # Generated documentation
│  ├─ index.html
│  ├─ getting-started/
│  ├─ api/
│  └─ examples/
├─ .github/
│  ├─ workflows/
│  │  ├─ dotnet.yml              # CI/CD pipeline
│  │  └─ publish-docs.yml        # Doc deployment
│  └─ copilot-instructions.md    # 244 lines
└─ Directory.Build.props         # Solution-wide config

The Spec: Spec 002 - Clean Compiler Warnings

Below is the actual spec that drove me from "unknown number of warnings" to zero warnings with enforcement enabled. It's intentionally explicit and measurable.

# Spec 002: Clean Compiler Warnings

## Summary
Achieve zero compiler warnings across all three projects in the WebSpark.HttpClientUtility solution and enable TreatWarningsAsErrors for CI/CD enforcement.

Target frameworks: net8.0, net9.0
Projects: Library, Test, Web App

## Goals
- Zero compiler warnings in Release and Debug configurations
- Enable TreatWarningsAsErrors solution-wide
- Maintain 100% test pass rate (520 tests × 2 frameworks)
- Comprehensive XML documentation for all public APIs
- Professional quality baseline for NuGet package

## Non-Goals
- Suppress warnings without fixing root causes
- Compromise API design to avoid warnings
- Skip test documentation (treat tests as product)
- Delay enforcement—enable immediately after cleanup

## Constraints
- Cannot break existing public API contracts
- Cannot reduce test coverage
- Must target both net8.0 and net9.0
- Must pass all 520 existing tests
- Changes must be backward compatible

## Current State Analysis Required
1. Run `dotnet build -c Release -v detailed > build_warnings.txt`
2. Categorize warnings by type (CS1591, CS8602, CA2007, etc.)
3. Prioritize: Public API docs > Null safety > Code analysis
4. Document baseline count per category

## Acceptance Criteria
- `dotnet build` produces 0 warnings and 0 errors
- All 520 tests pass on net8.0 and net9.0
- `TreatWarningsAsErrors` enabled in Directory.Build.props
- XML docs for all public classes, methods, properties
- Null reference warnings resolved (not suppressed)
- Code analysis rules properly configured in .editorconfig

## File Plan
- src/WebSpark.HttpClientUtility/**/*.cs (add XML docs, null checks)
- test/WebSpark.HttpClientUtility.Test/**/*.cs (document test intent)
- Directory.Build.props (enable TreatWarningsAsErrors)
- .editorconfig (configure analyzer severities)
- Build verification scripts

## Done Definition
- Build log shows "0 Warning(s)"
- Test output shows "520 passed"
- CI/CD pipeline passes with TreatWarningsAsErrors
- No #pragma warning disable directives added
- Documentation complete for all public surface area

Notice how the spec avoids prescribing HOW to fix warnings—it defines the target state and constraints, letting the implementer (human or AI) determine the optimal approach.

Driving Implementation with the Spec

With SPEC.md in place, Copilot had a clear target and generated the implementation according to the spec's requirements. The actual code changes involved adding XML documentation, implementing null guards, and configuring analyzer rules.

Tests as Acceptance Criteria

Writing tests from the spec gave Copilot unambiguous targets. The existing 520-test suite (260 tests × 2 frameworks) served as acceptance criteria, ensuring no regressions while adding XML documentation and null guards.

The spec's constraint "Must pass all 520 existing tests" made the test suite non-negotiable, preventing shortcuts that might have broken existing functionality.

Packaging for NuGet

One of the most valuable outcomes of the Spec Kit approach was integrating CI/CD directly into the "Done Definition." GitHub Actions workflows became gatekeepers that validated every change before allowing new versions to ship.

This automation simplified the release process dramatically. Instead of manually running tests, checking warnings, packing, and publishing, a single code git tag v1.5.1 | command triggers the entire validated pipeline. The GitHub Spec Kit "Done Definition" became executable infrastructure, not just documentation. For complete workflow details, see the a.text-decoration-none(href='https://github.com/markhazleton/WebSpark.HttpClientUtility/tree/main/.github/workflows' target='_blank' rel='noopener') .github/workflows directory | in the repository.

Results: Zero Documentation Debt

Over two specifications on WebSpark.HttpClientUtility, I achieved the real win: specs that still accurately describe the codebase three months later. Implementation took the same 7 hours it always does. Documentation sync took an additional 20 minutes. That 20 minutes is what traditional approaches skip—and why documentation always becomes outdated.

The Long-Term Value: What Happens After You Ship

The spec-driven approach doesn't make you faster initially—it prevents knowledge decay. When you return to the codebase a year later, or when a new team member joins, the specs accurately describe what was built and why. That's institutional knowledge, not tribal knowledge.

The Feedback Loop in Practice

Each time AI generated wrong code, I fixed it and had AI update the specs. Here's why that matters: these lessons are now permanent documentation that future developers (and AI agents) will read before making changes.

Three Implementation Lessons That Became Institutional Knowledge

Why This Solves a 40-Year-Old Problem

In waterfall, specs froze at design and diverged immediately. In agile, we stopped writing specs because maintaining them was humanly impossible. GitHub Spec Kit closes the loop: when implementation teaches you something, you spend 20 minutes having AI update the specs. The path resolution lesson, the warning fix patterns, the test documentation standard—all permanent institutional knowledge that AI agents read before generating the next feature. That's what survives team turnover.

Frequently Asked Questions

Following the Spec Kit Flow

Ready to try it yourself? Here's the recommended workflow with the slash commands that guide Copilot through each phase. Each command has a specific purpose and builds on the previous steps.

The power of this flow is that each step constrains Copilot's focus. Instead of trying to solve everything at once, you guide it through a logical progression that produces reliable, well-documented results.

The Critical Step: Close the Documentation Loop

Here's the reality: after /speckit.implement completes, you'll tweak edge cases, adjust UX, and fix bugs the AI missed. This iteration is expected and normal. What's different is what you do next.

The feedback loop keeps specs synchronized with reality. Your specs document what you built and what you learned—useful for your future self and your team.

Conclusion: Institutional Knowledge That Survives Team Turnover

The win wasn't 7-hour implementation—it was specs that still accurately describe the codebase three months later. Path resolution decisions, warning remediation strategies, test documentation standards—all captured in markdown that AI reads before generating new features. That's institutional knowledge that survives team turnover, not tribal knowledge that walks out the door.

Use Spec Kit When:

• Institutional knowledge matters: Libraries, APIs, multi-year projects where team turnover is inevitable
• Multiple developers: When onboarding cost of inaccurate documentation compounds over time
• Long-term maintenance: Projects that will be maintained beyond the original author
• Compliance requirements: When you need audit trails and documented decision rationale
• Complex domain logic: When tribal knowledge creates single points of failure

Skip Spec Kit When:

• Throwaway prototypes: POCs you'll rewrite from scratch if successful
• Solo projects with short lifespans: Personal tools you'll maintain alone for 6 months
• Exploratory work: Research spikes where requirements are genuinely unknown
• Trivial features: Single-file utilities that don't need coordination
• Time-critical emergencies: Production fires where documentation can wait

Start small: one .specify/ directory, one SPEC.md with clear acceptance criteria. After implementation, spend 20 minutes having the agent update the spec to match what you actually built. Six months later, you'll thank yourself for the accurate documentation.