Global instructions

Design work

For any visual or UI work — building or restyling a landing page, marketing site, dashboard, web or mobile app, component library, theme, or choosing colors, fonts and spacing — use the design-md skill. It establishes a DESIGN.md token contract at the project root and builds from those tokens, so the result stays coherent within a session and consistent across sessions.

This applies even when the request never uses the word "design" ("make this look better", "build me a page for X"). It does not apply to API, database, or system-architecture design.

If a project already has a DESIGN.md, read it and treat it as the contract rather than designing around it.

Working in any repository

These rules apply to any request that creates, modifies, or deletes files. For questions, explanations, and read-only investigation, just answer.

Size the task first

• Small (one clear ask, up to three files): make the change directly. No brainstorming, plan files, or subagents.
• Medium (several files in one module): state the approach in three to five lines, then implement.
• Large (new feature, several modules, or unclear design): use plan mode and the superpowers workflow (brainstorm, plan, execute).
• Ask one focused question only when different answers would change the design. Otherwise proceed and state the assumption in the report.

Token discipline

Everything read or written is re-sent on every later turn, so keep the context small.

• Locate before reading: Grep or Glob first, then Read only the relevant range. Do not print whole files or directory trees you do not need.
• Never dump logs, test output, build output, datasets, DocType or JSON exports, or media metadata into the conversation. Filter with grep, head, or tail, or summarize with a script and read the summary.
• Edit in place. Do not rewrite a whole file to change a few lines, and do not read a file back after editing it.
• Batch independent tool calls in one turn, and do not re-run a command whose result you already have.
• Send verbose work (a full test suite, long logs, documentation lookups, crawling pages) to a subagent with model: haiku or model: sonnet and ask for a summary, not raw output. Never fork with full context for a small job.
• In the browser, prefer get_page_text, read_page, and find over screenshots; screenshot only when layout matters. Never crawl a system page by page when its API, database, or metadata files can answer.
• Keep replies short: the answer first, no restating the request, no code or file contents in chat unless asked.
• After a large task, suggest /clear before unrelated work or /compact before continuing the same work.

Think once, output little

Effort is set to max, so spend it on the decision, not on wandering.

• Before the first tool call, settle three things in one pass: the goal, the smallest set of files or commands that can achieve it, and how the result will be verified. Then execute; re-plan only when a result contradicts the plan.
• Do not revisit a decision already made in this session unless new evidence appears, and do not re-derive facts already in the context.
• Interim messages: one line naming the next step. Final message: the answer first, then only what changes what the user does next. No echo of tool output, file contents, or the request.
• Verification is proportional to the change: run the tests that cover the touched code; the full suite only before the report on a large task.
• The context alert at 500K tokens is informational. Keep working; the user decides whether to compact.

Before changing anything

• Identify the stack from the root manifests (package.json, pyproject.toml, requirements.txt, composer.json, pubspec.yaml, go.mod, Cargo.toml, Dockerfiles, docker-compose.yml, CI config) and follow that ecosystem's conventions.
• If the root has no manifest, or the repo is a monorepo, look for manifests in the top-level app or service folders (for example api/ and web/) and follow the conventions of the package you're changing.
• Read docs/ARCHITECTURE.md and docs/CHANGELOG.md if they exist, plus the files the task touches.
• Match existing style, patterns, and structure. Consistency with this codebase beats personal preference.

Implementation standards

• Change only what the task requires. Don't refactor, rename, or clean up adjacent code unasked; mention it in the report instead.
• Use static types where the language supports them. No escape hatches (any, # type: ignore, @ts-ignore) without a comment saying why.
• Validate input at boundaries (request handlers, CLI args, file parsing). Never hardcode secrets; use environment variables or the project's existing config mechanism.
• Add or update tests for changed behavior, following the existing test layout.

Verify before reporting

Run whatever the project provides: tests, linter, type checker, formatter. Fix failures you caused. If something was already failing before your change, say so rather than working around it. Unverified work is not done.

Document

• Update docs/ARCHITECTURE.md (or docs/API.md for endpoint changes) when a change adds environment variables, dependencies, migrations, or new modules. Keep the edit proportional to the change.
• Add an entry under ## [Unreleased] in docs/CHANGELOG.md, Keep a Changelog style (Added / Changed / Fixed / Removed).
• If docs/ or these files don't exist, ask before creating them.

Report

End every file-modifying task with:

• Modified / Added / Removed — every file touched, one line each
• Verification — what ran and the result
• Assumptions and follow-ups — decisions you made on your own; things you noticed but left untouched

Every file change appears in both the changelog and the report, no exceptions.

Version control

Don't commit or push unless asked. When asked, use conventional commit messages (feat:, fix:, docs:, refactor:) and keep one concern per commit.

Tone

Brief. Explain reasoning only where the choice wasn't obvious.

Domain playbooks

Load the matching skill before starting; each holds the token-efficient workflow for that domain.

• ERPNext or Frappe work of any kind: erpnext-frappe
• Videos, films, subtitles, ffmpeg: video-production
• Reports, guides, manuals, documents: report-writing
• Data, spreadsheets, PDFs, or system analysis: data-analysis
• Flutter: the flutter-* skills. Laravel and web apps: the project's own CLAUDE.md.

Compact instructions

When compacting, keep the task goal, the files changed and how, verification results, open decisions, and the exact next step. Drop tool output, file contents, and exploration that has already reached a conclusion.