ProductSpec Agent Skill

Product Specs are the product contract for consequential software work.

When a repo uses Agent Run files, treat them as the receipt for one agent execution against a pinned Product Spec revision.

Before planning, coding, testing, or changing scope, look for relevant

.product-spec.md

files in the repository. Common locations include:

```
specs/
```
```
product-specs/
```
```
docs/product-specs/
```
paths named in the task, issue, pull request, or engineering spec

If a relevant Product Spec exists, read it before acting.

How To Use A Product Spec

Read these sections in order:

```
Problem
```
: who is hurting and why the work matters.
```
Hypothesis
```
: the causal bet behind the product.
```
Product Summary
```
: what should exist when the work is done.
```
Scope
```
: what is in, out, and deliberately cut.
```
Acceptance Criteria
```
: the build contract, including AI evals when present.
```
Success Metrics
```
: post-launch outcome checks.
```
Related Artifacts
```
: issues, pull requests, eval runs, dashboards, designs, engineering specs, or other Product Specs the work depends on.

Acceptance Criteria are the build contract. Plans, tasks, code changes, tests, and pull request summaries should cite the relevant

AC-<number>

IDs.

AI evals are pre-launch gates inside Acceptance Criteria, not a separate

## AI Evals

section. Cite

EVAL-<number>

when implementing or changing model behavior.

Success Metrics are post-launch outcomes. Do not treat

SM-<number>

items as implementation tasks.

Planning Rules

When creating an implementation plan:

List which Product Spec and
```
spec_revision
```
you are implementing.
If ProductSpec MCP is available, call
```
begin_spec_session
```
before planning and include the returned
```
spec_revision
```
and session id in your plan.
Map each task to the relevant Acceptance Criteria.
Name any Acceptance Criteria that are not covered by the plan.
Treat
```
scope.out
```
and
```
scope.cut
```
as explicit non-goals.
Use
```
applies_to
```
and
```
Related Artifacts
```
to find relevant code, issues, pull requests, designs, evals, and dashboards.
Resolve
```
product_spec
```
related artifacts before planning. A spec whose
```
depends_on
```
target is not built yet is blocked, not buildable, and the plan should say what it waits for.
For a folder of specs, run
```
productspec graph <dir> --json
```
(or the
```
get_spec_graph
```
MCP tool) to get the buildable set, the blocked set with what each spec waits for, and a dependency-respecting build order in one call, instead of re-reading every spec to derive it.
For a repo with Product Specs, Agent Runs, Decision Traces, and evidence links, run
```
productspec garden <repo> --json
```
before selecting work. Use it to find missing evidence, stale revision pins, run gaps, Decision Trace gaps, unscoped specs, contention, and waves.
If another agent may be working the same folder, read
```
contention
```
and
```
waves
```
from that same call. Two specs that touch one surface must not be built at the same time, even when both are buildable. Take work from the current wave, and treat a spec listed in
```
unscoped
```
as unknown scope rather than safe scope.
Treat
```
RESOLVE-IN-PLAN:
```
markers as unresolved technical bindings. Resolve each marker against the codebase with a source citation before coding.
Do not implement guessed table names, fields, endpoints, services, or file paths as if they were binding instructions.

Change Rules

Do not silently change product intent.

If implementation pressure conflicts with the Product Spec, state the conflict and propose one of:

update the Product Spec
update the implementation
accept a tradeoff and record a Decision Trace
reopen the work

If behavior changes after implementation, propose a Product Spec revision or a Decision Trace entry instead of treating code drift as intent.

Output Rules

When reporting progress or opening a pull request:

If ProductSpec MCP is available, call
```
check_spec_session
```
first. If the Product Spec changed, re-read it and re-plan before claiming done.
If ProductSpec MCP is available, call
```
get_evidence_checklist
```
and attach or name evidence for covered
```
AC-
```
and
```
EVAL-
```
IDs.
If the repo uses Agent Run files, call
```
draft_agent_run
```
or run
```
productspec init-run <spec> <agent-run>
```
to create a receipt, then fill in checked
```
AC-
```
,
```
EVAL-
```
, and
```
SM-
```
IDs, evidence links, drift state, and completion claim. Validate it with
```
productspec validate-run
```
.
Before claiming completion, run
```
productspec reconcile <spec> --against <agent-run>
```
when a local CLI is available. Fix missing checked items, failed items, stale spec revisions, passed items without evidence, or drift without Decision Trace before saying the work is done.
cite the Product Spec path and
```
spec_revision
```
cite the Acceptance Criteria covered
cite AI evals added or changed
name scope items intentionally deferred
link related issues, pull requests, eval runs, or dashboards when available

productspec

NPX Install

Tags

SKILL.md Content

ProductSpec Agent Skill

How To Use A Product Spec

Planning Rules

Change Rules

Output Rules