Feeding Spec PDFs to Antigravity 2.1.4: A Practical Attachment Workflow

Implementing spec-first, step by step

Here is the flow from when I actually built the payment client, laid out so you can reproduce it.

1. Run the text check, then attach (the pdftotext step above)
2. Hand it to the agent with the pages and the task scoped down
3. Generate "types only" first, and eyeball them against the PDF
4. Once the types are firm, generate the function bodies that use them
5. Pass the error-code table as a separate instruction to build the exception mapping

Locking the types down first is the key. Ask it to "build the whole client" up front, and the types, transport, and error handling all spill out together, leaving you unsure which part came from the PDF and which was guessed.

The generated type settles into something like this.

// Type lifted from the Create Charge definition on PDF pages 14-18.
// Required/optional follows the PDF's "Required" column.
export interface CreateChargeRequest {
  amount: number;          // smallest currency unit (integer yen as-is)
  currency: "jpy" | "usd"; // from the PDF's Supported currencies table
  customerId: string;
  description?: string;     // Optional in the PDF
  metadata?: Record<string, string>;
}
 
export interface CreateChargeResponse {
  id: string;
  status: "succeeded" | "pending" | "failed";
  createdAt: string;       // ISO 8601, stated in the PDF's Notes column
}

With the type held fixed, I then ask for the function body. Because the type is settled, the agent can concentrate on the transport, and the output wavers far less.

export async function createCharge(
  req: CreateChargeRequest,
  apiKey: string,
): Promise<CreateChargeResponse> {
  const res = await fetch("https://api.example-pay.test/v1/charges", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(req),
  });
 
  if (!res.ok) {
    // The error-code table is mapped separately in the next step.
    throw new Error(`charge failed: ${res.status}`);
  }
  return (await res.json()) as CreateChargeResponse;
}

The scanned-image PDF trap

This is what tripped me up first. I attached an image PDF assuming it was readable, and the type that came back was full of names that aren't in the PDF. The agent can't lift characters off an image, so it was imagining what it couldn't see from context.

There are two fixes: find the original text data, or add a text layer with OCR. The latter was easy with ocrmypdf.

# Add a text layer to an image PDF.
# Specify the language pack if Japanese is present.
ocrmypdf -l jpn+eng scanned-spec.pdf searchable-spec.pdf
 
# Confirm text is now extractable.
pdftotext searchable-spec.pdf - | head -c 400

OCR'd PDFs don't recognize table structure perfectly. Digits and symbols can shift, so when I hand over a spec that went through OCR, I eyeball the numeric ranges and enums in the types with extra care. It's less about avoiding the trap and more about raising the inspection density once I know the trap is there.

Don't hand over a large PDF whole

I once attached a 100+ page spec in full, and it was a mistake. Responses slowed, most of the context filled with irrelevant pages, and attention to the few pages that mattered thinned out. The token cost is not trivial either.

Now I cut out only the sections I need before attaching. Splitting is more reliable left to a script that takes a page range than done by hand.

# A small script to cut a spec into chapters.
# pip install pypdf
from pypdf import PdfReader, PdfWriter
 
def extract_pages(src: str, start: int, end: int, dst: str) -> None:
    """Write pages start..end (1-based, inclusive) to dst."""
    reader = PdfReader(src)
    writer = PdfWriter()
    for i in range(start - 1, end):
        writer.add_page(reader.pages[i])
    with open(dst, "wb") as f:
        writer.write(f)
 
# Example: cut out just the Create Charge chapter.
extract_pages("payment-api.pdf", 14, 18, "charge-section.pdf")

In practice, handing over just the five pages I needed gave a visibly faster response than the full document, and the generated type was more accurate too. Keeping irrelevant information out of the context seems to translate directly into precision.

Build a way to verify the output

To avoid over-trusting what's generated, I keep verification in two layers.

The first is making the agent state its source pages. Ask it to "note, for each field's type, which PDF page the entry is based on," and the cross-checking effort drops sharply. A field for which it can't write a page number is a sign that the field isn't in the PDF — likely a guess.

The second is a mechanical check. I confirm the generated type passes a minimal test on my end.

// Minimal confirmation that the generated type is as expected.
import { CreateChargeRequest } from "./payment-client";
 
const sample: CreateChargeRequest = {
  amount: 1000,
  currency: "jpy",
  customerId: "cus_test_001",
  // description and metadata are optional, so they should be omittable.
};
 
// If it made description required, this line throws a type error.
console.log("type check OK:", sample.amount);

Whether this sample compiles is enough to catch the common slip of turning an optional field into a required one. A type lifted from a spec is safer with this kind of small guard in front of it.

Where I've landed

After a few days, my conclusion is that PDF attachment is at its strongest when you hand over a text-layer spec, section by section, while making the agent cite its source pages.

Conversely, passing an image PDF whole, without saying which pages to read, trades away the retyping effort for the effort of hunting down invisible errors later. The more convenient the feature, the more the result depends on the manners of handing it over.

If you're staring down a spec PDF the same way, I hope this gives you one starting point to work from. Thank you for reading.