Sprint Contracts and Incremental Progress

Sprint Contracts and Incremental Progress

The ‘One-Shot’ Trap: Why Agents Fail at Big Tasks

If you ask an autonomous AI agent to ‘build a full-stack e-commerce application,’ it will almost certainly try to do exactly that—all at once. This phenomenon is known as the ‘One-Shot Trap.’ The agent attempts to simultaneously generate the database schema, the frontend React components, the backend API, and the CSS styling within a single, massive output stream. The inevitable result? A messy, hallucinated, half-finished codebase that refuses to compile.

Think of it like hiring a human contractor to build a house. If they tried to pour the concrete foundation, wire the electricity, and paint the walls at the exact same time, the project would end in disaster. To build robust, long-running applications, your harness must force your AI agents to slow down, break the work into manageable pieces, and progress incrementally.

Introducing Sprint Contracts

To artificially constrain an agent’s ambition, we use a technique called the ‘Sprint Contract.’ Before a single line of functional code is written, the harness demands a formal, structured agreement detailing exactly what small, atomic piece of the application will be built next.

This contract serves as a binding agreement between the Generator (the agent writing the code) and the Evaluator (the agent reviewing the work). A solid Sprint Contract is built on three main pillars:

• Strict Scope Limit: A tightly bounded description of the feature (e.g., ‘Create the user login UI component ONLY, without hooking up the backend authentication API’).
• Concrete Acceptance Criteria: A bulleted list of boolean conditions that must be true for the feature to be considered complete.
• Verification Plan: The exact terminal commands or automated tests that the Evaluator will run to mechanically prove the code works as expected.

The Negotiation Phase

The true magic of the Sprint Contract lies in the negotiation phase. In a well-designed Multi-Agent Architecture, the Planner or Generator drafts the initial contract. However, it cannot proceed to execution until the Evaluator agent explicitly approves it. If the Evaluator determines that the scope is too broad or the acceptance criteria are too vague, it pushes back and demands revisions.

Here is an example of what that contract structure might look like under the hood, formatted as JSON, which the agents use to negotiate:

{
  "sprint_id": "spr_004",
  "focus": "Implement Email Validation Utility",
  "scope": {
    "included":[
      "Regex validation for standard email formats",
      "Unit tests for validation logic"
    ],
    "excluded":[
      "Database integration",
      "Frontend UI components"
    ]
  },
  "acceptance_criteria":[
    "Function isValidEmail(email) returns true for valid emails.",
    "Function isValidEmail(email) returns false for missing '@' or top-level domain."
  ],
  "verification_command": "npm test src/utils/email.test.js"
}

Orchestrating the Incremental Loop

Once the contract is locked in, the harness orchestrates a strict, repetitive loop. This loop ensures the agent stays laser-focused on the current contract and does not wander off to build unapproved, out-of-scope features.

Phase	Action	Responsible Agent
1. Proposal	Drafts the scope and criteria for the next small task.	Generator
2. Review	Approves or rejects the contract based on complexity and clarity.	Evaluator
3. Execution	Writes code to satisfy ONLY the current active contract.	Generator
4. Verification	Runs the agreed-upon tests to ensure total compliance.	Evaluator

Rigorous End-to-End Self-Verification

The final piece of the puzzle is self-verification. An agent should never be allowed to arbitrarily declare, ‘I am done!’ Instead, the harness must mechanically execute the verification commands agreed upon in the Sprint Contract.

If the tests fail, the harness intercepts the error logs and feeds them directly back to the Generator, forcing a retry. The feature is only marked as ‘done’ when the Evaluator receives passing test signals and validates that all acceptance criteria are met. This programmatic boundary actively prevents the AI from hallucinating success.

Here is a Python pseudo-code example demonstrating how your AI Harness might enforce this incremental verification loop:

# Python pseudo-code for enforcing a Sprint Contract in the Harness

def execute_sprint(generator, evaluator, sprint_contract):
    max_retries = 3
    attempt = 0

    while attempt < max_retries:
        # 1. Generator writes the code based strictly on scope
        code_diff = generator.implement(sprint_contract.scope)
        apply_to_workspace(code_diff)

        # 2. Harness mechanically runs the agreed verification command
        test_results = run_command(sprint_contract.verification_command)

        # 3. Evaluator checks the results against acceptance criteria
        evaluation = evaluator.review(sprint_contract, test_results)

        if evaluation.is_approved:
            print(f"Sprint {sprint_contract.sprint_id} completed successfully!")
            return True
        else:
            # Feed the exact failure reasons (logs) back to the generator
            generator.add_context(evaluation.failure_feedback)
            attempt += 1

    raise Exception("Sprint failed to meet contract criteria after maximum retries.")

By wrapping your agents in this strict, contract-driven harness, you completely eliminate the ‘One-Shot Trap.’ You transform them from erratic speed-coders into disciplined, methodical engineers capable of building massive systems—one reliable, fully-verified block at a time.