npx specpack audit          # bloat score for the agent files in this repo (offline)
npx specpack init           # write a lean AGENTS.md from your manifests (offline)
npx specpack spec --describe "Booking app for dog groomers with deposits and SMS reminders"

$ npx specpack audit CLAUDE.md
CLAUDE.md  59% bloat  · 44 lines · ~341 tokens every session
  10 keep · 12 cut · 15 offload of 37 non-empty lines · ceiling 200, trimmed files land near 60
  Over half of this file is doing nothing. It is not neutral weight — it is what your real rules are competing against.

     3  cut     You are an expert senior full-stack developer with 10 years of experience.
        ↳ role-play preamble: CLAUDE.md is project memory, not a system prompt. "You are an expert…" costs tokens and changes nothing about the code produced.
     4  cut     Please always write clean, readable and maintainable code.
        ↳ default behaviour: Removing this line does not make the model write worse code — it already tries to do this. It only dilutes the lines that matter.
     5  cut     IMPORTANT: follow best practices at all times.
     …
    12  cut     - Next.js 15.1
        ↳ restates a manifest: package.json / composer.json / requirements.txt already state this, and the agent reads them. Keep it only if the version pin has a non-obvious reason.
     …
    18  offload ## Database schema
        ↳ situational section: Only a fraction of your sessions need this. Move the section to its own file and point at it with @docs/… so it loads when the task asks for it.
     …
    31  offload src/
        ↳ file tree: Root of a pasted directory tree. The agent can run ls and get the real one — a copy goes stale after the first refactor.
     …
  Trimmed copy (8 lines): specpack audit CLAUDE.md --trimmed

# .github/workflows/agent-files.yml
name: Agent files
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx -y specpack audit --max-bloat 30

$ npx specpack init
✓ Wrote AGENTS.md (37 lines, 0% bloat)
  Scanned from package.json, tsconfig.json, prisma/schema.prisma, .nvmrc, docker-compose.yml, .env.example, .gitignore, .claude/commands/.

# AGENTS.md — ledgerly

Invoicing app for freelancers. A web application.

## Stack
- Next.js (App Router)
- Tailwind CSS
- Zod
- Stripe
- Vitest
- Playwright
- ESLint
- TypeScript (strict)
- Prisma + PostgreSQL (schema: prisma/schema.prisma)
- Local services via Docker Compose (docker-compose.yml): db

## Commands
- `pnpm dev` — `next dev --turbopack -p 3001` (port 3001)
- `pnpm build` — `next build`
- `pnpm start` — `next start`
- `pnpm test` — `vitest run`
- `pnpm test:e2e` — `playwright test`
- `pnpm lint` — `next lint`
- `pnpm db:migrate` — `prisma migrate dev`
- `pnpm db:seed` — `tsx prisma/seed.ts`
- `docker compose up -d`

## Project rules
These are things the agent cannot guess from the code. Follow them exactly.
- Use pnpm (pnpm-lock.yaml), not npm or yarn — another package manager ignores the lockfile.
- Runtime: Node 20 (.nvmrc).
- Environment variables are listed in `.env.example`; the real `.env` is git-ignored — do not commit it.
<!-- Add the rules the code cannot tell the agent, one per line: the directory scheduled for deletion,
     money stored in cents, the command that must never run against staging. -->

# AI drafts the answers from a description (10–40 s), then the spec is generated
npx specpack spec --describe "Booking app for dog groomers with deposits and SMS reminders" --out ./groombook

# your own answers (see GET /questions in the API)
npx specpack spec --answers answers.json --type saas

# or answer the questionnaire in the terminal
npx specpack spec

claude mcp add specpack -- npx -y specpack mcp

{
  "mcpServers": {
    "specpack": { "command": "npx", "args": ["-y", "specpack", "mcp"], "env": { "SPECPACK_API_KEY": "" } }
  }
}

claude mcp add --transport http specpack https://prompt-generator-website.com/mcp

import { audit, scanProject, renderAgentsMd, SpecpackClient } from "specpack";

const { stats, lines, trimmed } = audit(fs.readFileSync("CLAUDE.md", "utf8"));
console.log(`${stats.bloat}% bloat`, lines.filter((l) => l.verdict === "cut").length, "lines to cut");

const agentsMd = renderAgentsMd(scanProject("."));

const client = new SpecpackClient({ apiKey: process.env.SPECPACK_API_KEY });
const draft = await client.draft("A booking app for dog groomers");
const spec = await client.createSpec(draft.type, draft.answers); // spec.spec, spec.files["AGENTS.md"]…