Lucas WintherandClaude Opus 5.5
15740a054f
Adds AGENTS.md (clean-room and Bun rules), pointer files, agent permission configs, docs tree, the STaurtomation design spec (draft) and sanitized licensing/competitor research. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
98 lines
5.4 KiB
Markdown
98 lines
5.4 KiB
Markdown
# 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.
|