A PDF resizing tool solves this problem by allowing users to change the page dimensions of an existing PDF without recreating the document from scratch.

Whether you're preparing business reports, invoices, scanned documents, eBooks, presentations, or government forms, resizing pages helps ensure documents fit the required paper size while maintaining a professional appearance.

In this tutorial, you'll build a browser-based PDF Resizer using JavaScript. Users will be able to upload PDF files, preview document pages, choose preset or custom page sizes, configure scaling behavior, add page margins, and generate a resized PDF directly inside the browser.

Everything happens locally using JavaScript, so uploaded documents never leave the user's device. This improves privacy, eliminates server-side processing, and provides a faster experience.

By the end of this guide, you'll understand how browser-based PDF resizing works and how to build a practical tool that can be extended with additional document editing features.

Table of Contents

• Why PDF Resizing Is Useful

• How PDF Resizing Works

• Project Setup

• What Library Are We Using?

• Creating the Upload Interface

• Previewing Uploaded PDF Pages

• Configuring Resize Settings

• Applying the Resize

• Generating the Resized PDF

• Demo: How the PDF Resize Tool Works

• Important Notes from Real-World Use

• Common Mistakes to Avoid

• Conclusion

Why PDF Resizing Is Useful

PDF files are created for many different purposes, and not every document uses the same page dimensions. A presentation might be designed for widescreen viewing, an invoice could use Letter size, a government application may require A4 paper, and engineering drawings often use Legal or Tabloid formats.

When documents don't match the required page size, they can be difficult to print correctly. Content may appear cut off, excessive white space may be introduced, or the document may scale incorrectly during printing.

A PDF resizing tool helps solve these problems by allowing users to convert pages into standardized sizes without rebuilding the document.

This is especially useful in everyday situations. Businesses often receive invoices and contracts from different organizations that use different paper standards. Before storing or printing these documents, employees frequently resize them to a consistent format.

Students regularly download lecture notes, assignments, research papers, and ebooks from different sources. Converting these files to a common page size makes printing and reading much easier.

Graphic designers and publishers also resize PDFs before sending artwork for commercial printing, ensuring that documents match the required dimensions of the printing service.

One practical example comes from e-commerce businesses. Imagine a seller who receives hundreds of shipping labels every day from platforms like Amazon, Flipkart, or Meesho. Different marketplaces may generate labels using different paper sizes. Before printing them in bulk, the seller can resize every PDF to A4 so all labels print consistently without manual adjustments.

Government offices, banks, educational institutions, and legal firms also work with PDFs from multiple sources. Standardizing page sizes simplifies document management, digital archiving, scanning, and future editing.

Instead of recreating an entire document, resizing allows users to adapt existing PDFs quickly while preserving their original content.

How PDF Resizing Works

A PDF resizing tool changes the dimensions of one or more pages inside an existing PDF document while preserving the page content.

When a user uploads a PDF, the browser first reads the document and extracts information such as page count, page dimensions, and page objects. Instead of editing the original file directly, a new PDF is created with the selected page size, and each page is copied into the new document using the chosen scaling method.

Depending on the resize settings, the page content can be scaled to fill the page, stretched to match the new dimensions, centered without scaling, or cropped to fit the selected paper size.

Users can also choose whether the resize operation should apply to every page or only a specific page range. This is useful when only part of a document needs to be converted to another paper size.

Because all processing happens inside the browser, uploaded files remain on the user's device throughout the entire workflow. No documents are sent to external servers, making the tool suitable for confidential reports, contracts, invoices, educational documents, business records, and other sensitive files.

Project Setup

Create a new project folder for the PDF resizer.

A simple project structure looks like this:

pdf-resizer/
│── index.html
│── style.css
│── script.js
│── assets/

The HTML file contains the upload area, page preview, resize settings, and download section.

The CSS file handles the overall layout and responsive design.

The JavaScript file manages PDF loading, page previews, resize operations, and exporting the updated document.

Keeping the project organized makes it easier to add new features later, such as cropping, page rotation, watermarking, metadata editing, or PDF merging.

What Library Are We Using?

This project uses pdf-lib, one of the most popular JavaScript libraries for creating and editing PDF documents directly in the browser.

It allows developers to:

• Read existing PDF files.

• Create new PDF documents.

• Copy pages between PDFs.

• Resize pages.

• Rotate pages.

• Add text, images, and shapes.

• Modify document metadata.

• Export updated PDFs.

Unlike many online PDF services, pdf-lib works entirely in the browser and doesn't require a backend server.

Install the library using npm:

npm install pdf-lib

Or include it directly from a CDN:

<script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script>

Once loaded, the library exposes the PDFDocument object that is used throughout the application.

Example:

const { PDFDocument } = PDFLib;

Creating the Upload Interface

The first step is allowing users to upload a PDF document.

The interface includes a drag-and-drop area together with a traditional file picker so users can choose whichever method they prefer.

When a file is selected, JavaScript validates that it is a PDF before loading it into memory.

Here's a simple upload input:

<input
    type="file"
    id="pdfUpload"
    accept="application/pdf"
/>

Next, listen for file selection:

const upload = document.getElementById("pdfUpload");

upload.addEventListener("change", async (event) => {
    const file = event.target.files[0];

    if (!file) return;

    console.log(file.name);
});

Read the uploaded file:

const bytes = await file.arrayBuffer();

const pdfDoc = await PDFLib.PDFDocument.load(bytes);

At this point, the uploaded PDF is loaded into memory and is ready for preview generation and resizing.

Previewing Uploaded PDF Pages

After the document has been uploaded, the next step is generating page previews.

Displaying page thumbnails helps users confirm that the correct file has been selected before changing its size.

For multi-page PDFs, previewing every page also makes it easier to understand how the resize operation will affect the document.

Your tool displays thumbnails for every page, allowing users to visually inspect the PDF before making any modifications.

Developers can retrieve the total number of pages using pdf-lib:

const totalPages = pdfDoc.getPageCount();

console.log(totalPages);

Retrieve individual pages:

const pages = pdfDoc.getPages();

pages.forEach((page, index) => {
    console.log(`Page ${index + 1}`);
});

Once the pages are available, the application can generate preview thumbnails and display them inside the browser.

Users can then decide whether to resize the entire document or only selected pages.

Configuring Resize Settings

Once the PDF pages have been loaded, users need to configure how the document should be resized.

A flexible PDF resizing tool should support both standard paper sizes and custom dimensions while allowing users to control how the existing content fits inside the new page.

In this project, users can choose whether the resize operation should be applied to every page or only a specific page range.

For page dimensions, the tool supports popular paper formats such as A4, A5, Letter, Legal, Tabloid, and Square. If none of these meet the user's requirements, custom width and height values can also be entered.

Another important setting is content scaling. Depending on the document, users may want to fit the existing content inside the page, stretch it to fill the available space, keep the original size centered on the page, or crop the content to match the selected paper size.

The resize panel also includes margin controls so users can add additional spacing around the document if required.

Together, these settings provide complete control over the final page layout before generating the resized PDF.

Choosing Preset Paper Sizes

Many users simply want to convert documents into common paper formats.

Instead of entering page dimensions manually, the tool provides several predefined page sizes that can be selected with a single click.

These presets are especially useful when preparing PDFs for printing, business reports, contracts, government forms, books, or educational documents.

Using Custom Page Sizes

If a standard paper size isn't suitable, users can enter custom page dimensions.

The width and height can be specified using supported measurement units, allowing documents to match exact printing or publishing requirements.

The Lock Aspect Ratio option ensures that the document maintains its original proportions while resizing.

Selecting Content Scaling

Different documents require different scaling behavior.

The tool offers several scaling modes so users can choose the most appropriate layout for their document.

For example, Fit to Page scales content while preserving proportions, Stretch to Fit expands the content to fill the page completely, Keep Original Size (Center) places the original page in the center without scaling, and Crop to Fit trims overflowing content to match the selected page dimensions.

Example Resize Settings

Here's a simplified configuration object that stores the selected resize options.

const resizeOptions = {
    width: 210,
    height: 297,
    unit: "mm",
    scaleMode: "fit",
    applyTo: "all"
};

The selected values are then used while generating the resized PDF.

Applying the Resize

After the resize settings have been configured, the application creates a new PDF document and copies each page into it using the selected dimensions.

Each page is resized according to the chosen paper size and scaling mode before being added to the new document.

A simplified example looks like this:

const newPdf = await PDFLib.PDFDocument.create();

const copiedPages = await newPdf.copyPages(
    pdfDoc,
    pdfDoc.getPageIndices()
);

copiedPages.forEach(page => {
    page.setSize(595, 842);

    newPdf.addPage(page);
});

The dimensions shown above represent an A4 page measured in PDF points.

Developers can replace these values with custom dimensions depending on the selected paper size.

After every page has been resized, the new document is ready for export.

Generating the Resized PDF

Once all pages have been processed, the updated document is converted into a downloadable PDF.

The browser creates a binary PDF file and generates a temporary download link without sending the document to a server.

Saving the resized document is straightforward.

const pdfBytes = await newPdf.save();

const blob = new Blob([pdfBytes], {
    type: "application/pdf"
});

const url = URL.createObjectURL(blob);

The generated URL can then be attached to a download button.

const link = document.createElement("a");

link.href = url;
link.download = "resized-document.pdf";

link.click();

The user immediately receives the updated document with the newly selected page dimensions.

Demo: How the PDF Resize Tool Works

Step 1: Upload Your PDF File

The process begins by uploading a PDF document into the browser.

Users can either drag and drop a file into the upload area or choose a document using the file picker.

Once selected, the browser validates the file type and loads the document locally without uploading it to a server. This keeps the entire resizing process private and ensures sensitive documents remain on the user's device.

Step 2: Preview Uploaded PDF Pages

After the PDF has been loaded, the tool generates page previews for the entire document.

Displaying thumbnails allows users to verify that the correct document has been selected before making any modifications.

Users can also select individual pages if they only want to resize certain parts of the document.

This preview step helps avoid mistakes before generating the final PDF.

Step 3: Configure Resize Settings

Next, users configure how the document should be resized.

The tool supports standard paper sizes such as A4, A5, Letter, Legal, Tabloid, and Square, while also allowing completely custom dimensions.

Users can specify whether the resize operation should apply to all pages or only selected page ranges.

Additional options include locking the aspect ratio, choosing page orientation, selecting a content scaling mode, and adding page margins when necessary.

These settings provide complete control over the final document layout before processing begins.

Step 4: Generate the Resized PDF

After reviewing the selected options, users simply click the Resize PDF button.

The browser processes every selected page according to the configured paper size and scaling method.

Because the entire operation runs locally, even large documents can usually be processed within a few seconds depending on the number of pages.

If users want to process another document, the Start Over button clears the current session and returns the tool to its initial state.

Step 5: Preview the Resized PDF

Once processing is complete, the newly generated PDF is displayed inside the browser.

Users can review the resized pages before downloading the document.

The preview section includes page navigation controls, making it easy to move through multi-page PDFs and confirm that every page has been resized correctly.

Reviewing the output before download helps catch formatting issues and ensures the selected page size and scaling options produced the expected results.

Step 6: Download the Final PDF

After confirming the resized document, users can download the updated PDF.

The final output section displays useful information such as the output filename, total number of pages, and file size.

Users may also rename the document before downloading it, making it easier to organize files after processing.

The Download PDF button saves the resized document, while the Start Over button allows users to upload another PDF without refreshing the page.

Important Notes from Real-World Use

Resizing PDF pages can significantly improve document compatibility, but it's important to validate uploaded files before processing.

For example:

if (file.type !== "application/pdf") {
    alert("Please upload a valid PDF file.");
    return;
}

Very large PDF files may require additional processing time depending on the number of pages and embedded images.

When resizing documents containing hundreds of pages, processing them page by page can help reduce memory usage.

Before generating the final PDF, it's also a good idea to verify the selected page size.

For example:

console.log(`Selected Size: ${pageSize}`);
console.log(`Scale Mode: ${scaleMode}`);

Previewing the resized document before downloading helps ensure that text, images, and page layouts appear correctly.

Because everything happens inside the browser, uploaded documents remain on the user's device throughout the entire resizing process.

Common Mistakes to Avoid

One common mistake is selecting a page size that doesn't match the intended output.

For example, resizing a wide presentation directly to A4 portrait may cause content to become too small or appear compressed.

Always verify the selected paper size before processing.

if (pageWidth <= 0 || pageHeight <= 0) {
    alert("Invalid page dimensions.");
}

Another common mistake is choosing the wrong content scaling mode.

Stretching content may distort images and text, while cropping may remove important information from the page.

Users should preview different scaling modes before generating the final PDF.

It's also important to check whether the resize operation should apply to every page or only selected pages.

const applyMode = "all";

console.log(`Resize Mode: ${applyMode}`);

Finally, always review the generated PDF before downloading it.

Taking a few seconds to inspect page layouts, margins, and scaling can prevent unnecessary reprocessing later.

Conclusion

In this tutorial, you built a browser-based PDF Resizer using JavaScript.

You learned how to upload PDF files, preview document pages, configure page sizes, adjust scaling behavior, resize pages, and generate downloadable PDF files directly inside the browser.

More importantly, you saw how modern browsers can perform PDF page resizing locally without requiring a backend server.

This approach keeps document processing fast, private, and easy to use while giving users complete control over the final document layout.

If you'd like to see a working example, try the PDF Resize Tool and explore how PDF pages can be resized directly in your browser.

Once you understand this workflow, you can extend it further with features like page cropping, rotation, watermarking, metadata editing, page numbering, document organization, and other advanced PDF editing capabilities.

The tool is spec-writer: a Claude Code skill that takes a vague feature request and generates a structured spec, technical plan, and task breakdown before a single line of code gets written.

The problem it solves is one most developers hit within their first week of using AI coding agents seriously: the agent writes confidently in the wrong direction and you pay for it twice, once in tokens, once in rewrites.

This tutorial shows you how to install spec-writer, how to invoke it on a real feature, and how to read the output so you can catch the assumptions that would have wasted your time.

Table of Contents

1. The Problem with Prompting Agents Directly

2. What Spec-Driven Development Is

3. How spec-writer Works

4. How to Install spec-writer

5. How to Write Your First Spec

6. How to Read the Output

7. How to Hand the Spec to Your Agent

8. Where to Go Next

The Problem with Prompting Agents Directly

Here is what happens when you skip the spec.

You have a feature in your head: "Add a way for users to export their data." You open Claude Code and describe it. The agent produces code. It looks right. You run it. It's mostly right – except it exports everything including soft-deleted records, it doesn't paginate, it times out on large accounts, and it has no authentication check on the export endpoint.

None of those things were in your prompt. The agent guessed, and it guessed plausibly – which is worse than guessing obviously wrong. You didn't notice until testing.

This is the fundamental problem with prompting agents directly on anything non-trivial: your prompt carries your conscious requirements, but every feature has a shadow of requirements you didn't think to state. And the agent fills that shadow with assumptions.

Most of the time, those assumptions are reasonable. Some of the time, they're wrong in ways that take hours to unravel.

The failure mode isn't hallucination. It's the agent being exactly as helpful as the prompt allowed, which wasn't helpful enough.

Spec-Driven Development addresses this directly. The methodology – documented extensively by practitioners like Julián Deangelis – argues that a written spec isn't documentation overhead. It's the mechanism that forces you to make decisions before the agent does.

What Spec-Driven Development Is

Spec-Driven Development is the practice of writing a structured specification before you write code or prompt an agent. The spec defines what the feature must do, what assumptions are being made, and what tasks the implementation breaks into.

The key insight is what a spec is for. A spec is not trying to replace code. It's trying to surface the decisions that would otherwise be invisible. The agent will make those decisions either way: with a spec, you make them first. Without a spec, you discover them during testing.

The strongest counterargument to SDD comes from Gabriella Gonzalez: a sufficiently detailed spec is just code. She's right that some specs devolve into pseudocode so specific they might as well be implementations.

But that's a spec written at the wrong level of abstraction. The goal is to name the decisions, not to pre-implement them. "Only authenticated users can trigger this export" is a decision. "Call verifyJWT(token) and return 401 if it fails" is implementation. The spec needs the first. The agent handles the second.

SDD has three levels:

1. Spec-First: write a spec before every feature and hand it to the agent as context. This is the entry point and the workflow this tutorial focuses on.

2. Spec-Anchored: the spec lives in the repository and evolves alongside the code. When requirements change, you update the spec and re-prompt the agent to realign.

3. Spec-as-Source: the spec is the primary artifact. Code is generated from it and considered disposable. This is the most ambitious level and the direction many teams are moving toward.

spec-writer gets you to Spec-First immediately, with no ceremony.

How spec-writer Works

spec-writer is a Claude Code skill – a markdown file that loads into the agent's context and changes how it responds when invoked.

The skill follows one rule: generate first, flag assumptions inline. Instead of asking you clarifying questions before producing output, it generates the full spec immediately and marks every decision it made without your explicit input using [ASSUMPTION: ...] tags. Then you correct what's wrong.

This is faster than Q&A because it makes the decisions visible in a form you can react to rather than anticipate.

The output has three sections in fixed order:

1. SPEC: the what. One-line purpose, user stories, requirements, edge cases, and acceptance criteria in Given/When/Then format.

2. PLAN: the how. Stack and architecture decisions, data model changes, API contracts, testing strategy, and security constraints.

3. TASKS: the breakdown. Ordered, self-contained tasks each completable in a single agent session, each with its own acceptance criteria.

After the three sections, the skill produces an Assumptions summary: every [ASSUMPTION: ...] from the output, ranked by impact. This is the part you review before handing anything to the agent.

The skill is compatible with GitHub Spec Kit and OpenSpec. If you use either framework, save the spec output to your .specify/ or openspec/changes/ directory and continue from there.

How to Install spec-writer

spec-writer uses the Agent Skills standard, which means the same SKILL.md file works across Claude Code, Cursor, GitHub Copilot, Gemini CLI, and any other agent that supports the standard. You install it once and it works everywhere.

Installation

Create the skills directory if it doesn't exist and clone the repo:

mkdir -p ~/.claude/skills
git clone https://github.com/dannwaneri/spec-writer.git ~/.claude/skills/spec-writer

On Windows PowerShell:

(Note: PowerShell uses backtick (`) for line continuation, not backslash.)

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills"
git clone https://github.com/dannwaneri/spec-writer.git "$HOME\.claude\skills\spec-writer"

That's the entire installation. No package to install, no configuration file to edit, no API key. The skill is a markdown file. The agent reads it.

Verification

Open Claude Code and type:

/spec-writer test

If the skill is installed correctly, the agent will read the SKILL.md and produce a spec structure – even for "test" as input. You'll see the three sections and the Assumptions summary. If nothing happens, confirm that the ~/.claude/skills/spec-writer/SKILL.md file exists.

How to Write Your First Spec

The invocation pattern is:

/spec-writer [your feature description]

The description can be as rough as you'd write in a Slack message. The skill's job is to structure it. You don't need to be precise. Being precise is what the spec is for.

A Real Example

Here is a real invocation from the Foundation project, a federated knowledge base built on Cloudflare Workers:

/spec-writer Add CLI capture for Claude Code sessions stored in ~/.claude/projects/

That's twelve words. No mention of the tech stack, no data model details, no authentication requirements, no error handling spec. All of that comes out in the spec.

Here is the abbreviated output:

SPEC

One-line purpose: Developers can capture Claude Code session logs from their local filesystem into Foundation before they are deleted after 30 days.

Users and use cases:

• As a developer using Claude Code daily, I want my coding sessions captured automatically so that architectural decisions and debugging patterns don't disappear after 30 days.

• As a Foundation user, I want CLI sessions and browser extension captures in the same knowledge base so that I have one place to query across all my AI interactions.

Acceptance criteria:

Given a developer with Claude Code sessions in ~/.claude/projects/
When they run the Foundation CLI capture command
Then a list of uncaptured sessions is displayed, sorted by most recent first
 
Given a session already in Foundation
When the developer runs capture again
Then that session does not appear in the review list
 
Given a malformed .jsonl file
When the capture command processes it
Then an error is logged for that file and processing continues on remaining sessions

PLAN

Stack and architecture:

CLI capture runs locally — it needs to read the local filesystem, which
Cloudflare Workers cannot do. [ASSUMPTION: CLI capture is a local Node.js
or Bun script that calls the Foundation API to insert sessions, rather
than a Worker itself]

API contracts:

• POST /api/sessions/import – accepts parsed session JSON, returns session ID

• Returns 409 if session already exists

• Triggers evaluator pipeline after successful insert

TASKS

## Task 1: .jsonl parser
 
**What to build:** A parser that reads a Claude Code .jsonl session file
and outputs Foundation's internal message format.
**Files likely affected:** cli/src/parsers/claudeCode.js (create)
**Acceptance criteria:**
1. Parses a valid .jsonl file into the correct message format
2. Handles malformed lines without crashing — logs and skips
3. Returns empty array for empty file
**Dependencies:** none

Assumptions to review:

1. CLI capture is a local script calling the Foundation API, not a Worker
   Impact: HIGH
   Correct this if: you want a purely serverless approach
 
2. Manual curation before capture, not automatic bulk import
   Impact: HIGH
   Correct this if: you want automatic background capture
 
3. Session ID from .jsonl filename is the deduplication key
   Impact: MEDIUM
   Correct this if: session IDs are stored differently in your schema
 
4. No sensitive data scrubbing in v1
   Impact: MEDIUM
   Correct this if: your sessions contain credentials or keys

Twelve words in, four decisions surfaced immediately – three of which had real architectural implications.

The third assumption ("Session ID from .jsonl filename is the deduplication key") is the one that would have caused the most subtle bug. The agent would have implemented deduplication based on the filename and it would have worked until a session was renamed. The spec caught it before a line of code was written.

How to Read the Output

The output is designed to be scanned for [ASSUMPTION: ...] tags first, read for the tasks second.

Reading the Assumptions

Every [ASSUMPTION: ...] tag marks a place where the agent filled in something you didn't specify. Your job is to go through the Assumptions summary and decide for each one:

• Correct: the assumption is right, leave it

• Override: the assumption is wrong, restate it and re-run the spec

• Defer: the assumption doesn't matter for this iteration, mark it and move on

The impact rating tells you which assumptions to fix before you start coding. HIGH-impact assumptions affect architecture or data model. If they're wrong, fixing them requires rework. LOW-impact assumptions affect behavior details that are easy to change later.

Reading the Acceptance Criteria

The acceptance criteria in Given/When/Then format are the most useful part of the spec for catching scope errors. Read each one and ask: is this actually what I want?

Criteria are binary by design. "Returns 401 when unauthenticated" is a criterion. "Works correctly" is not. If you find yourself reading a criterion and thinking "well, it depends", then that's a signal that the criterion is hiding an assumption. Restate it.

Reading the Tasks

The tasks are ordered and self-contained. Each task produces a verifiable change. Before you hand any task to an agent, check two things:

1. Does the task have all the context it needs? If a task says "follow the existing auth pattern" and you haven't pointed the agent at your auth code, it will guess.

2. Does the acceptance criteria match what you'd actually test? If the criteria are vague, tighten them before the agent sees the task.

How to Hand the Spec to Your Agent

The spec is context, not a prompt. When you start an agent session for a task, include the relevant spec sections alongside the task description.

For Task 1 from the example above, your agent session might open like this:

Context:
- This is a federated knowledge base built on Cloudflare Workers, D1, and Vectorize
- Sessions are stored in ~/.claude/projects/ as .jsonl files
- The API runs at https://<your-worker>.workers.dev
 
Spec:
[paste the SPEC and PLAN sections]
 
Task:
[paste Task 1]

The context block is just an example. Replace it with your own project's tech stack, file locations, and API URL. The point is to give the agent the same context a new team member would need on day one.

The agent now has requirements, architecture context, and a single scoped task with binary acceptance criteria. It cannot guess the deduplication key incorrectly because the spec already resolved that assumption. It cannot skip error handling because the acceptance criteria explicitly require it.

This is the workflow the spec is designed for. The spec doesn't replace the agent. Rather, it removes the decisions from the agent's hands and puts them in yours, before the work starts.

Saving the Spec for Later

If you want to move toward Spec-Anchored development – where the spec lives in the repository – save the output to a specs/ directory in your project:

# Create specs directory
mkdir -p specs
 
# Save your spec
# Paste the output into specs/cli-capture.md

When requirements change, update the spec and re-prompt the agent to realign the implementation. The spec becomes the source of truth, not the code comments.

Where to Go Next

Try it on your next feature before you write a line of code. The assumptions it flags will tell you something about your feature you hadn't consciously decided yet – and correcting the HIGH-impact ones before you hand anything to an agent is the whole point. Skipping that step is the same as prompting directly.

If your project is growing, move toward Spec-Anchored. Save specs in your repository under specs/. When a new contributor joins or an agent starts a session cold, the specs give them the decisions that got made without requiring them to reverse-engineer the code.

The strongest ongoing challenge to this workflow is Gabriella Gonzalez's argument that detailed specs become code. If your specs are getting implementation-specific, you've crossed a line. Pull back to decisions – "only authenticated users can trigger this" – and leave implementation to the agent. The spec's job is to name what the agent would have guessed wrong, not to write the feature in prose.

The Agent Skills standard now works across Claude Code, GitHub Copilot, Cursor, and Gemini CLI. The spec-writer repo is at github.com/dannwaneri/spec-writer.

The irony of spending 64% of a Claude budget building a token-efficiency tool is real. But the spec surfaced four decisions on a twelve-word prompt. The fourth one – the deduplication key assumption – would have produced a bug that worked perfectly until a session got renamed.

That's not a hallucination. That's the agent being exactly as helpful as the prompt allowed.

The spec is how you raise the ceiling on what "helpful" means.