AGENTS.md

Entry point for coding agents. Read this first, match the user's request to a skill in the routing table, load that skill, and follow it. This file is the only source of instructions for this repo — other agent instruction files point here and add nothing of their own.

Skills are the ground truth for CLI/SDK usage. This file routes; the skill owns the flow. Don't duplicate a skill's steps here.

Routing is your job, not the user's

Never expect the user to name a skill. There is no /skill invocation, no slash command, no menu. Users describe what they want in plain language — "let users upload a profile picture", "why does login redirect back to the login page", "add German translations" — and you map that to the right skill and execute it.

• Do not ask "which skill should I use?" or list skills for the user to pick from. Reading the request and choosing is your work.
• Do not wait to be told. Once the request matches a row in the routing table, load that skill and proceed.
• If the request genuinely spans several skills, pick the one that owns the first concrete step, run it, then move to the next. Sequence them yourself.
• If nothing matches, check the installed skills (see Loading a skill) before concluding no skill applies — the table below can lag the installed set. The published catalog is skills/ in the blocks-skills repo.
• Ask the user only about things the routing table cannot settle: a destructive confirmation, a missing credential, or an ambiguous goal — never about which skill to run.

The routing table exists so you can decide unaided. Treat a request that names no skill as the normal case, because it is.

Workflow

1. Understand the objective.
2. If login/project/app state is unknown, probe (below) and start with blocks-bootstrap.
3. Match the request against the Skill routing table yourself, then load the skill by reading its vendored SKILL.md (see Loading a skill below).
4. Inspect the existing implementation before changing it.
5. Make the smallest correct change, then verify it.

Prerequisites

The blocks CLI is required for terminal/admin work:

npm install -g @seliseblocks/cli-os@latest
blocks --version

Do not install it automatically. If blocks --version fails, ask first. The SDK for app code is npm install @seliseblocks/client@latest.

Read-only probe when state is unknown:

blocks --version
blocks auth status --json
blocks doctor --json

If blocks is missing, stop the probe and ask before installing. Don't claim bootstrap is runnable until the CLI exists.

Never guess a command or a flag — ask the CLI. blocks help <command> prints one command's exact positionals, flags, scope, and whether it mutates; blocks help <family> lists a family; blocks --help --json lists every command. Read that before running anything unfamiliar, and prefer it over any command spelling you remember, including one from this file. Set BLOCKS_STRICT_FLAGS=1 in scripted runs so an unrecognized flag hard-fails instead of being warned and ignored.

Loading a skill

Skills are files, not a CLI command. They reach an agent one of two ways, and a given repo uses one, not both — with both, the agent sees every skill twice:

• Plugin (Claude Code, Cursor). The selise-blocks plugin installs every skill, and the agent lists and loads them by name like any other plugin skill.
• Vendored (every other agent, or any repo set up with BOOTSTRAP.md). Skills live on disk as .agents/skills/<name>/SKILL.md, the cross-agent location most coding agents read natively. An agent that only reads its own directory (Claude Code reads .claude/skills/, Qwen Code reads .qwen/skills/) finds the same set through a pointer stub there whose body sends you to the .agents copy. Read the .agents copy directly.

There is no blocks skill list/show/add command, and the CLI package does not bundle the skill tree. Don't reach for those commands, and don't treat their absence as a broken install.

If a skill named in the routing table isn't installed, the fix is to update the plugin, or re-run the vendoring runbook (BOOTSTRAP.md in the blocks-skills repo) — not to fetch the file ad hoc or write a replacement from memory. The published catalog is skills/ in the blocks-skills repo; read from there only to confirm a name, never as a substitute for installing.

Hard rules

• Never raw fetch/curl against api.seliseblocks.com. Use the blocks CLI or the @seliseblocks/client SDK. Every skill states which surface it uses. Bypassing them with raw HTTP is the failure mode these skills exist to prevent. The one sanctioned raw curl is the anonymous report endpoint at seliseblocks.com/api/reports (see Report what you find), which is not the platform API.
• Never send a report to Blocks unless reporting is opt-in or the user asked for that report, and never put anything identifying or secret in one. The rules are in Report what you find below.
• --dry-run before --yes on every mutating CLI command. Get human confirmation before destructive or cloud-mutating operations.
• Never read the CLI's local storage files (config/token/secret files on disk) or print anything inside them — client ids, root tenant id, account names, tokens. Interact only through blocks commands. To repair broken state use blocks login, blocks auth remove <account>, blocks projects list --json, blocks use <tenantId>.
• blocks projects create accepts the Blocks terms on the user's behalf (isAcceptBlocksTerms, isUseBlocksExclusively). Never run it without explicit consent to that, and never to "try something" — it provisions real cloud tenancy. Run --dry-run --json first, then --yes only after approval. It creates exactly one app in the dev environment; further environments are portal-only.
• Never expose secrets or credentials. blocks secrets get and friends exist for operating the store, not for printing values into a conversation or a file the user did not ask for. Never work around a missing capability with raw HTTP.
• Don't attribute work to an AI tool anywhere in this repo — no assistant names in docs, comments, or commit messages.

Report what you find

When something in Blocks does not behave as documented, cannot do what you need, or took real effort to figure out, it is worth a report to the Blocks team: a bug, a quirk, a limitation, a learning, or a suggestion. Reports are anonymous, need no account, and go to https://seliseblocks.com/api/reports — a website endpoint, not the platform API, so the raw-HTTP rule above does not apply to it.

Whether you may send one on your own is the user's choice, recorded once at bootstrap in .agents/skills/.blocks-reporting. Read that file before deciding:

A plugin install has no such file until the user asks for one, so it starts as opt-out. Turning reporting on writes .agents/skills/.blocks-reporting in the repo the same way.

Two things hold regardless of the setting:

• The user can ask for a one-off report at any time ("report this to Blocks", "send them this finding"). File it, following the steps below.
• The user can change the setting at any time ("turn Blocks reporting on", "stop sending reports"). Rewrite the file with the new value — the only accepted values are reporting=opt-in and reporting=opt-out — and confirm what it now says. Nothing else needs to change; the file is the whole preference.

Filing a report

1. Read https://seliseblocks.com/api/reports once per session; it explains every field and what the answers mean.
2. In a temp directory (mktemp -d), not the repo, write blocks-report.md starting from https://seliseblocks.com/api/reports/template. Fill in cli (blocks --version), sdk (the installed @seliseblocks/client version, if used), agent (the harness, never a person), model, and platform. For skills, use name@<version>. Skills carry no version of their own: when vendored, use the first seven characters of commit (skills_commit in an older stamp) from .agents/skills/.blocks-skills-source; when installed as a plugin, use plugin-<version> with the plugin version stated in the blocks skill. Set security: true when the finding is a security risk. Say what was run, what came back, what was expected, and how to reproduce it.

3. Read the file back for anything listed under What never goes in a report, then validate and send:

   curl -fsS -X POST https://seliseblocks.com/api/reports/validate -H "Content-Type: text/markdown" --data-binary @blocks-report.md
   curl -fsS -X POST https://seliseblocks.com/api/reports -H "Content-Type: text/markdown" --data-binary @blocks-report.md

   Fix anything validate returns as an error before sending. A 201 means it is recorded; tell the user the id from the answer. On 429 wait for Retry-After; on 503 keep the file and retry later rather than dropping the report.

What never goes in a report

Nothing that identifies a person or grants access: no names, emails, tokens, secrets, cookies, or paths under a home directory. Trim logs to the relevant lines and read them for leaks before sending — the endpoint strips some of this as a safety net, but you are the guard, not it. Tenant ids and project keys are public and fine. Keep the user's application code and business data out unless a minimal excerpt is needed to reproduce the finding, and strip anything identifying from that excerpt too.

Skill routing table

Surface: CLI = terminal/admin, project-scoped · SDK = @seliseblocks/client in app code · Both = each surface covers part of the job.

Start here

Data

IAM

Localization

Messaging

Backend logic

Platform operations

Local development

Routing notes

• Own account vs. other users vs. role definitions — blocks-iam-account / blocks-iam-users / blocks-iam-access-control. Pick by whose record changes.
• Configuration vs. implementation — most areas split in two: a CLI skill that defines the thing and an SDK skill that consumes it at runtime. "Create a schema" is configuration; "fetch products" is implementation.
• notifier sends, notification configures. Different services.
• Inline call vs. workflow — a single call the app makes itself ("send this email", "save this record") belongs to that service's skill. Reach for blocks-workflow only when the logic must run server-side on an event, webhook, or schedule.
• Proxy vs. function vs. workflow — forwarding to one third-party API with a hidden key is blocks-proxy; code you write (validation, computation, several calls, a webhook handler) is blocks-functions; a multi-step graph started by a data event or schedule is blocks-workflow, which can call both as steps.
• blocks-data-storage operates on files; blocks-storage-configuration chooses the provider underneath.
• Dependencies: schema work must be reloaded before CRUD sees it; SSO implementation needs a registered OIDC client and HTTPS on the real domain to test.

What lives here

This repo is the single source for the SELISE Blocks skills and everything that ships them:

A new skill is one PR: its directory under skills/ plus its routing-table row. A skill missing from that table is invisible to agents and is never vendored — the runbook treats the table as its manifest, and npm run lint:router fails on a directory with no row.

Checks. npm test runs both lints. npm run lint checks every skill, including that each blocks … command it cites is registered in the CLI. It asks a real binary: the published blocks on PATH (at least blocksCli.minVersion), or a built blocks-cli checkout named by BLOCKS_CLI_DIR for a command that isn't published yet. Requires Node 20+.

The CLI is a separate repo. Skills depend on SELISEdigitalplatforms/blocks-cli; it never reads them. A CLI change that renames, removes, or changes a command a skill cites needs a matching PR here — nothing in the CLI repo fails when a skill goes stale. The nightly CI run against the latest published CLI is what catches it.

Skills lived in blocks-cli under blocks-skills/ until they moved here with their history (tag skills-last-in-cli there marks the last commit that had them). Installs vendored before the move are stamped with that repo; bootstrap/update.md handles them, so keep that history intact.

Changing the runbook. BOOTSTRAP.md is the only file a consumer's agent is pointed at; it reads a bootstrap/ file only when BOOTSTRAP.md's Pick your task or The full install table names it. So when you add, rename, split, or remove a file under bootstrap/, update both tables in the same change, and fix every link to it from the other bootstrap/ files. Keep each fact in one file — link to it from the others rather than restating it. When an agent's behavior changes, the only file to edit is bootstrap/agents.md.

An older generation of skills lived in this repo's skills/ directory before Aug 2026 and drove api.seliseblocks.com over raw HTTP with manual impersonation (x-blocks-key/PTOK). That generation is superseded — the current skills forbid raw HTTP outright. Never restore anything from a commit before the move.

Skill authoring conventions

These govern every skill under skills/ and the routing-table row that accompanies it:

• SKILL.md frontmatter is name + a trigger-rich, third-person description. The description is what routes a request — say what the skill does and the phrases and contexts that should invoke it, plus what it is not (name the sibling skill). Lean slightly pushy; under-triggering is the common failure.
• Ground every claim in verified behavior. Drive the real command or SDK call before documenting it. Capture real request/response shapes. If you can't verify something, mark it unverified rather than smoothing it over — never fabricate output or invent flags. Honesty beats completeness.
• Style: imperative, concrete, American spelling, tables over prose walls, no marketing language.
• Name the sibling skills a skill borders in its description, so misrouting between neighbors is caught. Do not link across skill directories — vendoring copies each directory independently, so every relative link must resolve inside the skill's own directory.
• Scope: one clear job per skill; split rather than sprawl. One skill per PR where practical.

See CONTRIBUTING.md for the full contribution bar.