Saturngod Repository Engineering Study

Evidence-backed synthesis of Saturngod's public repositories. Authored repositories were distinguished from forks, and recent production-shaped projects were weighted more strongly than historical experiments.

Scope

Inspected the current public repository listing.
Sampled native Swift/macOS, Electron/TypeScript, Laravel/React/Go, web, Myanmar-language, and AI-learning projects.
Searched default branches for AGENT.md, AGENTS.md, CLAUDE.md, contributor guides, manifests, tests, and build scripts.
Read instruction files and implementation structure from MyaeEditor, Waing, and Oxygen, including Oxygen's scoped Go worker guide.

The profile also includes fonts, converters, dictionaries, editors, Kindle tools, dashboards, teaching repositories, and focused prototypes. One project is evidence, not a universal rule; the conclusions below recur across multiple current repositories.

Agent instruction files found

MyaeEditor

AGENTS.md defines repository structure, exact Swift/package/app build commands, naming and actor rules, test location/framework, behavior-oriented test names, commits, and visual PR evidence. CLAUDE.md adds a precise architecture map, the deliberately small public API, Markdown round-trip contract, and AppKit/TextKit invariants that must not regress.

Waing

AGENTS.md declares plan.md the source of truth, requires phase-order acceptance evidence, specifies Electron trust boundaries and typed/runtime-validated IPC, mandates sandboxing and npm, and forbids credentials, permission weakening, or automatic publishing. CLAUDE.md maps package dependency direction, schemas, adapters, migrations, generated code, strict TypeScript, and E2E test behavior.

Oxygen

The root AGENTS.md points to an authoritative CLAUDE.md; independent Go services have scoped guides. The root describes Laravel as control plane and Go services as media workers, complete verification, generated paths, cross-language enums, multi-tenancy, uploads, background processes, Docker topology, frontend rules, and Octane safety. The worker guide narrows this to package responsibilities, writable data, payload/config traps, one-ffmpeg-process invariant, progress semantics, and likely agent errors.

Recurring engineering style

Explicit architecture and thin shells

MyaeEditor keeps reusable logic in MyaeEditorKit; the macOS app is a thin shell.
Waing keeps domain and agent logic in workspace packages; Electron composes them.
Oxygen separates the Laravel control plane from Go media-processing services.
Guides state dependency direction and the responsibility of each module.

Boundaries are executable contracts

Provider-specific types stay in adapters.
Cross-boundary values begin as schemas/enums and are runtime-validated.
Renderer-to-main access uses a narrow frozen preload API.
Multi-tenant identifiers are checked at persistence boundaries.
Workers reread authoritative records instead of trusting queue payloads.
Generated routes/protocol types are regenerated rather than hand-edited.

Security is structural

Sandboxed renderer, context isolation, and no Node integration
No generic filesystem/process/shell IPC
Canonicalized workspace paths and executable resolution without a shell
Sensitive-data redaction before persistence/UI delivery
Organization-scoped queries and resource authorization
Service-token boundaries for internal APIs
Credentials excluded and permissions never weakened to make tests pass

Verification is named and composable

MyaeEditor: swift test, focused filters, full xcodebuild
Waing: npm run check combines typecheck, lint, test, and build; E2E/package checks at boundaries
Oxygen: formatting, lint, types, Pest, and Go tests; composer ci:check is the broad proof command
Tests protect contracts/regressions; visual changes require screenshots or recordings.

Project memory lives beside code

Root instructions carry global architecture and workflow. Scoped instructions explain independent runtimes and non-obvious traps. They document what an agent cannot safely infer from source alone.

Acceptance governs progress

Large projects use plans and definitions of done. Progress trackers change only after acceptance criteria are demonstrated, matching Spec Map Build Prove Learn.

Small stable public surfaces

MyaeEditor names a small public API. Waing exposes typed package entry points and a narrow preload surface. Oxygen centralizes routes and enums. Contracts stay stable while internals evolve.

Generated code is clearly separated

Generated paths are named, excluded where appropriate, and updated through exact generation commands. Applied migrations are forward-only.

Operations belong to architecture

Processes, queues, retries, cancellation, cleanup, configuration precedence, progress semantics, packaging, deployment, and supervision are documented with code—not postponed until release.

Idiomatic per language

Swift: standard API naming, one primary type per file, actor isolation, Swift Testing
TypeScript: strict flags, schema-inferred boundary types, workspaces, ESLint/Prettier/Vitest
Laravel/PHP: framework conventions, middleware/policies, enums, factories, Pest/Pint
Go: explicit packages, context cancellation, explicit SQL, restricted writable state, small entrypoints

Consistency is in engineering judgment, not identical syntax across ecosystems.

Coding/build habits

Descriptive domain names rather than vague helpers
Interfaces/adapters around external providers
UI kept separate from domain, codec, and persistence behavior
Parsers/codecs protected by round-trip tests
Capability/state validation before side effects
Focused tests during iteration; one combined check before completion
Separate dev, package, E2E, and release paths
Explicit toolchain/CI versions and release prerequisites
Adding a long-running process also updates production supervision
Short imperative, focused commits; PRs state behavior, tests, issues, screenshots, and compatibility impact

Cautions

Forks are not evidence of original authorship/style.
Old experiments should not outweigh newer instructed repositories.
Tests and current implementation outrank stale plans.
Project-specific constraints such as “npm only” or “one ffmpeg invocation” should be copied only with the same underlying need.

Reusable derivative

Use Saturngod-Inspired Repository Guide to apply these lessons to your own projects.