galactic-engineering

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Galactic Engineering

Apply these conventions when working on code in the `galactic-ide` repository.

- Apply the testing and versioning rules to all feature work.
- Apply the React/TypeScript/Tailwind rules when editing renderer code in `src/`.

---

## Repository-Wide Testing Requirement (GLOBAL)

- For every new feature or changed feature, add or update unit tests that verify expected behavior.
- Include at least one edge case or failure-path test for changed behavior.
- A feature is not complete until the relevant unit tests are passing locally.
- Exception: pure documentation/content updates with no runtime behavior change do not require tests.

---

## Repository-Wide Analytics Requirement (GLOBAL)

- For every new user-facing feature or meaningful workflow change, add or update product analytics that answer adoption, usage, success, and failure questions for that feature.
- Keep analytics privacy-safe and low-cardinality: never capture secrets, filesystem paths, terminal input/output, raw commands, raw errors, tokens, or user-authored content.
- Prefer typed analytics event names and small wrapper helpers that mirror existing Galactic patterns; add tests for new analytics wrappers and payload-shaping helpers.
- If PostHog dashboards or insights are requested, create them only after the relevant events exist in the PostHog schema; do not create empty placeholder dashboards.

---

## Repository-Wide Versioning Requirement (GLOBAL)

- For a given feature branch, bump the app version only once for the same feature.
- Do not repeatedly increment version for follow-up commits that are part of the same feature branch scope.

---

## File Structure Rules

NEVER:
- Create `index.ts` or `index.tsx` files
- Use deep relative imports (`../../../components/...`)
- Mix logic, UI, and styling in the same file

ALWAYS:
- Import directly into component files
- Use path aliases (`@/`, `@components/`, `@pages/`, `@styles/`)
- Structure each component with `.tsx` plus colocated hooks/utilities only
- Follow the Single Responsibility Principle (SRP)

---

## File Size Rules

HARD LIMIT:
- No file should exceed ~140 lines of code
- Applies to both new and existing files; if your edits would push a file past ~140 lines, split it before finishing.

If a file approaches 140 lines, you MUST:
- Split logic into custom hooks or utilities
- Break UI into smaller sub-components
- Separate responsibilities strictly by SRP

A file larger than 140 lines is considered an architectural smell.

---

## Styling Rules (CRITICAL)

- Use Tailwind utilities and shadcn variants for all visual styling; avoid inline `style` except for CSS variables.
- Prefer `gap` for spacing between siblings; avoid `margin` for layout. Use padding only for container interior spacing.
- Avoid arbitrary pixel values. Stick to the Tailwind scale (rem-based). If a token is missing, request it rather than hard-coding.
- Keep styling inside `className` via `cn(...)`; do not use template string concatenation.
- Add custom CSS only when Tailwind/shadcn cannot express a requirement; use design tokens and CSS variables when doing so.

### Shadcn UI Components

- Prefer components from `@/components/ui` over raw HTML when available.
- Use provided `variant`, `size`, and `asChild` props instead of ad-hoc classes.
- Keep layout simple: flex/grid with Tailwind `gap`, `items`, `justify`, `rounded`, `shadow`, etc.

### Tooltips (CRITICAL)

- ONLY use shadcn Tooltip:

```tsx
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";

<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <Button size="icon" variant="ghost">?</Button>
    </TooltipTrigger>
    <TooltipContent side="top">Helpful text</TooltipContent>
  </Tooltip>
</TooltipProvider>
```

### Icons

- Use `lucide-react` only; no custom SVGs.
- Size icons with Tailwind classes (`className="h-4 w-4"`). No inline `width`/`height`.

### Toasts (CRITICAL)

- ALWAYS use `useAppToast` from `@/hooks/use-app-toast` in feature code.
- NEVER import `sonner`, `@/hooks/use-toast`, or `@/components/ui/use-toast` directly outside toast infrastructure files.
- Use `error(...)` for standard failures; shared error toasts auto-dismiss after 5 seconds unless an explicit override is required.
- Use `info(...)` for non-error informational messages and `success(...)` for standard completion messages.
- Use `loading(...)` for long-running async flows; update the same toast during progress and finish it with `success(...)`, `error(...)`, `info(...)`, or `dismiss()`.
- Only use persistent toasts when product behavior requires it, and set `duration: Infinity` explicitly.

---

## TypeScript Rules

- Define an `interface` for all component props; use `type` for unions/utility shapes.
- Export interfaces when used elsewhere.
- Avoid `switch` statements for mapping; prefer object maps:

```tsx
const statusLabels: Record<Status, string> = { loading: "Loading...", success: "Done!", error: "Failed" };

From idolaman/galactic, AGPL-3.0.

More from idolaman/galactic