Goal-Driven Agents

Goal-Driven Agents

Goal-driven agents use an iterative refinement loop where success is verified through observables, not assumed from execution. Instead of "do X then Y," agents verify "X is done" before proceeding.

Note: The dedicated MCP iteration tools (iteration_start, iteration_validate, iteration_next, iteration_complete) have been removed. Agents now self-manage their iteration loops using standard tooling (run tests via Bash, check results, iterate). The goal-driven philosophy remains the same -- only the mechanism has changed.

Overview

Traditional agents execute procedural workflows: "Read file, make changes, write file." Goal-driven agents verify outcomes: "Verify tests pass, verify code compiles, verify acceptance criteria met."

Architecture

Agent receives task
        │
        ▼
┌──────────────────────┐
│ Define success        │ ← Success criteria from task
│ criteria              │
│ - maxIterations: N   │
│ - validation checks  │
└──────────────────────┘
        │
        ▼
    ┌───────────────────────────┐
    │   Make changes / work     │
    └───────────────────────────┘
        │
        ▼
┌──────────────────────┐
│ Validate via Bash     │ ← Check observables
│ - Run tests          │
│ - Check compiles     │
│ - Verify goals       │
└──────────────────────┘
        │
        ├─────────────────┐
        │                 │
        ▼                 ▼
    SUCCESS           NOT YET
        │                 │
        │                 ├──────────────┐
        │                 │              │
        │                 ▼              ▼
        │         maxIterations?    BLOCKED?
        │            reached?           │
        │                 │             │
        │                 │             ▼
        │                 │        Update task
        │                 │        status blocked
        │                 │             │
        │                 ▼             │
        │         Analyze gap           │
        │         Refine approach       │
        │         Try again             │
        │                 │             │
        │                 └─────────────┘
        │                       │
        ▼                       │
┌──────────────────────┐       │
│ Store work product    │ ←─────┘
│ Update task status    │
└──────────────────────┘

Agent Schema

Agents define their iteration approach in their YAML frontmatter:

---
name: me
description: Feature implementation agent
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
---

Agents self-manage iteration loops without dedicated MCP tools. The iteration pattern is documented in the agent's workflow section.

Validation Checks

Common validation checks for different agent types:

Validation checks are executed via Bash commands. Agents can define custom checks based on their domain.

Goal-Driven Workflow

Example: Implementation Agent (me.md)

## Workflow

1. Check task state: `tc task get <id> --json`
2. Use `skill_evaluate({ files, text })` to load relevant skills
3. Read existing code to understand patterns
4. FOR EACH iteration (up to max retries):
   - Make changes to code
   - Run tests via Bash
   - IF all tests pass AND lint clean: BREAK (success)
   - IF blocked by external dependency: Update task status, BREAK
   - ELSE: Analyze failure, refine approach
5. Store work product: `tc wp store --task <id> --type implementation --title "..." --content "..." --json`
6. Update task: `tc task update <id> --status completed --json`

Example: Test-Driven Development

Agent: me
Task: Add authentication middleware

Iteration 1:
- Write initial middleware code
- Run tests via Bash -> 4 failures
- Analyze test failures

Iteration 2:
- Fix token validation logic
- Run tests via Bash -> 2 failures, compiles OK
- Fix edge cases

Iteration 3:
- Handle expired tokens
- Run tests via Bash -> all pass, compiles OK, lint clean
- Store work product: tc wp store --task <id> ...
- Update task: tc task update <id> --status completed --json

Practical Examples

Example 1: Implementation with TDD

## Task: Implement User Login Endpoint

### Iteration Loop

**Iteration 1:**
- Write login endpoint skeleton
- Add basic JWT generation
- Run tests: ❌ 5/12 passing
- **Validation:** `tests_pass: false`
- **Next:** Fix password validation

**Iteration 2:**
- Implement bcrypt password check
- Run tests: ❌ 8/12 passing
- **Validation:** `tests_pass: false`
- **Next:** Handle invalid credentials

**Iteration 3:**
- Add error handling for invalid credentials
- Run tests: ❌ 10/12 passing
- **Validation:** `tests_pass: false`
- **Next:** Fix token expiry edge case

**Iteration 4:**
- Implement token refresh logic
- Run tests: ✅ 12/12 passing
- **Validation:** `tests_pass: true`, `compiles: true`, `lint_clean: true`
- **Complete:** All criteria met

**Result:** Success in 4 iterations

Example 2: Architecture Planning

## Task: Design Multi-Tenant Architecture

### Iteration Loop

**Iteration 1:**
- Design initial schema with tenant isolation
- Create PRD and task breakdown
- **Validation:** Conflict detected in database migrations (checked via `git diff`)
- **Next:** Resolve conflict with Stream-B

**Iteration 2:**
- Adjust migration strategy to avoid conflict
- Recreate tasks with updated dependencies via `tc task create ...`
- **Validation:** No conflicts (checked via `git diff`), tasks created
- **Complete:** All criteria met

**Result:** Success in 2 iterations

Example 3: Blocked State

## Task: Fix Authentication Bug

### Iteration Loop

**Iteration 1:**
- Identify root cause: third-party API change
- Attempt workaround with updated API calls
- Run tests: ❌ Still failing with same error
- **Validation:** `tests_pass: false`
- **Next:** Try alternative approach

**Iteration 2:**
- Implement fallback authentication method
- Run tests: ❌ New error: "API key invalid"
- **Validation:** Agent detects external dependency failure
- **Emit:** `<promise>BLOCKED</promise>`
- **Complete:** Outcome = "blocked"

**Result:** Blocked - requires API key update from external team

Success Criteria Format

Transformation: Procedural → Goal-Driven

Before (Procedural):

## Workflow

1. Read the existing code
2. Make the necessary changes
3. Write the updated code
4. Run the tests
5. Fix any errors

After (Goal-Driven):

## Success Criteria

- [ ] Code compiles without errors
- [ ] All existing tests pass
- [ ] New tests cover added functionality
- [ ] Lint checks pass
- [ ] Code follows existing patterns

## Iteration Loop

1. FOR EACH iteration (up to max retries):
   - Make changes
   - Run validation checks via Bash (tests, compile, lint)
   - IF success: store work product via `tc wp store ...`, update task via `tc task update <id> --status completed --json`
   - IF blocked: update task via `tc task update <id> --status blocked --json`
   - ELSE: analyze failure, refine approach

Agent Instruction Patterns

Replace "Do X" with "Verify X":

Max Iteration Handling

When the maximum number of attempts is reached without success:

1. Store work product with detailed analysis via tc wp store --task <id> ...:

   ## Iteration Limit Reached
   
   Attempted 15 iterations without achieving success criteria.
   
   ### What Was Tried
   - Iteration 1-5: Initial implementation approach
   - Iteration 6-10: Alternative error handling strategy
   - Iteration 11-15: Edge case fixes
   
   ### Remaining Issues
   - Test failure: "Token validation timing issue"
   - Likely cause: Race condition in async token refresh
   
   ### Recommended Next Steps
   - Review token refresh timing logic
   - Add synchronization mechanism
   - Consider involving @agent-sec for security review
   

2. Update task status to "blocked" with human-readable summary: tc task update <id> --status blocked --json

BLOCKED Signal Usage

Agents should emit <promise>BLOCKED</promise> when:

When blocked:

1. Store work product explaining blocker: tc wp store --task <id> --type other --title "Blocked: ..." --content "..." --json
2. Update task with blocker details: tc task update <id> --status blocked --json

Configuration

Agent-Level Defaults

Agents define their iteration approach directly in their workflow instructions. The max retry count and validation checks are documented as part of the agent's markdown file.

Task-Level Context

Task metadata provides context for the agent's iteration decisions:

# Agent retrieves task details to understand scope
tc task get TASK-xxx --json
# Returns metadata including complexity, files, acceptance criteria

Project-Level Configuration

Quality gates in .claude/quality-gates.json define project-level validation checks that run on task completion.

Best Practices

1. Start with Clear Success Criteria

Good:

validationRules: [
  "tests_pass",           // All tests pass
  "compiles",             // No compilation errors
  "lint_clean",           // No lint warnings
  "coverage_threshold"    // >80% code coverage
]

Avoid:

validationRules: [
  "looks_good",  // Too vague
  "done"         // Not verifiable
]

2. Keep Iterations Small

Each iteration should make incremental progress:

• Fix one test failure
• Resolve one lint error
• Add one missing feature

Avoid trying to fix everything in one iteration.

3. Analyze Failures Between Iterations

Between iterations, agents should:

• Review validation failure messages from test/compile output
• Identify patterns in errors
• Adjust approach based on feedback
• Document what was learned

4. Set Realistic maxIterations

5. Store Iteration History

In work products, include:

## Iteration History

- **Iteration 1:** Initial implementation → 4 test failures
- **Iteration 2:** Fixed validation logic → 2 test failures
- **Iteration 3:** Added edge case handling → All tests pass ✅

Metrics and Observability

Iteration data can be used for:

Future: Dashboard showing iteration statistics across all tasks.

Comparison with Traditional Agents

Migration Guide

Adapting Existing Agents

Step 1: Update agent tools

Remove iteration MCP tools from the tools list. Agents use standard tools (Read, Write, Edit, Bash, Grep, Glob) plus tc CLI commands.

Step 2: Transform workflow to success criteria

Change from procedural steps to verifiable outcomes:

- 1. Read files
- 2. Make changes
- 3. Write files
+ 1. Verify code compiles (run compiler via Bash)
+ 2. Verify tests pass (run test suite via Bash)
+ 3. Verify meets acceptance criteria

Step 3: Add self-managed iteration loop

## Workflow

1. tc task get <id> --json
2. FOR EACH attempt (up to max retries):
   - Do work
   - Run validation checks via Bash
   - IF all pass: store work product, update task, BREAK
   - IF blocked: update task status to blocked, BREAK
   - ELSE: analyze failure, refine approach
3. tc wp store --task <id> --type <t> --title "..." --content "..." --json
4. tc task update <id> --status completed --json

Step 4: Test with real tasks

Run agent on actual tasks and verify:

• Iterations converge to success
• Blocked states are detected
• Max retries prevent infinite loops

Related Documentation

• Agent Development Guide
• Task Management (tc CLI)
• Lifecycle Hooks
• Testing Patterns