Clifier

Generate a reusable website-automation package, not a one-off script. Default to a Deno CLI plus a runtime-neutral client library. Keep the result concise, polished, and JSR-ready.

Bias toward small, sharp, readable software: production-ready, highly usable, and free of wasted motion.

Use references progressively. Read only what the current step needs:

• command surface:

references/cli-command-patterns.md

• site investigation:

references/investigation-workflow.md

• runtime choice:

references/fetch-vs-playwright.md

• auth/session reuse:

references/auth-and-session.md

• docs/output: references/output-and-docs.md
• JSR packaging: references/jsr-publishing.md

Workflow

1. Define the CLI first.
2. Investigate the site with playwright-cli.
3. Prove or disprove fetch.
4. Decide on fetch, hybrid, or playwright-cli-backed browser automation.
5. Generate from assets/templates/deno-cli/.
6. Validate the happy path and publishability.

Define The CLI

Read references/cli-command-patterns.md before naming commands.

• Prefer product nouns, then verbs.
• Use direct top-level verbs only for cross-cutting commands such as login.
• Prefer @cliffy/command for Deno CLIs.
• Keep the CLI thin: parse flags, call library code, format output, and handle

Deno-specific filesystem or session work.

• Always include a root -v, --version flag.
• Keep the surface small, predictable, and guessable from the product

vocabulary.

• Make the happy path obvious from --help.
• Map meaningful UI controls to flags before finalizing commands.
• Give high-value explicit flags a shorthand alias when it is clear and

memorable, such as --session-path/-s and --out/-o.

• Put global flags before the command path in docs, help examples, and

agent-facing snippets, such as tool-name --json --session-path ~/.auth/[email protected] jobs get <job-id>. Keep command-specific flags near the command they configure, such as tool-name --json jobs download <job-id> --out ./downloads.

• Keep operational commands non-interactive after auth/bootstrap.
• Emit stable IDs from create-style commands and accept them directly in

follow-up commands.

• Keep only commands that deliver real value. Do not keep doctor, login, or

other template-era commands unless the real tool needs them.

Investigate

Read references/investigation-workflow.md before implementing.

• Use playwright-cli for discovery and for unavoidable browser automation. Do

not build the generated package around the vanilla Playwright runtime.

• Default to Chrome unless the user or site requires another browser.
• Reproduce one real happy-path run.
• Capture only the requests, identifiers, auth inputs, downloads, and UI

controls that matter.

• Ask the user for manual login, MFA, sample inputs, or copied cookies or

headers when needed.

• Clean up temporary investigation artifacts unless they are intentionally

reused by the generated tool.

Choose Runtime

Read references/fetch-vs-playwright.md before deciding.

• Prefer fetch.
• Use hybrid only when playwright-cli is needed for login or bootstrap and the

saved state can be translated into the exact runtime cookies, headers, tokens, CSRF values, or other inputs that fetch needs.

• Use playwright-cli-backed browser automation only after a serious failed

attempt to make fetch or hybrid work.

• Explain briefly what was investigated, how auth works at runtime, and why the

chosen runtime is the simplest robust option.

• Validate at least one authenticated fetch request before calling a hybrid

design production-ready.

Handle Auth

Read references/auth-and-session.md when auth is required.

• Prefer explicit flags and environment variables.
• Do not add a general config file by default.
• For browser-login flows, default session storage to

~/.auth/<project_namespace>@<project_repo>.json, resolving ~ through the OS home directory. For a JSR name such as @acme/my-tool, use ~/.auth/[email protected].

• Keep --session-path, -s <path> as the explicit override on login and later

authenticated commands.

• When a tool supports multiple auth bootstrap methods, prefer an auth noun

group and validate any automatic cookie discovery against the target site.

• Never assume browser storage state is sufficient for plain fetch; prove how

runtime auth is constructed.

• Keep secrets out of normal output, --json output, and repo files.

Generate The Tool

Start from assets/templates/deno-cli/.

• Prefer the simplest clear implementation.
• Keep the package root for the library and export the CLI from ./cli.
• Keep mod.ts as the public library root and cli.ts as the Deno CLI

entrypoint.

• Keep code compact and readable.
• Prefer expressive names and straightforward structure.
• Keep runtime-neutral client code under lib/.
• Include deno compile tasks for all supported Deno targets.
• Keep compiled binaries under bin/.
• Make compile the aggregate task that builds every supported target, and add

one task per target for direct use.

• Include Deno helper task(s) for reading deno.json.version and comparing it

to the previous git ref used by the release workflow.

• Include a GitHub Actions release workflow that watches deno.json.version,

uses the Deno version helper task(s), compiles all targets, creates a GitHub Release with the binaries, and publishes to JSR.

• Include name, version, exports, and deno publish --dry-run validation.
• Treat deno.json as the single source of truth for package and CLI version

metadata. Do not duplicate the version string in cli.ts.

• Avoid indirection unless it earns its keep.
• Make the intent obvious from names, control flow, and file layout.
• Prefer code that is easy to scan over clever or aggressively compressed code.
• Favor direct solutions over ceremony, helper churn, or architecture that only

serves the template.

• Detect missing mandatory runtime dependencies and print exact install

instructions when a command needs them.

• Remove template placeholder text, example commands, and unused support files

from the final generated package.

• Remove scaffolding layers that do not improve usability.

Finish

Read references/output-and-docs.md while polishing the result.

• Deliver concise human output, stable JSON, useful errors, and clear next-step

affordances.

• Include a root README.md and a root COMMANDS.md.
• Make COMMANDS.md a cheat sheet: short, scan-friendly, and centered on

copy-pasteable CLI invocations rather than prose.

• Keep command names, help text, docs, and examples aligned.
• When the tool depends on playwright-cli, browser binaries, or other

non-bundled runtime dependencies, validate the missing-dependency path too.

• Validate --help, deno task check, the happy path, and

deno publish --dry-run.

• Validate a real invocation path users will actually use, not only local task

wrappers.