STaurtomation/AGENTS.md

STaurtomation

Clean-room, AGPL-3.0-or-later workflow automation platform meant to supersede n8n, Kestra, Windmill and Activepieces. Planned stack: TypeScript on Bun 1.3, React + React Flow editor, SQLite/Postgres. No code exists yet — the approved design is docs/specs/001-staurtomation.md; read it first.

AGENTS.md is the single source of truth for agents here. CLAUDE.md and GEMINI.md only point here. Deeper context on demand: docs/ARCHITECTURE.md, docs/DECISIONS.md, docs/TODO.md, docs/research/.

Clean room — read before anything else

This project must never be struck down: it supersedes those tools, it does not copy them. Full rules: spec §3.2. The ones agents break:

• Never read source code of n8n, Kestra, Windmill or Activepieces — no cloning, no browsing their GitHub source files, no npm view/npm pack/unpacking their packages, no reading node_modules copies of n8n-workflow, n8n-core, n8n-nodes-base, @n8n/*, @activepieces/*.
• Allowed: their public documentation sites, published specs (e.g. Windmill OpenFlow), workflow files exported from a running instance, observed behaviour of a running instance.
• Never copy code from any repository unless it is permissively licensed, AGPL-compatible, and recorded in THIRD_PARTY.md (source URL, license, commit). Nothing from the four products at all.
• Never add those products' packages as dependencies. Dependencies must be AGPL-compatible (MIT, BSD, ISC, Apache-2.0, MPL-2.0, (L)GPL-3.0, AGPL-3.0); ask first for any new one.
• Own naming. Identifiers, file layout and module names follow STaurtomation conventions. n8n node type strings (n8n-nodes-base.httpRequest) appear only inside importer mapping tables.
• Every PR touching importers, expression compatibility or compatibility layers needs a provenance note (which docs/exports/behaviour it was based on) and human sign-off.
• If you realise you were exposed to prohibited source for an area: stop, record it in the PR, and do not implement that area.
• Never use the products' names as or in our product, package or node names. "Imports n8n workflows" is fine.

Commands

TODO(maintainer): confirm commands once tooling exists (no package.json yet) — planned: bun install --frozen-lockfile, bun test, bunx tsc --noEmit.

Bun conventions (from bun init)

• bun <file>, bun test, bun build, bun install, bun run, bunx — never node, npm, jest, vitest, webpack, esbuild, ts-node. Bun loads .env itself; no dotenv.
• Bun.serve() routes + WebSockets, not express. bun:sqlite, Bun.sql (Postgres), Bun.redis, built-in WebSocket, Bun.file, Bun.$`cmd` — not better-sqlite3, pg, ioredis, ws, execa.
• Frontend: HTML imports served by Bun.serve() (they bundle .tsx/CSS/Tailwind). No Vite.
• Bun API docs: node_modules/bun-types/docs/**.mdx once dependencies are installed.

Workflow

Required skills: superpowers, impeccable. Check at session start; install if missing. Specs → docs/specs/NNN-slug.md (permanent). Plans → docs/plans/NNN-slug.md while in progress; git rm them before opening a merge request — the spec is the record. (Overrides the superpowers default paths.)

Anything beyond a trivial fix: brainstorm → spec (sign-off) → plan (sign-off) → TDD → review. TDD means failing test first, watch it fail, minimal code, watch it pass, commit. Tick plan checkboxes as you go so an interrupted session is resumable. Trivial changes (typo, version bump, one-line config): say "trivial, skipping spec" and proceed.

Use impeccable for user-facing UI — craft for new, audit/polish on existing, harden before shipping. Design context: PRODUCT.md, DESIGN.md.

Rules

• Every source file starts with // SPDX-License-Identifier: AGPL-3.0-or-later.
• No feature is ever gated by edition, license key, user count or payment.
• Importers never drop data: unsupported nodes become visible placeholders and block activation.
• Permission checks happen server-side on every route; the UI only mirrors them.

Boundaries

Never commit .env, secrets, or credentials. Never force-push, rewrite pushed history, or commit directly to main.

Ask first: new runtime dependencies · public API or schema/migration changes · auth, credential encryption, runner isolation, licensing files · anything destructive (rm -rf, git reset --hard, DB resets) · work the approved plan does not cover.

If the task turns out much larger than the plan assumed: stop, report, re-plan.

Docs duties

Same commit as the code, not "later":

• docs/ARCHITECTURE.md — when a module, boundary, or data flow changes.
• docs/DECISIONS.md — append-only; any choice a future maintainer would reverse-engineer.
• docs/TODO.md — anything noticed and deliberately not fixed. No TODO comments in source.
• docs/PERMISSIONS.md — together with every tool permission file (.claude/settings.json, .codex/, .gemini/settings.json), in one commit.

Git

Remote: origin → Gitea lucasw89/STaurtomation. Branches: feat|fix|chore/<slug>. Commits: Conventional Commits. Small, each leaving tests green.

Done means verified

Do not report success on work you have not run. Before saying done: tests run in this session and seen passing · lint and typecheck clean · matches the approved spec · docs duties complete · git status clean and the diff is only what you intended. "It should work" is not verification.