# estimate

Adopt this skill: https://proskills.md/skills/other/kiloloop-agent-estimate-skills-estimate-codex

Page: https://proskills.md/skills/other/kiloloop-agent-estimate-skills-estimate-codex
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/estimate/codex/SKILL.md
size: 4681
sha: 2bc6632bc0e4e63939789e7ddf8435d49b9ca785
upstream: https://github.com/kiloloop/agent-estimate/blob/main/skills/estimate/codex/SKILL.md

````text
---
name: estimate
description: Codex skill for running agent-estimate CLI commands (estimate, validate, calibrate).
---

# estimate (Codex)

Use this skill when a user asks to estimate AI-agent effort, compare agent time
with human time, validate an estimate against observed work, or recalibrate
local model factors.

The skill is command-first: execute the `agent-estimate` CLI and return its
output. Do not invent computed values.

## Intent Mapping

| User intent | Command |
| --- | --- |
| Estimate one task | `agent-estimate estimate "<task>"` |
| Estimate tasks from a file | `agent-estimate estimate --file <path>` |
| Estimate GitHub issues | `agent-estimate estimate --issues <nums> --repo <owner/name>` |
| Validate estimate vs actuals | `agent-estimate validate <observation.yaml>` |
| Recompute calibration summary | `agent-estimate calibrate` |

## Estimate Inputs

Accept exactly one input source:

- task description argument
- `--file <path>`
- `--issues <nums>` with `--repo <owner/name>`

If the input source is missing or ambiguous, ask for the missing piece.

## Estimate Flags

- `--config <path>` - custom agent fleet config.
- `--format markdown|json` - output format.
- `--review-mode none|standard|complex|3-round` - additive review tier:
  - `none`: +0m
  - `standard`: +15m
  - `complex`: +25m
  - `3-round`: +35m
- `--type coding|brainstorm|research|config|documentation|frontend|app_dev`.
- `--spec-clarity <0.3..1.3>`.
- `--warm-context <0.3..1.15>`.
- `--agent-fit <0.9..1.2>`.
- `--title <text>`.
- `--verbose`.

When `--type` is omitted, the CLI auto-detects the category. Research-grounded
brainstorms with citation, OSS, benchmark, source, or landscape signals route to
the research band instead of the flat brainstorm band.

## Type Guidance

- `coding`: default tiered PERT model for feature work, bug fixes, tests, and refactors.
- `brainstorm`: pure ideation and design exploration.
- `research`: audits, investigations, OSS comparisons, citation/source-grounded work.
- `config`: deploys, infra, CI/CD, runbooks, monitoring, and SRE changes.
- `documentation`: API docs, guides, README changes, changelogs.
- `frontend`: UI/page work. Content patches use 15/25/40; page builds use 40/60/90.
- `app_dev`: app shells and desktop/mobile builds. Uses a cold generic L-style prior; use modifiers for warm or highly specified work.

## Reliability Policy Model Keys

Current provenance-labeled local-policy keys include:

- `fable_5_1`, `opus_5_5`
- `gpt_6_astra`, `gpt_6_1_sol`, `gpt_6_sol`, `gpt_6_luna`
- `sonnet_5_5`
- `haiku_4_5`

Earlier keys such as `opus_4_x`, `opus_4_7`, `opus_4_6`, `opus`,
`sonnet_4_6`, and `gpt_5` through `gpt_5_5` remain accepted.

Warnings compare friction-adjusted work only. The shipped values are local
reliability policy (unmeasured), not published METR horizons. Duration priors
draw on 33 internal coding dispatches and 6 brainstorm dispatches; the report
states that the estimate pipeline applies no SQLite calibration-store feedback.

## Execution Rules

1. Execute commands from the repository root.
2. Prefer the installed `agent-estimate` binary.
3. If the binary is absent, use `python -m agent_estimate.cli.app`.
4. Capture stdout, stderr, and exit code.
5. If the command fails, return the error concisely and include the attempted command.
6. If the command succeeds, return the CLI output directly.
7. Treat `--format json` as a normal success path.

## Examples

```bash
agent-estimate estimate "Add login button with OAuth"
agent-estimate estimate "Audit dependencies for known CVEs" --type research
agent-estimate estimate "Build a landing page" --type frontend
agent-estimate estimate "Build an Electron app shell" --type app_dev --spec-clarity 0.3 --warm-context 0.3
agent-estimate estimate --file tasks.md
agent-estimate estimate --issues 1,2,3 --repo org/name
agent-estimate estimate --review-mode 3-round "Refactor auth module"
agent-estimate validate observation.yaml --db ~/.agent-estimate/calibration.db
agent-estimate calibrate --db ~/.agent-estimate/calibration.db
```

## Observation YAML Example

```yaml
task_type: frontend
estimated_minutes: 60.0
actual_work_minutes: 52.0
actual_total_minutes: 87.0
file_count: 4
line_count: 180
test_count: 3
execution_mode: single
review_mode: 3-round
review_overhead_minutes: 35.0
modifiers:
  spec_clarity: 1.0
  warm_context: 0.9
```

## Notes

- Requires `agent-estimate` installed: `pip install agent-estimate` or
  `pip install -e '.[dev]'` in this repo.
- Default config uses bundled `default_agents.yaml`.
- Estimates are generic priors. User-local `validate` and `calibrate` should tune
  them against local SQLite history over time.
````

## File: README.md
upstream: https://github.com/kiloloop/agent-estimate/blob/main/README.md

````text
# agent-estimate

[![PyPI Version](https://img.shields.io/pypi/v/agent-estimate)](https://pypi.org/project/agent-estimate/)
[![Python Versions](https://img.shields.io/pypi/pyversions/agent-estimate)](https://pypi.org/project/agent-estimate/)
[![License](https://img.shields.io/pypi/l/agent-estimate)](https://github.com/kiloloop/agent-estimate/blob/main/LICENSE)
[![CI](https://github.com/kiloloop/agent-estimate/actions/workflows/ci.yml/badge.svg)](https://github.com/kiloloop/agent-estimate/actions/workflows/ci.yml)

**Know before you build.**

PERT estimates for AI-agent tasks — how long, which model's reliable enough, and the human-equivalent cost. In one command.

**[Website](https://kiloloop.com/agent-estimate/)** · [Compare](https://kiloloop.com/agent-estimate/compare/) · [PyPI](https://pypi.org/project/agent-estimate/)

## Why

AI agents can write the code — but *how long will the task actually take?* Manual estimation is slow and biased toward optimism; no estimate means scope creep and missed deadlines. The gap between "agents can do it" and "we know when it'll be done" is where projects break down.

`agent-estimate` closes that gap in one command: a three-point PERT timeline built from priors drawn from 33 internal coding dispatches and 6 brainstorm dispatches, plus a human-speed comparison so you see the compression before you spend the compute. It sizes the task, picks a tier, routes it to a model, and flags when the work exceeds that model's configured reliability policy — forecasts in seconds, not meetings.

Multi-model matters because the models aren't interchangeable. A measured p80 horizon is the human-expert task duration at which a model is estimated to succeed 80% of the time. The shipped limits below are instead provenance-labeled local policy (unmeasured), because current models such as Opus 5.5 and GPT-6 Astra do not have matching published measurements. agent-estimate models the whole fleet, not a single agent — so the number reflects who actually runs the work.

## Quick Start

> First estimate: 30 seconds to install. Every one after: instant.

### With your agent (recommended)

Paste this into your Claude Code or Codex session:

~~~
Install the agent-estimate plugin (https://github.com/kiloloop/agent-estimate) and
estimate this task for me: "Implement OAuth 2.0 flow (Google + GitHub)". Tell me the
expected time, the human-speed equivalent, and the compression ratio.
~~~

Your agent installs the tool, runs the estimate, and reads back the numbers. Nothing to memorize — describe the task in plain English and let the agent translate to flags.

For a whole backlog:

~~~
Estimate every open issue in this repo with agent-estimate, group them into parallel
waves, and tell me the total wall-clock time for a 2-agent fleet versus doing them
sequentially myself.
~~~

### Manual

```bash
pip install agent-estimate
agent-estimate estimate "your task description here"
```

No config required — sensible defaults for a 2-agent fleet (Claude, Codex). Point it at a file or GitHub issues when you're ready:

```bash
agent-estimate estimate --file tasks.txt
agent-estimate estimate --repo myorg/myrepo --issues 11,12,14
agent-estimate session --agents 3 --rounds 2 --type review
```

### v0.8 forecast contract

The v0.8 source introduces a versioned request for callers that already know the
task and executor. These features are not in the published v0.7.5 package; use an
installation from this checkout until v0.8 is released. Bare task descriptions,
text files, and GitHub issue input remain available.

| Contract | Owns |
|----------|------|
| `TaskSpec` | Task facts, required capabilities, dependencies, and independent scope estimates |
| `ExecutionProfile` | Runtime and model identity, configuration provenance, context, modifiers, and review plan |
| `AdmissionEnvelope` | Declared minute/file caps and optional replayable cap calculations |
| `ForecastRecord` | Expected wall minutes, expected files, additive review minutes, and forecast provenance |

The [typed contracts](src/agent_estimate/contract/schema.py) are frozen, reject
unknown fields and non-finite numbers, and require explicit schema versions.
Model identity must be either a supplied identifier or an `unknown_reason`;
selecting an agent does not establish its serving model. IDs are caller supplied.
The library also exposes `OutcomeObservation` with nullable future actuals slots;
it does not ingest actuals or persist binding receipts.

From the repository root, with the matching package installed, run the complete
checked-in [request example](examples/estimate-request.yaml):

```bash
agent-estimate estimate --spec examples/estimate-request.yaml --format json
```

The JSON includes `"schema_version": "agent-estimate/report/v1"`, assigns
`Add input validation` to `Codex`, and reports `forecast.basis: expected-wall`.
The example's 90-minute admission cap does not determine its expected minutes.
`--spec` emits the versioned report; library callers can construct the separate
`ForecastRecord` with `forecast_from_report` in `agent_estimate.contract.duration`.

`--spec` accepts one full `EstimateRequest` containing `task_spec`,
`execution_profile`, and `admission`, plus an optional `token_prior`. It can be
combined with `--config`, `--format`, `--compact`, and `--title`. Put task facts,
scope, and modifiers in the request; alternate input sources and history flags
cannot be combined with `--spec`. Conflicts and invalid fields exit 2. It does
not read ambient `data.json` history.
The named agent must exist in the selected fleet and satisfy every required
capability. `config_profile` records provenance; `--config` selects the actual
fleet file. This single-task CLI path requires empty `dependency_task_ids` and
`execution_profile.estimate_multiplier: 1.0`; use the configured agent's
`estimate_multiplier` for [profile adjustments](#agent-fleet).

Context identity belongs to `execution_profile.context.context_key`. An explicit
`modifiers.warm_context` takes precedence: pairing it with
`context.implicit_co_dispatch: true` is rejected to prevent double counting.
Review intent is additive: supported plans are no review, one or two standard or
complex rounds, or three standard rounds. Unsupported plans exit 2.

**Expected values and caps.** Reports label duration `expected-wall`, with
`source` and `as_of` provenance (an unknown date stays null). Expected wall minutes
include work and additive review. Score matching actual wall minutes against
independent expected minutes, never `declared_cap_minutes` or a cap divided by
guessed headroom. File expectations likewise come from task scope, not file caps.
The `validate` command uses `actual_total_minutes` for `expected-wall` observations
and `actual_work_minutes` for `expected-work`; cap-only and cap-derived inputs are
rejected. Wall scoring is report-only in the current calibration store. Legacy
`estimated_minutes` means expected work only, and `calibrate --basis expected-work`
is an explicit attestation that every stored estimate is expected work rather
than a cap; inspect the rows before using it. Without that attestation,
`calibrate` exits 2 with guidance on stderr.

**Token honesty.** Typed forecasts default to `tokens.basis: unavailable`, with
null `expected_tokens_total`, `expected_tokens_output` and
`expected_tokens_cache_read`. Total means processed tokens including cache carry;
output and cache-read tokens are separate counts included in total. A
caller-supplied prior uses `basis: local-policy`, a source, date, population,
and a mandatory population mismatch warning. An absent count stays unavailable;
zero is a supplied count. A caller can also pass its own observed tokens per
closed leg with `--token-observations`; the request's task-type × execution-profile
segment then reports `basis: measured` at five or more legs, as a shrunk
log-median that names the segment, its `n` and the observation window. JSON
includes `forecast.tokens` when a prior or obs
````