Agent instructions

This file is the single landing page for coding assistants (Cursor, Kilo Code, Claude Code, Aider, …) working on ZeroAgent Studio — a $0-hosting, browser-native AI workflow editor on GitHub Pages.

The authoritative source for humans is docs/CONTRIBUTING.md. When anything below conflicts with CONTRIBUTING.md, the docs win.

Sections: TL;DR · Architecture · Project boundaries · Before you change code · Portable skills · Personas · Commands · Adding things · Ignore & secret scanning · Do not commit · Security

TL;DR

1. Read first — docs/CONTRIBUTING.md and docs/ARCHITECTURE.md.
2. No backend. No Express, no DB server, no API routes, no env secrets in the repo.
3. Registry-driven. Tools in src/tools/registry.ts + manifests — never hardcode in dag.ts or palette.
4. Honest brain guidance. OpenRouter recommended when users can paste a free key; Transformers.js is the no-key local path (brainResolver.ts, brainChoiceGuidance.ts).
5. 100 % test coverage on included src/ (vite.config.ts excludes UI shells). Catalog count 203 is test-enforced.
6. Quality gate: npm ci + npm run ci — must be green before any commit or PR.
7. Never commit plans, secrets, build artifacts, or hardcoded catalog numbers.
8. Ask the user before: adding a dependency, bumping package.json / lockfile, deploying, tagging a release, or pushing.

Non-negotiable architecture

Project boundaries

Before you change code

1. Read docs/CONTRIBUTING.md and docs/ARCHITECTURE.md — first time or after a long break.
2. Match existing patterns in the file you edit. Smallest correct diff. No unrelated refactors.
3. Run the gate before any commit: npm ci && npm run ci (audit → lint → typecheck → test:coverage 100 % → build). Never commit on red.
4. Cover new behavior in tests/ — real scenarios, not trivial expect(true). See .kilo/rules/06-test-engineer.md (Kilo) or .cursor/rules/zeroagent-test-engineer.mdc (Cursor).
5. Update user-facing docs in the same PR when behavior changes: README, in-app Guide (src/components/guide/GuidePage.tsx), docs/SECURITY.md, docs/TOOL-SAFETY.md, and CHANGELOG.md for user-visible changes.
6. Use the PR template at .github/pull_request_template.md. CODEOWNERS routes review at .github/CODEOWNERS.
7. Never commit, push, deploy, or tag a release without explicit user confirmation. See .kilo/kilo.jsonc permission.edit for the supply-chain-guarded paths.

Portable skills

Two parallel sets of agent playbooks stay in sync. If you change a Cursor rule / skill, mirror the edit in .kilo/ (or vice versa) so a developer switching tools does not lose context.

Specialized personas (Kilo)

Switch via /agents or Cmd+. in Kilo. Each persona has scoped permissions and an optimal model override.

The built-in Kilo agents (code, plan, ask, debug) are still available — the ZeroAgent personas add project-specific knowledge on top.

Quick commands (Kilo)

Type the slash command in chat to invoke a multi-step workflow.

Adding things

Assistant ignore & secret scanning

Defense-in-depth: the same secret/credential patterns live in four places. Keep them in sync — when you add a pattern, update all four.

Patterns covered (all four): .env*, *.pem, *.key, *.p12, *.pfx, *id_rsa*, *id_ed25519*, *id_ecdsa*, *.gpg, *.asc, .netrc, .aws/, .gcp/, .azure/, .gcloud/, .ssh/, credentials/, secrets/, node_modules/, dist/, coverage/, *.map, *.tsbuildinfo.

Automated scanning: CI runs CodeQL (github/codeql-action@v4, javascript-typescript, security-and-quality query pack, weekly Monday 06:00 UTC) + PR dependency review

• Dependabot (weekly npm + GitHub Actions, grouped). Locally, install gitleaks or trufflehog for the same coverage before opening a PR.

Do not commit

Security

• API keys: session storage default (AES-GCM vault in sessionKeyVault.ts); never in exports, URLs, screenshots, or test fixtures. src/lib/keyStorage.ts.
• Custom Script: runs in a Web Worker with no fetch / importScripts / XHR / WebSocket; warn users not to paste secrets.
• Web scraper: text extraction only — never inject untrusted HTML into the React DOM. SSRF blocklist in src/lib/validateUrl.ts (no loopback, private IPs, embedded credentials). CORS proxies see requested URLs — document the trust boundary.
• Speech / mic: activate only on explicit tool run; handle permission errors gracefully.
• Model downloads: WebLLM and Transformers.js pull from third-party CDNs (Hugging Face, …). It is a download, not us receiving your chat — but pin versions and treat as supply-chain.
• Dependencies: npm audit --audit-level=moderate is part of npm run ci; Dependabot PRs grouped weekly; review every engine bump; dependency review on PRs when lockfile changes.
• Export redaction: .zeroagent.json strips common API-key patterns in all string fields (config, prompts, chat messages). Prevention is still better.
• Docs must match code — if behavior changes (privacy UI, locked tools, export redaction, safety notices), update README, Guide, docs/SECURITY.md, and docs/TOOL-SAFETY.md in the same PR.

We are a trusted educator, not a token funnel: no analytics, no backend that sees user data, honest cloud caveats in copy.

Full model: docs/SECURITY.md. Per-tool warnings: docs/TOOL-SAFETY.md. Privacy copy source: src/lib/cloudPrivacy.ts.

Quality gate: npm ci && npm run ci — green only. Live site: https://sakurablush.github.io/zeroagent-studio/ Tone: plain language, explain jargon, no shame, no "just buy a better machine" — see "Empathy in copy" in docs/CONTRIBUTING.md.