AIgile

The working paper: the whole method in one document

Mon, 01 Jan 0001 00:00:00 +0000

Prefer a file? Get the PDF or markdown on the downloads page.

Subtitle: Why the agile core survives the agentic era, and how to rebuild software methodology on top of it

Status: Working paper, version 0.1 (draft for discussion) Date: July 2026 Intended audience: Software engineering leaders, architects, methodologists, and practitioners working with agentic AI systems Purpose of this document: This paper establishes the conceptual foundation of the aigile approach. It is intentionally foundational. In-depth methodology papers, concrete playbooks, tooling guides, and worked examples are expected to build on the definitions and arguments established here.

An assessment of spec-driven development

Mon, 01 Jan 0001 00:00:00 +0000

Spec-driven development (SDD) is the software industry’s first structured answer to coding agents. The idea is to write a specification first and let agents build against it. Tools such as GitHub Spec Kit, AWS Kiro, and Tessl put this idea into practice, and many teams use them today.

What SDD gets right

Three ideas inside SDD hold up well, and aigile builds on all of them. Agents work much better with clear, written, lasting context than with ad hoc chat prompts. Some project knowledge really is foundational, such as architecture rules, domain invariants, and key decisions, and writing it down helps everyone. And breaking work into small, well-described tasks improves both what agents produce and what humans can review.

Reading guide: how the deep dives fit together

Mon, 01 Jan 0001 00:00:00 +0000

Status: Series v0.1, July 2026 Foundation: All papers in this series elaborate the aigile working paper v0.1. Terminology follows the working paper glossary, which is canonical.

Purpose

The working paper establishes the aigile framework as a whole. Each paper in this series takes one load-bearing element, develops it to full depth, specifies its protocols normatively, illustrates it with a running example, and names the derivative artifacts (playbook chapters, slides, website sections, tooling requirements) that should be built from it.

Aigile with SpecKit

Mon, 01 Jan 0001 00:00:00 +0000

The aigile kit referenced below is on the downloads page and at the kit repository; <kit-path> means your local clone of it.

This tutorial takes you from installation to your first sealed feature using the aigile extension, preset, and workflow for GitHub Spec Kit. It uses one small example throughout: a notes app called Taggr gets a tagging feature. Expect one to two hours for the full pass, most of it real work on the feature.

The working loop

Mon, 01 Jan 0001 00:00:00 +0000

Every aigile team runs the same loop, whatever its size or level of automation.

The forward flow has seven steps. A human writes the intent. The feature is cut into slices. Each slice gets a one-screen spec. An agent builds the slice. The change is reviewed as one unit. A human checks the running software at defined points. A retrospective sorts what was learned into the right documents.

Why feedback beats upfront specs

Mon, 01 Jan 0001 00:00:00 +0000

Series: Aigile deep dives, paper 01 of 09. Elaborates working paper Parts I and II. No dependencies.

Abstract

This paper establishes the intellectual foundation of aigile. It argues that waterfall’s defining property is not sequence but the freezing of outputs between phases; that agile’s essential innovation is the backward edge, the sanctioned channel through which learning flows against the direction of production; that prevailing spec-driven development reproduces the frozen-output shape in compressed time; and that agentic AI changes three economic conditions under which agile was derived, without touching the condition that made agile correct. Every protocol in the aigile framework is a formalized backward edge, and this paper is the justification all of them share.

Slicing the work

Mon, 01 Jan 0001 00:00:00 +0000

Slicing sets the pace of everything else in the method. Review stays honest only when a change fits one sitting. An agent stays coherent only when a slice fits one session. Demos happen only when every slice can run end to end. And a wrong decision costs one slice only when slices are actually small. For these reasons, slicing deserves more attention than it usually gets, and this page covers the how and the why.

Aigile with Claude Code

Mon, 01 Jan 0001 00:00:00 +0000

The aigile kit referenced below is on the downloads page and at the kit repository; <kit-path> means your local clone of it.

This tutorial takes you from installation to your first sealed feature using the aigile plugin for Claude Code. It uses the same example as the other tutorials: a notes app called Taggr gets a tagging feature.

1. What you need

Claude Code (current version), signed in
A project repository, ideally fresh or small for the first pass
Windows: run shell snippets in Git Bash (ships with Git), or use the PowerShell equivalents noted in the kit’s docs/INSTALL.md

2. Install

From the published kit repository:

Organizing project documents

Mon, 01 Jan 0001 00:00:00 +0000

Series: Aigile deep dives, paper 02 of 09. Elaborates working paper Section 6. Depends on Paper 01.

Abstract

Agents are stateless; some written layer is therefore mandatory. But treating all written artifacts alike reproduces either waterfall (everything heavy) or vibe coding (everything absent). This paper develops the three-layer model that resolves the tension: a durable layer maintained like law, an ephemeral layer treated as disposable work product, and a derived layer regenerated rather than maintained. It then specifies layered truth: the precedence rules that decide, in advance, which representation wins when representations disagree. The layer assignment of an artifact determines its maintenance model, its authority, its review process, and its drift exposure; most documentation dysfunction in agentic projects traces to artifacts living in the wrong layer.

The artifact layers

Mon, 01 Jan 0001 00:00:00 +0000

Agents keep nothing between sessions; every context window starts near zero. Some written knowledge layer is therefore necessary. At the same time, writing everything down and keeping it all current fails on cost, because a document pile grows until nobody can afford the upkeep, and then it decays all at once. Aigile handles this tension by splitting all project documents into three layers, each with its own maintenance rules.

Glossary

Mon, 01 Jan 0001 00:00:00 +0000

Every term of the method, one sentence each, grouped by kind. For terms that also appear in the working paper’s glossary, the working paper remains canonical; this file adds the terms introduced after it (standards and domain files, intent weights, the readiness gate, the slicing vocabulary, findings) and is the complete current register.

Written artifacts

Full treatments: the artifact layers, the constitution, the working loop, and the practitioner guide for complete examples of each artifact.

Aigile with OpenSpec

Mon, 01 Jan 0001 00:00:00 +0000

The aigile kit referenced below is on the downloads page and at the kit repository; <kit-path> means your local clone of it.

OpenSpec has no plugin API, so this adapter is a composition: you keep OpenSpec’s delta-spec workflow (propose, apply, archive) and add the aigile layers on top. This tutorial shows the combined setup and one feature through it, using the same Taggr tagging example as the other tutorials. It assumes OpenSpec is already installed and initialized in your project per its own documentation; everything here is the aigile layer.

Downloads

Mon, 01 Jan 0001 00:00:00 +0000

All content on this site is published as plain markdown, with the working paper additionally available as PDF. The files may be read, forked, and supplied to agents as working context.

Start here

The working paper (PDF) or markdown: the whole method in one document.
The practitioner guide: one feature carried through the complete loop, twice (a collaborative team and an agentic one), with copy-able artifact templates.
The reading guide: which deep dive covers what.
The glossary: every term of the method in one sentence.

The deep dives, by topic

Why feedback beats upfront specs (01, the backward edge)
Organizing project documents (02, the artifact layers)
Project rules that can change safely (03, the constitution)
Making review affordable (04, review economics)
When specs and code disagree (05, deviation and drift)
Keeping humans in charge of what matters (06, validation)
How much agents may do on their own (07, the authority matrix)
Learning that lasts (08, retrospectives and gardening)
Slicing the work (09, the craft of slicing)

Everything at once

aigile-complete-bundle.zip: all documents in one folder structure, suitable for a repository. Inside the bundle the papers keep their canonical numbered names (01-the-backward-edge.md and so on), because the kit and the papers cross-reference them that way.

Figures

The framework figures are available as SVG for reuse: the loop, the authority matrix, the artifact layers.

Project rules that can change safely

Mon, 01 Jan 0001 00:00:00 +0000

Series: Aigile deep dives, paper 03 of 09. Elaborates working paper Section 7. Depends on Paper 02.

Abstract

The constitution is the anchor artifact of the durable layer: the smallest written statement of a project’s binding intent. Because every agent reads it in every session, it has the widest blast radius of any artifact in the system; an error in it is not a mistake but a broadcast. This paper specifies its content model, its amendment process, its semantic versioning, the increment-stamping mechanism that makes it auditable, and its rollback semantics. The governing design principle: law-like process, Git-native mechanics. The constitution must be deliberately hard to change and deliberately possible to change, and must never silently drift or silently freeze.

The constitution

Mon, 01 Jan 0001 00:00:00 +0000

The constitution is a one-page statement of the project’s binding rules. Because every agent reads it at the start of every session, a wrong sentence in it affects all ongoing work at once, and for that reason this document gets stronger governance than any other artifact in the project.

What goes in

A single test decides admission: would violating this statement justify stopping work? If not, the statement is a preference rather than a rule, and it belongs somewhere else. Here are a few clauses from an order system’s constitution:

Deviation and drift

Mon, 01 Jan 0001 00:00:00 +0000

Specifications and systems drift apart over time. People and agents discover mid-build that a spec is wrong, hotfixes slip in outside the loop, and assumptions quietly go stale. Aigile treats all of this as a normal part of the work. Experience with earlier methods suggests that teams which treat drift as shameful end up with hidden drift instead of less of it, so the goal here is fast detection and repair rather than a spotless record.

Making review affordable

Mon, 01 Jan 0001 00:00:00 +0000

Series: Aigile deep dives, paper 04 of 09. Elaborates working paper Sections 5 and 8. Depends on Paper 02.

Abstract

When generation is nearly free, verification is the constraint, and any methodology that treats review failure as a discipline problem will fail with disciplined people. This paper develops aigile’s structural answer: review economics over review discipline. It specifies the four mechanisms that reprice review (executable acceptance criteria, diff-based review, the atomic PR, and the increment sizing rule), derives the sizing rule’s three-way alignment of human attention, agent context, and blast radius, and defines the day-to-day working loop these mechanisms compose into. The claim throughout is economic: people review what is cheap to review and skip what is expensive, and the methodology’s job is to move the important checks into the cheap category.

The validation architecture

Mon, 01 Jan 0001 00:00:00 +0000

It helps to keep two questions apart. Verification asks whether the system was built as specified, and it has something to check against: the tests, the spec, the constitution. Agents handle it increasingly well. Validation asks whether the specified system is the right one, and the only reference for that question is human intent itself, including the parts nobody has put into words yet. Those parts tend to surface when a person uses the running software, and for that reason validation stays with humans in this method, at every level of automation. The limit comes from the structure of the question, so it does not shrink as models improve.

When specs and code disagree

Mon, 01 Jan 0001 00:00:00 +0000

Series: Aigile deep dives, paper 05 of 09. Elaborates working paper Sections 9 and 10. Depends on Papers 02, 03, 04.

Abstract

Specifications are maps; code and tests are territory. This paper specifies the two protocols that keep them aligned: the deviation protocol, which governs the moment an implementer (human or agent) discovers mid-work that the map is wrong, and the drift-management pipeline, which governs divergence discovered late. Both rest on one observable classification boundary and one philosophical commitment: drift is thermodynamics, not sin, and methodologies that treat it as shameful get hidden drift instead of managed drift. The target variable is drift half-life, the time from divergence to resolution, not drift count.

Keeping humans in charge of what matters

Mon, 01 Jan 0001 00:00:00 +0000

Series: Aigile deep dives, paper 06 of 09. Elaborates working paper Sections 12 and 14. Depends on Paper 04.

Abstract

Verification asks whether the thing was built right; validation asks whether the right thing was built. This paper develops aigile’s claim that validation is structurally human at every level of automation, specifies the three-trigger demo architecture (skeleton, feature, risk-pulled) that spends human attention proportionally to risk rather than volume, defines the demo verdict as a routed artifact rather than a feeling, and states the brains-eyes-hands rule that keeps validation unmediated. It then closes the framework’s largest loop: at full autonomy, the retrospective becomes a recursive self-improvement circle, and that circle is a Goodhart machine unless its fitness function is injected from outside. The human demo verdict is that injection. The demo and the self-improvement circle are one design, adopted together or not at all.

The authority matrix

Mon, 01 Jan 0001 00:00:00 +0000

Discussions of agentic development often assume two separate modes: a collaborative one, where humans take part in every check, and a fully agentic one, where agents run the delivery. Aigile describes both with one structure. A close look at the fully agentic end shows that humans still own the intent there as well; what differs between the two is who performs each kind of check. That is a setting per checking layer rather than one big switch, and the figure below shows the layers with typical positions for both setups.

How much agents may do on their own

Mon, 01 Jan 0001 00:00:00 +0000

Series: Aigile deep dives, paper 07 of 09. Elaborates working paper Section 13. Depends on Papers 03 and 06.

Abstract

Aigile spans the spectrum from human-AI pair collaboration to fully agentic delivery without forking into two methodologies. This paper specifies the mechanism: authority over verification is assigned per layer in a matrix, not per project in a mode switch; autonomy moves rightward through the matrix on evidence and moves back on incident, in the manner of graduated licensing; and one row never moves. It then develops the structural hazard specific to the right side of the matrix, correlated verification failure, and the independence requirements that mitigate it. The framing sentence for the whole paper: humans always own the why; the dial only ever moves who owns the check.

Learning that lasts

Mon, 01 Jan 0001 00:00:00 +0000

Series: Aigile deep dives, paper 08 of 09. Elaborates working paper Sections 5.3 and 11. Depends on Papers 02 and 05.

Abstract

The retrospective is aigile’s learning organ, and it differs from its classic ancestor in three ways. First, its outputs must land in artifacts, because half its participants have no memory: routing learnings to the correct layer is the entire trick. Second, it produces a category of learning that human teams never had to write down, collaboration knowledge, which must compound in the durable layer or evaporate daily. Third, it carries a maintenance duty its ancestor lacked: the gardening rule, under which the document layer is refactored with the seriousness of code, because it is load-bearing. Woven through all three is the comprehension budget: the deliberate expenditure that keeps human mental models accurate in a system humans no longer implement, without which the feedback quality every other paper depends on silently decays.

Slicing the work

Mon, 01 Jan 0001 00:00:00 +0000

Series: Aigile deep dives, paper 09 of 09. Elaborates working paper Section 8 step 2 and the sizing rule of Paper 04. Depends on Papers 04, 05, 06.

Abstract

Slicing is the step that sets the clock speed of the entire loop. Every downstream protocol inherits its properties from slice shape: review honesty depends on slice size (Paper 04), agent coherence depends on slice fitting one session, validation cadence depends on every slice being demoable (Paper 06), and the blast radius of a wrong decision is bounded by one slice (Paper 05). A methodology can state all of those protocols correctly and still fail in practice if teams slice by layer, by component, or by convenience, because each of those shapes silently disables a downstream protocol. This paper treats slicing as a craft with teachable rules: the unit of slicing (the user question answered), the two-sided binary sizing test, ordering by discovery value, the embedded-infrastructure rule, a catalog of split patterns, and the calibration loop that keeps the sizing parameters honest as agents and teams change. It contributes rules R33 through R36 and a full worked slicing session.