awizemann/scarf/scarf-template-author

Scarf Template Author

Scaffold a new Scarf-compatible project from a conversational interview. The output is both (a) a working project on disk the user can register with Scarf and use immediately, and (b) correctly shaped to be exported as a .scarftemplate bundle via Scarf's Export flow later.

READ THIS FIRST — use the scarf-projects tools, don't hand-edit Scarf's files

Scarf ships an MCP server called `scarf-projects`. When you can see its tools, they are the only way you register a project, write a dashboard, add a slash command, or check a project's health. They are not a convenience wrapper — they are the same code Scarf's own UI runs, so a write that goes through them cannot produce a shape Scarf can't read.

Notes that save you a retry:

• project accepts a display name or an absolute path. ~ is never expanded — pass the resolved path.
• dashboard takes the complete document, as a JSON object or as a string containing one. It replaces the file, so if you are enriching rather than authoring from scratch, read the existing .scarf/dashboard.json first and send it back whole. (project_get reports whether a dashboard exists and parses, and where it lives — it does not hand you its contents; read the file for that.)
• project_add_slash_command also takes optional argumentHint, model, tags (array of strings) and overwrite (bool, default false).
• project_validate takes repair: true to apply only the repairs Scarf considers safe.
• A tool that refuses tells you why, by JSON path for a bad dashboard (sections[0].widgets[0].type: unknown widget type), and writes nothing. Read the reason and fix your input — do not fall back to editing the file by hand because a tool said no. A refusal is the system working.
• Read tools report the registry's health. If they say it is damaged, stop and run project_validate rather than working around it. project_register refuses outright in that state, on purpose: rewriting a damaged registry would make the unreadable rows permanently lost. The project-local writes (dashboard, slash commands) aren't blocked, but they still resolve their target through the registry — so a project whose row is unreadable can't be addressed either way. "No projects found" from a damaged registry does not mean the user has no projects; never respond to it by re-registering everything.

There is no tool for configuration. .scarf/manifest.json and .scarf/config.json are still authored as files; see Config Schema Design below.

When the tools are absent

scarf-projects is registered for a local Hermes only. On a remote/SSH host you will not see these tools — and only then do you fall back to writing Scarf's files directly, using the file-format reference sections in this skill. The fallback is a last resort, not a shortcut: a hand-written registry row with a malformed field is how projects disappear from Scarf's sidebar. Check whether the tools exist before you decide.

When to invoke this skill

Activate when the user says things like:

• "Create a new Scarf project that watches / tracks / reports on …"
• "Scaffold a dashboard for …"
• "Set up a project that runs a daily check on …"
• "Help me author a Scarf template."
• "Build me a Scarf project to monitor …"
• "Upgrade this project to use Scarf's full feature set." (the upgrade/enrichment path — see below)

Do not activate for pure reference questions like "what widget types does Scarf support?" or "how does Scarf handle secrets?" — answer those inline from the reference sections below.

Also do not activate for a one-off "tweak this one widget" edit — that's a plain file edit, not a scaffold.

Upgrading / enriching an EXISTING project

Scarf hands off here right after a one-click "Upgrade Project" runs its deterministic structure pass on an existing project. By the time you're invoked, Scarf has already ensured: the stable id (.scarf/project.json), the AGENTS.md managed block (only on Hermes older than v0.16 — on v0.16+ Scarf passes a short project hint to chats instead and writes no block), a Kanban tenant (if the host has Kanban), and a placeholder .scarf/dashboard.json. Your job is to enrich it in place — do NOT re-scaffold and do NOT clobber the user's files:

1. Read what's already there first — README, the project's source, existing .scarf/ files, the placeholder dashboard — so the enrichment fits THIS project.
2. Replace the placeholder dashboard (the single "Configure this project" text widget) with a real one tailored to the project, using the widget catalog below. Read the existing .scarf/dashboard.json first, then send the complete new document with project_update_dashboard — it replaces the file. If the dashboard already has real widgets, read-merge — never delete the user's widgets.
3. Add slash commands with project_add_slash_command and, where a recurring job fits, cron jobs (hermes cron create, created paused) — see the Cron section.
4. Build a starter mini-app or two — invoke the `scarf-miniapp-author` skill for the bridge contract + .scarf/miniapps/<id>/ format. A task board, an approval queue, or a status panel makes the upgrade tangible. Prefer non-sensitive bridge permissions so it runs immediately.
5. BOUNDED: the structure pass already wrote the safe scaffolding (identity, tenant, and on Hermes older than v0.16 the managed AGENTS.md block). Only ADD or REPLACE-THE-PLACEHOLDER; never write outside managed markers or overwrite user content.

Everything below (widget catalog, config schema, cron, file-writing rules) applies to both new scaffolds and upgrades.

How a Scarf project is shaped on disk

A Scarf project is a directory that Scarf knows about: it carries a canonical record at <project>/.scarf/project.json and a row in the registry at ~/.hermes/scarf/projects.json. project_register writes both halves in one call, with a stable id — that is why you never write either file yourself when the tools are there. For Scarf to render a useful dashboard and for the project to be exportable as a .scarftemplate, it needs these files at minimum:

<project>/
├── .scarf/
│   ├── dashboard.json       # REQUIRED for dashboard rendering
│   └── manifest.json        # OPTIONAL — required only if the project declares a config schema or you want to export cleanly
├── AGENTS.md                # Cross-agent instructions (agents.md standard) — ship this for every project
└── README.md                # User-facing explanation

If the project will have a scheduled job, ALSO register a cron entry via hermes cron create. For an exportable bundle, also author cron/jobs.json in the staging directory — that's where Scarf's exporter will pick jobs up from.

Secrets never land in dashboard.json or config.json. At install time, Scarf routes secret-type config values to the macOS Keychain; config.json stores keychain://service/account URIs. When scaffolding from scratch (no install), the user either manages secrets via the post-install Configuration editor after export, or stashes them in their ~/.hermes/config.yaml if they're Hermes-level secrets rather than project-level.

The interview

Ask these questions in order. Don't batch. Each answer shapes the next question.

1. Purpose and data source

• "In one sentence — what does this project do?"
• "Where does its data come from? Files, a URL, a shell command's output, an API call, a database, a spreadsheet?"

Goal: figure out whether the project is passive (user maintains some files, dashboard reflects them), pull-based (we fetch from an HTTP endpoint or CLI tool on a schedule), or push-based (something external writes to a file we watch).

2. Refresh cadence

• "How often should it refresh? Every hour? Daily? Weekly? Only when I ask?"

If "only when I ask" → no cron job; user invokes the agent manually. If any scheduled cadence → cron job.

Map to cron expressions:

• Every hour: 0 * * * *
• Daily at 9 AM: 0 9 * * *
• Weekly Monday 9 AM: 0 9 * * 1
• Every 15 minutes: */15 * * * *

3. What the dashboard shows

Explain the widget catalog (see Widget Catalog sections below) in plain English, then ask which ones feel right. Offer concrete suggestions based on the purpose:

• Counting things (open PRs, failing tests, up/down sites) → stat widgets. Add sparkline: [Number] (v2.7+) if you have a recent trend handy.
• A list of items with status → list with text + status per item (≤8 items). 12+ items → use status_grid (v2.7+) for a denser layout.
• Time-series data → chart with line or bar type.
• Rows × columns of heterogeneous data → table.
• A live URL (useful for monitoring a site) → webview. Including a webview widget exposes a Site tab next to the Dashboard tab — worth noting to the user.
• A static image / generated chart → image (v2.7+; local file or remote URL).
• A progress bar for something with a clear 0-to-N scale → progress.
• Static help / markdown → text with format: "markdown".
• A longer markdown report the cron job writes → markdown_file (v2.7+; reads from a file under the project, refreshes when the cron job rewrites it).
• The last N lines of a log/output file → log_tail (v2.7+).
• The state of one Hermes cron job (last run / next run / output) → cron_status (v2.7+).

v2.7 file-reading widgets (markdown_file, log_tail, image-with-path) read files relative to the project root. By convention, write the underlying files inside `<project>/.scarf/` (e.g. .scarf/reports/weekly.md, .scarf/reports/run.log) so the project-wide directory watch picks up changes and the widgets refresh automatically. Files outside .scarf/ work too but only refresh when dashboard.json itself changes, so cron jobs writing outside .scarf/ should touch dashboard.json after each run.

4. Configuration needs

• "Does this project need anything configurable by the user — URLs to watch, API tokens, thresholds, a list of accounts?"

If yes → design a config schema. Fields map to seven types (see Config Schema Design below). Remember: secret fields never have defaults; that's a hard validator rule.

If no → skip .scarf/manifest.json; the project works but won't have a Configuration form.

5. Target agents

• "Which agents will operate this project? Just Claude Code? Also Cursor / Codex / Aider / other?"

For v1 just write AGENTS.md — every modern agent reads it, and if you need a specific shim (CLAUDE.md, GEMINI.md, .cursorrules), add it as a symlink to AGENTS.md so content stays in sync.

Widget Catalog (JSON shapes)

All widgets require type and title. Type-specific fields below.

project_update_dashboard validates every widget against this exact catalog before it writes anything, so a type or a missing required field that isn't in here comes back as a refusal rather than a broken dashboard. The accepted types are: stat, progress, text, table, chart, list, webview, markdown_file, log_tail, cron_status, image, status_grid, kanban_summary.