AHD · Usage

How to use AHD.

There are three ways to use AHD in production. There is also a single-command demo that does not count as a production path. The three production flows are independent; adopt one without touching the others.

Quick demo: ahd try

The fastest way to see the framework produce something. One brief in, one HTML page out, linted automatically. Offline by default, no API keys required.

npx ahd try briefs/landing.yml

The brief is read from disk. Its token field (or a --token override) resolves to a style token. The brief compiles in mode: final, a runner is chosen (offline mock-swiss by default; a CF OSS model if CF credentials are in the environment), the runner is called once, the response is extracted to HTML, a header comment is stamped in declaring token, model, timestamp and a Demo artifact, not production output line, and the file writes to ./out/. Unless --no-lint is set, the source linter runs on the output immediately.

npx ahd try briefs/landing.yml --model mock-swiss
npx ahd try briefs/landing.yml --model cf:@cf/meta/llama-3.3-70b-instruct-fp8-fast
npx ahd try briefs/landing.yml --token monochrome-editorial
npx ahd try-image briefs/editorial-illustration.yml   # needs CF_API_TOKEN + CF_ACCOUNT_ID

ahd try exists to make the framework demonstrable in one command. It is not a production path. For production, use the three flows below.

1. As a linter in continuous integration

The cheapest integration. No model calls, no API keys. Treat AHD the way you treat ESLint or Stylelint. Run it on the HTML and CSS your AI tools emit and fail the build when the taxonomy catches a slop tell.

npm install --save-dev @adastra/ahd
npx ahd lint dist/*.html src/**/*.css
npx ahd lint-rules

Exit code zero is clean. Exit code one means at least one error-severity rule fired. The framework repository carries reference GitHub Actions workflows and pre-commit hook scripts under .github/workflows/*.example.yml and .github/examples/.

2. Inside a design agent, via MCP

If your agent speaks MCP — Claude Code, Cursor, Windsurf, Zed, Continue — start the AHD MCP server once and the agent picks up the tools on its own.

npx ahd mcp-serve

In Claude Code, the .mcp.json entry looks like this.

{
  "mcpServers": {
    "ahd": {
      "command": "npx",
      "args": ["ahd-mcp"]
    }
  }
}

The server registers eight tools. ahd.list_tokens enumerates the library. ahd.get_token returns one token as JSON. ahd.brief compiles a brief against a token. ahd.palette, ahd.type_system and ahd.reference return the palette, typography and reference lineage for a token. ahd.lint runs the twenty-eight-rule source linter on an HTML and CSS pair. ahd.vision_rules lists the thirteen vision-only rules for when the agent has a screenshot.

The canonical agent loop is three steps. Call ahd.brief to get a token-anchored system prompt. Generate. Call ahd.lint on the output and iterate until clean.

3. As an evaluation loop

The most involved and highest-signal integration. Run the same brief through several models in raw and compiled conditions, let the source linter and vision critic score the output, and publish the report.

Text to HTML:

CF_API_TOKEN=… CF_ACCOUNT_ID=… \
  ahd eval-live swiss-editorial \
    --brief briefs/landing.yml \
    --models cf:@cf/meta/llama-3.3-70b-instruct-fp8-fast,cf:@cf/mistralai/mistral-small-3.1-24b-instruct \
    --n 10 \
    --report docs/evals/$(date +%Y-%m-%d)-swiss.md

Adding claude-opus-4-7, gpt-5 or gemini-3-pro to --models needs the corresponding provider keys. Cloudflare AI Gateway wraps every frontier call transparently when CF_AI_GATEWAY=<account>/<gateway> is set, so you get caching and spend tracking for free.

Image generation:

CF_API_TOKEN=… CF_ACCOUNT_ID=… ANTHROPIC_API_KEY=… \
  ahd eval-image editorial-illustration \
    --brief briefs/editorial-illustration.yml \
    --models cfimg:@cf/black-forest-labs/flux-1-schnell,cfimg:@cf/bytedance/stable-diffusion-xl-lightning \
    --n 5 \
    --report docs/evals/$(date +%Y-%m-%d)-editorial-image.md

Raw and compiled PNGs land in evals/<token>/images/<model>/<condition>/. Each is critiqued by the vision critic against the thirteen vision-only rules. The report carries per-model deltas and per-tell frequency the same way the text eval does. Pass --critic mock to score offline.

Run the whole pipeline for free

Every live runner has a deterministic mock twin. You can exercise the full pipeline offline.

ahd eval-live swiss-editorial \
  --brief briefs/landing.yml \
  --models mock-slop,mock-swiss \
  --n 3

ahd critique swiss-editorial --samples evals --critic mock

The test suite uses the same mocks. Running them locally is the right way to confirm the wiring works before you spend anything on live API calls.

Adjacent: how we measure, the thirty-eight-tell taxonomy, positioning.