Skip to main contentSkip to footer
For agents · Pro / Teams

The PM Agent

Call spec.validate to get a Blueprint Readiness Score (0–100, grade A–F) on a written specification before anyone builds from it. The PM Agent reviews your proposal, requirements doc, or OpenSpec-style change bundle against the 8 laws of the Spec Quality Blueprint, returns a per-law verdict with cited evidence and a fix, and grades it on the same severity-weighted scorer the other two lenses use. Pro and Teams plans only.

See pricingTrust and data handling

Pro and Teams members. The PM Agent is the Blueprint's what-to-build review lens, the PM seat of the validator trio, applied before code exists: architect.validate scores built agentic architecture, design.validate scores the rendered surface, spec.validate scores the written intent the team will build from. It reads the full spec text verbatim under a strict no-training policy, treats any instruction-shaped text inside the document as inert untrusted data, and supports private_session=true to skip the stored run (operational security and cost logs are kept per the Privacy Policy). Source code and UI artefacts are marked not_applicable, not failed. Submit the actual specification.

What you get back

Every run returns four things, in the same ValidationResponse shape the other two lenses use:

  1. spec_classification

    spec_document or non_spec, source code and UI artefacts are marked not_applicable rather than failed, so submitting a code file never produces a fake spec grade; the response points you to architect.validate or design.validate instead.

  2. per-law findings

    A verdict for each of the eight laws with severity_score (0–100), severity_class, evidence cited from your actual text, and one specific recommendation.

  3. readiness

    Score, grade, and tier from the same severity-weighted scorer the architecture and surface lenses use, so all three grade on one rubric. The grade penalises only production_blocker findings: a high grade means the spec floors hold, not that the document is exhaustive.

  4. spec dimension

    Runs persist to your validation-history dashboard tagged as the spec dimension, next to your architecture and surface runs on the same project when you pass a repository.

The eight laws it scores against

The rubric is the Spec Quality Blueprint: eight laws of buildable intent, each scored with the same verdict vocabulary the other lenses use.

  • S1 · State the right problem as an outcome

    Name who is stuck and the observable change that proves the problem is solved, before naming any mechanism.

  • S2 · Scope one bounded change

    One coherent change with a named boundary and an explicit out-of-scope list.

  • S3 · Make every requirement testably acceptable

    Every requirement carries an observable acceptance signal someone can check. A load-bearing requirement without one is a production_blocker.

  • S4 · Record the decision trail

    Alternatives considered, why they lost, and open questions with owners: the reasoning survives the author.

  • S5 · Complete the handoff

    Every seam the work touches has its contract named: event shapes, states, identifiers. If the engineer or designer must ask, the spec is not done.

  • S6 · Cite the doctrine upfront

    The principles and constraints the work must honour are named in the spec, not discovered in review.

  • S7 · Keep decomposition traceable

    Tasks trace back to requirements, so nothing ships that no requirement asked for.

  • S8 · Name risk and reversibility

    State-changing and user-visible steps name their rollback path and their human gate. An irreversible step with no named gate is a production_blocker.

Testability is the floor

When two laws conflict, the order is fixed: testable acceptance beats completeness, scope discipline beats ambition, and handoff completeness beats author convenience. The validator does not average a floor breach into a friendly number. A load-bearing requirement with no observable acceptance signal, or an irreversible step with no named human gate, is a production_blocker that caps the grade, exactly as a failed trust boundary does on the architecture lens.

How to call it

Send the full spec text verbatim as implementation_context; for an OpenSpec change, concatenate proposal.md, design.md, tasks.md, and the delta specs. No truncation and no placeholder ellipses (they are read as literal content). Pass the same repository value across calls to group rounds under the spec dimension of one project. spec.validate is sync-only and single-pass in v1 (no certification or consensus mode yet; those stay architect.validate-only). If the call times out client-side, do not retry, the run persists server-side; recover it via me.validation_history(run_id=...) using the run_id from the first progress event. One honest calibration note: the v1 scoring prompt mirrors the architect's contract structure but is not yet tuned against a corpus of real runs the way architect.validate was, so treat the grade as a directional quality signal, not a certified verdict.

Sample

Sample spec review

What you see after every spec.validate run on a written specification. One document, eight laws, one readiness grade, before anyone builds from it.

Blueprint Readiness Score

acme/checkout-service

C
66/ 100emerging5 of 8 laws aligned

Production blocker

S3 · Make every requirement testably acceptable

Requirement 4, “exports should be fast”, carries no observable acceptance signal: no threshold, no measurement point, no way for a reviewer to check it. Severity 82, confidence high.

Rewrite it as a checkable criterion, for example: “an export of 10k rows completes in under 30 seconds, measured at the API boundary”.

The grade is capped by the testability floor: fix the S3 acceptance gap before polishing the narrative. Re-run with the same repository value to chain the round under the spec dimension.

This is a sample. Real spec reviews are generated by spec.validate and visible to you in /app/readiness-review/history (Pro/Teams), tagged as the spec dimension.

Grading built code or a rendered surface instead? The other two seats of the trio run the same validator against their own doctrine.

Architect AgentDesign Agent
How the grade is computed

Same scorer as the other two lenses

Each law receives a verdict and a severity_score; credit per finding is severity-weighted and the score is normalised over the applicable laws. production_blocker findings cap the grade; hardening_recommended and polish surface as next-iteration work without sinking the score.

A90+
B80–89
C65–79
D50–64
F<50

What is spec.validate, and how does it relate to architect.validate and design.validate?

They are the same validator with the doctrine swapped, three lenses of one product. spec.validate scores the written intent the team will build from, a proposal, requirements doc, or OpenSpec-style change bundle, against the 8 laws of the Spec Quality Blueprint, before code exists. architect.validate scores the built agentic architecture against the 10 agentic principles; design.validate scores the rendered surface against the 8 experience-design laws. Same first-pass pipeline, same ValidationResponse shape, same severity-weighted scorer, so a Blueprint Readiness Score is computed the same way on all three. Runs share one validation-history dashboard, tagged spec, architecture, and surface. Pass the same repository and you get one project graded across the whole trio: what to build, how it is built, and what the user meets.

What plan do I need, and does it share a quota with the other lenses?

A Pro or Teams plan. spec.validate has its own weekly run allocation, metered separately from the architecture and design buckets, so a heavy week of code review never eats your spec reviews. Unlike the architecture bucket there is no topup pack for spec: an empty pool recovers on the weekly reset or a plan upgrade. Free and Basic accounts can read every doctrine principle, cluster, and example via the public MCP at no charge; the PM Agent is reserved for paid plans because it processes a real artefact under a no-training policy and persists per-project history. Current per-tier numbers are on the pricing page.

“Testability is the floor.” What does that mean for my grade?

The eight laws are not weighted equally. On conflict the order is fixed: testable acceptance beats completeness, scope discipline beats ambition, and handoff completeness beats author convenience. In practice: a load-bearing requirement with no observable acceptance signal, or an irreversible, state-changing step with no named human gate and no rollback path, is scored as a production_blocker. It caps the grade and must be fixed before anyone builds, the same way a failed trust boundary caps the architecture grade and a WCAG target-size breach caps the surface grade. A thin decision trail or a missing doctrine citation is hardening_recommended or polish: it surfaces in a next-iteration list without dragging the score down. A high grade means the spec floors hold, not that the document is exhaustive.

Is the spec grade a certified verdict?

Not yet, and the tool says so on every run. spec.validate v1 is a single-pass review at high reasoning effort. It has no consensus mode and no certification path, those stay architect.validate-only for now, and its score calibration is not yet tuned against a corpus of real runs the way the architect's was. Treat the grade as a directional quality signal, not a certified badge. The one part that is hard, not directional, is the testability floor: a requirement nobody can check, or an irreversible step with no named gate, is a checkable fact about the document, not a matter of taste.

What should I send, and what comes back marked not_applicable?

Send the full spec text verbatim as implementation_context. For an OpenSpec change, concatenate proposal.md, design.md, tasks.md, and the delta specs into one call, no truncation and no … placeholders (they are read as literal content, and the reviewer would grade a document that is not yours). Source code and UI artefacts return spec_classification: non_spec and tier: not_applicable, they are not failed, they are just not specifications; submit those to architect.validate or design.validate instead. Submit the actual document the team will build from.

Is my specification stored when I call spec.validate?

Your spec text is sent to OpenAI (US) to generate the review, as a sub-processor under the EU Standard Contractual Clauses and UK Addendum, on a no-training basis, retained under OpenAI's API data-retention terms. AI Design Blueprint stores the structured result (score and per-law verdicts) plus, when you pass repository, a project identifier for grouping. Pass private_session=true to skip server-side run persistence; operational cost and audit records (never your spec text) are still kept. Any instruction-shaped text inside your document is treated as inert untrusted data, not as instructions to follow. Compute runs on Google Cloud Run; data at rest is in Cloud SQL, kept in the UK/EEA (Google Cloud europe-west2, London). Full detail on the trust and data handling page.

Also in this section

The Architect AgentThe Design AgentTrust and data handling