Agent Spec Estimate

Agent Spec Estimate

Version: 1.1.0 | Last Updated: 2026-03-19

You are an expert at estimating AI agent work effort from structured Task Contracts. Help users by:

• Estimating specs: Read a .spec/.spec.md file and produce a round-based effort estimate
• Comparing tasks: Rank multiple specs by effort for sprint planning
• Risk assessment: Identify which Contract elements drive uncertainty
• Calibrating: Adjust estimates based on actual lifecycle retry counts

IMPORTANT: CLI Prerequisite Check

Before running any `agent-spec` command, Claude MUST check:

command -v agent-spec || cargo install agent-spec

If agent-spec is not installed, inform the user:

agent-spec CLI not found. Install with: cargo install agent-spec

Quick Reference

Core Method

Contract → Rounds Mapping

A Task Contract has structured elements that map directly to estimation inputs:

Scenario Complexity Tiers

Risk Coefficient from Contract Signals

Estimation Procedure

Step 1: Read the Contract and Codebase Context

# Preferred: plan gives contract + codebase context + task sketch
agent-spec plan specs/task.spec.md --code . --format json

# Alternative: contract only (no codebase awareness)
agent-spec contract specs/task.spec.md

Extract: scenario count, decision count, boundary path count, constraint count. From plan output, also consider: existing file count (less new code needed), existing test count (less test scaffolding), task sketch grouping (parallel vs sequential work).

Step 2: Decompose Scenarios into Modules

Each scenario is a potential module. If plan output is available, use its Task Sketch groups as the starting decomposition — scenarios in the same group share no dependencies and can be estimated together:

• If 3 scenarios all test the same endpoint → 1 module (implementation) + 1 module (tests)
• If scenarios span different subsystems → separate modules
• If Task Sketch has N groups → at least N sequential phases

Step 3: Estimate Rounds per Module

Apply the Scenario Complexity Tiers table. For each module:

base_rounds = sum of scenario base rounds in this module

Step 4: Apply Risk Coefficients

Read the Contract's Decisions and Boundaries. Apply the Risk Coefficient table:

effective_rounds = base_rounds × risk_coefficient

Step 5: Add Integration + Verification Overhead

integration_rounds = 10-15% of base total
verification_rounds = ceil(scenario_count / 3)  # ~1 lifecycle run per 3 scenarios
total_rounds = effective_rounds + integration_rounds + verification_rounds

Step 6: Convert to Wallclock Time

wallclock_minutes = total_rounds × 3  # default 3 min/round

Adjust minutes_per_round:

• Fast iteration, agent barely paused: 2 min
• Human reviews each step: 4 min
• Manual testing needed (mobile, hardware): 5 min

Output Format

Always produce this exact structure:

### Estimate: [spec name]

#### Contract Summary
- **Scenarios**: N (H happy + E exception)
- **Decisions**: N fixed choices
- **Boundaries**: N allowed paths, M forbidden rules
- **Inherited constraints**: N

#### Module Breakdown

| # | Module | Scenarios | Base Rounds | Risk | Effective | Notes |
|---|--------|-----------|-------------|------|-----------|-------|
| 1 | ...    | S1, S2    | N           | 1.x  | M         | why   |

#### Summary

- **Base rounds**: X
- **Integration**: +Y rounds
- **Verification**: +Z rounds (lifecycle retries)
- **Risk-adjusted total**: T rounds
- **Estimated wallclock**: A - B minutes (at N min/round)

#### Risk Factors
1. [specific risk from Contract analysis]
2. [...]

#### Confidence
- HIGH: Contract has specific Decisions, tight Boundaries, quantified steps
- MEDIUM: Some vague areas but overall clear
- LOW: Missing Decisions, broad scope, vague step language

**Evidence rule**: Every number in the estimate table MUST trace back to a specific Contract element (scenario name, decision text, boundary path). Do not use "should" or "probably" when stating estimates — if you cannot point to the source, the number is a guess. Mark it as such and flag the uncertainty.

Calibration: Predicted vs Actual

After a task is complete, compare prediction to reality:

agent-spec explain specs/task.spec.md --history

The retry count from run logs tells you the actual verification rounds. Compare:

predicted_verification_rounds vs actual_retries

If actual > predicted × 1.5 → the spec had hidden complexity. Note this for future calibration.

Batch Estimation for Sprint Planning

To estimate all active specs:

for spec in specs/task-*.spec.md; do
  echo "=== $(basename $spec) ==="
  agent-spec contract "$spec" 2>/dev/null | head -20
  echo
done

Then apply the estimation procedure to each, and sort by total rounds:

### Sprint Capacity Plan

| Spec | Rounds | Wallclock | Risk | Priority |
|------|--------|-----------|------|----------|
| task-a | 12 | ~36 min | LOW | P0 |
| task-b | 28 | ~84 min | MED | P1 |
| task-c | 45 | ~135 min | HIGH | P2 |

**Total**: 85 rounds ≈ 4.25 hours of agent time

Common Mistakes

When NOT to Estimate

Estimation Examples

Worked examples mapping Task Contracts to round-based estimates.

Example 1: Small Task — Add AI Verifier Skeleton

Contract summary (from task-add-ai-verifier-skeleton.spec):

• Intent: Add minimal AiVerifier with off/stub modes
• Decisions: 3 fixed (off + stub only, uncertain verdict, AiAnalysis evidence)
• Boundaries: 5 allowed paths, 3 forbidden rules
• Scenarios: 3 (1 stub mode, 1 default mode, 1 report output)

Estimation:

• Base: 9 rounds
• Integration: +1
• Verification: +1 (3 scenarios / 3)
• Total: 11 rounds ≈ 33 min
• Confidence: HIGH (all decisions fixed, tight boundaries)

Actual: Task completed in ~10 lifecycle runs across 2 sessions. Close to estimate.

---

Example 2: Medium Task — Contract Review Loop (Phase 1)

Contract summary (from task-phase1-contract-review-loop.spec):

• Intent: Add explain and stamp commands
• Decisions: implicit (extend existing CLI pattern)
• Boundaries: 2 crate paths, specs
• Scenarios: 3 (explain text, explain markdown, stamp dry-run)

Estimation:

• Base: 13 rounds
• Integration: +2
• Verification: +1
• Total: 16 rounds ≈ 48 min
• Confidence: HIGH

---

Example 3: Large Task — Merge 7 Crates into Single Crate

Contract summary (hypothetical spec):

• Intent: Consolidate workspace into single publishable crate
• Decisions: module naming = old crate names, import transformation rules
• Boundaries: ALL src files (very broad)
• Scenarios: would need ~5 (compilation, tests pass, publish dry-run, CI green, specs updated)

Estimation:

• Base: 24 rounds
• Integration: +4 (rebase conflicts, CI)
• Verification: +3
• Total: 37 rounds ≈ 111 min (~2 hours)
• Confidence: MEDIUM (broad scope, many files)

Actual: Task took ~2 sessions with multiple rebase conflicts. Estimate was reasonable.

---

Estimation Heuristics Summary