Boilerplate Generator (Template-Driven)
Primary method: run the v2 scaffold script — it renders everything below deterministically and writes a
.manifest.jsonprovenance file:python ${CLAUDE_PLUGIN_ROOT}/scripts/scaffold-cli.py <app>/agent-harness \ --app-name <app> \ --protocol <rest|graphql|html-scraping|batchexecute> \ --http-client <httpx|curl_cffi> \ --auth-type <none|cookie|api-key|google-sso> \ --resource <name> [--resource <name> ...] \ [--has-polling] [--has-context] [--has-partial-ids]Requires
pip install jinja2(TEMPLATE_VERSION 2.1.0). Each repeatable--resourceflag scaffolds acommands/<resource>.pymodule.If the script is unavailable, do NOT render templates by hand from memory — follow
skills/shared/RECOVERY.md§scaffold-cli.py Unavailable (adapt from the newest generated CLI, e.g.,capitoltrades/agent-harness/).
All templates live in ${CLAUDE_PLUGIN_ROOT}/templates/*.tpl (Jinja2 syntax).
Generated code must satisfy skills/shared/CONVENTIONS.md — the templates
already encode those rules; never "simplify" them away.
Step 1: Collect Template Variables
| Variable | Type | Source | Example |
|---|---|---|---|
app_name | str | CLI name (cli-web-<app> → <app>) | hackernews |
APP_NAME | str | UPPER_SNAKE (hyphens → underscores first) | HACKERNEWS |
AppName | str | PascalCase | HackerNews |
protocol | enum | traffic-analysis.json: rest, graphql, html-scraping, batchexecute | rest |
http_client | enum | protection detection: httpx, curl_cffi | httpx |
auth_type | enum | site profile: none, cookie, api-key, google-sso | cookie |
resources | list[str] | <APP>.md endpoint groups (one --resource flag each) | stories users |
has_polling | bool | async/long-running operations exist | false |
has_context | bool | CLI needs use <id> / status context | false |
has_partial_ids | bool | resource IDs support prefix matching | false |
Casing is derived inside the templates via Jinja2 filters — you only supply
--app-name.
Step 2: Template → Output Map
Template (templates/) | Output | Rendered when |
|---|---|---|
exceptions.py.tpl | core/exceptions.py | always |
client_rest_httpx.py.tpl | core/client.py | http_client=httpx, non-batchexecute (GraphQL/HTML variants are {% if %} blocks inside) |
client_rest_curl.py.tpl | core/client.py | http_client=curl_cffi, non-batchexecute |
client_batchexecute.py.tpl | core/client.py | protocol=batchexecute |
auth.py.tpl (UNIFIED) | core/auth.py | auth_type != none — google-sso specifics (cookie domain priority, regional forcing) are a {% if auth_type == "google_sso" %} block; there is no separate Google template |
cli_entry.py.tpl | <app>_cli.py (+ __main__.py) | always — REPL default, UTF-8 fix, --json propagation |
command_group.py.tpl | commands/<resource>.py | once per --resource flag — Click group skeleton wired to the client |
helpers.py.tpl | utils/helpers.py | always (handle_errors, print_json) |
helpers_polling.py.tpl | appended to helpers | --has-polling |
helpers_context.py.tpl | appended to helpers | --has-context |
helpers_partial_ids.py.tpl | appended to helpers | --has-partial-ids |
output.py.tpl | utils/output.py | always (json_success/json_error) |
setup.py.tpl | setup.py | always — namespace packages, entry point, deps per http_client/protocol |
conftest.py.tpl | tests/conftest.py | always |
test_e2e.py.tpl | tests/test_e2e.py | always — _resolve_cli + TestCLISubprocess fixtures pre-wired |
rpc_types.py.tpl, rpc_encoder.py.tpl, rpc_decoder.py.tpl | core/rpc/ | protocol=batchexecute only |
README.md.tpl | cli_web/<app>/README.md skeleton | always |
SKILL.md.tpl | per-CLI skill skeleton | always (filled in during Phase 4) |
Also produced by the script (not templates): __init__.py files, the vendored
runtime adapters utils/repl_skin.py, utils/doctor.py, and
utils/mcp_server.py (canonical source cli-web-core/cli_web_core/, synced by
cli-web-devkit resync; the entry point registers doctor + mcp-serve from
them), utils/config.py, and .manifest.json
at the harness root recording template_version, profile
(protocol/http_client/auth), resources, and generation timestamp — fleet
tooling (cli-web-devkit drift) depends on it.
Step 3: Profile Recipes
| Site profile | Flags |
|---|---|
| No-auth + read-only (HN, gh-trending) | --auth-type none — NO auth.py, NO session.py, NO auth commands (dead code is a checklist FAIL) |
| No-auth + CRUD (Dev.to) | --auth-type api-key — minimal auth module, auth set-key |
| Cookie auth (reddit, linkedin) | --auth-type cookie + --has-polling if generation ops exist |
| Google SSO + RPC (notebooklm, stitch) | --auth-type google-sso --protocol batchexecute — renders rpc/ subpackage + Google block in auth.py |
| Anti-bot protected (Cloudflare/WAF) | --http-client curl_cffi — see capture/references/protection-detection.md escalation ladder |
| Stateful apps (notebooks/projects) | add --has-context; UUID-keyed resources add --has-partial-ids |
Step 4: Post-Scaffold Checklist
-
.manifest.jsonexists at the harness root withtemplate_version: 2.1.0 -
cli_web/has NO__init__.py;cli_web/<app>/HAS one - No unresolved Jinja2 markers (
{{,{%) remain in any output file -
FILL_IN_BASE_URLmarkers noted — replace during implementation -
auth_type=none→ nocore/auth.py, no auth command group anywhere -
protocol=batchexecute→core/rpc/has types/encoder/decoder; otherwisecore/rpc/does NOT exist - One
commands/<resource>.pyexists per--resourceflag, all registered on the CLI group - All files pass
python -m py_compile
Then continue with methodology/SKILL.md Step B: fill in endpoint methods in
client.py from <APP>.md, flesh out the scaffolded command modules, and
keep _print_repl_help() in sync (CONVENTIONS.md §REPL Rules).