guided-implementation Overview

The guided-implementation addon provides bounded iteration control for autonomous issue-to-code workflows. It supplies a single skill (`iteration-control`) that manages retry logic and escalation, complementing the `/flow-guided-implementation` command.

The Problem It Solves

Most implementation capabilities already exist in Claude Code: file search (Grep, Glob), task decomposition (TodoWrite), code generation (Edit), code review (code-reviewer agent), and test debugging (debugger agent). What was missing is a component that manages the loop itself — knowing when to retry a failed implementation attempt versus when to escalate to the user.

Without iteration control, an agent facing a failing test either gives up after one attempt (too conservative) or retries indefinitely in ways that produce increasingly divergent code (too aggressive). Iteration control establishes a bounded retry budget with structured escalation when the budget runs out.

What the Addon Provides

Component	Purpose
`iteration-control` skill	Manages bounded retries with structured escalation

Everything else the workflow needs — file operations, code generation, testing, review — is handled by Claude Code's native tools and the existing SDLC agents.

How Iteration Control Works

For each implementation task:

iteration = 0
loop:
  generate_code()
  validate() → result

  if result.pass:
    proceed to next task
  elif result.fail AND iteration < max:
    retry with feedback (iteration += 1)
  elif result.fail AND iteration >= max:
    escalate to user

The skill tracks what was tried in each iteration and includes that history in the escalation message so the user has enough context to make a decision.

Escalation Format

When the retry budget is exhausted, the skill produces a structured escalation:

ESCALATION: Max iterations reached (3/3)

Task: Implement JWT token validation

Attempts:
- Iter 1: Test failed — undefined token variable
- Iter 2: Test failed — token missing userId field  
- Iter 3: Test failed — userId format mismatch (string vs number)

Pattern detected: userId type inconsistency between implementation and test

Question: The implementation uses string, the test expects number.
Which format should userId be?
  A) string (implementation matches this)
  B) number (test expects this)
  C) Show me the relevant type definition

The escalation identifies the pattern across attempts rather than just reporting the last failure. This gives the user actionable context: the problem is a type inconsistency, not just a test failure.

Usage

The skill is invoked by the `/flow-guided-implementation` command:

/flow-guided-implementation Add user authentication with JWT

With a custom retry limit:

/flow-guided-implementation --max-retries 5 Fix the login validation bug

The default retry limit is 3 attempts per task. For complex tasks requiring more exploration, increase it. For simple bugs, 3 is usually sufficient.

Research Foundation

The iteration control design is based on MAGIS (Multi-Agent GitHub Issue Resolution) research, which found that bounded developer-QA iteration loops improve code quality while preventing infinite loops. The key insight is that bounded retries with human escalation outperform both single-attempt implementations and unbounded retry loops.

Reference: `@$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/commands/flow-guided-implementation.md`

References

• `@$AIWG_ROOT/agentic/code/addons/guided-implementation/skills/iteration-control/SKILL.md` — Full skill definition
• `@$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/commands/flow-guided-implementation.md` — The command this skill supports